Share via

Biblioteca cliente HTTP de Azure Core para JavaScript: versión 1.11.0

  • Artículo

Esta es la canalización HTTP principal para las bibliotecas de JavaScript del SDK de Azure que funcionan en el explorador y Node.js. Esta biblioteca está pensada principalmente para usarse en el código generado por AutoRest y autorest.typescript.

Introducción

Requisitos

Entornos admitidos actualmente

Para más información, consulte la directiva de compatibilidad.

Instalación

Este paquete se usa principalmente en el código generado y no está pensado para que lo consuman directamente los usuarios finales.

Conceptos clave

PipelineRequest

Un PipelineRequest describe toda la información necesaria para realizar una solicitud a un punto de conexión REST HTTP.

PipelineResponse

Un PipelineResponse describe la respuesta HTTP (cuerpo, encabezados y código de estado) de un punto de conexión REST que se devolvió después de realizar una solicitud HTTP.

SendRequest

Un método SendRequest es un método que, si se proporciona un objeto PipelineRequest, puede devolver de forma asincrónica un PipelineResponse.

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

HttpClient

Un HttpClient es cualquier objeto que satisface la siguiente interfaz para implementar un método SendRequest:

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

se espera que los HttpClient realicen la solicitud HTTP a un punto de conexión de servidor mediante algún mecanismo específico de la plataforma.

Directivas de canalización

Un PipelinePolicy es un objeto simple que implementa la interfaz siguiente:

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

Es similar en forma a HttpClient, pero incluye un nombre de directiva, así como una firma de SendRequest ligeramente modificada que le permite llamar condicionalmente a la siguiente directiva de la canalización.

Podríamos pensar en la función de las directivas como la de middleware, un concepto que es familiar para los desarrolladores de NodeJS que han trabajado con marcos como Express.

La implementación de sendRequest puede transformar la solicitud saliente, así como la respuesta entrante:

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 mayoría de las directivas solo se centran en la solicitud o la respuesta, pero hay algunas excepciones, como LogPolicy, que registra información de cada una.

Pipelines

Una Pipeline es un objeto que administra un conjunto de objetos PipelinePolicy. Su función principal es asegurarse de que las directivas se ejecutan en un orden coherente y predecible.

Podemos decir que las directivas se aplican como una pila (primera en entrar, última en salir). La primera PipelinePolicy es capaz de modificar a la PipelineRequest antes que cualquier otra política, y también es la última en modificar la PipelineResponse, lo que la convierte en la más cercana al autor de la llamada. La directiva final es la última capaz de modificar la solicitud saliente y la primera en controlar la respuesta, lo que la convierte en la más cercana a la red.

Un Pipeline satisface la siguiente interfaz:

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

Como puede ver, permite agregar o quitar directivas y se acopla de forma flexible con HttpClient para realizar la solicitud real al punto de conexión del servidor.

Un concepto importante de las Pipelines es que agrupan directivas en fases ordenadas:

  1. Fase de serialización
  2. Directivas que no están en una fase
  3. Fase de deserialización
  4. Fase de reintento

Las fases se producen en el orden anterior: las directivas de serialización se aplican primero y las directivas de reintento se aplican en último lugar. La mayoría de las directivas personalizadas se clasifican en la segunda categoría y no se les asigna ningún nombre de fase.

Al agregar una directiva a la canalización, no solo puede especificar en qué fase se encuentra, sino también si tiene dependencias:

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

beforePolicies son directivas que la nueva directiva debe ejecutar antes y afterPolicies son directivas que la nueva directiva debe ejecutar después. De forma similar, afterPhase significa que la directiva solo debe ejecutarse después de que haya tenido lugar la fase especificada.

Esta sintaxis permite a los autores de directivas personalizadas expresar las relaciones necesarias entre sus propias directivas y las directivas integradas que proporciona @azure/core-rest-pipeline al crear una canalización mediante createPipelineFromOptions.

Los implementadores también pueden eliminar directivas por nombre o fase, en caso de que deseen modificar una Pipeline existente sin tener que crear una nueva mediante createEmptyPipeline. El método clone es especialmente útil para volver a crear una Pipeline sin modificar la original.

Una vez que se han cumplido todas las demás restricciones, las directivas se aplican en el orden en que se agregaron.

Ejemplos

Se pueden encontrar ejemplos en la carpeta samples.

Pasos siguientes

Puede compilar y ejecutar las pruebas localmente ejecutando rushx test. Explore la carpeta test para ver el uso avanzado y el comportamiento de las clases públicas.

Solución de problemas

Si tiene problemas al usar esta biblioteca, no dude en presentar un problema.

Contribuciones

Si desea contribuir a esta biblioteca, lea la guía de contribución para obtener más información sobre cómo compilar y probar el código.

Impresiones