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

Artigo
11/16/2024

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

Introdução

Requisitos

Ambientes com suporte no momento

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

Consulte nossa política de suporte para obter mais detalhes.

Instalação

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

Principais conceitos

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 após fazer uma solicitação HTTP.

SendRequest

Um método SendRequest é um método que, dado um PipelineRequest, pode retornar de forma assíncrona 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 HttpClientfaça 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>;
}

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

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

A implementação do sendRequest pode transformar a solicitação de saída, bem como 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 informações de cada um.

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.

Você pode pensar em políticas que estão sendo aplicadas como uma pilha (primeiro a entrar/último a sair).) O primeiro PipelinePolicy é capaz de modificar o PipelineRequest antes de qualquer outra política 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 elas são fracamente acopladas a HttpClient executar a solicitação real para o ponto de extremidade do servidor.

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

Fase serializar
Políticas não em uma fase
Desserializar fase
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 se enquadra no segundo bucket e não recebem um nome de fase.

Ao adicionar uma política ao pipeline, você pode especificar não apenas em qual fase uma política está, mas também se ela tiver 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 ocorrer depois. Da mesma forma, afterPhase significa que a política só deve ser executada após a fase especificada.

Essa sintaxe permite que os autores de políticas personalizadas expressem as relações necessárias entre suas 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 desejem modificar uma Pipeline existente sem precisar criar uma nova usando createEmptyPipeline. O método clone é particularmente útil 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

Exemplos podem ser encontrados na pasta samples.

Próximas etapas

Você pode compilar 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.

Solucionando problemas

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

Contribuindo

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

impressões

Compartilhar via