Biblioteka klienta HTTP platformy Azure Core dla języka JavaScript — wersja 1.18.2

Jest to podstawowy potok HTTP dla bibliotek JavaScript zestawu Azure SDK, które działają w przeglądarce i Node.js. Ta biblioteka ma być używana głównie w kodzie generowanym przez autorest i autorest.typescript.

Wprowadzenie

Wymagania

Obecnie obsługiwane środowiska

• wersje Node.js LTS
• Najnowsze wersje przeglądarek Safari, Chrome, Edge i Firefox.

Aby uzyskać więcej informacji, zobacz nasze zasad pomocy technicznej.

Instalacja

Ten pakiet jest używany głównie w generowanym kodzie i nie jest przeznaczony do bezpośredniego użycia przez użytkowników końcowych.

Kluczowe pojęcia

PipelineRequest

W PipelineRequest opisano wszystkie informacje niezbędne do wykonania żądania do punktu końcowego REST HTTP.

PipelineResponse

PipelineResponse opisuje odpowiedź HTTP (treść, nagłówki i kod stanu) z punktu końcowego REST, który został zwrócony po wykonaniu żądania HTTP.

SendRequest

Metoda SendRequest to metoda, która z PipelineRequest może asynchronicznie zwracać PipelineResponse.

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

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

HttpClient

HttpClient to dowolny obiekt, który spełnia następujący interfejs, aby zaimplementować metodę SendRequest:

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

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

HttpClientoczekuje się, że żądanie HTTP do punktu końcowego serwera zostanie faktycznie skierowane do punktu końcowego serwera przy użyciu pewnego mechanizmu specyficznego dla platformy.

Zasady potoku

PipelinePolicy to prosty obiekt, który implementuje następujący interfejs:

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

Jest on podobny do HttpClient, ale zawiera nazwę zasad, a także nieco zmodyfikowany SendRequest podpis, który umożliwia warunkowe wywołanie następnych zasad w potoku.

Można wyświetlić rolę zasad jako zasady middleware, pojęcie znane deweloperom środowiska NodeJS, którzy pracowali z platformami, takimi jak Express.

Implementacja sendRequest może zarówno przekształcić żądanie wychodzące, jak i odpowiedź przychodzącą:

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

Większość zasad dotyczy tylko żądania lub odpowiedzi, ale istnieją pewne wyjątki, takie jak LogPolicy, które rejestrują informacje z każdej z nich.

Rurociągów

Pipeline to obiekt, który zarządza zestawem obiektów PipelinePolicy. Jej główną funkcją jest zapewnienie, że zasady są wykonywane w spójnej i przewidywalnej kolejności.

Zasady można traktować jak stos (pierwszy w/ostatni). Pierwsza PipelinePolicy jest w stanie zmodyfikować PipelineRequest przed innymi zasadami, a także ostatnią, aby zmodyfikować PipelineResponse, co sprawia, że znajduje się najbliżej elementu wywołującego. Ostateczne zasady są ostatnią w stanie zmodyfikować żądanie wychodzące, a pierwszy do obsługi odpowiedzi, co sprawia, że znajduje się najbliżej sieci.

Pipeline spełnia następujący interfejs:

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

Jak widać, umożliwia dodawanie lub usuwanie zasad i luźno powiązane z HttpClient wykonywanie rzeczywistego żądania do punktu końcowego serwera.

Jedną z ważnych koncepcji Pipelinejest grupowanie zasad w uporządkowanych fazach:

1. Serializowanie fazy
2. Zasady nie są w fazie
3. Deserializowanie fazy
4. Faza ponawiania prób

Fazy występują w powyższej kolejności, a zasady serializacji są stosowane najpierw, a zasady ponawiania są stosowane ostatnio. Większość zasad niestandardowych należy do drugiego zasobnika i nie ma nazwy fazy.

Podczas dodawania zasad do potoku można określić nie tylko fazę, w której znajduje się zasada, ale także jeśli ma jakiekolwiek zależności:

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

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

beforePolicies to zasady, które należy wykonać przed i afterPolicies są zasadami, po których muszą nastąpić nowe zasady. Podobnie afterPhase oznacza, że zasady muszą być wykonywane tylko po wystąpieniu określonej fazy.

Ta składnia umożliwia autorom zasad niestandardowych wyrażanie wszelkich niezbędnych relacji między własnymi zasadami a wbudowanymi zasadami udostępnianymi przez @azure/core-rest-pipeline podczas tworzenia potoku przy użyciu createPipelineFromOptions.

Implementatory mogą również usuwać zasady według nazwy lub fazy, w przypadku gdy chcą zmodyfikować istniejącą Pipeline bez konieczności tworzenia nowego przy użyciu createEmptyPipeline. Metoda clone jest szczególnie przydatna podczas ponownego tworzenia Pipeline bez modyfikowania oryginału.

Po spełnieniu wszystkich innych ograniczeń zasady są stosowane w kolejności, w której zostały dodane.

Przykłady

Przykłady można znaleźć w folderze samples.

Następne kroki

Testy można kompilować i uruchamiać lokalnie, wykonując rushx test. Zapoznaj się z folderem test, aby zobaczyć zaawansowane użycie i zachowanie klas publicznych.

Rozwiązywanie problemów

Jeśli wystąpią problemy podczas korzystania z tej biblioteki, możesz zgłosić problem.

Przyczyniając się

Jeśli chcesz współtworzyć tę bibliotekę, przeczytaj przewodnik dotyczący współtworzenia , aby dowiedzieć się więcej na temat tworzenia i testowania kodu.