JavaScript 用 Azure Core HTTP クライアント ライブラリ - バージョン 1.18.0
これは、ブラウザーと Node.jsで動作する Azure SDK JavaScript ライブラリのコア HTTP パイプラインです。 このライブラリは主に、AutoRest および autorest.typescriptによって生成されるコードで使用することを目的としています。
はじめ
必要条件
現在サポートされている環境
- Node.js の LTS バージョンを
する - Safari、Chrome、Edge、Firefox の最新バージョン。
詳細については、サポート ポリシーの を参照してください。
取り付け
このパッケージは主に生成されたコードで使用され、エンド ユーザーが直接使用するためのものではありません。
主な概念
PipelineRequest
PipelineRequest は、HTTP REST エンドポイントへの要求を行うために必要なすべての情報を記述します。
PipelineResponse
PipelineResponse は、HTTP 要求を行った後に返された REST エンドポイントからの HTTP 応答 (本文、ヘッダー、および状態コード) を記述します。
SendRequest
SendRequest メソッドは、PipelineRequest が PipelineResponseを非同期的に返すことができるメソッドです。
import { PipelineRequest, PipelineResponse } from "@azure/core-rest-pipeline";
type SendRequest = (request: PipelineRequest) => Promise<PipelineResponse>;
HttpClient
HttpClient は、SendRequest メソッドを実装するために次のインターフェイスを満たす任意のオブジェクトです。
import { SendRequest } from "@azure/core-rest-pipeline";
interface HttpClient {
/**
* The method that makes the request and returns a response.
*/
sendRequest: SendRequest;
}
HttpClientは、プラットフォーム固有のメカニズムを使用して、サーバー エンドポイントに対して HTTP 要求を実際に行うことを想定しています。
パイプライン ポリシー
PipelinePolicy は、次のインターフェイスを実装する単純なオブジェクトです。
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>;
}
これは HttpClientに似ていますが、ポリシー名と、パイプライン内の次のポリシーを条件付きで呼び出す SendRequest 署名が少し変更されています。
Expressなどのフレームワークを使用した NodeJS 開発者にとってなじみのある概念である、middlewareのポリシーの役割を確認できます。
sendRequest 実装では、送信要求と受信応答の両方を変換できます。
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;
},
};
ほとんどのポリシーは要求または応答にのみ関係しますが、LogPolicy、それぞれの情報をログに記録するなど、いくつかの例外があります。
パイプライン
Pipeline は、一連の PipelinePolicy オブジェクトを管理するオブジェクトです。 その主な機能は、ポリシーが一貫した予測可能な順序で実行されるようにすることです。
ポリシーはスタックのように適用されていると考えることができます (先入れ先出し/最後の出力)。最初の PipelinePolicy は、他のポリシーの前に PipelineRequest を変更でき、PipelineResponseを最後に変更して、呼び出し元に最も近いものにすることもできます。 最後のポリシーは最後に送信要求を変更でき、最初に応答を処理してネットワークに最も近いものにします。
Pipeline は、次のインターフェイスを満たします。
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;
}
ご覧のように、ポリシーを追加または削除することができ、サーバー エンドポイントへの実際の要求を実行する HttpClient と疎結合されています。
Pipelineの重要な概念の 1 つは、ポリシーを順序付けされたフェーズにグループ化することです。
- シリアル化フェーズ
- フェーズに含まれていないポリシー
- 逆シリアル化フェーズ
- 再試行フェーズ
フェーズは上記の順序で行われ、シリアル化ポリシーが最初に適用され、再試行ポリシーが最後に適用されます。 ほとんどのカスタム ポリシーは 2 番目のバケットに分類され、フェーズ名は指定されません。
パイプラインにポリシーを追加する場合は、ポリシーがどのフェーズにあるかだけでなく、依存関係がある場合も指定できます。
import { PipelinePhase } from "@azure/core-rest-pipeline";
interface AddPipelineOptions {
beforePolicies?: string[];
afterPolicies?: string[];
afterPhase?: PipelinePhase;
phase?: PipelinePhase;
}
beforePolicies は、新しいポリシーを前に実行する必要があるポリシーであり、afterPolicies は新しいポリシーの後に実行する必要があるポリシーです。 同様に、afterPhase は、指定したフェーズが発生した後にのみポリシーを実行する必要があることを意味します。
この構文を使用すると、カスタム ポリシー作成者は、独自のポリシーと、createPipelineFromOptionsを使用してパイプラインを作成するときに @azure/core-rest-pipeline によって提供される組み込みポリシーとの間に必要な関係を表現できます。
実装者は、createEmptyPipelineを使用して新しいものを作成することなく、既存の Pipeline を変更する場合は、名前またはフェーズによってポリシーを削除することもできます。
clone メソッドは、元のメソッドを変更せずに Pipeline を再作成する場合に特に便利です。
他のすべての制約が満たされると、ポリシーは追加された順序で適用されます。
例
例は、samples フォルダーにあります。
次の手順
rushx testを実行することで、テストをローカルでビルドして実行できます。
test フォルダーを調べて、パブリック クラスの高度な使用方法と動作を確認します。
トラブルシューティング
このライブラリの使用中に問題が発生した場合は、問題を
貢献
このライブラリに投稿する場合は、コードをビルドしてテストする方法の詳細については、投稿ガイド を参照してください。
Azure SDK for JavaScript