Azure Core HTTP-Clientbibliothek für JavaScript – Version 1.19.0

Artikel
02/06/2025

Dies ist die Kern-HTTP-Pipeline für Azure SDK-JavaScript-Bibliotheken, die im Browser und Node.jsfunktionieren. Diese Bibliothek soll in erster Linie in Code verwendet werden, der von AutoRest- und autorest.typescriptgeneriert wird.

Erste Schritte

Anforderungen

Derzeit unterstützte Umgebungen

LTS-Versionen von Node.js
Neueste Versionen von Safari, Chrome, Edge und Firefox.

Weitere Informationen finden Sie in unserer Supportrichtlinie.

Installation

Dieses Paket wird in erster Linie in generierten Code verwendet und sollte nicht direkt von Endbenutzern genutzt werden.

Schlüsselkonzepte

PipelineRequest

Ein PipelineRequest beschreibt alle Informationen, die zum Senden einer Anforderung an einen HTTP-REST-Endpunkt erforderlich sind.

PipelineResponse

Ein PipelineResponse beschreibt die HTTP-Antwort (Textkörper, Header und Statuscode) von einem REST-Endpunkt, der nach der Erstellung einer HTTP-Anforderung zurückgegeben wurde.

SendRequest

Eine SendRequest-Methode ist eine Methode, die einem PipelineRequest asynchron eine PipelineResponsezurückgeben kann.

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

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

HttpClient

Ein HttpClient ist jedes Objekt, das die folgende Schnittstelle erfüllt, um eine SendRequest-Methode zu implementieren:

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

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

HttpClientwerden davon ausgegangen, dass die HTTP-Anforderung tatsächlich an einen Serverendpunkt gesendet wird, wobei hierfür ein plattformspezifischer Mechanismus verwendet wird.

Pipelinerichtlinien

Ein PipelinePolicy ist ein einfaches Objekt, das die folgende Schnittstelle implementiert:

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

Es ähnelt in Form HttpClient, enthält jedoch einen Richtliniennamen sowie eine leicht geänderte SendRequest Signatur, die es ermöglicht, die nächste Richtlinie in der Pipeline bedingt aufzurufen.

Man kann die Rolle von Richtlinien als die von middlewareanzeigen, ein Konzept, das NodeJS-Entwicklern vertraut ist, die mit Frameworks wie Expressgearbeitet haben.

Die sendRequest Implementierung kann sowohl die ausgehende Anforderung als auch die eingehende Antwort transformieren:

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

Die meisten Richtlinien betreffen sich nur mit der Anforderung oder der Antwort, aber es gibt einige Ausnahmen, z. B. die LogPolicy-, die Informationen aus den einzelnen Protokollen protokolliert.

Pipelines

Ein Pipeline ist ein Objekt, das eine Gruppe von PipelinePolicy Objekten verwaltet. Die Hauptfunktion besteht darin, sicherzustellen, dass Richtlinien in einer konsistenten und vorhersehbaren Reihenfolge ausgeführt werden.

Sie können sich vorstellen, dass Richtlinien wie ein Stapel angewendet werden (first-in/last-out).) Der erste PipelinePolicy kann die PipelineRequest vor allen anderen Richtlinien ändern, und es ist auch die letzte, die PipelineResponsezu ändern, wodurch sie dem Aufrufer am nächsten kommt. Die endgültige Richtlinie ist die letzte Möglichkeit, die ausgehende Anforderung zu ändern, und die erste, um die Antwort zu verarbeiten, wodurch sie dem Netzwerk am nächsten kommt.

Eine Pipeline erfüllt die folgende Schnittstelle:

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

Wie Sie sehen können, können Richtlinien hinzugefügt oder entfernt werden, und sie ist lose mit HttpClient gekoppelt, um die echte Anforderung an den Serverendpunkt auszuführen.

Ein wichtiges Konzept für Pipelineist, dass sie Richtlinien in geordnete Phasen gruppieren:

Serialisieren der Phase
Richtlinien, die nicht in einer Phase sind
Deserialisieren der Phase
Wiederholungsphase

Phasen treten in der obigen Reihenfolge auf, wobei zuerst Serialisierungsrichtlinien angewendet werden und Zuletzt angewendete Wiederholungsrichtlinien angewendet werden. Die meisten benutzerdefinierten Richtlinien fallen in den zweiten Bucket und erhalten keinen Phasennamen.

Beim Hinzufügen einer Richtlinie zur Pipeline können Sie nicht nur angeben, in welcher Phase sich eine Richtlinie befindet, sondern auch, wenn sie Abhängigkeiten hat:

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

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

beforePolicies sind Richtlinien, die die neue Richtlinie vor und afterPolicies Richtlinien sind, nach denen die neue Richtlinie ausgeführt werden muss. Ebenso bedeutet afterPhase, dass die Richtlinie erst ausgeführt werden muss, nachdem die angegebene Phase aufgetreten ist.

Diese Syntax ermöglicht es benutzerdefinierten Richtlinienautoren, alle erforderlichen Beziehungen zwischen ihren eigenen Richtlinien und den integrierten Richtlinien auszudrücken, die von @azure/core-rest-pipeline beim Erstellen einer Pipeline mit createPipelineFromOptionsbereitgestellt werden.

Implementierungen können Richtlinien auch anhand des Namens oder der Phase entfernen, falls sie eine vorhandene Pipeline ändern möchten, ohne eine neue mithilfe von createEmptyPipelineerstellen zu müssen. Die clone Methode ist besonders nützlich, wenn sie eine Pipeline neu erstellen, ohne das Original zu ändern.

Nachdem alle anderen Einschränkungen erfüllt wurden, werden Richtlinien in der Reihenfolge angewendet, in der sie hinzugefügt wurden.

Beispiele

Beispiele finden Sie im Ordner samples.

Nächste Schritte

Sie können die Tests lokal erstellen und ausführen, indem Sie rushx testausführen. Erkunden Sie den Ordner test, um die erweiterte Verwendung und das Verhalten der öffentlichen Klassen anzuzeigen.

Fehlerbehebung

Wenn bei der Verwendung dieser Bibliothek Probleme auftreten, Sie ein Problem.

Beitragend

Wenn Sie an dieser Bibliothek mitwirken möchten, lesen Sie bitte den mitwirkenden Leitfaden, um mehr über das Erstellen und Testen des Codes zu erfahren.

Freigeben über