Fetch API

Fetch API — интерфейс для работы с HTTP-запросами и ответами, предоставляет возможность взаимодействия с веб-сервисами, ресурсами сети непосредственно из узла JavaScript.

Интерфейс Fetch API включает в себя следующие объекты:

• Headers — заголовки запроса/ответа;
• Request — запрос ресурса сети;
• Response — ответ на запрос;
• AbortController — управление отменой запроса;
• fetch() — функция, используемая для получения ресурсов сети.

Перед использованием вышеуказанные объекты должны быть импортированы из встроенного модуля builtIn/Fetch:

import {fetch, Request, Response, Headers, AbortController} from "builtIn/Fetch";

Также доступен объект AbortSignal. Он предоставляется через свойство signal экземпляра AbortController и отдельно не импортируется.

Примечание: у объектов Request и Response отсутствует часть методов и свойств, стандартных для браузеров. Полный перечень см. в Полное описание API, а также в описании ниже.

Описание объектов

Headers

Представляет итерируемую коллекцию HTTP-заголовков. Методы объекта позволяют получать, устанавливать, добавлять и удалять заголовки из коллекции заголовков запроса.

Конструктор

let headers = new Headers([init]);

где:

• init принимает объект типа HeadersInit (см. Полное описание API). Необязательный параметр.

Создает объект Headers(см. Полное описание API).

Методы Headers

Request

Представляет собой HTTP-запрос.

Конструктор

let request = new Request(input[, init]);

где:

• input — объект типа RequestInfo (см. Полное описание API). Обязательный параметр. Принимает URL-адрес запрашиваемого ресурса или объект, реализующий интерфейс Request.
• init — объект, реализующий интерфейс RequestInit (см. Полное описание API). Необязательный параметр. Принимает параметры HTTP-запроса. init-объект может содержать следующие параметры:
  • body — тело HTTP-запроса. Объект типа BodyInit (см. Полное описание API). body может быть строкой или объектом типов ArrayBuffer, ArrayBufferView.
  • headers — заголовки HTTP-запроса. headers-объект (см. также Полное описание API).
  • method — строка, содержащая метод HTTP-запроса (get, post и т.д.).
  • redirect — строка, содержащая режим обработки перенаправлений (follow, error, manual).
  • signal — объект AbortSignal, используемый для досрочной отмены запроса.

Создает объект Request (см. Полное описание API).

Особенности реализации

Разрешена установка HTTP-заголовков Cookie и Cookie2.

Свойства Request

Методы Request

Response

Представляет собой ответ на HTTP-запрос.

Конструктор

Можно создать новый Response-объект с помощью конструктора, но на практике скорее всего встретится объект, возвращаемый функцией fetch().

let response = new Response([body][, init]);

где:

• body принимает объект типа BodyInit (см. Полное описание API) или null. Необязательный параметр.
• init принимает объект, реализующий интерфейс ResponseInit (см. Полное описание API). Необязательный параметр.

Создает объект Response (см. Полное описание API).

Особенности реализации

Разрешены заголовки Set-Cookie и Set-Cookie2 для использования совместно с заголовками Cookie и Cookie2 запроса.

Свойства Response

Методы Response

AbortController

Предназначен для досрочной отмены HTTP-запроса, выполняемого функцией fetch().

Конструктор

let controller = new AbortController();

Создает объект AbortController и связанный с ним сигнал отмены.

Свойства AbortController

Методы AbortController

{
    name: "AbortError",
    message: "signal is aborted without reason"
}

AbortSignal

Содержит состояние и причину отмены запроса. Объект AbortSignal получают через свойство signal экземпляра AbortController.

Свойства AbortSignal

Методы AbortSignal

fetch()

fetch(resource[, init]), где

• resource — принимает объект, реализующий интерфейс Request, или строку, содержащую URL запроса. Обязательный параметр.
• init — принимает объект, реализующий интерфейс RequestInit (см. Полное описание API). Необязательный параметр.

Асинхронная функция fetch запускает процесс извлечения ресурса из сети, возвращая promise объекта Response (см. Полное описание API).

В параметре init.signal можно передать объект AbortSignal. Если сигнал уже отменен или отменяется во время выполнения запроса, promise функции fetch() переходит в отклоненное состояние с причиной, содержащейся в свойстве signal.reason.

