Libreria client HTTP di Azure Core per JavaScript - versione 1.0.0-beta.1

(Sperimentale)

Si tratta della pipeline HTTP di base per le librerie JavaScript di Azure SDK che funzionano nel browser e in Node.js. Questa libreria viene in genere usata nel codice generato da AutoRest e autorest.typescript.

Introduzione

Requisiti

Installazione

Questo pacchetto viene in genere usato nel codice generato e non è destinato a essere utilizzato direttamente dagli utenti finali.

Concetti chiave

PipelineRequest

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

PipelineResponse

PipelineResponse descrive la risposta HTTP (corpo, intestazioni e codice di stato) da un endpoint REST restituita dopo l'invio di una richiesta HTTP.

SendRequest

Un metodo SendRequest, dato un PipelineRequest oggetto, può restituire in modo asincrono un oggetto PipelineResponse.

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

HttpsClient

HttpsClient è un oggetto che soddisfa l'interfaccia seguente per implementare un metodo SendRequest:

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

Gli oggetti HttpsClient devono effettivamente inviare la richiesta HTTP a un endpoint del server, usando a tale scopo un meccanismo specifico della piattaforma.

Criteri per pipeline

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

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

Nella forma è simile a HttpsClient, ma include un nome di criterio 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 middleware, un concetto familiare agli sviluppatori NodeJS che hanno lavorato con framework come Express.

L'implementazione di sendRequest può trasformare sia la richiesta in uscita che la risposta in ingresso:

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 (response.status === 403) {
      // Do something special if this policy sees Forbidden
    }
    return result;
  }
};

La maggior parte dei criteri gestisce solo la richiesta o la risposta, ma esistono alcune eccezioni, ad esempio LogPolicy, che registrano le informazioni da entrambe.

Pipelines

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

Si potrebbe dire che i criteri vengono applicati come uno stack (first-in/last-out.) Il primo PipelinePolicy può modificare PipelineRequest prima degli altri criteri ed è anche l'ultimo a modificare PipelineResponse, essendo la più vicina al chiamante. Il criterio finale è l'ultimo in grado di modificare la richiesta in uscita e il primo a gestire la risposta, essendo la più vicina alla rete.

Pipeline soddisfa l'interfaccia seguente:

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

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

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

  1. Fase di serializzazione
  2. Criteri in nessuna fase
  3. Fase di deserializzazione
  4. Fase di ripetizione dei tentativi

Le fasi seguono l'ordine precedente, ovvero i criteri di serializzazione vengono applicati per primi e i criteri di ripetizione dei tentativi per ultimi. La maggior parte dei criteri personalizzati rientra nel secondo bucket e non viene assegnato loro alcun nome di fase.

Quando si aggiunge un criterio alla pipeline, è possibile specificare non solo la fase in cui si trova un criterio, ma anche se presenta dipendenze:

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

beforePolicies sono i criteri prima dei quali deve essere eseguito il nuovo criterio e afterPolicies sono i criteri dopo i quali deve verificarsi il nuovo criterio. 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-https durante la creazione di una pipeline tramite createPipelineFromOptions.

I responsabili dell'implementazione possono anche rimuovere i criteri in base al nome o alla fase, nel caso in cui vogliano modificare una Pipeline esistente senza doverne creare una nuova usando createEmptyPipeline. Il metodo clone è particolarmente utile quando si ricrea una Pipeline senza modificare l'originale.

Una volta soddisfatti tutti gli altri vincoli, i criteri vengono applicati nell'ordine in cui sono stati aggiunti.

Esempio

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.

Contributo

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

Impression

  • Last updated on