Pipelines et clients HTTP dans le Kit de développement logiciel (SDK) Azure pour Java

Cet article offre une vue d’ensemble de l’utilisation de la fonctionnalité pipeline et client HTTP dans le Kit de développement logiciel (SDK) Azure pour Java. Cette fonctionnalité fournit une expérience cohérente, puissante et flexible aux développeurs qui utilisent l’ensemble des bibliothèques du Kit de développement logiciel (SDK) Azure pour Java.

Clients HTTP

Le Kit de développement logiciel (SDK) Azure pour Java est implémenté à l’aide d’une abstraction HttpClient. Cette abstraction active une architecture enfichable qui accepte plusieurs bibliothèques de client HTTP ou implémentations personnalisées. Toutefois, pour simplifier la gestion des dépendances pour la plupart des utilisateurs, toutes les bibliothèques de client Azure dépendent de azure-core-http-netty. Par conséquent, le client HTTP Netty est le client par défaut utilisé dans toutes les bibliothèques du Kit de développement logiciel (SDK) Azure pour Java.

Bien que Netty soit le client HTTP par défaut, le SDK fournit trois implémentations client, en fonction des dépendances que vous avez déjà dans votre projet. Ces implémentations sont pour :

• Netty
• OkHttp
• HttpClient introduit dans JDK 11

Remplacer le client HTTP par défaut

Si vous préférez une autre implémentation, vous pouvez supprimer la dépendance Netty en l’excluant des fichiers de configuration de build. Dans un fichier pom.xml Maven, excluez la dépendance Netty et incluez une autre dépendance.

L’exemple suivant montre comment exclure la dépendance Netty d’une dépendance réelle dans la bibliothèque azure-security-keyvault-secrets. Veillez à exclure Netty de toutes les bibliothèques com.azure appropriées, comme illustré ici :

<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>

Configurer des clients HTTP

Lorsque vous générez un client de service, il utilise HttpClient.createDefault()par défaut . Cette méthode renvoie une instance de HttpClient de base en fonction de l’implémentation du client HTTP fournie. Si vous avez besoin d’un client HTTP plus complexe, tel qu’un proxy, chaque implémentation propose un générateur qui vous permet de construire une instance de HttpClient configurée. Les générateurs sont NettyAsyncHttpClientBuilder, OkHttpAsyncHttpClientBuilder et JdkAsyncHttpClientBuilder.

Les exemples suivants montrent comment créer des instances de HttpClient avec Netty, OkHttp et le client HTTP JDK 11. Ces instances proxysent via http://localhost:3128 et s’authentifient avec l’utilisateur example avec le mot de passe 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();

Vous pouvez maintenant transmettre l’instance de HttpClient construite vers un générateur de client de service pour une utilisation en tant que client pour communiquer avec le service. L’exemple suivant utilise la nouvelle instance de HttpClient pour créer un client Azure Storage Blob.

BlobClient blobClient = new BlobClientBuilder()
    .connectionString(<connection string>)
    .containerName("container")
    .blobName("blob")
    .httpClient(httpClient)
    .build();

Pour les bibliothèques de gestion, vous pouvez définir HttpClient lors de la configuration du gestionnaire.

AzureResourceManager azureResourceManager = AzureResourceManager.configure()
    .withHttpClient(httpClient)
    .authenticate(credential, profile)
    .withDefaultSubscription();

Pipeline HTTP

Le pipeline HTTP est l’un des composants clés pour assurer la cohérence et les diagnostics dans les bibliothèques de client Java pour Azure. Un pipeline HTTP est composé des éléments suivants :

• Un transport HTTP
• Des stratégies de pipeline HTTP

Vous pouvez fournir votre propre pipeline HTTP personnalisé lors de la création d’un client. Si vous ne fournissez pas de pipeline, la bibliothèque cliente en crée une configurée pour fonctionner avec cette bibliothèque cliente spécifique.

Transport HTTP

Le transport HTTP est responsable de l’établissement de la connexion au serveur ainsi que de l’envoi et de la réception des messages HTTP. Le transport HTTP forme la passerelle pour que les bibliothèques de client du Kit de développement logiciel (SDK) Azure interagissent avec les services Azure. Comme indiqué plus haut dans cet article, le SDK Azure pour Java utilise Netty par défaut pour son transport HTTP. Toutefois, il fournit également un transport HTTP enfichable pour que vous puissiez utiliser d’autres implémentations, le cas échéant. Le SDK fournit également deux implémentations de transport HTTP supplémentaires pour OkHttp et le client HTTP fourni avec JDK 11 et versions ultérieures.

Des stratégies de pipeline HTTP