Функция fetch() не ограничивает ожидание ответа собственным фиксированным тайм-аутом. Для ограничения времени запроса используется AbortController совместно с функцией setTimeout() (см. пример Ограничение времени выполнения запроса).

Примеры

Использование Fetch API

import {fetch, Request, Headers} from "builtIn/Fetch";

// Создание объекта заголовков запроса:
let headers = new Headers({"Content-Type": "text/html", "Custom-Header": "delete me"})
// Вывод значения заголовка
console.log("Custom-Header: ", headers.get("Custom-Header"))
// Удаление заголовка
headers.delete("Custom-Header") 
// Проверка существования заголовка
console.log(headers.has('Custom-Header')); 
// Добавление нового заголовка
headers.append("Accept-Charset", "utf-8")
// Изменение значения заголовка
headers.set("Content-Type", "application/json")

// Создание объекта запроса:
let request = new Request("http://httpbin.org/post", { 
    method: "post", 
    headers: headers,
    body: "{ \"str\": message }",
    redirect: "follow"
});

// Вывод параметров запроса:
console.log("url: " + request.url);
console.log("bodyUsed: " + request.bodyUsed);
console.log("redirect: " + request.redirect);
console.log("method: " + request.method);
for (let header of headers.entries()) {
    console.log(header[0]+ ': '+ header[1]);
}

// Вызов сервиса httpbin.org и вывод параметров ответа:
fetch(request)
    .then(response => {
        console.log("ok: " + response.ok);
        console.log("status: " + response.status);
        console.log("statusText: " + response.statusText);
        console.log("redirected: " + response.redirected);
        console.log("url: " + response.url);
        headers.forEach(function(value, key) {
            console.log("Name : ", key, " Value : ", value)
        });
        response.text().then(text => console.log(text));
    }).catch(e => console.log(e));

Получение курсов валют ЦБ РФ

import {fetch} from "builtIn/Fetch";

// Запрос сервиса ЦБ:
fetch("https://www.cbr-xml-daily.ru/daily_json.js")
    .then(response => {
        if (!response.ok) {
            throw new Error(`HTTP error! status: ${response.status}, 
                            statusText: ${response.statusText}`);
        }
        return response.json();
    })
    .then(json => console.log(JSON.stringify(json)))
    .catch(e => console.log(e));

Последовательное выполнение запросов

import {fetch, Headers} from "builtIn/Fetch";

(async() => {
    try {
        // Запрос 1-ого сервиса
        let response1 = await fetch('https://jsonplaceholder.typicode.com/posts', {
            method: 'POST',
            body: JSON.stringify({
                title: "foo",
                body: "bar",
                userId: 1,
            }),
            headers: new Headers({"Content-type": "application/json; charset=UTF-8"}),
        });
        let payload = await response1.arrayBuffer();

        // Запрос 2-ого сервиса
        let response2 = await fetch('http://httpbin.org/post', {
            method: 'POST',
            headers: new Headers({"Content-Type": "application/json",
                                  "Accept-Charset": "utf-8"}),
            body: payload,
        });
        console.log(await response2.text())        
    } catch(e) {
        console.log(e);
    }
})()

Ограничение времени выполнения запроса

В следующем примере запрос к сервису с задержкой ответа отменяется через три секунды:

import {fetch, AbortController} from "builtIn/Fetch";

(async() => {
    let controller = new AbortController();

    // По истечении трех секунд переводим сигнал в состояние отмены.
    let timeoutId = setTimeout(function() {
        controller.abort();
    }, 3000);

    try {
        let response = await fetch("https://httpbin.org/delay/10", {
            signal: controller.signal
        });

        if (!response.ok) {
            throw new Error(`HTTP error! status: ${response.status},
                            statusText: ${response.statusText}`);
        }

        console.log(await response.text());
    } catch(error) {
        // Проверяем, что ошибка вызвана отменой именно этого запроса.
        if (error && error.name === "AbortError") {
            console.log("Превышено допустимое время выполнения запроса");
        } else {
            throw error;
        }
    } finally {
        // Если запрос завершился раньше, запланированная отмена не нужна.
        clearTimeout(timeoutId);
    }
})()