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

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

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

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

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

    要求プロパティ

    Fetch Request API は、HTTP 要求に関する詳細情報を提供するいくつかの読み取り専用プロパティをサポートしています。これらのいくつかには、 url (リクエストの URL)、 メソッド (HTTP メソッド)、 ヘッダー (関連するヘッダー)、 本文 (ストリームとしてのリクエスト本文) が含まれます。その他のプロパティには、キャッシュ、認証情報、およびリファラーの設定が含まれます。これらのプロパティは読み取り専用です。つまり、要求の作成後はアクセスできますが、変更することはできません。各プロパティの詳細については、「 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 ゲートウェイタイムアウトステータスで応答します。

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

    • 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 */
  });
    認証情報 読み取り専用です。認証情報オプションの Request() コンストラクターに指定された値を反映します。認証情報は、Cookie、TLS クライアント証明書、またはユーザー名とパスワードを含む認証ヘッダーです。
    指定できる値:
    • include:クロスオリジン要求の場合でも、常に認証情報を含めます。
    • 省略:要求で認証情報を送信したり、応答に認証情報を含めたりしません。
    • same-origin:同一オリジン要求の認証情報のみを送信して含めます。

    データタイプ：文字列

    		 
    const request = new Request("flowers.jpg");
const request = request.request; // returns "same-origin" by default
    宛先 読み取り専用です。要求されているコンテンツのタイプを説明する文字列を返します。
    指定できる値:
    • audio:対象は音声データです。
    • audioworklet:ターゲットは、オーディオワークレットで使用するためにフェッチされるデータです。
    • document:ターゲットは HTML または XML ドキュメントです。
    • embed: taget は埋め込みコンテンツです。
    • fencedframe: ターゲットはフェンスで囲まれたフレームです。
    • font:ターゲットはフォントです。
    • frame:ターゲットはフレームです。
    • iframe:ターゲットは iframe です。
    • image:ターゲットはイメージです。
    • json:ターゲットは JSON ファイルです
    • manifest:ターゲットはマニフェストです。
    • オブジェクト:ターゲットはオブジェクトです。
    • paintworklet: ターゲットはペイント作業letです。
    • report:ターゲットはレポートです。
    • スクリプト:ターゲットはスクリプトです。
    • 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));
    ヘッダー 読み取り専用です。要求に関連付けられたヘッダーオブジェクト。

    データタイプ:Headers オブジェクト

    		 
    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"
    isHistoryNavigation 読み取り専用です。要求が履歴ナビゲーションであるかどうかを示すブール値。
    指定できる値:
    • 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()以外で作成されたリクエストの場合 constructor、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
    redirect 読み取り専用です。リダイレクトの処理方法のモード。
    有効な値：
    • エラー
    • 従う
    • manual

    データタイプ：文字列

    デフォルト:フォロー

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

    データタイプ：文字列

    		 
    const myRequest = new Request("flowers.jpg");
const myReferrer = myRequest.referrer; // returns "about:client" by default
    referrerPolicy 読み取り専用です。要求とともに 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 またはオブジェクトリソースから要求オブジェクトを作成します。

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

    有効な値：

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

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

    表 : 9. パラメーター
    名前 タイプ 説明
    なし
    表 : 10. 返される内容
    タイプ 説明
    要求 clone() が呼び出された要求の正確なコピーである Request オブジェクト。要求本文が既に使用されている場合、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
});