Azure Core HTTP-klientbibliotek för JavaScript – version 1.19.0

Artikel
02/06/2025

Detta är den centrala HTTP-pipelinen för Azure SDK JavaScript-bibliotek som fungerar i webbläsaren och Node.js. Det här biblioteket är främst avsett att användas i kod som genereras av AutoRest och autorest.typescript.

Komma igång

Krav

Miljöer som stöds för närvarande

LTS-versioner av Node.js
De senaste versionerna av Safari, Chrome, Edge och Firefox.

Mer information finns i vår supportprincip.

Installation

Det här paketet används främst i genererad kod och är inte avsett att användas direkt av slutanvändare.

Viktiga begrepp

PipelineRequest

En PipelineRequest beskriver all information som krävs för att göra en begäran till en HTTP REST-slutpunkt.

PipelineResponse

En PipelineResponse beskriver HTTP-svaret (brödtext, rubriker och statuskod) från en REST-slutpunkt som returnerades efter att ha gjort en HTTP-begäran.

SendRequest

En SendRequest-metod är en metod som med en PipelineRequest asynkront kan returnera en PipelineResponse.

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

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

HttpClient

Ett HttpClient är ett objekt som uppfyller följande gränssnitt för att implementera en SendRequest-metod:

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

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

HttpClients förväntas faktiskt göra HTTP-begäran till en serverslutpunkt, med hjälp av någon plattformsspecifik mekanism för att göra det.

Pipelineprinciper

En PipelinePolicy är ett enkelt objekt som implementerar följande gränssnitt:

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

Det liknar i form HttpClient, men innehåller ett principnamn samt en något ändrad SendRequest signatur som gör att den villkorligt kan anropa nästa princip i pipelinen.

Man kan se rollen för principer som för middleware, ett begrepp som är bekant för NodeJS-utvecklare som har arbetat med ramverk som Express.

Den sendRequest implementeringen kan både transformera den utgående begäran och det inkommande svaret:

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

De flesta principer handlar bara om begäran eller svaret, men det finns vissa undantag, till exempel LogPolicy som loggar information från var och en.

Rörledningar

En Pipeline är ett objekt som hanterar en uppsättning PipelinePolicy objekt. Dess huvudsakliga funktion är att säkerställa att principer körs i en konsekvent och förutsägbar ordning.

Du kan tänka dig att principer tillämpas som en stack (först in/sist ut.) Den första PipelinePolicy kan ändra PipelineRequest före andra principer, och det är också den sista som ändrar PipelineResponse, vilket gör den närmast anroparen. Den sista principen är den sista som kan ändra den utgående begäran och den första som hanterar svaret, vilket gör den närmast nätverket.

En Pipeline uppfyller följande gränssnitt:

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

Som du ser tillåter det att principer läggs till eller tas bort och det är löst kopplat till HttpClient för att utföra den verkliga begäran till serverslutpunkten.

Ett viktigt begrepp för Pipelineär att de grupperar principer i ordnade faser:

Serialisera fas
Principer som inte är i en fas
Deserialisera fas
Försök med fas igen

Faser sker i ovanstående ordning, med serialiseringsprinciper som tillämpas först och återförsöksprinciper som tillämpas sist. De flesta anpassade principer hamnar i den andra bucketen och får inte ett fasnamn.

När du lägger till en princip i pipelinen kan du ange inte bara vilken fas en princip finns i, utan även om den har några beroenden:

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

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

beforePolicies är principer som den nya principen måste köra före och afterPolicies är principer som den nya principen måste ske efter. På samma sätt innebär afterPhase att principen endast får köras efter att den angivna fasen har inträffat.

Med den här syntaxen kan anpassade principförfattare uttrycka alla nödvändiga relationer mellan sina egna principer och de inbyggda principer som tillhandahålls av @azure/core-rest-pipeline när du skapar en pipeline med hjälp av createPipelineFromOptions.

Implementerare kan också ta bort principer efter namn eller fas, om de vill ändra en befintlig Pipeline utan att behöva skapa en ny med hjälp av createEmptyPipeline. Metoden clone är särskilt användbar när du återskapar en Pipeline utan att ändra originalet.

När alla andra begränsningar har uppfyllts tillämpas principerna i den ordning som de lades till.

Exempel

Exempel finns i mappen samples.

Nästa steg

Du kan skapa och köra testerna lokalt genom att köra rushx test. Utforska mappen test för att se avancerad användning och beteende för de offentliga klasserna.

Felsökning

Om du stöter på problem när du använder det här biblioteket kan du fil ett problem.

Bidragande

Om du vill bidra till det här biblioteket kan du läsa bidragsguide för att lära dig mer om hur du skapar och testar koden.

Dela via