Bibliothèque partagée Azure Core pour Java - version 1.45.0

Azure Core fournit des primitives, des abstractions et des helpers partagés pour les bibliothèques clientes modernes du SDK Azure Java. Ces bibliothèques suivent les instructions de conception du Kit de développement logiciel (SDK) Azure pour Java et peuvent être facilement identifiées par des noms de package commençant com.azure par et des noms de modules commençant par azure-, par exemple com.azure.storage.blobs , se trouvent dans le /sdk/storage/azure-storage-blob répertoire. Vous trouverez ici une liste plus complète des bibliothèques clientes utilisant Azure Core.

Azure Core permet aux bibliothèques clientes d’exposer des fonctionnalités communes de manière cohérente, de sorte qu’une fois que vous avez appris à utiliser ces API dans une bibliothèque cliente, vous saurez comment les utiliser dans d’autres bibliothèques clientes.

Prise en main

Prérequis

• Un Kit de développement Java (JDK), version 8 ou ultérieure.

Inclure le package

Inclure le fichier de nomenclature

Incluez azure-sdk-bom dans votre projet pour dépendre de la version de disponibilité générale de la bibliothèque. Dans l’extrait de code suivant, remplacez l’espace réservé {bom_version_to_target} par le numéro de version. Pour en savoir plus sur la nomenclature, consultez le README BOM du KIT DE DÉVELOPPEMENT LOGICIEL AZURE.

<dependencyManagement>
    <dependencies>
        <dependency>
            <groupId>com.azure</groupId>
            <artifactId>azure-sdk-bom</artifactId>
            <version>{bom_version_to_target}</version>
            <type>pom</type>
            <scope>import</scope>
        </dependency>
    </dependencies>
</dependencyManagement>

Incluez ensuite la dépendance directe dans la section des dépendances sans la balise de version. En règle générale, vous n’avez pas besoin d’installer ou de dépendre d’Azure Core, mais il est téléchargé de manière transitive par votre outil de génération lorsque vous dépendez des bibliothèques clientes qui l’utilisent.

<dependencies>
    <dependency>
        <groupId>com.azure</groupId>
        <artifactId>azure-core</artifactId>
    </dependency>
</dependencies>

Inclure une dépendance directe

Si vous souhaitez dépendre d’une version particulière de la bibliothèque qui n’est pas présente dans la nomenclature, ajoutez la dépendance directe à votre projet comme suit.

<dependency>
    <groupId>com.azure</groupId>
    <artifactId>azure-core</artifactId>
    <version>1.45.0</version>
</dependency>

Concepts clés

Les concepts clés d’Azure Core (et donc de toutes les bibliothèques clientes Azure utilisant Azure Core) sont les suivants :

• Configuration des clients de service, par exemple, configuration des nouvelles tentatives, journalisation, etc. (HttpTrait<T>, ConfigurationTrait<T>, etc.)
• Accès aux détails de la réponse HTTP (Response<T>).
• Appel d’opérations de longue durée (PollerFlux<T>).
• Pagination et flux asynchrones (ContinuablePagedFlux<T>).
• Exceptions pour la création de rapports d’erreurs à partir de demandes de service de manière cohérente.
• Abstractions pour la représentation des informations d’identification du Kit de développement logiciel (SDK) Azure.
• Délais d’expiration de l’opération

Celles-ci seront introduites au moyen des exemples présentés ci-dessous.

Exemples

Accès aux détails de la réponse HTTP à l’aide de Response<T>

Les clients de service ont des méthodes qui appellent des services Azure. Nous faisons référence à ces méthodes.

Les méthodes de service peuvent retourner un type Response<T>Azure Core partagé. Ce type fournit un accès à la fois au résultat désérialisé de l’appel de service et aux détails de la réponse HTTP retournée par le serveur.

Pipelines HTTP avec HttpPipeline

HttpPipeline est une construction qui contient une liste de HttpPipelinePolicy qui sont appliquées à une requête séquentiellement pour la préparer à être envoyée par un HttpClient.

Hiérarchie d’exceptions avec AzureException

AzureException est l’exception racine dans la hiérarchie utilisée dans Azure Core. Des exceptions supplémentaires telles que HttpRequestException et HttpResponseException sont utilisées pour réduire l’étendue des motifs d’exception.

Pagination avec ContinuablePagedFlux<T>

ContinuablePageFlux gère l’envoi d’une demande de page initiale à un service et la récupération de pages supplémentaires à mesure que le consommateur demande plus de données jusqu’à ce que le consommateur ait terminé le traitement ou que toutes les pages aient été consommées.

Opérations de longue durée avec PollerFlux<T>

PollerFlux gère l’envoi d’une demande de service initiale et la demande de traitement des mises à jour sur un intervalle de correction jusqu’à ce que l’interrogation soit annulée ou atteigne un état terminal.

