要求のフェッチ: スコープ、グローバル

  • リリースバージョン: Yokohama
  • 更新日 2025年01月30日
  • 所要時間：26分

    • フェ ッチ要求 API には、アプリケーションがサーバーから JSON、テキスト、バイナリデータなどのリソースを非同期に要求し、応答を処理できるように、要求オブジェクトを作成または取得するためのメソッドが含まれています。この API は、GET、POST、PUT、DELETE などのさまざまな HTTP メソッドをサポートしています。

    この API は、外部 Web サイトからリソースを取得するためのさまざまなアクションを提供する一連の フェッチ API の一部です。完全な Fetch API コレクションには次のものが含まれます。

    フェッチアクションをサポートするために、システムプロパティ glide.hosts.allowlist を使用すると、フェッチメソッドがアクセスできるホストを制御できます。これは、 RestMessageV2 などの HTTP API や上記の API に適用されます。glide.hosts.allowlist の詳細については、「Available system properties」を参照してください。

    要求プロパティ

    フェ ッチ要求 API は、HTTP 要求に関する詳細情報を提供するいくつかの読み取り専用プロパティをサポートしています。これらには、 url (要求の URL)、 method (HTTP メソッド)、 ヘッダー (関連するヘッダー)、 および body (ストリームとしての要求本文) が含まれます。その他のプロパティには、キャッシュ、認証情報、およびリファラーの設定が含まれます。これらのプロパティは読み取り専用であるため、アクセスすることはできますが、要求の作成後に変更することはできません。各プロパティの詳細については、「 https://developer.mozilla.org/en-US/docs/Web/API/Request」を参照してください。

    表 : 1. 要求プロパティ
    プロパティ名 説明 例
    本文 準備完了専用プロパティ。要求に追加された本文の内容を含む、バイトデータの読み取り可能なストリームが含まれます。

    データタイプ/値:ReadableStream または null。

    		 
    const request = new Request("/myEndpoint", {
  method: "POST",
  body: "Hello world",
});

request.body; // ReadableStream
    bodyUsed 準備完了専用プロパティ。要求本体がまだ読み取られたかどうかを示すフラグ。
    許容値:
    • true:要求本文が読み取られました。
    • false:要求本文は読み取られていません。

    データタイプ：ブール

    		 
    const request = new Request("/myEndpoint", {
  method: "POST",
  body: "Hello world",
});

request.bodyUsed; // false

request.text().then((bodyAsText) => {
  console.log(request.bodyUsed); // true
});
    キャッシュ 準備完了専用プロパティ。要求がブラウザーの HTTP キャッシュとやり取りする方法を制御する要求のキャッシュモードが含まれています。
    許容値:
    • default:ブラウザーは HTTP キャッシュで一致する要求を検索します。
      • 一致があり、それが新しい場合は、キャッシュから返されます。
      • 一致するものが古い場合、ブラウザーはリモートサーバーに条件付き要求を行います。リソースが変更されていないことをサーバーが示した場合、リソースはキャッシュから返されます。それ以外の場合は、リソースがサーバーからダウンロードされ、キャッシュが更新されます。
      • 一致するものがない場合、ブラウザは通常の要求を行い、ダウンロードしたリソースでキャッシュを更新します。
    • force-cache:ブラウザーは HTTP キャッシュで一致する要求を探します。
      • 一致するもの (新規または古い) がある場合は、キャッシュから返されます。
      • 一致するものがない場合、ブラウザは通常の要求を行い、ダウンロードしたリソースでキャッシュを更新します。
    • no-cache:ブラウザーは HTTP キャッシュで一致する要求を探します。
      • 一致するもの (新規または古い) がある場合、ブラウザーはリモートサーバーに条件付き要求を行います。リソースが変更されていないことをサーバーが示した場合、リソースはキャッシュから返されます。それ以外の場合は、リソースがサーバーからダウンロードされ、キャッシュが更新されます。
      • 一致するものがない場合、ブラウザは通常の要求を行い、ダウンロードしたリソースでキャッシュを更新します。
    • no-store:ブラウザーは最初にキャッシュを調べずにリモートサーバーからリソースをフェッチし、ダウンロードしたリソースでキャッシュを更新しません。
    • only-if-cached:ブラウザーは HTTP キャッシュで一致する要求を検索します。
      • 一致するもの (新規または古い) がある場合は、キャッシュから返されます。
      • 一致するものがない場合、ブラウザーは 504 ゲートウェイタイムアウトステータスで応答します。

      キャッシュされた場合のみモードは、要求のモードが同一生成元の場合にのみ使用できます。要求の リダイレクト プロパティが フォロー され、リダイレクトが 同一オリジン モードに違反していない場合、キャッシュされたリダイレクトがフォローされます。

    • reload:ブラウザーは、最初にキャッシュを調べずにリモートサーバーからリソースをフェッチしますが、ダウンロードしたリソースでキャッシュを更新します。

    データタイプ：文字列

    		 
    // Download a resource with cache busting, to bypass the cache
