Biblioteca de clientes HTTP do Azure Core para JavaScript – versão 1.11.0

  • Artigo

Esse é o pipeline do HTTP principal para bibliotecas JavaScript do SDK do Azure que funcionam no navegador e no Node.js. Essa biblioteca deve ser usada principalmente no código gerado pelo AutoRest e o autorest.typescript.

Introdução

Requisitos

Ambientes com suporte no momento

Confira nossa política de suporte para mais detalhes.

Instalação

Este pacote é usado principalmente no código gerado e não deve ser consumido diretamente pelos usuários finais.

Principais conceitos

PipelineRequest

Uma PipelineRequest descreve todas as informações necessárias para fazer uma solicitação a um ponto de extremidade REST HTTP.

PipelineResponse

A PipelineResponse descreve a resposta HTTP (corpo, cabeçalhos e código de status) de um ponto de extremidade REST que foi retornado após uma solicitação HTTP.

SendRequest

Um método SendRequest é aquele que ao receber uma PipelineRequest pode retornar um PipelineResponse de modo assíncrono.

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

HttpClient

Um HttpClient é qualquer objeto que satisfaça a seguinte interface para implementar um método SendRequest:

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

HttpClients são esperados para realmente fazer a solicitação HTTP a um ponto de extremidade de servidor usando algum mecanismo específico da plataforma.

Políticas de pipeline

Um PipelinePolicy é um objeto simples que implementa a seguinte interface:

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

Ele é semelhante ao formato de HttpClient, mas inclui um nome de política, bem como uma assinatura de SendRequest um pouco modificada que permite chamar a próxima política no pipeline de modo condicional.

É possível exibir a função das políticas como a de middleware, um conceito que é familiar para desenvolvedores do NodeJS que já trabalharam com estruturas como o Express.

A implementação de sendRequest pode transformar a solicitação de saída, bem como a resposta de entrada:

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

A maioria das políticas se preocupa apenas com a solicitação ou a resposta, mas há algumas exceções, como a LogPolicy, que registra informações de cada uma delas.

Pipelines

Um Pipeline é um objeto que gerencia um conjunto de objetos PipelinePolicy. Sua função principal é garantir que as políticas sejam executadas em uma ordem consistente e previsível.

Entenda as políticas sendo aplicadas como uma pilha (primeiro a entrar, último a sair). A primeira PipelinePolicy pode modificar a PipelineRequest antes de qualquer outra política e também é a última a modificar a PipelineResponse, aproximando-a do chamador. A política final é a última capaz de modificar a solicitação de saída e a primeira a processar a resposta, aproximando-a da rede.

O Pipeline satisfaz a seguinte interface:

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 você pode ver, ele permite que as políticas sejam adicionadas ou removidas e elas são fracamente associadas a HttpClient para executar a solicitação real ao ponto de extremidade de servidor.

Um conceito importante de Pipelines é que eles agrupam políticas em fases ordenadas:

  1. Fase de serialização
  2. Políticas que não estão em uma fase
  3. Fase de desserialização
  4. Fase de repetição

As fases ocorrem na ordem acima, com as políticas de serialização aplicadas primeiro e as políticas de repetição aplicadas por último. A maioria das políticas personalizadas se enquadra no segundo grupo e não recebe um nome de fase.

Ao adicionar uma política ao pipeline, você pode especificar em qual fase a política está e também se ela tem dependências:

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

beforePolicies: a nova política precisa ser executada antes dessas políticas. afterPolicies: a nova política precisa ocorrer depois dessas políticas. Da mesma forma, afterPhase significa que a política só pode ser executada após a fase especificada.

Essa sintaxe permite que autores de políticas personalizadas expressem as relações necessárias entre as próprias políticas e as políticas internas fornecidas por @azure/core-rest-pipeline ao criar um pipeline usando createPipelineFromOptions.

Os implementadores também podem remover políticas por nome ou fase, caso queiram modificar um Pipeline existente sem precisar criar outro usando createEmptyPipeline. O método clone é útil principalmente ao recriar um Pipeline sem modificar o original.

Depois que todas as outras restrições forem atendidas, as políticas serão aplicadas na ordem em que foram adicionadas.

Exemplos

Veja exemplos na pasta samples.

Próximas etapas

Você pode criar e executar os testes localmente executando rushx test. Explore a pasta test para ver o uso e o comportamento avançados das classes públicas.

Solução de problemas

Se você tiver problemas ao usar essa biblioteca, fique à vontade para registrar um problema.

Contribuição

Se você quiser contribuir com essa biblioteca, leia o guia de contribuição para saber como criar e testar o código.

Impressões