Configuration des générateurs

Les générateurs sont utilisés pour créer des clients de service et certaines TokenCredential implémentations. Ils peuvent être configurés avec diverses options, notamment HttpPipeline et HttpClient pour les clients HTTP et des options plus générales telles que Configuration etendpoint . Pour permettre une intégration plus simple dans des frameworks tels que Spring et pour permettre l’utilisation de méthodes génériques pour tous les générateurs azure-core , fournit un ensemble d’interfaces qui peuvent être implémentées pour fournir les fonctionnalités nécessaires.

HttpTrait

HttpTrait<T> contient des méthodes pour définir des configurations de clés pour les clients HTTP. Cette interface vous permet de configurer , HttpClient, HttpPipelinePolicyHttpPipelines, RetryOptions, HttpLogOptionset ClientOptions (de préférenceHttpClientOptions, car il est plus spécifique pour les clients de service HTTP).

Pour les générateurs qui exposent HttpTrait<T>, si un HttpPipeline ou HttpClient n’est pas défini comme instance par défaut est créé en fonction des configurations classpath et du ClientOptions basé sur le générateur. Cela peut entraîner une confusion si vous attendez un comportement spécifique pour votre client, tel que l’utilisation d’un proxy qui n’a pas été chargé à partir de l’environnement. Pour éviter cela, il est recommandé de toujours définir ou HttpPipelineHttpClient dans tous les clients si vous générez si vos configurations ne sont pas basées sur l’environnement exécutant l’application.

Caractéristiques des informations d’identification

Azure Core fournit différentes informations d’identification pour l’authentification auprès des services Azure. Chaque type d’informations d’identification a une caractéristique correspondante qui peut être implémentée pour fournir les informations d’identification au générateur de client. Le tableau suivant répertorie les caractéristiques d’informations d’identification et le type d’informations d’identification correspondant.

Caractéristique des informations d’identification	Type d'informations d'identification
AzureKeyCredentialTrait	AzureKeyCredential
AzureNamedKeyCredentialTrait	AzureNamedKeyCredential
AzureSasCredentialTrait	AzureSasCredential
ConnectionStringCredentialTrait	String (il n’existe aucun type formel pour les chaînes de connexion)
KeyCredentialTrait	KeyCredential
TokenCredentialTrait	TokenCredential

ConfigurationTrait

ConfigurationTrait<T> permet de définir sur les Configuration clients de service. Configuration peut être utilisé pour transmettre un ensemble de comportements d’exécution au générateur de client, tels que le mode ProxyOptions de chargement à partir de l’environnement, la transmission implicite d’informations d’identification à certains générateurs de clients qui le prennent en charge, etc.

EndpointTrait

EndpointTrait<T> permet de définir le point de terminaison de service sur les clients de service.

Délais d’expiration de l’opération

Les kits SDK Azure fournissent quelques méthodes cohérentes pour configurer des délais d’expiration sur les appels d’API. Chaque délai d’expiration affecte une étendue différente des kits SDK Azure et de l’application appelante.

Délais d’expiration HTTP

Les délais d’expiration HTTP sont le niveau le plus bas de gestion du délai d’expiration fourni par les kits SDK Azure. Ces délais d’expiration peuvent être configurés lors de la génération HttpClientde ou de l’utilisation HttpClientOptions lors de la création de clients de service sans configurer vous-même HttpClient . Le tableau suivant répertorie le délai d’expiration HTTP, la méthode correspondante HttpClientOptions qui peut être utilisée pour le définir, la variable d’environnement pour contrôler la valeur par défaut, la valeur par défaut si la valeur d’environnement n’est pas définie et une brève description des effets du délai d’expiration.

Délai d’expiration HTTP	HttpClientOptions Méthode	Variable d’environnement	Valeur par défaut	Description
Connect Timeout	setConnectTimeout(Duration)	AZURE_REQUEST_CONNECT_TIMEOUT	10 secondes	Durée d’établissement d’une connexion avant l’expiration du délai d’attente.
Délai d’expiration de l’écriture	setWriteTimeout(Duration)	AZURE_REQUEST_WRITE_TIMEOUT	60 secondes	Durée entre chaque requête d’écriture des données sur le réseau avant l’expiration du délai d’attente.
Délai d’expiration de la réponse	setResponseTimeout(Duration)	AZURE_REQUEST_RESPONSE_TIMEOUT	60 secondes	Délai entre la fin de l’envoi de la demande et la réception des premiers octets de réponse avant l’expiration du délai d’attente.
Délai d’expiration de lecture	setReadTimeout(Duration)	AZURE_REQUEST_READ_TIMEOUT	60 secondes	Durée entre chaque données de réponse lues à partir du réseau avant l’expiration du délai d’attente.

Étant donné que ces délais d’expiration sont les plus proches du réseau, s’ils se déclenchent, ils sont propagés dans le HttpPipeline et doivent généralement faire l’objet d’une nouvelle tentative par le RetryPolicy.