// completely.
fetch("some.json", { cache: "no-store" }).then((response) => {
  /* consume the response */
});

// Download a resource with cache busting, but update the HTTP
// cache with the downloaded resource.
fetch("some.json", { cache: "reload" }).then((response) => {
  /* consume the response */
});

// Download a resource with cache busting when dealing with a
// properly configured server that will send the correct ETag
// and Date headers and properly handle If-Modified-Since and
// If-None-Match request headers, therefore we can rely on the
// validation to guarantee a fresh response.
fetch("some.json", { cache: "no-cache" }).then((response) => {
  /* consume the response */
});

// Download a resource with economics in mind! Prefer a cached
// albeit stale response to conserve as much bandwidth as possible.
fetch("some.json", { cache: "force-cache" }).then((response) => {
  /* consume the response */
});

// Naive stale-while-revalidate client-level implementation.
// Prefer a cached albeit stale response; but update if it's too old.
// AbortController and signal to allow better memory cleaning.
// In reality; this would be a function that takes a path and a
// reference to the controller since it would need to change the value
let controller = new AbortController();
fetch("some.json", {
  cache: "only-if-cached",
  mode: "same-origin",
  signal: controller.signal,
})
  .catch((e) =>
    e instanceof TypeError && e.message === "Failed to fetch"
      ? { status: 504 } // Workaround for chrome; which fails with a TypeError
      : Promise.reject(e),
  )
  .then((res) => {
    if (res.status === 504) {
      controller.abort();
      controller = new AbortController();
      return fetch("some.json", {
        cache: "force-cache",
        mode: "same-origin",
        signal: controller.signal,
      });
    }
    const date = res.headers.get("date"),
      dt = date ? new Date(date).getTime() : 0;
    if (dt < Date.now() - 86_400_000) {
      // if older than 24 hours
      controller.abort();
      controller = new AbortController();
      return fetch("some.json", {
        cache: "reload",
        mode: "same-origin",
        signal: controller.signal,
      });
    }

    // Other possible conditions
    if (dt < Date.now() - 300_000)
      // If it's older than 5 minutes
      fetch("some.json", { cache: "no-cache", mode: "same-origin" }); // no cancellation or return value.
    return res;
  })
  .then((response) => {
    /* consume the (possibly stale) response */
  })
  .catch((error) => {
    /* Can be an AbortError/DOMException or a TypeError */
  });
    認証情報 読み取り専用です。credentials オプションの Request() コンストラクターに指定された値を反映します。認証情報は、cookie、TLS クライアント証明書、またはユーザー名とパスワードを含む認証ヘッダーです。
    許容値:
    • include:クロスオリジン要求であっても、常に認証情報を含めます。
    • omit:要求で認証情報を送信しないか、応答に認証情報を含めません。
    • same-origin:同一生成元の要求に対してのみ認証情報を送信し、含めます。

    データタイプ：文字列

    		 
    const request = new Request("flowers.jpg");
const request = request.request; // returns "same-origin" by default
    宛先 読み取り専用です。要求されているコンテンツのタイプを説明する文字列を返します。
    許容値:
    • audio:対象はオーディオデータです。
    • audioworklet: ターゲットは、オーディオワークレットで使用するためにフェッチされるデータです。
    • document:ターゲットは HTML または XML ドキュメントです。
    • embed:タグは埋め込みコンテンツです。
    • fencedframe:ターゲットはフェンスされたフレームです。
    • font:対象はフォントです。
    • frame:ターゲットはフレームです。
    • iframe:ターゲットはiframeです。
    • image:ターゲットは画像です。
    • json:ターゲットは JSON ファイルです
    • マニフェスト:ターゲットはマニフェストです。
    • object:ターゲットはオブジェクトです。
    • paintworklet:ターゲットはペイントワークレットです。
    • report:ターゲットはレポートです。
    • script:ターゲットはスクリプトです。
    • sharedworker:ターゲットは共有ワーカーです。
    • style:ターゲットはスタイルです。
    • track:ターゲットは HTML <track>です。
    • video:対象はビデオデータです。
    • worker:ターゲットはワーカーです。
    • xslt: ターゲットは XSLT 変換です。

    データタイプ：文字列

    		 
    fetch('https://example.com/image.jpg', {
  destination: 'image'
})
  .then(response => response.blob())
  .then(blob => {
    console.log('Image fetched successfully', blob);
  })
  .catch(error => console.error('Error:', error));
    ヘッダー 読み取り専用です。要求に関連付けられたヘッダーオブジェクト。

    データタイプ:ヘッダーオブジェクト

    		 
    const myRequest = new Request("flowers.jpg");
