共用方式為

適用於 JavaScript 的 Azure Core HTTP 用戶端連結庫 - 1.18.0 版

  • 發行項

這是 Azure SDK JavaScript 連結庫的核心 HTTP 管線，在瀏覽器中運作，Node.js。 此連結庫主要用於由 AutoRest 和 autorest.typescript所產生的程式代碼中。

開始

要求

目前支持的環境

如需詳細資訊，請參閱我們的 支持原則。

安裝

此套件主要用於產生的程式代碼中，而不是由終端使用者直接取用。

重要概念

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 簽章，可讓它有條件地呼叫管線中的下一個原則。

您可以將原則的角色視為 middleware，這是與 Express等架構搭配使用之 NodeJS 開發人員熟悉的概念。

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. 不分階段的原則
  3. 還原串行化階段
  4. 重試階段

階段會以上述順序發生，並先套用串行化原則，最後套用重試原則。 大部分的自定義原則會落在第二個貯體中，而不會提供階段名稱。

將原則新增至管線時，您不僅可以指定原則處於哪個階段，而且如果原則具有任何相依性，也可以指定：

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 所提供的內建原則之間的任何必要關聯性。

實作者也可以依名稱或階段移除原則，以防他們想要修改現有的 Pipeline，而不需要使用 createEmptyPipeline建立新的原則。 當重新建立 Pipeline 而不修改原始時，clone 方法特別有用。

滿足所有其他條件約束之後，原則會依新增的順序套用。

例子

您可以在 samples 資料夾中找到範例。

後續步驟

您可以在本機建置及執行測試，方法是執行 rushx test。 探索 test 資料夾，以查看公用類別的進階使用方式和行為。

故障排除

如果您在使用此連結庫時遇到問題，請隨意 提出問題。

貢獻

如果您想要參與此連結庫，請閱讀 參與指南，以深入瞭解如何建置和測試程序代碼。

印象