fetch() グローバル関数
===============

**`fetch()`** はグローバルのメソッドで、ネットワークからリソースを取得するプロセスを開始し、レスポンスが利用できるようになったら履行されるプロミスを返します。

このプロミスはそのリクエストに対するレスポンスを表す `Response` で解決します。

`fetch()` のプロミスはネットワークエラーが発生した場合（普通は権限の問題があったときなど）のみ拒否されます。 `fetch()` のプロミスは HTTP エラー（`404` など）では拒否*されません*。代わりに、 `then()` ハンドラーで `Response.ok` や `Response.status` プロパティをチェックする必要があります。

`WindowOrWorkerGlobalScope` は `Window` と `WorkerGlobalScope` の両方で実装されています。これはつまり `fetch()` メソッドは、リソースを取得したいと思うような大部分コンテキストで使用可能ということです。

`fetch()` メソッドは取得するリソースのディレクティブではなく、コンテンツセキュリティポリシーの `connect-src` ディレクティブによって制御されます。

**メモ:** `fetch()` メソッドの引数は `Request()` コンストラクターと全く同じです。

構文
--


```js
fetch(resource)
fetch(resource, options)
```

### 引数

`resource`

取得したいリソースを定義します。以下のどちらかが使用できます。

* 文字列または文字列化できるその他のオブジェクト（`URL` オブジェクトを含む）。取得したいリソースの直接の URL を含む文字列です。
* `Request` オブジェクト。

`options` 省略可

リクエストに適用したいカスタム設定を含むオブジェクト。可能なオプションは以下の通りです。

`method`

 リクエストするメソッド、`"GET"`、`"POST"` など。既定値は `"GET"` です。
 なお、 `Origin` ヘッダーは `HEAD` または `GET` メソッドの読み取りリクエストでは設定されません。
 (この動作は Firefox 65 で修正されました。 Firefox バグ 1508661 を参照)
 RFC 9110 のメソッドのいずれかと大文字小文字を区別せずに照合する文字列は、自動的に大文字になります。
 （`PATCH` のような）カスタムメソッドを使用したい場合は、自分で大文字にする必要があります。


`headers`

 リクエストに追加したいヘッダーで、 `Headers` オブジェクトまたは `String` 値を持つオブジェクトリテラルで指定してください。
 なお、一部の名前は禁止されています。


**メモ:** HTTP の `Authorization` ヘッダーがリクエストに追加される場合がありますが、そのリクエストがオリジン間でリダイレクトされた場合は削除されます。

`body`

リクエストに追加したい本体です。これには `Blob`, `ArrayBuffer`, `TypedArray`, `DataView`, `FormData`, `URLSearchParams`, 文字列オブジェクトまたはリテラル、 `ReadableStream` オブジェクトなどが使用できます。これは最新の利用可能状況で、まだ実験的なものです。互換性情報を調べて、あなたがこれを使用できるかどうかを確認してください。メソッドが `GET` や `HEAD` の場合は使用できないので注意してください。

`mode`

リクエストで使用するモードです。例えば `cors`、`no-cors`、`same-origin` などです。

`credentials`

ブラウザーが資格情報を使用して何を行うか（クッキー、 HTTP 認証項目、 TLS クライアント証明書）を制御します。以下の文字列のうちの何れかでなければなりません。

`omit`

リクエストから資格情報を除外し、レスポンスで返される資格情報（`Set-Cookie` ヘッダーなど）を無視するようブラウザーに指示します。

`same-origin`

同一オリジンの URL へのリクエストに資格情報を記載し、同一オリジンの URL からのレスポンスで送り返されるすべての資格情報を使用するようブラウザーに指示します。**これが既定値です。**

`include`

ブラウザーに、同一オリジンおよびオリジン間リクエストの両方に資格情報を記載し、レスポンスで送り返された資格情報を常に使用するように指示します。

**メモ:** 資格情報は単純な、そして「最終的な」オリジン間リクエストに記載することができますが、 CORS プリフライトリクエストには記載されるべきではありません。



`cache`

文字列で、このリクエストがブラウザーの HTTP キャッシュにどう作用するかを示します。利用可能な値は `default`, `no-store`, `reload`, `no-cache`, `force-cache`, `only-if-cached` で、 `Request` オブジェクトの `cache` プロパティの記事に記述されています。

`redirect`

リダイレクトレスポンスを取り扱う方法を示します。

`follow`

自動的にリダイレクトを行います。他の方法が指定されていない限り、リダイレクトモードは `follow` に設定されます。

`error`

リダイレクトが発生した場合は、エラーで中止します。

`manual`

 呼び出し側は、レスポンスを別のコンテキストで処理する予定です。
 詳しくは WHATWG fetch standard を参照してください。



`referrer`

文字列で、リクエストのリファラーを指定します。これは同じオリジンの URL、 `about:client`、空文字列のいずれかを取ることができます。

`referrerPolicy`

リクエストで使用するリファラーポリシーを指定します。使用可能な値は、 `no-referrer`, `no-referrer-when-downgrade`, `same-origin`, `origin`, `strict-origin`, `origin-when-cross-origin`, `strict-origin-when-cross-origin`, `unsafe-url` のいずれかです。

`integrity`

リクエストのサブリソース完全性の値を保持します（`sha256-BpfBw7ivV8q2jLiT13fxDYAe2tJllusRSZ273h2nFSE=` など）。