const myHeaders = myRequest.headers; // Headers {}
    完全性 読み取り専用です。要求のサブリソース整合性値。

    値:要求の作成時に options.integrity 引数として渡された値。整合性が指定されていない場合、このプロパティは '' を返します。

    		 
    const myRequest = new Request("flowers.jpg", {
  integrity: "sha256-abc123",
});
console.log(myRequest.integrity); // "sha256-abc123"
    履歴ナビゲーション 読み取り専用です。要求が履歴ナビゲーションであるかどうかを示すブール値。
    許容値:
    • true:要求は履歴ナビゲーションです。
    • false:要求は履歴ナビゲーションではありません。

    データタイプ：ブール

    		 
    self.addEventListener("request", (event) => {
  // ...

  if (event.request.isHistoryNavigation) {
    event.respondWith(
      caches.match(event.request).then((response) => {
        if (response !== undefined) {
          return response;
        } else {
          return fetch(event.request).then((response) => {
            let responseClone = response.clone();

            caches.open("v1").then((cache) => {
              cache.put(event.request, responseClone);
            });

            return response;
          });
        }
      }),
    );
  }

  // ...
});
    キープアライブ 読み取り専用です。要求のキープアライブ設定 (true または false)。要求で整合性の値が渡されない場合は、空の文字列を返します。
    許容値:
    • true:要求が完了する前に要求を開始したページがアンロードされた場合、ブラウザーは関連する要求を存続させます。
    • false:要求が完了する前に、関連する要求を開始したページがアンロードされた場合、ブラウザーは関連する要求を存続させません。

    データタイプ：ブール

    		 
    const options = {
  keepalive: true,
};

const myRequest = new Request("flowers.jpg", options);
let myKeepAlive = myRequest.keepalive; // true
    メソッド 読み取り専用です。要求のメソッド (GET、 POST など)

    データタイプ：文字列

    		 
    const myRequest = new Request("flowers.jpg");
const myMethod = myRequest.method; // GET
    mode 読み取り専用です。要求のモード。クロスオリジン要求が有効な応答につながるかどうか、および応答のどのプロパティが読み取り可能であるかを判断するために使用されます。
    許容値:
    • cors: 要求がクロスオリジンである場合、クロスオリジンリソース共有 (CORS) メカニズムが使用されます。
    • navigate:ナビゲーションをサポートするためのモード。navigate 値は、HTML ナビゲーションでのみ使用することを意図しています。ナビゲート要求は、ドキュメント間を移動するときにのみ作成されます。
    • no-cors:クロスオリジン要求の CORS を無効にします。応答は不透明です。つまり、そのヘッダーと本文は JavaScript で使用できません。
    • same-origin:クロスオリジン要求を禁止します。このモードが設定された状態で別の送信元に要求が行われた場合、結果はエラーになります。

    要求はさまざまな方法で開始できますが、要求のモードは、要求が開始された特定の手段によって異なります。たとえば、 Request() コンストラクターを使用して Request オブジェクトが作成されると、その Request の mode プロパティの値が cors に設定されます。ただし、Request() 以外で作成された要求の場合は、 コンストラクタ、no-cors は通常モードとして使用されます。たとえば、要求がマークアップから開始される埋め込みリソースの場合、CrossOrigin 属性が存在しない限り、ほとんどの場合、要求は no-cors モード、つまり <link> または <script> elements (except when used with modules), or <img>, <audio>,<video>, <object>, <embed>, or <iframe> elements.

    データタイプ：文字列

    		 
    const myRequest = new Request("flowers.jpg");
