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

Artigo
06/01/2023

Este é o pipeline HTTP principal para bibliotecas JavaScript do SDK do Azure que funcionam no browser e Node.js. Esta biblioteca destina-se principalmente a ser utilizada no código gerado pelo AutoRest e autorest.typescript.

Introdução

Requisitos

Ambientes atualmente suportados

Versões LTS do Node.js
Versões mais recentes do Safari, Chrome, Edge e Firefox.

Veja a nossa política de suporte para obter mais detalhes.

Instalação

Este pacote é utilizado principalmente no código gerado e não se destina a ser consumido diretamente pelos utilizadores finais.

Conceitos-chave

PipelineRequest

A PipelineRequest descreve todas as informações necessárias para fazer um pedido a um ponto final REST HTTP.

PipelineResponse

A PipelineResponse descreve a resposta HTTP (corpo, cabeçalhos e código de estado) de um ponto final REST que foi devolvido após fazer um pedido HTTP.

EnviarRequest

Um SendRequest método é um método que, tendo em conta uma PipelineRequest pode devolver assíncronamente um PipelineResponse.

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

HttpClient

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

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

HttpClientespera-se que o s faça o pedido HTTP para um ponto final de servidor, utilizando algum mecanismo específico da plataforma para o fazer.

Políticas de Pipeline

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

É semelhante em forma a HttpClient, mas inclui um nome de política, bem como uma assinatura ligeiramente modificada SendRequest que lhe permite chamar condicionalmente a política seguinte no pipeline.

Pode-se ver a função das políticas como a do middleware, um conceito que é familiar para os programadores do NodeJS que trabalharam com arquiteturas como o Express.

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

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 preocupa-se apenas com o pedido ou com a resposta, mas existem algumas exceções, como o LogPolicy , que regista informações de cada uma.

Pipelines

A Pipeline é um objeto que gere um conjunto de PipelinePolicy objetos. A função principal é garantir que as políticas são executadas por uma ordem consistente e previsível.

Pode pensar nas políticas que estão a ser aplicadas como uma pilha (primeiro/último a sair.) A primeira PipelinePolicy é capaz de modificar as PipelineRequest políticas anteriores e também é a última a modificar o PipelineResponse, tornando-o o mais próximo do autor da chamada. A política final é a última capaz de modificar o pedido de envio e a primeira a processar a resposta, tornando-a a mais próxima da rede.

A 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 pode ver, permite que as políticas sejam adicionadas ou removidas e é vagamente associada HttpClient a para efetuar o pedido real para o ponto final do servidor.

Um conceito importante para Pipelines é agrupar políticas em fases ordenadas:

Serializar Fase
As políticas não estão numa fase
Desserializar Fase
Fase de Repetição

As fases ocorrem na ordem acima, com as políticas de serialização a serem aplicadas primeiro e as políticas de repetição a serem aplicadas pela última vez. A maioria das políticas personalizadas enquadra-se no segundo registo e não é atribuído um nome de fase.

Ao adicionar uma política ao pipeline, pode especificar não só em que fase está uma política, mas também se tiver dependências:

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

beforePolicies são políticas que a nova política tem de executar antes e afterPolicies são políticas que a nova política tem de acontecer depois. Da mesma forma, afterPhase significa que a política só tem de ser executada após a fase especificada ter ocorrido.

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

Os implementadores também podem remover políticas por nome ou fase, caso pretendam modificar uma existente Pipeline sem terem de criar uma nova com createEmptyPipeline. O clone método é particularmente útil ao recriar um Pipeline sem modificar o original.

Depois de todas as outras restrições terem sido cumpridas, as políticas são aplicadas pela ordem em que foram adicionadas.

Exemplos

Podem ser encontrados exemplos na samples pasta.

Passos seguintes

Pode criar e executar os testes localmente ao executar rushx test. Explore a test pasta para ver a utilização e o comportamento avançados das classes públicas.

Resolução de problemas

Se tiver problemas ao utilizar esta biblioteca, não hesite em apresentar um problema.

Contribuir

Se quiser contribuir para esta biblioteca, leia o guia de contribuição para saber mais sobre como criar e testar o código.

Impressões

Partilhar via