Delen via

Azure Core HTTP-clientbibliotheek voor JavaScript - versie 1.22.1

Dit is de belangrijkste HTTP-pijplijn voor Azure SDK JavaScript-bibliotheken die werken in de browser en Node.js. Deze bibliotheek is voornamelijk bedoeld om te worden gebruikt in code die wordt gegenereerd door AutoRest- en autorest.typescript.

Slag

Eisen

Momenteel ondersteunde omgevingen

Zie ons ondersteuningsbeleid voor meer informatie.

Installatie

Dit pakket wordt voornamelijk gebruikt in gegenereerde code en is niet bedoeld om rechtstreeks door eindgebruikers te worden gebruikt.

Sleutelbegrippen

Pijplijn Aanvraag

Een PipelineRequest beschrijft alle informatie die nodig is om een aanvraag naar een HTTP REST-eindpunt te verzenden.

Reactie op pijpleiding

Een PipelineResponse beschrijft het HTTP-antwoord (hoofdtekst, headers en statuscode) van een REST-eindpunt dat is geretourneerd na het maken van een HTTP-aanvraag.

Verzoek verzenden

Een SendRequest methode is een methode die een gegeven PipelineRequest asynchroon een PipelineResponsekan retourneren.

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

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

HttpClient

Een HttpClient is een object dat voldoet aan de volgende interface om een SendRequest methode te implementeren:

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

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

HttpClients worden verwacht de HTTP-aanvraag daadwerkelijk naar een servereindpunt te verzenden, met behulp van een platformspecifiek mechanisme om dit te doen.

Pijplijnbeleid

Een PipelinePolicy is een eenvoudig object dat de volgende interface implementeert:

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

Het is vergelijkbaar met HttpClient, maar bevat een beleidsnaam en een enigszins gewijzigde SendRequest handtekening waarmee het volgende beleid in de pijplijn voorwaardelijk kan worden aangeroepen.

U kunt de rol van beleid bekijken als die van middleware, een concept dat bekend is met NodeJS-ontwikkelaars die met frameworks hebben gewerkt, zoals Express.

De sendRequest-implementatie kan zowel de uitgaande aanvraag als het binnenkomende antwoord transformeren:

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 meeste beleidsregels maken zich alleen zorgen over de aanvraag of het antwoord, maar er zijn enkele uitzonderingen, zoals de LogPolicy- die informatie van elk beleid registreert.

Pijpleidingen

Een Pipeline is een object dat een set PipelinePolicy objecten beheert. De belangrijkste functie is ervoor te zorgen dat beleidsregels in een consistente en voorspelbare volgorde worden uitgevoerd.

U kunt beleidsregels zien die worden toegepast als een stack (first-in/last-out.) De eerste PipelinePolicy kan de PipelineRequest wijzigen vóór andere beleidsregels en het is ook de laatste om de PipelineResponsete wijzigen, waardoor deze het dichtst bij de beller ligt. Het laatste beleid is de laatste mogelijkheid om de uitgaande aanvraag te wijzigen en de eerste om het antwoord af te handelen, waardoor deze het dichtst bij het netwerk ligt.

Een Pipeline voldoet aan de volgende interface:

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

Zoals u kunt zien, kunnen beleidsregels worden toegevoegd of verwijderd en wordt het losjes gekoppeld aan HttpClient om de echte aanvraag naar het servereindpunt uit te voeren.

Een belangrijk concept voor Pipelines is dat ze beleidsregels groeperen in geordende fasen:

  1. Fase serialiseren
  2. Beleid niet in een fase
  3. Fase deserialiseren
  4. Fase opnieuw proberen

Fasen vinden plaats in de bovenstaande volgorde, waarbij eerst serialisatiebeleid wordt toegepast en beleidsregels voor opnieuw proberen als laatste worden toegepast. De meeste aangepaste beleidsregels vallen in de tweede bucket en krijgen geen fasenaam.

Wanneer u een beleid toevoegt aan de pijplijn, kunt u niet alleen opgeven in welke fase een beleid zich bevindt, maar ook als er afhankelijkheden zijn:

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

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

beforePolicies beleidsregels zijn die door het nieuwe beleid moeten worden uitgevoerd voordat en afterPolicies beleidsregels zijn die na het nieuwe beleid moeten plaatsvinden. Op dezelfde manier betekent afterPhase dat het beleid alleen moet worden uitgevoerd nadat de opgegeven fase is opgetreden.

Met deze syntaxis kunnen aangepaste beleidsauteurs alle benodigde relaties uitdrukken tussen hun eigen beleid en de ingebouwde beleidsregels die worden geleverd door @azure/core-rest-pipeline bij het maken van een pijplijn met behulp van createPipelineFromOptions.

Implementeerfuncties kunnen ook beleidsregels op naam of fase verwijderen, in het geval dat ze een bestaande Pipeline willen wijzigen zonder dat ze een nieuw beleid hoeven te maken met behulp van createEmptyPipeline. De methode clone is met name handig bij het opnieuw maken van een Pipeline zonder het origineel te wijzigen.

Nadat aan alle andere beperkingen is voldaan, worden beleidsregels toegepast in de volgorde waarin ze zijn toegevoegd.

Voorbeelden

Voorbeelden vindt u in de map samples.

Volgende stappen

U kunt de tests lokaal bouwen en uitvoeren door npm run testuit te voeren. Verken de map test om geavanceerd gebruik en gedrag van de openbare klassen te bekijken.

Probleemoplossing

Als u problemen ondervindt tijdens het gebruik van deze bibliotheek, kunt u gerust een probleem indienen.

Bijdragen

Als u een bijdrage wilt leveren aan deze bibliotheek, leest u de gids voor bijdragen voor meer informatie over het bouwen en testen van de code.