Bibliothèque de client HTTP Azure Core pour JavaScript - version 1.18.0

Article
11/16/2024

Il s’agit du pipeline HTTP principal pour les bibliothèques JavaScript du Kit de développement logiciel (SDK) Azure qui fonctionnent dans le navigateur et Node.js. Cette bibliothèque est principalement destinée à être utilisée dans le code généré par autorest et autorest.typescript.

Commencer

Exigences

Environnements actuellement pris en charge

versions LTS de Node.js
Dernières versions de Safari, Chrome, Edge et Firefox.

Pour plus d’informations, consultez notre de stratégie de support .

Installation

Ce package est principalement utilisé dans le code généré et n’est pas destiné à être consommé directement par les utilisateurs finaux.

Concepts clés

PipelineRequest

Un PipelineRequest décrit toutes les informations nécessaires pour effectuer une requête à un point de terminaison REST HTTP.

PipelineResponse

Un PipelineResponse décrit la réponse HTTP (corps, en-têtes et code d’état) à partir d’un point de terminaison REST retourné après avoir effectué une requête HTTP.

SendRequest

Une méthode SendRequest est une méthode qui, en fonction d’un PipelineRequest, peut retourner de manière asynchrone un PipelineResponse.

import { PipelineRequest, PipelineResponse } from "@azure/core-rest-pipeline";

type SendRequest = (request: PipelineRequest) => Promise<PipelineResponse>;

HttpClient

Un HttpClient est n’importe quel objet qui satisfait à l’interface suivante pour implémenter une méthode SendRequest :

import { SendRequest } from "@azure/core-rest-pipeline";

interface HttpClient {
  /**
   * The method that makes the request and returns a response.
   */
  sendRequest: SendRequest;
}

HttpClients sont censés effectuer la requête HTTP vers un point de terminaison de serveur, à l’aide d’un mécanisme spécifique à la plateforme pour ce faire.

Stratégies de pipeline

Un PipelinePolicy est un objet simple qui implémente l’interface suivante :

import { PipelineRequest, SendRequest, PipelineResponse } from "@azure/core-rest-pipeline";

interface PipelinePolicy {
  /**
   * The policy name. Must be a unique string in the pipeline.
   */
  name: string;
  /**
   * The main method to implement that manipulates a request/response.
   * @param request - The request being performed.
   * @param next - The next policy in the pipeline. Must be called to continue the pipeline.
   */
  sendRequest(request: PipelineRequest, next: SendRequest): Promise<PipelineResponse>;
}

Il est similaire à HttpClient, mais inclut un nom de stratégie ainsi qu’une signature SendRequest légèrement modifiée qui lui permet d’appeler conditionnellement la stratégie suivante dans le pipeline.

On peut voir le rôle des stratégies comme celle de middleware, un concept familier aux développeurs NodeJS qui ont travaillé avec des frameworks tels que Express.

L’implémentation sendRequest peut transformer la requête sortante ainsi que la réponse entrante :

import { PipelineRequest, SendRequest, PipelineResponse } from "@azure/core-rest-pipeline";

const customPolicy = {
  name: "My wonderful policy",
  async sendRequest(request: PipelineRequest, next: SendRequest): Promise<PipelineResponse> {
    // Change the outgoing request by adding a new header
    request.headers.set("X-Cool-Header", 42);
    const result = await next(request);
    if (result.status === 403) {
      // Do something special if this policy sees Forbidden
    }
    return result;
  },
};

La plupart des stratégies se préoccupent uniquement de la demande ou de la réponse, mais il existe certaines exceptions telles que la LogPolicy qui journalise les informations de chacun d’eux.

Pipelines

Un Pipeline est un objet qui gère un ensemble d’objets PipelinePolicy. Sa fonction principale est de s’assurer que les stratégies sont exécutées dans un ordre cohérent et prévisible.

Vous pouvez considérer les stratégies appliquées comme une pile (première entrée/dernière sortie).) La première PipelinePolicy est en mesure de modifier le PipelineRequest avant toute autre stratégie, et il est également le dernier à modifier le PipelineResponse, en le rendant le plus proche de l’appelant. La stratégie finale est la dernière en mesure de modifier la requête sortante et la première à gérer la réponse, ce qui en fait le plus proche du réseau.

Un Pipeline satisfait à l’interface suivante :

import {
  PipelinePolicy,
  AddPipelineOptions,
  PipelinePhase,
  HttpClient,
  PipelineRequest,
  PipelineResponse,
} from "@azure/core-rest-pipeline";

interface Pipeline {
  addPolicy(policy: PipelinePolicy, options?: AddPipelineOptions): void;
  removePolicy(options: { name?: string; phase?: PipelinePhase }): PipelinePolicy[];
  sendRequest(httpClient: HttpClient, request: PipelineRequest): Promise<PipelineResponse>;
  getOrderedPolicies(): PipelinePolicy[];
  clone(): Pipeline;
}

Comme vous pouvez le voir, il permet d’ajouter ou de supprimer des stratégies et il est faiblement couplé avec HttpClient pour effectuer la demande réelle sur le point de terminaison du serveur.

Un concept important pour les Pipelineest qu’ils regroupent des stratégies en phases ordonnées :

Sérialiser la phase
Stratégies non en phase
Désérialiser la phase
Phase de nouvelle tentative

Les phases se produisent dans l’ordre ci-dessus, avec les stratégies de sérialisation appliquées en premier et les stratégies de nouvelle tentative appliquées en dernier. La plupart des stratégies personnalisées entrent dans le deuxième compartiment et ne reçoivent pas de nom de phase.

Lors de l’ajout d’une stratégie au pipeline, vous pouvez spécifier non seulement la phase dans laquelle se trouve une stratégie, mais également si elle a des dépendances :

import { PipelinePhase } from "@azure/core-rest-pipeline";

interface AddPipelineOptions {
  beforePolicies?: string[];
  afterPolicies?: string[];
  afterPhase?: PipelinePhase;
  phase?: PipelinePhase;
}

beforePolicies sont des stratégies que la nouvelle stratégie doit exécuter avant et afterPolicies sont des stratégies que la nouvelle stratégie doit se produire après. De même, afterPhase signifie que la stratégie ne doit s’exécuter qu’après la phase spécifiée.

Cette syntaxe permet aux auteurs de stratégies personnalisés d’exprimer toutes les relations nécessaires entre leurs propres stratégies et les stratégies intégrées fournies par @azure/core-rest-pipeline lors de la création d’un pipeline à l’aide de createPipelineFromOptions.

Les implémenteurs peuvent également supprimer des stratégies par nom ou par phase, dans le cas où ils souhaitent modifier un Pipeline existant sans avoir à en créer un à l’aide de createEmptyPipeline. La méthode clone est particulièrement utile lors de la recréation d’un Pipeline sans modifier l’original.

Une fois toutes les autres contraintes satisfaites, les stratégies sont appliquées dans l’ordre dans lequel elles ont été ajoutées.

Exemples

Vous trouverez des exemples dans le dossier samples.

Étapes suivantes

Vous pouvez générer et exécuter les tests localement en exécutant rushx test. Explorez le dossier test pour voir l’utilisation et le comportement avancés des classes publiques.

Dépannage

Si vous rencontrez des problèmes lors de l’utilisation de cette bibliothèque, n’hésitez pas à fichier un problème.

Contribuant

Si vous souhaitez contribuer à cette bibliothèque, lisez le guide de contribution pour en savoir plus sur la génération et le test du code.

Impressions

Partager via