dart:io

Класс HttpClient

HTTP-клиент для взаимодействия с HTTP-сервером.

Отправляет HTTP-запросы HTTP-серверу и получает ответы. Сохраняет состояние, включая сеансовые и другие файлы cookie, между несколькими запросами к одному и тому же серверу.

Примечание: HttpClient предоставляет низкоуровневые функции HTTP. Рекомендуем начать с более удобных для разработчиков и компонуемых API из пакета package:http.

HttpClient содержит несколько методов для отправки HttpClientRequest HTTP-серверу и получения HttpClientResponse в ответ. Например, для запросов GET и POST соответственно можно использовать методы get, getUrl, post и postUrl.

Пример простого GET-запроса

Запрос getUrl выполняется в два этапа, запускаемых двумя объектами Future. Когда первый future завершается с результатом HttpClientRequest, базовое сетевое соединение уже установлено, но данные ещё не отправлены. В функции обратного вызова первого future можно задать заголовки HTTP и тело запроса. Запрос отправляется серверу либо при первой записи в объект запроса, либо при вызове close.

Когда от сервера получен HTTP-ответ, завершается второй future, возвращаемый методом close, и его результатом становится объект HttpClientResponse. Этот объект предоставляет доступ к заголовкам и телу ответа. Тело доступно как поток, реализованный с помощью HttpClientResponse. Если тело присутствует, его необходимо прочитать. В противном случае возможна утечка ресурсов. Если тело не используется, рассмотрите возможность вызова HttpClientResponse.drain.

var client = HttpClient();
try {
  HttpClientRequest request = await client.get('localhost', 80, '/file.txt');
  // Optionally set up headers...
  // Optionally write to the request object...
  HttpClientResponse response = await request.close();
  // Process the response
  final stringData = await response.transform(utf8.decoder).join();
  print(stringData);
} finally {
  client.close();
}

Future для HttpClientRequest создаётся такими методами, как getUrl и open.

HTTPS-соединения

Объект HttpClient может выполнять HTTPS-запросы, подключаясь к серверу по защищённому сетевому протоколу TLS (SSL). Вызов getUrl со схемой https: работает автоматически, если сертификат сервера подписан корневым центром сертификации (CA), включённым в составленный Mozilla стандартный список известных доверенных центров сертификации.

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

Заголовки

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

Accept-Encoding: gzip

Это позволяет HTTP-серверу по возможности использовать сжатие gzip для тела ответа. Если такое поведение нежелательно, задайте для заголовка Accept-Encoding другое значение. Чтобы отключить сжатие gzip ответа, очистите этот заголовок:

request.headers.removeAll(HttpHeaders.acceptEncodingHeader)

Закрытие HttpClient

HttpClient поддерживает постоянные соединения и кэширует сетевые соединения, чтобы по возможности повторно использовать их для нескольких запросов. Это означает, что сетевые соединения могут оставаться открытыми некоторое время после завершения запроса. Используйте HttpClient.close, чтобы принудительно завершить работу объекта HttpClient и закрыть неактивные сетевые соединения.

Включение и отключение прокси-серверов

По умолчанию HttpClient использует конфигурацию прокси-сервера из окружения; см. findProxyFromEnvironment. Чтобы отключить использование прокси-серверов, задайте для свойства findProxy значение null.

HttpClient client = HttpClient();
client.findProxy = null;

Конструкторы

HttpClient({SecurityContext? context})

фабричный

Свойства

authenticate ← (Future<bool> Function(Uri url, String scheme, String? realm)?)

только для записи

Задаёт функцию, вызываемую, когда сайт запрашивает аутентификацию.

authenticateProxy ← (Future<bool> Function(String host, int port, String scheme, String? realm)?)

только для записи

Задаёт функцию, вызываемую, когда прокси-сервер запрашивает аутентификацию.

autoUncompress ↔ bool

чтение / запись

Возвращает и задаёт, будет ли тело ответа автоматически распаковано.

badCertificateCallback ← (bool Function(X509Certificate cert, String host, int port)?)

только для записи

Задаёт функцию обратного вызова, которая решает, принимать ли защищённое соединение с сервером, сертификат которого не может быть проверен ни одним из доверенных корневых сертификатов.

connectionFactory ← (Future<ConnectionTask<Socket>> Function(Uri url, String? proxyHost, int? proxyPort)?)

