Klientská knihovna AZURE Core HTTP pro JavaScript – verze 1.11.0

Článek
06/01/2023

Toto je základní kanál HTTP pro javascriptové knihovny sady Azure SDK, které fungují v prohlížeči a Node.js. Tato knihovna je primárně určena pro 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 prohlížečů 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 není určen k přímému využívání koncovými uživateli.

Klíčové koncepty

Žádost o kanál

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

PipelineResponse

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

Odeslat žádost

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

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

HttpClient

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

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

HttpClientOčekává se, že skutečně vytvoří požadavek HTTP na koncový bod serveru, a to pomocí mechanismu specifického pro platformu.

Zásady kanálu

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

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

Má podobný tvar HttpClientjako , ale obsahuje název zásady i mírně upravený SendRequest podpis, který umožňuje podmíněné volání další zásady v kanálu.

Roli zásad middlewaremůžete považovat za koncept , který znají vývojáři NodeJS, kteří pracovali s architekturami, jako je Express.

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

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

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

Pipelines

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

Použití zásad si můžete představit jako zásobník (první příchozí a poslední out). První PipelinePolicy je schopen upravit PipelineRequest před jakékoli jiné zásady a je také poslední, který upraví PipelineResponse, takže je nejblíže volajícímu. Poslední zásada je poslední, která může upravit odchozí požadavek, a první, která zpracuje odpověď, takže je nejblíže k síti.

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

export interface Pipeline {
  addPolicy(policy: PipelinePolicy, options?: AddPolicyOptions): 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řidávat nebo odebírat zásady a volně se s HttpClient ní provádějí, aby bylo možné provést skutečný požadavek na koncový bod serveru.

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

Fáze serializace
Zásady nejsou ve fázi
Fáze deserializace
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 zásady opakování se použijí 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 to, v jaké fázi se zásada nachází, ale také jestli má nějaké závislosti:

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

beforePolicies jsou zásady, které musí nová zásada provést před, a afterPolicies jsou to zásady, po které se nová zásada musí provést. Podobně to znamená, afterPhase že zásady se musí spustit až po uplynutí zadané fáze.

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

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

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 rushx testpříkazu . test Prozkoumejte složku a podívejte se na pokročilé využití a chování veřejných tříd.

Řešení potíží

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

Přispívání

Pokud chcete přispívat do této knihovny, přečtěte si příručku pro přispívání , kde najdete další informace o tom, jak sestavit a otestovat kód.

Imprese

Sdílet prostřednictvím