Libreria client HTTP di Azure Core per JavaScript - versione 1.18.0

Articolo
11/16/2024

Si tratta della pipeline HTTP principale per le librerie JavaScript di Azure SDK che funzionano nel browser e Node.js. Questa libreria è destinata principalmente all'uso nel codice generato da AutoRest e autorest.typescript.

Introduttiva

Fabbisogno

Ambienti attualmente supportati

versioni LTS di Node.js
Versioni più recenti di Safari, Chrome, Edge e Firefox.

Per altri dettagli, vedere i criteri di supporto .

Installazione

Questo pacchetto viene usato principalmente nel codice generato e non deve essere utilizzato direttamente dagli utenti finali.

Concetti chiave

PipelineRequest

Un PipelineRequest descrive tutte le informazioni necessarie per effettuare una richiesta a un endpoint REST HTTP.

PipelineResponse

Un PipelineResponse descrive la risposta HTTP (corpo, intestazioni e codice di stato) da un endpoint REST restituito dopo aver effettuato una richiesta HTTP.

SendRequest

Un metodo SendRequest è un metodo che dato un PipelineRequest può restituire in modo asincrono un PipelineResponse.

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

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

HttpClient

Un HttpClient è qualsiasi oggetto che soddisfi l'interfaccia seguente per implementare un metodo SendRequest:

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

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

HttpClientdevono effettivamente effettuare la richiesta HTTP a un endpoint server, usando un meccanismo specifico della piattaforma per farlo.

Criteri della pipeline

Un PipelinePolicy è un oggetto semplice che implementa l'interfaccia seguente:

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

La forma è simile a HttpClient, ma include un nome di criteri e una firma SendRequest leggermente modificata che consente di chiamare in modo condizionale i criteri successivi nella pipeline.

È possibile visualizzare il ruolo dei criteri come quello di middleware, un concetto familiare agli sviluppatori NodeJS che hanno lavorato con framework come Express.

L'implementazione sendRequest può trasformare la richiesta in uscita e la risposta in ingresso:

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 maggior parte dei criteri riguarda solo la richiesta o la risposta, ma esistono alcune eccezioni, ad esempio il LogPolicy che registra le informazioni da ognuna.

Condutture

Un Pipeline è un oggetto che gestisce un set di oggetti PipelinePolicy. La sua funzione principale consiste nel garantire che i criteri vengano eseguiti in un ordine coerente e prevedibile.

È possibile considerare i criteri applicati come uno stack (first-in/last-out). Il primo PipelinePolicy è in grado di modificare il PipelineRequest prima di qualsiasi altro criterio ed è anche l'ultimo a modificare il PipelineResponse, rendendolo il più vicino al chiamante. Il criterio finale è l'ultimo in grado di modificare la richiesta in uscita e il primo per gestire la risposta, rendendolo il più vicino alla rete.

Un Pipeline soddisfa l'interfaccia seguente:

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

Come si può notare, consente di aggiungere o rimuovere i criteri ed è associato a HttpClient per eseguire la richiesta reale all'endpoint server.

Un concetto importante per Pipelineè che raggruppano i criteri in fasi ordinate:

Fase di serializzazione
Criteri non in una fase
Fase deserializzazione
Fase di ripetizione dei tentativi

Le fasi si verificano nell'ordine precedente, con i criteri di serializzazione applicati per primi e i criteri di ripetizione applicati per ultimo. La maggior parte dei criteri personalizzati rientra nel secondo bucket e non ha un nome di fase.

Quando si aggiungono criteri alla pipeline, è possibile specificare non solo la fase in cui si trovano i criteri, ma anche se presenta dipendenze:

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

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

beforePolicies sono criteri che i nuovi criteri devono essere eseguiti prima e afterPolicies sono criteri che i nuovi criteri devono essere eseguiti dopo. Analogamente, afterPhase indica che i criteri devono essere eseguiti solo dopo che si è verificata la fase specificata.

Questa sintassi consente agli autori di criteri personalizzati di esprimere le relazioni necessarie tra i propri criteri e i criteri predefiniti forniti da @azure/core-rest-pipeline durante la creazione di una pipeline usando createPipelineFromOptions.

Gli implementatori possono anche rimuovere i criteri in base al nome o alla fase, nel caso in cui desiderano modificare un Pipeline esistente senza dover crearne uno nuovo usando createEmptyPipeline. Il metodo clone è particolarmente utile quando si ricrea un Pipeline senza modificare l'originale.

Dopo aver soddisfatto tutti gli altri vincoli, i criteri vengono applicati nell'ordine in cui sono stati aggiunti.

Esempi

Gli esempi sono disponibili nella cartella samples.

Passaggi successivi

È possibile compilare ed eseguire i test in locale eseguendo rushx test. Esplorare la cartella test per visualizzare l'utilizzo e il comportamento avanzati delle classi pubbliche.

Risoluzione dei problemi

Se si verificano problemi durante l'uso di questa libreria, è possibile segnalare un problema.

Contribuire

Per contribuire a questa libreria, leggere la guida contribuire per altre informazioni su come compilare e testare il codice.

impressioni

Condividi tramite