Un pipeline se compose d’une séquence d’étapes exécutées pour chaque échange requête-réponse HTTP. Chaque stratégie a un objectif dédié et agit sur une demande ou une réponse ou parfois les deux. Étant donné que toutes les bibliothèques de client ont une couche « Azure Core » standard, cette couche garantit que chaque stratégie s’exécute dans l’ordre dans le pipeline. Lorsque vous envoyez une demande, les stratégies s’exécutent dans l’ordre dans lequel elles sont ajoutées au pipeline. Lorsque vous recevez une réponse du service, les stratégies s’exécutent dans l’ordre inverse. Toutes les stratégies ajoutées au pipeline s’exécutent avant l’envoi de la demande et après la réception d’une réponse. La stratégie doit décider s’il faut agir sur la demande, sur la réponse ou sur les deux. Par exemple, une stratégie de journalisation enregistre la demande et la réponse, mais la stratégie d’authentification n’est intéressée que par la modification de la demande.

L’infrastructure Azure Core fournit la stratégie avec les données de requête et de réponse nécessaires, ainsi que tout contexte nécessaire pour exécuter la stratégie. La stratégie peut ensuite effectuer son opération avec les données spécifiées et transmettre le contrôle à la stratégie suivante dans le pipeline.

Position de la stratégie de pipeline HTTP

Lorsque vous effectuez des requêtes HTTP vers des services cloud, il est important de gérer les défaillances temporaires et de relancer les tentatives ayant échoué. Étant donné que cette fonctionnalité est une exigence courante, Azure Core fournit une stratégie de nouvelle tentative qui peut surveiller les échecs temporaires et relancer automatiquement la demande.

Par conséquent, cette stratégie de nouvelle tentative divise le pipeline entier en deux parties : les stratégies qui s’exécutent avant la stratégie de nouvelle tentative et celles qui s’exécutent après la stratégie de nouvelle tentative. Les stratégies ajoutées avant la stratégie de nouvelle tentative ne s’exécutent qu’une seule fois par opération d’API, et celles ajoutées après la stratégie de nouvelle tentative s’exécutent autant de fois que le nombre de tentatives.

Ainsi, lors de la création du pipeline HTTP, vous devez déterminer s’il faut exécuter une stratégie pour chaque nouvelle tentative de requête ou seulement une fois par opération d’API.

Stratégies de pipeline HTTP courantes

Les pipelines HTTP pour les services REST ont des configurations avec des stratégies pour l’authentification, les nouvelles tentatives, la journalisation, la télémétrie et la spécification de l’ID de demande dans l’en-tête. Azure Core est préchargé avec ces stratégies HTTP couramment requises que vous pouvez ajouter au pipeline.

Stratégie de pipeline HTTP personnalisée

La stratégie de pipeline HTTP fournit un mécanisme pratique pour modifier ou décorer la demande et la réponse. Vous pouvez ajouter des stratégies personnalisées au pipeline créé par l’utilisateur ou le développeur de bibliothèque cliente. Lorsque vous ajoutez la stratégie au pipeline, vous pouvez spécifier si elle doit être exécutée par appel ou par nouvelle tentative.

Pour créer une stratégie de pipeline HTTP personnalisée, il vous suffit d’étendre un type de stratégie de base et d’implémenter une méthode abstraite. Vous pouvez ensuite brancher la stratégie dans le pipeline.

En-têtes personnalisés dans les requêtes HTTP

Les bibliothèques clientes Azure SDK pour Java offrent un moyen cohérent de définir des en-têtes personnalisés via Context des objets dans l’API publique, comme illustré dans l’exemple suivant :

// 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.

Pour plus d’informations, consultez la classe AddHeadersFromContextPolicy.

Bibliothèque TLS/SSL par défaut

Toutes les bibliothèques clientes, par défaut, utilisent la bibliothèque SSL Boring native Tomcat pour activer les performances de niveau natif pour les opérations TLS/SSL. La bibliothèque SSL Boring est un fichier JAR uber contenant des bibliothèques natives pour Linux, macOS et Windows, et offre de meilleures performances par rapport à l’implémentation TLS/SSL par défaut dans le JDK.

Réduire la taille des dépendances TLS/SSL Tomcat-Native

Par défaut, le fichier JAR uber de la bibliothèque SSL Tomcat-Native Boring est utilisé dans les sdk Azure pour Java. Pour réduire la taille de cette dépendance, vous devez inclure la dépendance avec un os classifieur comme par netty-tcnative, comme illustré dans l’exemple suivant :

<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>

Utiliser JDK TLS/SSL

Si vous préférez utiliser le protocole TLS/SSL JDK par défaut au lieu de Tomcat-Native Boring SSL, vous devez exclure la bibliothèque SSL Boring native de Tomcat. Sachez que, en fonction de nos tests, les performances de JDK TLS/SSL sont plus lentes que tomcat-native boring SSL. Lorsque vous utilisez com.azure:azure-core:1.28.0 ou une version ultérieure, la HttpClientbibliothèque -implementing (par exemple com.azure:azure-core-http-netty) gère la dépendance sur Tomcat-Native Boring SSL. Pour exclure la dépendance, ajoutez la configuration suivante à votre fichier 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>

Étapes suivantes

Maintenant que vous êtes familiarisé avec les fonctionnalités du client HTTP dans le Kit de développement logiciel (SDK) Azure pour Java, découvrez comment personnaliser davantage le client HTTP que vous utilisez. Pour plus d’informations, consultez Configurer des proxys dans le Kit de développement logiciel (SDK) Azure pour Java.