Biblioteka klienta HTTP platformy Azure Core dla języka JavaScript — wersja 1.0.0-beta.1

(Eksperymentalne)

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 funkcję AutoRest i autorest.typescript.

Wprowadzenie

Wymagania

• Node.js w wersji > 8.x

Instalacja

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

Kluczowe pojęcia

PipelineRequest

Element opisuje PipelineRequest wszystkie informacje niezbędne do wykonania żądania do punktu końcowego REST PROTOKOŁU HTTP.

PipelineResponse

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

SendRequest

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

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

HttpsClient

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

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

HttpsClientOczekuje się, że żądania HTTP do punktu końcowego serwera zostaną rzeczywiście skierowane do punktu końcowego serwera przy użyciu mechanizmu specyficznego dla danej platformy.

Zasady potoku

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

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

Jest ona podobna do HttpsClient, 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 middlewarekoncepcji znanej deweloperom nodeJS, którzy pracowali z platformami, takimi jak Express.

Implementacja sendRequest może przekształcać żądanie wychodzące, a także odpowiedź przychodzącą:

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

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

Pipelines

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

Zasady można traktować jako stos (pierwszy/ostatni).) Pierwszy PipelinePolicy jest w stanie zmodyfikować PipelineRequest element przed wszelkimi innymi zasadami, a także ostatni, aby zmodyfikować PipelineResponseelement , co czyni go najbliżej elementu wywołującego. Ostatnie zasady są ostatnią w stanie zmodyfikować żądanie wychodzące, a pierwszy do obsługi odpowiedzi, co czyni je najbliżej sieci.

Interfejs Pipeline spełnia następujące wymagania:

export interface Pipeline {
  addPolicy(policy: PipelinePolicy, options?: AddPolicyOptions): void;
  removePolicy(options: { name?: string; phase?: PipelinePhase }): PipelinePolicy[];
  sendRequest(httpsClient: HttpsClient, request: PipelineRequest): Promise<PipelineResponse>;
  getOrderedPolicies(): PipelinePolicy[];
  clone(): Pipeline;
}

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

Jedną z ważnych koncepcji jest Pipelineto, że grupują zasady w uporządkowane fazy:

1. Serializacja fazy
2. Zasady nie są w fazie
3. Deserializacja 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:

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

beforePolicies są zasadami, które nowe zasady muszą zostać wykonane przed i afterPolicies są zasadami, które należy wykonać po nowych zasadach. Podobnie oznacza, afterPhase ż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 podczas @azure/core-https tworzenia potoku przy użyciu polecenia createPipelineFromOptions.

Implementatory mogą również usuwać zasady według nazwy lub fazy, w przypadku gdy chcą zmodyfikować istniejący Pipeline bez konieczności tworzenia nowego przy użyciu polecenia createEmptyPipeline. Metoda jest szczególnie przydatna clone podczas ponownego tworzenia Pipeline elementu 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 polecenie rushx test. Zapoznaj się z folderem, test aby wyświetlić 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.

Współtworzenie

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