Улучшить эту документацию Просмотреть исходный код $http

Обзор

Сервис $http — это основной сервис AngularJS, который обеспечивает взаимодействие с удалёнными HTTP-серверами через объект XMLHttpRequest браузера или через JSONP.

Для тестирования приложений, использующих сервис $http, см. $httpBackend mock.

Для более высокого уровня абстракции, ознакомьтесь со службой $resource.

API $http основан на API отложенных задач/обещаний, предоставленных службой $q. Хотя для простых сценариев использования это не имеет большого значения, для продвинутых сценариев важно ознакомиться с этими API и предоставляемыми ими гарантиями.

Общее использование

Сервис $http — это функция, которая принимает один аргумент — объект конфигурации, используемый для генерации HTTP-запроса, и возвращает обещание, которое выполняется (успех запроса) или отклоняется (ошибка запроса) с объектом ответа.

// Simple GET request example:
$http({
  method: 'GET',
  url: '/someUrl'
}).then(function successCallback(response) {
    // this callback will be called asynchronously
    // when the response is available
  }, function errorCallback(response) {
    // called asynchronously if an error occurs
    // or server returns response with an error status.
  });

Методы сокращённого доступа

Также доступны методы сокращённого доступа. Все методы сокращённого доступа требуют указания URL, а данные запроса должны быть переданы для запросов POST/PUT. В качестве последнего аргумента можно передать необязательную конфигурацию.

$http.get('/someUrl', config).then(successCallback, errorCallback);
$http.post('/someUrl', data, config).then(successCallback, errorCallback);

Полный список методов сокращённого доступа:

• $http.get
• $http.head
• $http.post
• $http.put
• $http.delete
• $http.jsonp
• $http.patch

Написание юнит-тестов, использующих $http

При написании юнит-тестов (с использованием ngMock) необходимо вызвать $httpBackend.flush() для обработки каждого ожидающего запроса с использованием обученных ответов.

$httpBackend.expectGET(...);
$http.get(...);
$httpBackend.flush();

Установка HTTP-заголовков

Сервис $http автоматически добавляет определённые HTTP-заголовки ко всем запросам. Эти значения по умолчанию можно полностью настроить, обратившись к объекту конфигурации $httpProvider.defaults.headers, который в настоящее время содержит эту конфигурацию по умолчанию:

