JavaScript 用 Azure Core HTTP クライアント ライブラリ - バージョン 1.0.0-beta.1

(試験段階)

これは、ブラウザーと Node.js で動作する Azure SDK JavaScript ライブラリのコア HTTP パイプラインです。 このライブラリは主に AutoRest および autorest.typescript によって生成されたコードで使用することを目的としています。

作業の開始

要件

インストール

このパッケージは主に生成されたコードで使用され、エンド ユーザーが直接使用することを意図したものではありません。

主要な概念

PipelineRequest

PipelineRequest は、HTTP REST エンドポイントへの要求を出すのに必要なすべての情報を記述します。

PipelineResponse

PipelineResponse では、HTTP 要求を行った後に返された REST エンドポイントからの HTTP 応答 (本文、ヘッダー、および状態コード) について説明します。

SendRequest

SendRequest メソッドは、非同期で PipelineResponse を返すことができる PipelineRequest を指定するメソッドです。

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

HttpsClient

HttpsClient は、SendRequest メソッドを実装するために次のインターフェイスを満たす任意のオブジェクトです。

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

HttpsClient は、プラットフォーム固有のメカニズムを使用して、サーバー エンドポイントに対して実際に HTTP 要求を行うことが期待されています。

パイプライン ポリシー

PipelinePolicy は、次のインターフェイスを実装する単純なオブジェクトです。

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

形状は HttpsClient に似ていますが、ポリシー名と、パイプライン内の次のポリシーを条件付きで呼び出すことができるようにわずかに変更された SendRequest 署名が含まれています。

ポリシーの役割は、Express などのフレームワークを使用した NodeJS 開発者によく知られている概念である middleware の役割と見なすことができます。

sendRequest 実装では、送信要求と受信応答の両方を変換することができます。

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

ほとんどのポリシーは、要求または応答のいずれかにのみ関係するものです。ただし、それぞれからの情報をログに記録する LogPolicy などの例外がいくつかあります。

Pipelines

Pipeline は一連の PipelinePolicy オブジェクトを管理するオブジェクトです。 その主な機能は、ポリシーが一貫した予測可能な順序で確実に実行されるようにすることです。

ポリシーがスタックのように適用されていると考えることができます (先入れ/後出し)。最初の PipelinePolicy は、他のポリシーの前に PipelineRequest を変更できます。また、PipelineResponse を最後に変更することもができます。呼び出し元に最も近くなります。 最後のポリシーは、最後に送信要求を変更することができ、また、最初に応答を処理することができます。ネットワークに最も近くなります。

Pipeline では、次のインターフェイスを満たします。

export interface Pipeline {
  addPolicy(policy: PipelinePolicy, options?: AddPolicyOptions): void;
  removePolicy(options: { name?: string; phase?: PipelinePhase }): PipelinePolicy[];
  sendRequest(httpsClient: HttpsClient, request: PipelineRequest): Promise<PipelineResponse>;
  getOrderedPolicies(): PipelinePolicy[];
  clone(): Pipeline;
}

ご覧のように、ポリシーを追加または削除することができ、サーバーエンドポイントへの実際の要求を実行するために HttpsClient と緩く結合されています。

Pipeline の重要な概念の 1 つは、ポリシーを順序付けられたフェーズにグループ化することです。

  1. シリアル化フェーズ
  2. フェーズにポリシーは含まれない
  3. 逆シリアル化フェーズ
  4. 再試行フェーズ

フェーズは上記の順序で発生し、シリアル化ポリシーが最初に適用され、再試行ポリシーが最後に適用されます。 ほとんどのカスタム ポリシーは 2 番目のバケットに分類され、フェーズ名は指定されません。

パイプラインにポリシーを追加する場合、ポリシーがどのフェーズにあるかだけでなく、依存関係があるかどうかも指定できます。

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

beforePolicies は、新しいポリシーを前に実行する必要があるポリシーであり、afterPolicies は、新しいポリシーを後で実行する必要があるポリシーです。 同様に、afterPhase ポリシーは、指定したフェーズが発生した後にのみ実行する必要があることを意味します。

この構文により、カスタム ポリシーの作成者は、createPipelineFromOptions を使用してパイプラインを作成するときに、独自のポリシーと、@azure/core-https によって提供される組み込みポリシーとの間に必要な関係を表現できます。

実装者は、createEmptyPipeline を使用して新しいポリシーを作成しなくても、既存の Pipeline を変更したい場合に、名前またはフェーズでポリシーを削除することもできます。 この clone メソッドは、元のメソッドを変更せずに Pipeline を再作成する場合に特に便利です。

他のすべての制約が満たされると、ポリシーは追加された順序で適用されます。

例

例については、samples フォルダーを参照してください。

次のステップ

rushx test を実行することで、テストをローカルでビルドして実行できます。 test フォルダーを調べて、パブリック クラスの高度な使用状況と動作を確認します。

トラブルシューティング

このライブラリの使用中に問題が発生した場合は、お気軽に問題を提出してください。

共同作成

このライブラリに投稿する場合、コードをビルドしてテストする方法の詳細については、投稿ガイドを参照してください。

インプレッション数

  • Last updated on