Biblioteca de cliente HTTP Core do Azure para JavaScript - versão 1.18.2

Artigo
01/09/2025

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

Primeiros passos

Requerimentos

Ambientes atualmente suportados

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

Consulte o nosso de política de suporte para obter mais detalhes.

Instalação

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

Conceitos-chave

PipelineRequest

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

PipelineResponse

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

SendRequest

Um método SendRequest é um método que dado um PipelineRequest pode retornar assincronamente um PipelineResponse.

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

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

HttpClient

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

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

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

Espera-se que HttpClients realmente façam a solicitação HTTP para um ponto de extremidade do servidor, usando algum mecanismo específico da plataforma para fazer isso.

Políticas de pipeline

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

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

A sua forma é semelhante à HttpClient, mas inclui um nome de política, bem como uma assinatura de SendRequest ligeiramente modificada que lhe permite chamar condicionalmente a próxima política no pipeline.

Pode-se ver o papel das políticas como o de middleware, um conceito que é familiar para desenvolvedores NodeJS que trabalharam com estruturas como Express.

A implementação sendRequest pode transformar tanto a solicitação de saída quanto a resposta de entrada:

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

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

Condutas

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

Você pode pensar em políticas sendo aplicadas como uma pilha (primeiro a entrar/último a sair). O primeiro PipelinePolicy é capaz de modificar o PipelineRequest antes de quaisquer outras políticas, e também é o último a modificar o PipelineResponse, tornando-o o mais próximo do chamador. A política final é a última capaz de modificar a solicitação de saída e a primeira a lidar com a resposta, tornando-a a mais próxima da rede.

Um Pipeline satisfaz a seguinte interface:

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

Como você pode ver, ele permite que as políticas sejam adicionadas ou removidas e é vagamente acoplado ao HttpClient para executar a solicitação real para o ponto de extremidade do servidor.

Um conceito importante para Pipelineé que eles agrupam as políticas em fases ordenadas:

Fase de serialização
Políticas que não estão em fase
Fase de desserialização
Fase de repetição

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

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

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

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

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

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

Os implementadores também podem remover políticas por nome ou fase, caso desejem modificar um Pipeline existente sem ter que criar um novo usando createEmptyPipeline. O método clone é particularmente útil ao recriar um Pipeline sem modificar o original.

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

Exemplos

Exemplos podem ser encontrados na pasta samples.

Próximos passos

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

Solução de problemas

Se você tiver problemas ao usar esta biblioteca, sinta-se à vontade para registrar um problema.

Contribuição

Se você 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