Azure Core HTTP-clientbibliotheek voor JavaScript - versie 1.11.0

Artikel
06/01/2023

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.

Aan de slag

Vereisten

Momenteel ondersteunde omgevingen

LTS-versies van Node.js
Nieuwste versies van Safari, Chrome, Edge en Firefox.

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.

Belangrijkste concepten

PipelineRequest

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

PipelineResponse

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

SendRequest

Een SendRequest methode is een methode die op basis van een PipelineRequest asynchroon een PipelineResponsekan retourneren.

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

HttpClient

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

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

HttpClientVan s wordt verwacht dat de HTTP-aanvraag daadwerkelijk naar een servereindpunt wordt verzonden, met behulp van een platformspecifiek mechanisme om dit te doen.

Pijplijnbeleid

Een PipelinePolicy is een eenvoudig object waarmee de volgende interface wordt geïmplementeerd:

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

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 zien als die van middleware, een concept dat bekend is bij NodeJS-ontwikkelaars die met frameworks zoals Express hebben gewerkt.

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

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

De meeste beleidsregels hebben alleen betrekking op de aanvraag of het antwoord, maar er zijn enkele uitzonderingen, zoals de LogPolicy die informatie van elk beleid registreert.

Pipelines

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 die de PipelineResponsewijzigt, waardoor deze het dichtst bij de aanroeper ligt. Het laatste beleid is het laatste beleid dat de uitgaande aanvraag kan wijzigen en het eerste dat het antwoord verwerkt, waardoor deze het dichtst bij het netwerk ligt.

A Pipeline voldoet aan de volgende interface:

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

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

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

Fase serialiseren
Beleid niet in een fase
Fase deserialiseren
Fase voor opnieuw proberen

Fasen vinden plaats in de bovenstaande volgorde, waarbij serialisatiebeleid het eerst wordt toegepast en beleid voor opnieuw proberen als laatste wordt 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 of het beleid afhankelijkheden heeft:

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

beforePolicies zijn beleidsregels die het nieuwe beleid eerder moet uitvoeren en afterPolicies zijn beleidsregels waarna het nieuwe beleid moet worden uitgevoerd. afterPhase Op dezelfde manier betekent dit dat het beleid alleen mag worden uitgevoerd nadat de opgegeven fase heeft plaatsgevonden.

Met deze syntaxis kunnen auteurs van aangepaste beleidsregels eventuele benodigde relaties tussen hun eigen beleid en de ingebouwde beleidsregels van @azure/core-rest-pipeline bij het maken van een pijplijn met .createPipelineFromOptions

Implementeerders kunnen ook beleid op naam of fase verwijderen, in het geval dat ze een bestaande Pipeline willen wijzigen zonder een nieuwe te hoeven maken met .createEmptyPipeline De clone methode 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 samples map.

Volgende stappen

U kunt de tests lokaal bouwen en uitvoeren door uit te rushx testvoeren. Verken de test map om geavanceerd gebruik en gedrag van de openbare klassen te bekijken.

Problemen oplossen

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

Bijdragen

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

Weergaven

Delen via