• $httpProvider.defaults.headers.common (заголовки, общие для всех запросов):
  • Accept: application/json, text/plain, */*
• $httpProvider.defaults.headers.post: (заголовки по умолчанию для запросов POST)
  • Content-Type: application/json
• $httpProvider.defaults.headers.put (заголовки по умолчанию для запросов PUT)
  • Content-Type: application/json

Для добавления или перезаписи этих значений по умолчанию просто добавьте или удалите свойство из этих объектов конфигурации. Для добавления заголовков для метода HTTP, отличного от POST или PUT, просто добавьте новый объект с именем метода HTTP в нижнем регистре в качестве ключа, например $httpProvider.defaults.headers.get = { 'My-Header' : 'value' }.

Значения по умолчанию также можно установить во время выполнения через объект $http.defaults аналогичным образом. Например:

module.run(function($http) {
  $http.defaults.headers.common.Authorization = 'Basic YmVlcDpib29w';
});

Кроме того, вы можете указать свойство headers в объекте конфигурации, переданном при вызове $http(config), которое переопределяет значения по умолчанию без глобальных изменений.

Для явного удаления заголовка, автоматически добавленного через $httpProvider.defaults.headers в рамках отдельного запроса, используйте свойство headers, установив желаемый заголовок в значение undefined. Например:

var req = {
 method: 'POST',
 url: 'http://example.com',
 headers: {
   'Content-Type': undefined
 },
 data: { test: 'test' }
}

$http(req).then(function(){...}, function(){...});

Преобразование запросов и ответов

И запросы, и ответы можно преобразовывать с помощью функций преобразования: transformRequest и transformResponse. Эти свойства могут быть одиночной функцией, возвращающей преобразованное значение (function(data, headersGetter, status)) или массивом таких функций преобразования, что позволяет вам push или unshift новую функцию преобразования в цепочку преобразования.

Преобразования по умолчанию

Поставщик $httpProvider и служба $http экспонируют свойства defaults.transformRequest и defaults.transformResponse. Если запрос не предоставляет собственных преобразований, будут применены эти преобразования.

Можно дополнить или заменить преобразования по умолчанию, изменив эти свойства, добавив или заменив массив.

AngularJS предоставляет следующие преобразования по умолчанию:

Преобразования запросов ($httpProvider.defaults.transformRequest и $http.defaults.transformRequest) — это массив с одной функцией, которая выполняет следующее:

• Если свойство data объекта конфигурации запроса содержит объект, сериализуйте его в формате JSON.

Преобразования ответов ($httpProvider.defaults.transformResponse и $http.defaults.transformResponse) — это массив с одной функцией, которая выполняет следующее:

• Если обнаружен префикс XSRF, удалите его (см. раздел "Учёт мер безопасности" ниже).
• Если Content-Type равно application/json или ответ похож на JSON, десериализуйте его с помощью парсера JSON.

Переопределение преобразований по умолчанию для каждого запроса

Если вы хотите переопределить преобразования запросов/ответов только для одного запроса, укажите свойства transformRequest и/или transformResponse в объекте конфигурации, переданном в $http.

Обратите внимание, что если вы укажете эти свойства в объекте конфигурации, преобразования по умолчанию будут переопределены. Если вы хотите дополнить преобразования по умолчанию, необходимо включить их в ваш локальный массив преобразований.

Следующий код демонстрирует добавление нового преобразования ответа, которое будет выполнено после выполнения стандартных преобразований ответа.

function appendTransform(defaults, transform) {

  // We can't guarantee that the default transformation is an array
  defaults = angular.isArray(defaults) ? defaults : [defaults];

  // Append the new transformation to the defaults
  return defaults.concat(transform);
}

$http({
  url: '...',
  method: 'GET',
  transformResponse: appendTransform($http.defaults.transformResponse, function(value) {
    return doTransform(value);
  })
});

Кэширование

$http ответы по умолчанию не кэшируются. Чтобы включить кэширование, необходимо установить значение config.cache или значение по умолчанию для кэша в TRUE или в объект кэша (созданный с помощью $cacheFactory). Если определено, значение config.cache имеет приоритет над значением кэша по умолчанию.

Для того чтобы:

• кэшировать все ответы — установите значение кэша по умолчанию в TRUE или в объект кэша
• кэшировать определённый ответ — установите значение config.cache в TRUE или в объект кэша

Если кэширование включено, но ни кэш по умолчанию, ни config.cache не установлены в объект кэша, используется объект кэша по умолчанию $cacheFactory("$http").

Значение кэша по умолчанию можно установить, обновив свойство $http.defaults.cache или свойство $httpProvider.defaults.cache.

При включенном кэшировании, $http сохраняет ответ с сервера, используя соответствующий объект кэша. При последующем выполнении такого же запроса ответ возвращается из кэша без отправки запроса на сервер.

Обратите внимание на следующие моменты:

• Кэшируются только запросы GET и JSONP.
• Ключ кэша — это URL запроса, включая параметры поиска; заголовки не учитываются.
• Кэшированные ответы возвращаются асинхронно, так же, как и ответы с сервера.
• Если с помощью одного кэша выполняются несколько идентичных запросов, а кэш ещё не заполнен, один запрос будет отправлен на сервер, а остальные запросы вернут тот же ответ.
• Заголовок cache-control в ответе не влияет на кэширование ответов.

Перехватывающие фильтры

Прежде чем начать создание перехватывающих фильтров, убедитесь, что вы понимаете $q и API отложенных задач/обещаний.

Для целей обработки глобальных ошибок, аутентификации или любого вида синхронной или асинхронной предобработки запроса или постобработки ответов желательно иметь возможность перехватывать запросы перед отправкой на сервер и ответы перед передачей приложению, инициировавшему эти запросы. Перехватывающие фильтры используют API обещаний, чтобы удовлетворить эту потребность как для синхронной, так и для асинхронной предобработки.

Перехватывающие фильтры — это фабрики служб, которые регистрируются в $httpProvider путем добавления их в массив $httpProvider.interceptors. Фабрика вызывается и инжектируется зависимостями (если указаны) и возвращает перехватывающий фильтр.

Существует два типа перехватывающих фильтров (и два типа перехватывающих фильтров для отклонений):

• request: перехватывающие фильтры вызываются с объектом конфигурации http config. Функция может изменить объект config или создать новый. Функция должна вернуть объект config напрямую или обещание, содержащее объект config или новый объект config.
• requestError: перехватывающий фильтр вызывается, когда предыдущий перехватывающий фильтр генерирует ошибку или отклоняется.
• response: перехватывающие фильтры вызываются с объектом http response. Функция может изменить объект response или создать новый. Функция должна вернуть объект response напрямую или как обещание, содержащее объект response или новый объект response.
• responseError: перехватывающий фильтр вызывается, когда предыдущий перехватывающий фильтр генерирует ошибку или отклоняется.

// register the interceptor as a service
$provide.factory('myHttpInterceptor', function($q, dependency1, dependency2) {
  return {
    // optional method
    'request': function(config) {
      // do something on success
      return config;
    },

    // optional method
   'requestError': function(rejection) {
      // do something on error
      if (canRecover(rejection)) {
        return responseOrNewPromise
      }
      return $q.reject(rejection);
    },



    // optional method
    'response': function(response) {
      // do something on success
      return response;
    },

    // optional method
   'responseError': function(rejection) {
      // do something on error
      if (canRecover(rejection)) {
        return responseOrNewPromise
      }
      return $q.reject(rejection);
    }
  };
});

$httpProvider.interceptors.push('myHttpInterceptor');


// alternatively, register the interceptor via an anonymous factory
$httpProvider.interceptors.push(function($q, dependency1, dependency2) {
  return {
   'request': function(config) {
       // same as above
    },

    'response': function(response) {
       // same as above
    }
  };
});

Учёт мер безопасности

При проектировании веб-приложений следует учитывать угрозы безопасности от:

• уязвимости JSON
• XSRF

Как сервер, так и клиент должны сотрудничать, чтобы устранить эти угрозы. AngularJS поставляется с предварительно настроенными стратегиями, которые решают эти проблемы, но для их работы требуется сотрудничество с сервером.

Защита от уязвимости JSON

Уязвимость JSON позволяет сторонним веб-сайтам преобразовывать URL вашего ресурса JSON в запрос JSONP в определенных условиях. Для защиты от этого ваш сервер может добавлять к запросам JSON следующую строку ")]}',\n". AngularJS автоматически удалит префикс перед обработкой данных как JSON.

Например, если ваш сервер должен вернуть:

['one','two']

что уязвимо к атакам, ваш сервер может вернуть:

)]}',
['one','two']

AngularJS удалит префикс перед обработкой JSON.

Защита от межсайтовых поддельных запросов (XSRF)

XSRF — это метод атаки, при котором злоумышленник может обмануть авторизованного пользователя, чтобы он невольно выполнил действия на вашем сайте. AngularJS предоставляет механизм для защиты от XSRF. При выполнении запросов XHR служба $http считывает токен из куки (по умолчанию XSRF-TOKEN) и устанавливает его как HTTP-заголовок (по умолчанию X-XSRF-TOKEN). Так как только JavaScript, работающий на вашем домене, может получить доступ к куки, ваш сервер может быть уверен, что запрос XHR пришёл от JavaScript, работающего на вашем домене.

Для использования этой функции ваш сервер должен установить токен в куки сессии, доступной для JavaScript, с именем XSRF-TOKEN, при первом запросе HTTP GET. При последующих запросах XHR сервер может проверить, что куки соответствует HTTP-заголовку X-XSRF-TOKEN, и, следовательно, убедиться, что запрос был отправлен только JavaScript, работающим на вашем домене. Токен должен быть уникальным для каждого пользователя и проверяемым сервером (чтобы предотвратить создание JavaScript собственных токенов). Рекомендуется, чтобы токен был хешем вашего аутентификационного куки с добавленной солью для повышения безопасности.

Заголовок — по умолчанию — не будет устанавливаться для междоменных запросов. Это предотвращает несанкционированный доступ серверов (например, злонамеренных или взломанных API третьих сторон) к токенам XSRF пользователей и защищает от межсайтовой подделки запросов. Если необходимо, можно добавить разрешённые домены, которые также будут получать токен XSRF, добавив их в xsrfWhitelistedOrigins. Это может быть полезно, например, если ваше приложение, размещенное на example.com, должно получить доступ к вашему API на api.example.com. Подробнее см. $httpProvider.xsrfWhitelistedOrigins.

Имя куки и заголовка можно указать, используя свойства xsrfCookieName и xsrfHeaderName соответственно, либо во время конфигурации $httpProvider.defaults, либо во время выполнения $http.defaults, либо в объекте конфигурации для каждого запроса.

Для предотвращения коллизий в средах, где несколько приложений AngularJS используют один и тот же домен или поддомен, рекомендуется использовать уникальные имена куки для каждого приложения.