Lire en anglais

Partager via

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

  • Article

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

Clients HTTP

Le Kit de développement logiciel (SDK) Azure pour Java est implémenté à l’aide d’une abstraction HttpClient. Cette abstraction permet une architecture enfichable qui accepte plusieurs bibliothèques clientes HTTP ou implémentations personnalisées. Toutefois, pour simplifier la gestion des dépendances pour la plupart des utilisateurs, toutes les bibliothèques clientes 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 Kit de développement logiciel (SDK) fournit trois implémentations clientes, en fonction des dépendances que vous avez déjà dans votre projet. Ces implémentations sont destinées à :

Notes

Le JDK HttpClient en combinaison avec le Kit de développement logiciel (SDK) Azure pour Java est pris en charge uniquement avec JDK 12 et versions ultérieures.

Remplacer le client HTTP par défaut

Si vous préférez une autre implémentation, vous pouvez supprimer la dépendance sur Netty en l’excluant dans les fichiers de configuration de build. Dans un fichier Maven pom.xml, vous 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 sur la bibliothèque azure-security-keyvault-secrets. Veillez à exclure Netty de toutes les bibliothèques com.azure appropriées, comme indiqué ici :

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

Notes

Si vous supprimez la dépendance Netty mais ne fournissez aucune implémentation à sa place, l’application ne parvient pas à démarrer. Une implémentation HttpClient doit exister sur le classpath.

Configurer des clients HTTP

Lorsque vous générez un client de service, il utilise par défaut HttpClient.createDefault(). Cette méthode retourne une instance de base HttpClient basée sur l’implémentation du client HTTP fournie. Si vous avez besoin d’un client HTTP plus complexe, tel qu’un proxy, chaque implémentation offre 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 générer des instances HttpClient à l’aide de Netty, OkHttp et du client HTTP JDK 11. Ces instances proxy via http://localhost:3128 et s’authentifient auprès de l’utilisateur example avec le mot de passe weakPassword.

Java 
// 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 passer l'instance construite HttpClient à un constructeur de client de service pour l'utiliser comme client afin de communiquer avec le service. L’exemple suivant utilise la nouvelle instance de HttpClient pour générer un client Blob Stockage Azure.

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

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

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

Pipeline HTTP

Le pipeline HTTP est l’un des composants clés de l’obtention de la cohérence et du diagnostic dans les bibliothèques clientes Java pour Azure. Un pipeline HTTP est composé des 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 chargé d’établir la connexion au serveur et d’envoyer et de recevoir des messages HTTP. Le transport HTTP forme la passerelle pour les bibliothèques clientes du Kit de développement logiciel (SDK) Azure afin d’interagir avec les services Azure. Comme indiqué précédemment dans cet article, le Kit de développement logiciel (SDK) Azure pour Java utilise Netty par défaut pour son transport HTTP. Toutefois, le Kit de développement logiciel (SDK) fournit également un transport HTTP enfichable afin de pouvoir 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 aller-retour 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 clientes 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 d’envoyer la demande et après avoir reçu une réponse. La stratégie doit décider s’il faut agir sur la demande, la réponse ou 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 politique peut ensuite effectuer son opération avec les données fournies et transmettre le contrôle à la politique suivante dans le pipeline.

diagramme de pipeline HTTP

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 échecs temporaires et de réessayer 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 défaillances temporaires et réessayer automatiquement la requête.

Cette stratégie de nouvelle tentative fractionne donc l’ensemble du pipeline en deux parties : les stratégies qui s’exécutent avant la stratégie de nouvelle tentative et les stratégies 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 les stratégies ajoutées après l’exécution de la stratégie de nouvelle tentative autant de fois que les nouvelles tentatives.

Par conséquent, lors de la génération du pipeline HTTP, vous devez comprendre s’il faut exécuter une stratégie pour chaque nouvelle tentative de requête ou 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 requête dans l’en-tête. Azure Core est préchargé avec ces stratégies HTTP couramment requises que vous pouvez ajouter au pipeline.

Politique Lien GitHub
stratégie de nouvelle tentative RetryPolicy.java
stratégie d’authentification BearerTokenAuthenticationPolicy.java
stratégie de journalisation HttpLoggingPolicy.java
stratégie d’ID de requête RequestIdPolicy.java
stratégie de télémétrie UserAgentPolicy.java

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 politique au pipeline, vous pouvez spécifier si cette politique doit être exécutée pour chaque appel ou pour chaque nouvelle tentative.

Pour créer une stratégie de pipeline HTTP personnalisée, vous étendez simplement un type de stratégie de base et implémentez 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 du SDK Azure pour Java permettent de définir des en-têtes personnalisés à l'aide d'objets Context dans l’API publique, comme illustré dans l’exemple suivant :

Java 
// 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 de dépendance TLS/SSL Tomcat-Native

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

XML 
<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 TLS/SSL par défaut du JDK au lieu de Tomcat-Native Boring SSL, alors vous devez exclure la bibliothèque Tomcat-native Boring SSL. N’oubliez pas que, en fonction de nos tests, les performances de JDK TLS/SSL sont 30% plus lentes par rapport à Tomcat-Native SSL ennuyeux. Lorsque vous utilisez com.azure:azure-core:1.28.0 ou une version ultérieure, la bibliothèque d'implémentation HttpClient(telle que com.azure:azure-core-http-netty) gère la dépendance à Tomcat-Native BoringSSL. Pour exclure la dépendance, ajoutez la configuration suivante à votre fichier POM :

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