Klientská knihovna Azure Core HTTP pro JavaScript – verze 1.22.2

Toto je základní kanál HTTP pro javascriptové knihovny Azure SDK, které fungují v prohlížeči a Node.js. Tato knihovna je primárně určena k použití v kódu generovaném AutoRest a autorest.typescript.

Začínáme

Požadavky

Aktuálně podporovaná prostředí

• LTS verze Node.js
• Nejnovější verze Safari, Chrome, Edge a Firefox.

Další podrobnosti najdete v našich zásadách podpory .

Instalace

Tento balíček se primárně používá ve vygenerovaném kódu a nemá být využíván přímo koncovými uživateli.

Klíčové koncepty

Požadavek na potrubí

PipelineRequest popisuje všechny informace potřebné k provedení požadavku na koncový bod HTTP REST.

Reakce potrubí

PipelineResponse popisuje odpověď HTTP (tělo, hlavičky a stavový kód) z koncového bodu REST, který se vrátil po provedení požadavku HTTP.

Žádost o odeslání

Metoda SendRequest je metoda, která PipelineRequest může asynchronně vrátit PipelineResponse.

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

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

Protokol HttpClient

HttpClient je jakýkoli objekt, který splňuje následující rozhraní pro implementaci SendRequest metody:

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

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

očekává se, že HttpClientskutečně provede požadavek HTTP na koncový bod serveru pomocí některého mechanismu specifického pro platformu.

Zásady kanálu

PipelinePolicy je jednoduchý objekt, který implementuje následující rozhraní:

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

Podobá se HttpClient, ale obsahuje název zásady a mírně upravený podpis SendRequest, který umožňuje podmíněně volat další zásady v kanálu.

Můžete si prohlédnout roli zásad jako middleware, koncept, který je známý pro vývojáře NodeJS, kteří pracovali s architekturami, jako je Express.

Implementace sendRequest může transformovat odchozí požadavek i příchozí odpověď:

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

Většina zásad se týká pouze požadavku nebo odpovědi, ale existují některé výjimky, jako je LogPolicy, které protokolují informace z každého.

Pipelines

Pipeline je objekt, který spravuje sadu PipelinePolicy objektů. Její hlavní funkcí je zajistit, aby se zásady spouštěly v konzistentním a předvídatelném pořadí.

Zásady, které se používají, si můžete představit jako zásobník (first-in/last-out).) První PipelinePolicy je schopen upravit PipelineRequest před všemi dalšími zásadami a je také poslední úpravou PipelineResponse, takže je nejblíže volajícímu. Poslední zásadou je poslední možnost upravit odchozí požadavek a první, která bude zpracovávat odpověď, aby byla nejblíže k síti.

Pipeline splňuje následující rozhraní:

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 vidíte, umožňuje přidat nebo odebrat zásady a je volně svázán s HttpClient k provedení skutečného požadavku na koncový bod serveru.

Jedním z důležitých konceptů Pipelineje, že zásady seskupují do uspořádaných fází:

1. Fáze serializace
2. Zásady, které nejsou ve fázi
3. Fáze deserializace
4. Fáze opakování

Fáze probíhají ve výše uvedeném pořadí, přičemž zásady serializace se použijí jako první a opakujte použití zásad jako poslední. Většina vlastních zásad spadá do druhého kontejneru a nemá název fáze.

Při přidávání zásad do kanálu můžete určit nejen fázi, ve které se zásada nachází, ale také v případě, že má nějaké závislosti:

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

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

beforePolicies jsou zásady, které musí nová zásada spustit před a afterPolicies jsou zásady, ke kterým musí dojít po nové zásadě. Podobně afterPhase znamená, že zásady se musí spouštět až po dokončení zadané fáze.

Tato syntaxe umožňuje autorům vlastních zásad vyjádřit všechny nezbytné vztahy mezi vlastními zásadami a předdefinované zásady poskytované @azure/core-rest-pipeline při vytváření kanálu pomocí createPipelineFromOptions.

Implementátoři také můžou odebrat zásady podle názvu nebo fáze v případě, že chtějí upravit existující Pipeline, aniž by museli vytvořit novou pomocí createEmptyPipeline. Metoda clone je zvláště užitečná při opětovném vytvoření Pipeline beze změny originálu.

Po splnění všech ostatních omezení se zásady použijí v pořadí, v jakém byly přidány.

Příklady

Příklady najdete ve složce samples.

Další kroky

Testy můžete sestavit a spustit místně spuštěním npm run test. Prozkoumejte složku test a podívejte se na pokročilé využití a chování veřejných tříd.

Řešení problémů

Pokud při používání této knihovny narazíte na problémy, neváhejte vytvořit problém.

Přispívající

Pokud chcete přispívat do této knihovny, přečtěte si průvodce přispívání a přečtěte si další informace o vytváření a testování kódu.