Délais d’expiration httpPipeline

Les délais d’expiration HttpPipeline sont le niveau suivant de gestion du délai d’expiration fourni par les kits SDK Azure. Ces délais d’expiration sont configurés à l’aide d’un et d’un délai d’expiration HttpPipelinePolicy à l’aide de pour les Mono.timeout requêtes asynchrones ou d’un ExecutorService avec un chrono timed get(long, TimeUnit) pour les requêtes synchrones.

Selon l’emplacement dans , HttpPipelineces délais d’expiration peuvent être capturés par et RetryPolicy retentés. Si la stratégie de délai d’expiration est PER_RETRY (HttpPipelinePolicy.getPipelinePosition()), le délai d’expiration est capturé par le RetryPolicy car il sera positionné après le RetryPolicy, par conséquent, dans son étendue de capture, si elle tente à nouveau, la demande doit être gérée par la logique PER_CALL d’application.

Délais d’expiration du client de service

Les délais d’expiration du client de service sont le niveau le plus élevé de gestion du délai d’expiration fourni par les kits SDK Azure. Ces délais d’expiration sont configurés en passant Duration timeout dans des méthodes de service synchrones qui prennent en charge les délais d’expiration ou en utilisant Mono.timeout ou Flux.timeout sur des méthodes de service asynchrones.

Étant donné que ces délais d’expiration se trouvent sur l’appel d’API lui-même, ils ne peuvent pas être capturés par des mécanismes de nouvelle tentative dans les kits SDK Azure et doivent être gérés par la logique d’application.

Étapes suivantes

Prise en main des bibliothèques Azure créées à l’aide d’Azure Core.

Dépannage

Si vous rencontrez des bogues, envoyez des problèmes via GitHub Issues ou consultez StackOverflow pour le Kit de développement logiciel (SDK) Java Azure.

Activation de la journalisation

Les kits SDK Azure pour Java fournissent un article de journalisation cohérent pour faciliter la résolution des erreurs d’application et accélérer leur résolution. Les journaux produits capturent le flux d’une application avant d’atteindre l’état terminal pour faciliter la localisation du problème racine. Consultez la documentation de journalisation pour obtenir des conseils sur l’activation de la journalisation.

Journalisation des requêtes et des réponses HTTP

La journalisation des requêtes et des réponses HTTP peut être activée en définissant HttpLogDetailLevel dans le HttpLogOptions utilisé pour créer un client de service HTTP ou en définissant la variable d’environnement ou la propriété AZURE_HTTP_LOG_DETAIL_LEVELsystème . Le tableau suivant affiche les options valides pour AZURE_HTTP_LOG_DETAIL_LEVEL et le HttpLogDetailLevel avec lequel il est corrélé (les options valides ne respectent pas la casse) :

Valeur AZURE_HTTP_LOG_DETAIL_LEVEL	HttpLogDetailLevel Enum
basic	HttpLogDetailLevel.BASIC
headers	HttpLogDetailLevel.HEADERS
body	HttpLogDetailLevel.BODY
body_and_headers	HttpLogDetailLevel.BODY_AND_HEADERS
bodyandheaders	HttpLogDetailLevel.BODY_AND_HEADERS

Toutes les autres valeurs, ou valeurs non prises en HttpLogDetailLevel.NONEcharge, entraînent la désactivation de la journalisation des requêtes et des réponses HTTP. La journalisation doit être activée pour journaliser les requêtes et les réponses HTTP. La journalisation des en-têtes HTTP nécessite l’activation verbose de la journalisation. Le tableau suivant explique quelle journalisation est activée pour chaque HttpLogDetailLevel:

Valeur HttpLogDetailLevel	Journalisation activée
HttpLogDetailLevel.NONE	Aucune journalisation des requêtes ou des réponses HTTP
HttpLogDetailLevel.BASIC	Méthode de requête HTTP, code status réponse et URL de requête et de réponse
HttpLogDetailLevel.HEADERS	Tous les en-têtes de HttpLogDetailLevel.BASIC requête et de réponse si le niveau de journalisation est verbose
HttpLogDetailLevel.BODY	Tout le corps de la requête et de HttpLogDetailLevel.BASIC la réponse s’il est inférieur à 10 Ko
HttpLogDetailLevel.BODY_AND_HEADERS	HttpLogDetailLevel.HEADERS Tous les etHttpLogDetailLevel.BODY

Contribution

Pour plus d’informations sur la contribution à ce dépôt, consultez le guide de contribution.

1. Fourchez-le
2. Créer votre branche de fonctionnalité (git checkout -b my-new-feature)
3. Valider vos modifications (git commit -am 'Add some feature')
4. Envoyer (push) vers la branche (git push origin my-new-feature)
5. Créer une demande de tirage