`keepalive`

`keepalive` オプションは、ページの終了後のリクエストを許可するのに使用されます。 `keepalive` フラグつきのフェッチは `Navigator.sendBeacon()` API の置き換えです。

`signal`

`AbortSignal` オブジェクトのインスタンスです。つまり `AbortController` 経由でフェッチリクエストと通信したり望む場合には中止したりできます。

`priority`

同じ種類の他のリクエストに対する、この読み込みリクエストの優先度を指定します。以下の文字列のいずれかでなければなりません。

`high`

同じ種類の他のリクエストに対する優先度の高いフェッチリクエスト。

`low`

同じ種類の他のリクエストと相対した、優先度の低いフェッチリクエスト。

`auto`

同じ種類の他のリクエストに対するフェッチリクエストの優先度を自動的に決定します（既定値）。


### 返値

`Promise` で、 `Response` オブジェクトに解決します。

### 例外

`AbortError` `DOMException`

`AbortController` の `abort()` メソッドの呼び出しによりリクエストが中止された。

`TypeError`

以下の理由で発生します。



| 理由 | 失敗する例 |
| --- | --- |
| ヘッダー名が無効である。 | 
```
// "C ontent-Type" に空白がある
const headers = {
  'C ontent-Type': 'text/xml',
  'Breaking-Bad': '<3',
};
fetch('https://example.com/', { headers });
        
```
 |
| ヘッダーの値が無効である。ヘッダーオブジェクトは正確に 2 つの要素を含まなければなならない。 | 
```
const headers = [
  ['Content-Type', 'text/html', 'extra'],
  ['Accept'],
];
fetch('https://example.com/', { headers });
        
```
 |
| URLまたはスキームが無効であるか、フェッチが対応していないスキームを使用しているか、または特定のリクエストモードに対応していないスキームを使用している。 | 
```
fetch('blob://example.com/', { mode: 'cors' });
        
```
 |
| URL に資格情報が入っている。 | 
```
fetch('https://user:password@example.com/');
        
```
 |
| リファラー URL が不正である。 | 
```
fetch('https://example.com/', { referrer: './abc\u0000df' });
        
```
 |
| モードが不正（`navigate` や `websocket`）。 | 
```
fetch('https://example.com/', { mode: 'navigate' });
        
```
 |
| リクエストキャッシュモードが "only-if-cached" で、かつリクエストモードが "same-origin" 以外の場合。 | 
```
fetch('https://example.com/', {
  cache: 'only-if-cached',
  mode: 'no-cors',
});
        
```
 |
| リクエストメソッドが無効な名前トークンである場合、または禁止されたヘッダー（`'CONNECT'`, `'TRACE'`, `'TRACK'`）の 1 つである場合。 | 
```
fetch('https://example.com/', { method: 'CONNECT' });
        
```
 |
| リクエストモードが "no-cors" であり、リクエストメソッドが CORS-safe に掲載されているメソッド（`'GET'`, `'HEAD'`, `'POST'`）でない場合。 | 
```
fetch('https://example.com/', {
  method: 'CONNECT',
  mode: 'no-cors',
});
        
```
 |
| リクエストメソッドが `'GET'` または `'HEAD'` で、本体が null でないか、 undefined でない場合。 | 
```
fetch('https://example.com/', {
  method: 'GET',
  body: new FormData(),
});
        
```
 |
| fetch がネットワークエラーを発生した場合。 |  |

例
-

Fetch Request の例（Fetch Request のライブ版を参照）では、 `Request` オブジェクトを関連するコンストラクターで作成しています。その後で `fetch()` を呼び出して取得しています。画像を読み取っているため、レスポンスで `Response.blob()` を実行して正しい MIME タイプを指定して正しく扱われるようにし、オブジェクト URL を作成して `<img>` 要素に追加して表示させています。


```js
const myImage = document.querySelector("img");

const myRequest = new Request("flowers.jpg");

fetch(myRequest)
  .then((response) => {
    if (!response.ok) {
      throw new Error(`HTTP error! Status: ${response.status}`);
    }

    return response.blob();
  })
  .then((response) => {
    myImage.src = URL.createObjectURL(response);
  });
```


Fetch with init then Request の例（Fetch Request init のライブ版) では上記の内容に加えて、`fetch()` を呼び出すとき、初期化オブジェクト `init` を渡しています。


```js
const myImage = document.querySelector("img");

const myHeaders = new Headers();
myHeaders.append("Accept", "image/jpeg");

const myInit = {
  method: "GET",
  headers: myHeaders,
  mode: "cors",
  cache: "default",
};

const myRequest = new Request("flowers.jpg");

fetch(myRequest, myInit).then((response) => {
  // …
});
```


同様に `init` オブジェクトを `Request` コンストラクターに渡しても、同じ効果が得られます。


```js
const myRequest = new Request("flowers.jpg", myInit);
```


`init` の `headers` でオブジェクトリテラルを使用することもできます。


```js
const myInit = {
  method: "GET",
  headers: {
    Accept: "image/jpeg",
  },
  mode: "cors",
  cache: "default",
};

const myRequest = new Request("flowers.jpg", myInit);
```

仕様書
---

| Specification |
| --- |
| Fetch Standard # fetch-method |

ブラウザーの互換性
---------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

関連情報
----

* フェッチ API
* サービスワーカー API
* HTTP アクセス制御 (CORS)
* HTTP