fetch()
は WindowOrWorkerGlobalScope
ミックスインのメソッドで、ネットワークからリソースを取得するプロセスを開始し、レスポンスが利用できるようになったら満足するプロミスを返します。このプロミスはリクエストに対するレスポンスを表す Response
で解決します。プロミスは HTTP エラーでは拒否されず、ネットワークエラーでのみ拒否されます。 HTTP エラーをチェックするには、 then
ハンドラーを使用する必要があります。
WindowOrWorkerGlobalScope
は Window
と WorkerGlobalScope
の両方で実装されています。これはつまり fetch()
メソッドはあなたがリソースを取得したいと思うような大部分コンテキストで使用可能ということです。
fetch()
のプロミスはネットワークエラーが発生した場合 (すなわち普通はパーミッション問題などがあったとき) のみ拒否されます。 fetch()
のプロミスは HTTP エラー (404
など) では拒否されません。代わりに、 then()
ハンドラーで Response.ok
や Response.status
プロパティをチェックする必要があります。
fetch()
メソッドは取得するリソースのディレクティブではなく Content Security Policy の connect-src
ディレクティブによって制御されます。
注: fetch()
メソッドの引数は Request()
コンストラクターと全く同じです。
構文
const fetchResponsePromise = fetch(resource [, init])
引数
resource
- 取得したいリソースを定義します。以下の 2 つが使用出来ます。
init
省略可-
リクエストに適用したいカスタム設定を含むオブジェクト。可能なオプションは以下の通りです。
method
- リクエストするメソッド、
GET
、POST
など。なお、Origin
ヘッダーはHEAD
またはGET
メソッドの読み取りリクエストでは設定されません。
(この動作は Firefox 65 で修正されました — バグ 1508661 を参照) headers
- リクエストに追加したいヘッダーで、
Headers
オブジェクトかByteString
値を持つオブジェクトリテラルで指定してください。なお、一部の名前は禁止されています。 body
- リクエストに追加したい本文です。これには
Blob
,BufferSource
,FormData
,URLSearchParams
,USVString
,ReadableStream
オブジェクトなどが使用できます。メソッドがGET
やHEAD
の場合使用できないので注意してください。 mode
- リクエストで使いたいモードです。例:
cors
,no-cors
,same-origin
credentials
- リクエストに使用したいリクエスト認証情報、
omit
,same-origin
,include
です。現在のドメインの Cookie を自動で送るためにはこのオプションを指定する必要があります。 Chrome 50 から、このプロパティはFederatedCredential
インスタンスやPasswordCredential
インスタンスを受け付けるようになりました。 cache
- 使用したいリクエストのキャッシュモードです。
redirect
- 使用するリダイレクトモードです。
follow
(自動でリダイレクトに従う)、error
(リダイレクトが起こった場合エラーを伴って中止する)、manual
(手動でリダイレクトを処理する)。Chrome の既定値はfollow
です (バージョン 47 より前の既定値はmanual
でした)。 referrer
USVString
でリクエストのリファラーを指定します。これは同じオリジンの URL、about:client
、空文字列のいずれかを取ることができます。referrerPolicy
- リクエストで使用するリファラーポリシーを指定します。使用可能な値は、
no-referrer
,no-referrer-when-downgrade
,same-origin
,origin
,strict-origin
,origin-when-cross-origin
,strict-origin-when-cross-origin
, orunsafe-url
のいずれかです。 integrity
- リソースに subresource integrity 値を含ませることが出来ます (例:
sha256-BpfBw7ivV8q2jLiT13fxDYAe2tJllusRSZ273h2nFSE=
)。 keepalive
keepalive
オプションはページより長生きするリクエストを許可するのに使われます。keepalive
フラグつきの Fetch はNavigator.sendBeacon()
API の置き換えです。signal
AbortSignal
オブジェクトのインスタンスです。つまりAbortController
経由で fetch リクエストと通信したり望む場合には中止したりできます。
返値
例外
AbortError
AbortController
メソッドまたはabort()
メソッドの呼び出しによりリクエストが中止された。TypeError
- 指定された URL がユーザー認証情報を含んでいる。この情報は
Authorization
ヘッダーを用いて提供するべきです。
例
Fetch Request example リポジトリ (デモ: Fetch Request live) では Request
オブジェクトを関連するコンストラクターを使って作成しています。その後 fetch()
を呼んで取得しています。画像を fetch している時から適切な MIME タイプを与えるために response の Body.blob
を実行し、適切に処理されます。そして ObjectURL を作成し <img>
要素に追加して表示させています。
const myImage = document.querySelector('img');
let myRequest = new Request('flowers.jpg');
fetch(myRequest)
.then(function(response) {
if (!response.ok) {
throw new Error(`HTTP error! status: ${response.status}`);
}
return response.blob();
})
.then(function(response) {
let objectURL = URL.createObjectURL(response);
myImage.src = objectURL;
});
Fetch with init then Request example リポジトリ (デモ: Fetch Request init live) では上記の内容に加えて、fetch()
を呼び出すとき、初期化オブジェクト init
を渡しています。
const myImage = document.querySelector('img');
let myHeaders = new Headers();
myHeaders.append('Content-Type', 'image/jpeg');
const myInit = {
method: 'GET',
headers: myHeaders,
mode: 'cors',
cache: 'default'
};
let myRequest = new Request('flowers.jpg');
fetch(myRequest, myInit).then(function(response) {
// ...
});
同様に init
オブジェクトを Request
コンストラクターに渡しても、同じ効果が得られます。
let myRequest = new Request('flowers.jpg', myInit);
init
の init
としてオブジェクトリテラルを使用することもできます。
const myInit = {
method: 'GET',
headers: {
'Content-Type': 'image/jpeg'
},
mode: 'cors',
cache: 'default'
};
let myRequest = new Request('flowers.jpg', myInit);
仕様書
仕様書 | 状態 | 備考 |
---|---|---|
Fetch fetch() の定義 |
現行の標準 | 最新の仕様では WindowOrWorkerGlobalScope の中で部分的に定義。 |
Fetch fetch() の定義 |
現行の標準 | 初回定義 |
Credential Management Level 1 | 草案 | FederatedCredential または PasswordCredential のインスタンスを init.credentials の値として追加。 |
ブラウザーの互換性
BCD tables only load in the browser