только для записи

Задаёт функцию, используемую для создания сокетных соединений.

connectionTimeout ↔ Duration?

чтение / запись

Возвращает и задаёт время ожидания соединения.

findProxy ← (String Function(Uri url)?)

только для записи

Задаёт функцию, используемую для определения прокси-сервера, который будет применяться для открытия HTTP-соединения с указанным url. Если эта функция не задана, всегда используются прямые соединения.

hashCode → int

только для чтения, унаследовано

Хеш-код этого объекта.

idleTimeout ↔ Duration

чтение / запись

Возвращает и задаёт время ожидания неактивных постоянных соединений (keep-alive).

keyLog ← (dynamic Function(String line)?)

только для записи

Задаёт функцию обратного вызова, которая вызывается при обмене новыми ключами TLS с сервером. При каждом вызове ей передаётся одна текстовая строка в формате NSS Key Log Format. Запись этих строк в файл позволит инструментам (например, Wireshark) расшифровывать обмен данными между этим клиентом и сервером. Эта функция предназначена для отладки защищённых сокетов на сетевом уровне и не должна использоваться в производственном коде. Например:

maxConnectionsPerHost ↔ int?

чтение / запись

Возвращает и задаёт максимальное количество активных соединений с одним узлом.

runtimeType → Type

только для чтения, унаследовано

Представление типа объекта во время выполнения.

userAgent ↔ String?

чтение / запись

Возвращает и задаёт значение по умолчанию для заголовка User-Agent во всех запросах, создаваемых этим объектом HttpClient.

Методы

addCredentials(Uri url, String realm, HttpClientCredentials credentials) → void

Добавляет учётные данные для авторизации HTTP-запросов.

addProxyCredentials(String host, int port, String realm, HttpClientCredentials credentials) → void

Добавляет учётные данные для авторизации на HTTP-прокси-серверах.

close({bool force = false}) → void

Завершает работу HTTP-клиента.

delete(String host, int port, String path) → Future<HttpClientRequest>

Открывает HTTP-соединение, используя метод DELETE.

deleteUrl(Uri url) → Future<HttpClientRequest>

Открывает HTTP-соединение, используя метод DELETE.

get(String host, int port, String path) → Future<HttpClientRequest>

Открывает HTTP-соединение, используя метод GET.

getUrl(Uri url) → Future<HttpClientRequest>

Открывает HTTP-соединение, используя метод GET.

head(String host, int port, String path) → Future<HttpClientRequest>

Открывает HTTP-соединение, используя метод HEAD.

headUrl(Uri url) → Future<HttpClientRequest>

Открывает HTTP-соединение, используя метод HEAD.

noSuchMethod(Invocation invocation) → dynamic

унаследовано

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

open(String method, String host, int port, String path) → Future<HttpClientRequest>

Открывает HTTP-соединение.

openUrl(String method, Uri url) → Future<HttpClientRequest>

Открывает HTTP-соединение.

patch(String host, int port, String path) → Future<HttpClientRequest>

Открывает HTTP-соединение, используя метод PATCH.

patchUrl(Uri url) → Future<HttpClientRequest>

Открывает HTTP-соединение, используя метод PATCH.

post(String host, int port, String path) → Future<HttpClientRequest>

Открывает HTTP-соединение, используя метод POST.

postUrl(Uri url) → Future<HttpClientRequest>

Открывает HTTP-соединение, используя метод POST.

put(String host, int port, String path) → Future<HttpClientRequest>

Открывает HTTP-соединение, используя метод PUT.

putUrl(Uri url) → Future<HttpClientRequest>

Открывает HTTP-соединение, используя метод PUT.

toString() → String

унаследовано

Строковое представление этого объекта.

Операторы

operator ==(Object other) → bool

унаследовано

Оператор равенства.

Статические свойства

enableTimelineLogging ↔ bool

чтение / запись

Текущее состояние регистрации HTTP-запросов всех объектов HttpClient на временной шкале разработчика.

Статические методы

findProxyFromEnvironment(Uri url, {Map<String, String>? environment}) → String

Функция определения прокси-сервера для HTTP-соединения на основе конфигурации прокси-сервера, заданной переменными окружения.

Константы

defaultHttpPort → const int

80

defaultHttpsPort → const int

443