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

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

开始

要求

当前支持的环境

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

有关详细信息，请参阅我们的 支持策略。

安装

此包主要用于生成的代码中，不应由最终用户直接使用。

关键概念

管道请求

PipelineRequest 描述了向 HTTP REST 终结点发出请求所需的所有信息。

管道响应

PipelineResponse 描述发出 HTTP 请求后返回的 REST 终结点的 HTTP 响应（正文、标头和状态代码）。

发送请求

SendRequest 方法是一种给定 PipelineRequest 可以异步返回 PipelineResponse的方法。

import { PipelineRequest, PipelineResponse } from "@azure/core-rest-pipeline";

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

Http客户端

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 记录每个请求的信息。

Pipelines

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 意味着策略只能在指定阶段发生后执行。

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

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

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

例子

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

后续步骤

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

故障 排除

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

贡献

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