HTTP-клиенты и конвейеры в пакете SDK Azure для Java
В этой статье содержится обзор использования функции HTTP-клиента и конвейера в пакете SDK Azure для Java. Эта функция обеспечивает согласованный, мощный и гибкий интерфейс для разработчиков, использующих все библиотеки Azure SDK для Java.
HTTP-клиенты
Пакет SDK Azure для Java реализуется с помощью HttpClient абстракции. Эта абстракция позволяет использовать подключаемую архитектуру, которая поддерживает несколько клиентских библиотек HTTP или пользовательских реализаций. Однако для упрощения управления зависимостями для большинства пользователей все клиентские библиотеки Azure зависят от azure-core-http-netty. Поэтому клиент Netty HTTP используется по умолчанию во всех библиотеках Azure SDK для Java.
Хотя Netty является HTTP-клиентом по умолчанию, пакет SDK предоставляет три реализации клиента, в зависимости от того, какие зависимости у вас уже есть в проекте. Эти реализации предназначены для следующих вариантов:
- Netty
- OkHttp
- HttpClient появилась в JDK 11
Заметка
JDK HttpClient в сочетании с пакетом SDK Azure для Java поддерживается только с JDK 12 и выше.
Замена HTTP-клиента по умолчанию
Если вы предпочитаете другую реализацию, можно удалить зависимость от Netty, исключив ее в файлах конфигурации сборки. В файле Maven pom.xml вы исключите зависимость Netty и включите другую зависимость.
В следующем примере показано, как исключить зависимость Netty из реальной зависимости от библиотеки azure-security-keyvault-secrets. Не забудьте исключить Netty из всех соответствующих библиотек com.azure, как показано ниже:
<dependency>
<groupId>com.azure</groupId>
<artifactId>azure-security-keyvault-secrets</artifactId>
<version>4.2.2.</version>
<exclusions>
<exclusion>
<groupId>com.azure</groupId>
<artifactId>azure-core-http-netty</artifactId>
</exclusion>
</exclusions>
</dependency>
<dependency>
<groupId>com.azure</groupId>
<artifactId>azure-core-http-okhttp</artifactId>
<version>1.3.3</version>
</dependency>
Заметка
Если вы удаляете зависимость Netty, но не предоставляете его реализацию, приложение не запускается. Реализация HttpClient должна существовать в classpath.
Настройка HTTP-клиентов
При создании клиента службы по умолчанию используется HttpClient.createDefault(). Этот метод возвращает базовый экземпляр HttpClient на основе предоставленной реализации клиента HTTP. В случае, если требуется более сложный HTTP-клиент, например прокси- сервер, каждая реализация предлагает построитель, который позволяет создать настроенный экземпляр HttpClient. Строители NettyAsyncHttpClientBuilder, OkHttpAsyncHttpClientBuilderи JdkAsyncHttpClientBuilder.
В следующих примерах показано, как создавать экземпляры HttpClient с помощью Netty, OkHttp и HTTP-клиента JDK 11. Эти экземпляры проксируются через http://localhost:3128 и аутентифицируются с пользователем example и паролем weakPassword.
// Netty
HttpClient httpClient = new NettyAsyncHttpClientBuilder()
.proxy(new ProxyOptions(ProxyOptions.Type.HTTP, new InetSocketAddress("localhost", 3128))
.setCredentials("example", "weakPassword"))
.build();
// OkHttp
HttpClient httpClient = new OkHttpAsyncHttpClientBuilder()
.proxy(new ProxyOptions(ProxyOptions.Type.HTTP, new InetSocketAddress("localhost", 3128))
.setCredentials("example", "weakPassword"))
.build();
// JDK 11 HttpClient
HttpClient client = new JdkAsyncHttpClientBuilder()
.proxy(new ProxyOptions(ProxyOptions.Type.HTTP, new InetSocketAddress("localhost", 3128))
.setCredentials("example", "weakPassword"))
.build();
Теперь вы можете передать созданный экземпляр HttpClient в построитель клиентского сервиса для использования в качестве клиента для взаимодействия со службой. В следующем примере новый объект HttpClient используется для создания клиента Azure Blob.
BlobClient blobClient = new BlobClientBuilder()
.connectionString(<connection string>)
.containerName("container")
.blobName("blob")
.httpClient(httpClient)
.build();
Для библиотек управления можно задать HttpClient во время настройки Диспетчера.
AzureResourceManager azureResourceManager = AzureResourceManager.configure()
.withHttpClient(httpClient)
.authenticate(credential, profile)
.withDefaultSubscription();
Конвейер HTTP
Конвейер HTTP является одним из ключевых компонентов для обеспечения согласованности и диагностики в клиентских библиотеках Java для Azure. Конвейер HTTP состоит из:
- Транспорт по протоколу HTTP
- Политики конвейера HTTP
При создании клиента можно предоставить собственный пользовательский конвейер HTTP. Если вы не предоставляете конвейер, клиентская библиотека создает конвейер, настроенный для работы с этой библиотекой.
Передача данных HTTP
Транспорт HTTP отвечает за установку подключения к серверу и отправку и получение HTTP-сообщений. Транспорт HTTP формирует шлюз для клиентских библиотек пакета SDK Azure для взаимодействия со службами Azure. Как отмечалось ранее в этой статье, пакет SDK Azure для Java использует Netty по умолчанию для его транспорта HTTP. Однако пакет SDK также предоставляет подключаемый транспорт HTTP, чтобы можно было использовать другие реализации, если это необходимо. Пакет SDK также предоставляет еще две реализации транспорта HTTP для OkHttp и HTTP-клиента, который поставляется с JDK 11 и более поздних версий.
Политики конвейера HTTP
Конвейер состоит из последовательности шагов, выполняемых для каждого круга обработки запроса и ответа HTTP. Каждая политика имеет специальное назначение и действует по запросу или ответу или иногда обоим. Так как все клиентские библиотеки имеют стандартный уровень Azure Core, этот уровень гарантирует, что каждая политика выполняется в конвейере. При отправке запроса политики выполняются в том порядке, в который они добавляются в конвейер. При получении ответа от службы политики выполняются в обратном порядке. Все политики, добавленные в конвейер, выполняются перед отправкой запроса и после получения ответа. Политика должна решить, следует ли действовать по запросу, ответу или обоим. Например, политика ведения журнала регистрирует запрос и ответ, но политика проверки подлинности заинтересована только в изменении запроса.
Платформа Azure Core предоставляет политику с необходимыми данными запроса и ответа вместе с любым необходимым контекстом для выполнения политики. Затем правило может выполнить свою операцию с заданными данными и передать управление следующему правилу в потоке.
Позиция политики конвейера HTTP
При выполнении HTTP-запросов к облачным службам важно обрабатывать временные сбои и повторять неудачные попытки. Так как эта функция является общим требованием, Azure Core предоставляет политику повторных попыток, которая может отслеживать временные сбои и автоматически повторять запрос.
Таким образом, эта политика повторных попыток разделяет весь конвейер на две части: политики, которые выполняются перед политикой повторных попыток, и политики, которые выполняются после нее. Политики, добавленные до политики повторных попыток, выполняются только один раз для каждой операции API, а политики, добавленные после политики повторных попыток, выполняются столько раз, сколько раз выполняются повторные попытки.
Таким образом, при создании конвейера HTTP следует понять, следует ли выполнять политику для каждой повторных попыток запроса или один раз за операцию API.
Общие политики конвейера HTTP
Конвейеры HTTP для служб REST имеют конфигурации с политиками проверки подлинности, повторными попытками, ведением журнала, телеметрией и указанием идентификатора запроса в заголовке. Azure Core поставляется с заранее настроенными часто используемыми политиками HTTP, которые можно добавить в поток обработки.
| Политика | Ссылка на GitHub |
|---|---|
| Политика повторных попыток | RetryPolicy.java |
| Политика проверки подлинности | BearerTokenAuthenticationPolicy.java |
| Политика журналирования | HttpLoggingPolicy.java |
| Политика идентификатора запроса | RequestIdPolicy.java |
| Политика телеметрии | UserAgentPolicy.java |
Настраиваемая политика конвейера HTTP
Политика конвейера HTTP предоставляет удобный механизм для изменения или оформления запроса и ответа. Настраиваемые политики можно добавить в конвейер, созданный пользователем или разработчиком клиентской библиотеки. При добавлении политики в конвейер, можно указать, следует ли выполнять эту политику для каждого вызова или при каждой попытке повтора.
Чтобы создать настраиваемую политику конвейера HTTP, вы просто расширяете базовый тип политики и реализуете некоторый абстрактный метод. Затем вы можете подключить политику к конвейеру.
Пользовательские заголовки в HTTP-запросах
Клиентские библиотеки Azure SDK для Java обеспечивают согласованный способ определения настраиваемых заголовков с помощью Context объектов в общедоступном API, как показано в следующем примере:
// Add your headers
HttpHeaders headers = new HttpHeaders();
headers.set("my-header1", "my-header1-value");
headers.set("my-header2", "my-header2-value");
headers.set("my-header3", "my-header3-value");
// Call API by passing headers in Context.
configurationClient.addConfigurationSettingWithResponse(
new ConfigurationSetting().setKey("key").setValue("value"),
new Context(AddHeadersFromContextPolicy.AZURE_REQUEST_HTTP_HEADERS_KEY, headers));
// The three headers are now be added to the outgoing HTTP request.
Дополнительные сведения см. в классе AddHeadersFromContextPolicy
Библиотека TLS/SSL по умолчанию
Все клиентские библиотеки по умолчанию используют библиотеку SSL tomcat-native Boring, чтобы обеспечить производительность на уровне машинного уровня для операций TLS/SSL. Скучная библиотека SSL — это JAR-файл uber, содержащий собственные библиотеки для Linux, macOS и Windows, и обеспечивает более высокую производительность по сравнению с реализацией TLS/SSL по умолчанию в JDK.
Уменьшение размера зависимостей TLS/SSL Tomcat-Native
По умолчанию JAR-файл uber Tomcat-Native скучной SSL-библиотеки используется в пакетах SDK Azure для Java. Чтобы уменьшить размер этой зависимости, необходимо добавить зависимость с классификатором os в соответствии с netty-tcnative, как показано в следующем примере:
<project>
...
<dependencies>
...
<dependency>
<groupId>io.netty</groupId>
<artifactId>netty-tcnative-boringssl-static</artifactId>
<version>2.0.25.Final</version>
<classifier>${os.detected.classifier}</classifier>
</dependency>
...
</dependencies>
...
<build>
...
<extensions>
<extension>
<groupId>kr.motd.maven</groupId>
<artifactId>os-maven-plugin</artifactId>
<version>1.4.0.Final</version>
</extension>
</extensions>
...
</build>
...
</project>
Использование ПРОТОКОЛА TLS/SSL JDK
Если вы предпочитаете использовать протокол TLS/SSL по умолчанию, а не Tomcat-Native SSL скучно, необходимо исключить библиотеку SSL tomcat-native Boring SSL. Помните, что на основе наших тестов производительность JDK TLS/SSL составляет 30% медленнее по сравнению с Tomcat-Native Скучным SSL. При использовании com.azure:azure-core:1.28.0 или более поздней версии библиотека реализации HttpClient(например, com.azure:azure-core-http-netty) управляет зависимостью от Tomcat-Native BoringSSL. Чтобы исключить зависимость, добавьте следующую конфигурацию в файл POM:
<project>
...
<dependencies>
...
<dependency>
<groupId>com.azure</groupId>
<artifactId>azure-core-http-netty</artifactId>
<version>1.13.6</version>
<exclusions>
<exclusion>
<groupId>io.netty</groupId>
<artifactId>netty-tcnative-boringssl-static</artifactId>
</exclusion>
</exclusions>
</dependency>
...
</dependencies>
...
</project>
Дальнейшие действия
Теперь, когда вы знакомы с функциями клиента HTTP в пакете SDK Azure для Java, узнайте, как дополнительно настроить http-клиент, который вы используете. Дополнительные сведения см. в статье Настройка прокси-серверов в пакете SDK Azure для Java.