適用于 JavaScript 的 Azure Core HTTP 用戶端程式庫 - 1.11.0 版

發行項
06/01/2023

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

開始使用

規格需求

目前支援的環境

LTS 版本的 Node.js
Safari、Chrome、Edge 和 Firefox 的最新版本。

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

安裝

此套件主要用於已產生的程式碼中，並不提供終端使用者直接取用。

重要概念

PipelineRequest

PipelineRequest 用於描述向 HTTP REST 端點提出要求所需的所有資訊。

PipelineResponse

PipelineResponse 用於描述 REST 端點收到 HTTP 要求後所傳回的 HTTP 回應 (本文、標頭、狀態碼)。

SendRequest

SendRequest 方法是指收到 PipelineRequest 後，可非同步傳回 PipelineResponse 的方法。

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

HttpClient

HttpClient 是指任何可透過以下介面實作 SendRequest 方法的物件：

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

HttpClient 應該要能使用平台專屬機制，向伺服器端點實際提出 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>;
}

這個物件看起來很像 HttpClient，但包含原則名稱以及稍微修改過的 SendRequest 簽章，能夠有條件地呼叫管線中下一個原則。

您可以將原則的角色視為 middleware 的角色，使用 Express 等架構的 NodeJS 開發人員都很熟悉這個概念。

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(httpClient: HttpClient, request: PipelineRequest): Promise<PipelineResponse>;
  getOrderedPolicies(): PipelinePolicy[];
  clone(): Pipeline;
}

如您所見，這個物件可以自由新增或移除原則，而且與 HttpClient 鬆散耦合，因此能向伺服器端點實際執行要求。

Pipeline 的一大重要概念是依照排序階段將原則分組：

序列化階段
不處於任何階段的原則
還原序列化階段
重試階段

各階段會按照以上順序出現，最先套用序列化原則，最後套用重試原則。大多數自訂原則都歸類於第二個貯體，且沒有階段名稱。

將原則新增至管線時，您不僅可以指定原則所屬的階段，還能指定原則是否有任何相依性：

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

beforePolicies 是指新原則必須先執行的原則，afterPolicies 則是新原則必須後執行的原則。依此類推，afterPhase 代表只能在指定階段出現後才能執行的原則。

這個語法讓自訂原則建立者使用 createPipelineFromOptions 建立管線時，能夠表達他們的原則與 @azure/core-rest-pipeline 提供的內建原則之間，有哪些必要關聯性。

實作者想要修改現有 Pipeline 時，也能直接依名稱或階段移除原則，而不必使用 createEmptyPipeline 建立新管線。如想在不修改原始管線的前提下重新建立 Pipeline 時，clone 方法格外實用。

滿足所有其他條件限制後，原則就會按照新增順序來套用。

範例

您可在 samples 資料夾中查看更多範例。

後續步驟

您可執行 rushx test 以在本機組建和執行測試。請在 test 資料夾中查看公用類別的進階使用方式和行為。

疑難排解

如果您在使用此程式庫時遇到問題，可隨時提出問題。

參與

如果您希望向此程式庫投稿，請參閱投稿指南，深入瞭解如何組建與測試程式碼。

曝光數

共用方式為