const myMode = myRequest.mode; // returns "cors" by default
    リダイレクト 読み取り専用です。リダイレクトの処理方法のモード。
    有効な値：
    • エラー
    • フォロー
    • manual

    データタイプ：文字列

    デフォルト:フォロー

    		 
    const myRequest = new Request("flowers.jpg");
const myCred = myRequest.redirect;
    リファラー 読み取り専用です。要求のリファラー ( クライアント、 リファラーなし、URL など)。no-referrer の値は空の文字列を返します。

    データタイプ：文字列

    		 
    const myRequest = new Request("flowers.jpg");
const myReferrer = myRequest.referrer; // returns "about:client" by default
    リファラーポリシー 読み取り専用です。要求とともに Referrer ヘッダーに送信される Referrer 情報を管理する Referrer ポリシー。

    データタイプ：文字列

    		 
    const myRequest = new Request("flowers.jpg");
const myReferrer = myRequest.referrerPolicy; // returns "" by default
    シグナル 読み取り専用です。要求に関連付けられた AbortSignal。

    データタイプ：文字列

    		 
    // Create a new abort controller
const controller = new AbortController();

// Create a request with this controller's AbortSignal object
const req = new Request("/", { signal: controller.signal });

// Add an event handler logging a message in case of abort
req.signal.addEventListener("abort", () => {
  console.log("abort");
});

// In case of abort, log the AbortSignal reason, if any
fetch(req).catch(() => {
  if (req.signal.aborted) {
    if (req.signal.reason) {
      console.log(`Request aborted with reason: ${req.signal.reason}`);
    } else {
      console.log("Request aborted but no reason was given.");
    }
  } else {
    console.log("Request not aborted, but terminated abnormally.");
  }
});

// Actually abort the request
controller.abort();
    URL 読み取り専用です。要求の URL。

    データタイプ：文字列

    		 
    const myRequest = new Request("flowers.jpg");
const myURL = myRequest.url; // "https://github.com/mdn/dom-examples/tree/main/fetch/fetch-request/flowers.jpg"

    要求をフェッチ:request()

    新しい要求オブジェクトを作成します。オプションで、URL またはオブジェクトリソースから Request オブジェクトを作成します。

    表 : 2. パラメーター
    名前 タイプ 説明
    入力 文字列またはオブジェクト オプション。取得するリソース。

    有効な値：

    • フェッチするリソースの URL を含む文字列。API は、 http://user.password.example.com などの認証情報を含む URL を受け入れません。URL を解析できない場合は、例外がスローされます。
    • 既存の Request オブジェクトのコピーを効果的に作成する Request オブジェクト。オブジェクト構造は Request クラスによって指定されます。
      注:
      セキュリティを維持しながら、コンストラクターが例外をスローする可能性を低くするために、次の動作更新に注意してください。
      • このオブジェクトがコンストラクタ呼び出しの別の作成元に存在する場合、 Request.referrer プロパティは削除されます。
      • このオブジェクトに navigate の Request.mode プロパティがある場合、mode 値は same-origin に変換されます。
    オプション オブジェクト オプション。要求に適用するカスタム設定を含む RequestInit のフェッチ :スコープ対象、グローバル オブジェクト。既存の要求から新しい要求を作成する場合、新しい要求に設定されたオプションによって、元の要求の対応するオプションが上書きされます。

    デフォルト:すべてのプロパティのデフォルト値を返します。

    次の例は、 Request() コンストラクターを使用して新しい Request オブジェクトを作成する方法を示しています。

    var myImage = document.querySelector("img");
var myRequest = new Request("flowers.jpg");

    次の例は、入力パラメーターを使用して URL またはオブジェクトを取得する新しい Request オブジェクトを作成する方法を示しています。

    var myImage = document.querySelector("img");
var myRequest = new Request("flowers.jpg");

fetch(myRequest)
  .then((response) => response.blob())
  .then((response) => {
    var objectURL = URL.createObjectURL(response);
    myImage.src = objectURL;
  });

    次の例は、オブジェクトリテラルを使用して、ヘッダーオプションを持つ新しい Request オブジェクトを作成する方法を示しています。

    var myImage = document.querySelector("img");
var myRequest = new Request("flowers.jpg");

var options = {
  headers: {
    "Cache-Control": "max-age=60480",
  },
};

    要求をフェッチ:arrayBuffer()

    要求本文を読み取り、arrayBuffer で解決される Promise として返します。

    表 : 3. パラメーター
    名前 タイプ 説明
    なし
    表 : 4. 戻り値
    タイプ 説明
    Promise arrayBuffer で解決される Promise。

    arrayBuffer() メソッドを使用して新しいリクエストを作成する方法を以下に示します。

    var myArray = new Uint8Array(10);

