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

Artikel
06/01/2023

Dies ist die HTTP-Kernpipeline für JavaScript-Bibliotheken im Azure SDK, die im Browser und in Node.js funktionieren. Diese Bibliothek ist in erster Linie für Code gedacht, der von AutoRest und autorest.typescript generiert wird.

Erste Schritte

Requirements (Anforderungen)

Die derzeitig unterstützten Umgebungen

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

Ausführlichere Informationen finden Sie in der Supportrichtlinie.

Installation

Dieses Paket wird in erster Linie in generiertem Code verwendet und ist nicht für die direkte Nutzung durch Endbenutzer gedacht.

Wichtige Begriffe

PipelineRequest

PipelineRequest beschreibt alle Informationen, die notwendig sind, um eine Anforderung an einen HTTP-REST-Endpunkt zu stellen.

PipelineResponse

PipelineResponse beschreibt die HTTP-Antwort (Rumpf, Header und Statuscode) eines REST-Endpunkts, die nach der Erstellung einer HTTP-Anforderung zurückgegeben wurde.

SendRequest

Eine SendRequest-Methode ist eine Methode, die bei Angabe von PipelineRequest asynchron PipelineResponse zurückgeben kann.

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

HttpClient

HttpClient ist ein beliebiges Objekt, das die folgende Schnittstelle zur Implementierung einer SendRequest-Methode erfüllt:

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

Von HttpClient-Objekten wird erwartet, dass sie die HTTP-Anforderung an einen Serverendpunkt stellen und dazu einen plattformspezifischen Mechanismus verwenden.

Pipelinerichtlinien

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

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

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

Die Rolle von Richtlinien lässt sich als die von middleware betrachten, ein Konzept, das NodeJS-Entwicklern vertraut ist, die bereits mit Frameworks wie Express gearbeitet haben.

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

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

Die meisten Richtlinien befassen sich nur mit der Anforderung oder Antwort, aber es gibt auch einige Ausnahmen wie LogPolicy, die Informationen von beiden protokolliert.

Pipelines

Pipeline ist ein Objekt, das eine Menge von PipelinePolicy-Objekten verwaltet. Seine Hauptaufgabe besteht darin, sicherzustellen, dass die Richtlinien in einer konsistenten und vorhersehbaren Reihenfolge ausgeführt werden.

Sie können sich die Anwendung von Richtlinien wie einen Stapel vorstellen (First-in/Last-out). Die erste PipelinePolicy ist in der Lage, die PipelineRequest vor allen anderen Richtlinien zu ändern, und sie ist auch die letzte, die die PipelineResponse ändert, wodurch sie dem Aufrufer am nächsten ist. Die letzte Richtlinie ist die letzte, die die ausgehende Anforderung ändern kann, und die erste, die die Antwort bearbeitet, sodass sie dem Netzwerk am nächsten ist.

Pipeline erfüllt die folgende Schnittstelle:

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

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

Ein wichtiges Konzept für Pipeline-Objekte ist, dass sie Richtlinien in geordnete Phasen gliedern:

Serialisierungsphase
Richtlinien nicht in einer Phase
Deserialisierungsphase
Wiederholungsphase

Die einzelnen Phasen laufen in der oben genannten Reihenfolge ab, wobei die Serialisierungsrichtlinien zuerst und die Wiederholungsrichtlinien zuletzt angewendet werden. Die meisten benutzerdefinierten Richtlinien gehören zum zweiten Bucket und erhalten keinen Phasennamen.

Wenn Sie der Pipeline eine Richtlinie hinzufügen, können Sie nicht nur angeben, in welcher Phase sich die Richtlinie befindet, sondern auch, ob sie Abhängigkeiten hat:

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

beforePolicies sind Richtlinien, vor denen die neue Richtlinie ausgeführt werden muss. afterPolicies sind Richtlinien, nach denen die neue Richtlinie ausgeführt werden muss. Ähnlich bedeutet afterPhase, dass die Richtlinie erst ausgeführt werden darf, wenn die angegebene Phase eingetreten ist.

Mit dieser Syntax können Ersteller benutzerdefinierten Richtlinien alle notwendigen Beziehungen zwischen ihren eigenen Richtlinien und den integrierten Richtlinien von @azure/core-rest-pipeline ausdrücken, wenn sie mit createPipelineFromOptions eine Pipeline erstellen.

Implementierer können Richtlinien auch nach Namen oder Phase entfernen, falls sie eine vorhandene Pipeline ändern möchten, ohne mit createEmptyPipeline eine neue Richtlinie erstellen zu müssen. Die clone-Methode ist besonders nützlich, wenn Sie eine Pipeline neu erstellen möchten, ohne das Original zu verändern.

Sobald alle anderen Einschränkungen erfüllt sind, werden die 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 entwickeln und ausführen, indem Sie rushx test ausführen. Erkunden Sie den Ordner test, um die erweiterte Nutzung und das Verhalten der öffentlichen Klassen kennenzulernen.

Problembehandlung

Wenn bei Nutzung dieser Bibliothek Probleme auftreten, können Sie uns gerne ein Problem melden.

Mitwirken

Wenn Sie an dieser Bibliothek mitwirken möchten, lesen Sie die Anleitung für Mitwirkende, um mehr darüber zu erfahren, wie Sie den Code erstellen und testen können.

Aufrufe

Freigeben über