你当前正在访问 Microsoft Azure Global Edition 技术文档网站。如果需要访问由世纪互联运营的 Microsoft Azure 中国技术文档网站，请访问 https://docs.azure.cn。

适用于 JavaScript 的 Azure Core HTTP 客户端库 - 版本 1.18.2

项目
01/09/2025

这是 Azure SDK JavaScript 库的核心 HTTP 管道，可用于浏览器和 Node.js。此库主要用于由 AutoRest 和 autorest.typescript生成的代码。

开始

要求

当前支持的环境

LTS 版本的 Node.js
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 签名，允许它有条件地调用管道中的下一个策略。

人们可以将策略的角色视为 middleware的角色，而 NodeJS 开发人员熟悉该概念，这些开发人员曾使用过 Express等框架。

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的一个重要概念是，它们将策略分组到有序阶段：

序列化阶段
策略不在阶段
反序列化阶段
重试阶段

阶段按上述顺序发生，先应用序列化策略，最后应用重试策略。大多数自定义策略都属于第二个存储桶，未提供阶段名称。

将策略添加到管道时，不仅可以指定策略处于哪个阶段，还可以指定策略具有任何依赖项：

import { PipelinePhase } from "@azure/core-rest-pipeline";

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

beforePolicies 是新策略之前必须执行的策略，afterPolicies 是新策略之后必须发生的策略。同样，afterPhase 意味着策略只能在指定阶段发生后执行。

此语法允许自定义策略作者在使用 @azure/core-rest-pipeline创建管道时表达其自己的策略与 createPipelineFromOptions 提供的内置策略之间的任何必要关系。

实现者还可以按名称或阶段删除策略，以防他们希望修改现有 Pipeline，而无需使用 createEmptyPipeline创建新策略。重新创建 clone 而不修改原始方法时，Pipeline 方法特别有用。

满足所有其他约束后，策略将按添加的顺序应用。

例子

可以在 samples 文件夹中找到示例。

后续步骤

可以通过执行 rushx test在本地生成和运行测试。浏览 test 文件夹以查看公共类的高级用法和行为。

故障排除

如果在使用此库时遇到问题，请随时提交问题。

贡献

若要参与此库，请阅读贡献指南了解有关如何生成和测试代码的详细信息。

通过