var request = new Request("/myEndpoint", {
  method: "POST",
  body: myArray,
});

request.arrayBuffer().then((buffer) => {
  // perform an action with the buffer sent in the request
});

    要求をフェッチ:blob()

    要求本文を読み取り、Blob で解決される Promise として返します。

    表 : 5. パラメーター
    名前 タイプ 説明
    なし
    表 : 6. 戻り値
    タイプ 説明
    オブジェクト Blob で解決される Promise。

    次の例は、 blob() メソッドを使用して要求を形成する方法を示しています。

    var obj = { hello: "world" };
var myBlob = new Blob([JSON.stringify(obj, null, 2)], {
  type: "application/json",
});

var request = new Request("/myEndpoint", {
  method: "POST",
  body: myBlob,
});

request.blob().then((myBlob) => {
  // do something with the blob sent in the request
});

    要求をフェッチ:bytes()

    要求本文を読み取り、Uint8Array で解決される Promise として返します。

    表 : 7. パラメーター
    名前 タイプ 説明
    なし
    表 : 8. 戻り値
    タイプ 説明
    オブジェクト Uint8Array で解決される Promise。

    bytes() メソッドを使用して新しい要求を作成する方法を次に示します。

    var myArray = new Uint8Array(10);

var request = new Request("/myEndpoint", {
  method: "POST",
  body: myArray,
});

request.bytes().then((buffer) => {
  // do something with the buffer sent in the request
});

    要求をフェッチ:clone()

    現在の要求オブジェクトのコピーを作成します。

    表 : 9. パラメーター
    名前 タイプ 説明
    なし
    表 : 10. 戻り値
    タイプ 説明
    要求 clone() が呼び出された要求の正確なコピーである要求オブジェクト。clone() は、要求本体が既に使用されている場合、エラーをスローします。要求を変更する場合は、 要求をフェッチ:request() コンストラクターを使用します。

    次の例は、 request() を使用して新しい要求を作成し、 clone() を使用してそれをコピーする方法を示しています。

    var myRequest = new Request("flowers.jpg");
var newRequest = myRequest.clone(); // a copy of the request is now stored in newRequest

    要求をフェッチ:formData()

    要求本文を読み取り、FormData オブジェクトで解決される Promise として返します。

    表 : 11. パラメーター
    名前 タイプ 説明
    なし
    表 : 12. 戻り値
    タイプ 説明
    なし FormData オブジェクトで解決される Promise。

    次の例は、 request() を使用して新しいリクエストを作成し、formData() メソッドで解決して FormData オブジェクトとして解決する方法を示しています。

    var formData = new FormData();
var fileField = document.querySelector('input[type="file"]');

formData.append("username", "abc123");
formData.append("avatar", fileField.files[0]);

var request = new Request("/myEndpoint", {
  method: "POST",
  body: formData,
});

request.formData().then((data) => {
  // do something with the formdata sent in the request
});

    要求をフェッチ:json()

    要求本文を読み取り、コンテンツを JSON として解析して、解析された結果で解決される promise を返します。

    表 : 13. パラメーター
    名前 タイプ 説明
    なし
    表 : 14. 戻り値
    タイプ 説明
    オブジェクト JavaScript オブジェクトに解決される promise (非同期操作の最終的な完了または失敗とその結果の値)。このオブジェクトは、オブジェクト、アレイ、文字列、数値など、JSON で表すことができるものであれば何でもかまいません。

    次の例は、 request() と json() を使用して新しい要求を作成し、要求を解析して JSON オブジェクトとして返す方法を示しています。

    var obj = { hello: "world" };

var request = new Request("/myEndpoint", {
  method: "POST",
  body: JSON.stringify(obj),
});

request.json().then((data) => {
  // process the data sent in the request
});

    要求をフェッチ:text()

    要求本文を読み取り、UTF-8 を使用してデコードされた文字列で解決される Promise として返します。

    表 : 15. パラメーター
    名前 タイプ 説明
    なし
    表 : 16. 戻り値
    タイプ 説明
    なし UTF-8 形式の文字列で解決される Promise です。

    この例は、 text() を呼び出す方法を示しています。

    var text = "Hello world";

var request = new Request("/myEndpoint", {
  method: "POST",
  body: text,
});

request.text().then((text) => {
  // process the data sent in the request
});