Клиентская библиотека HTTP Azure Core для JavaScript — версия 1.0.0-beta.1

(Экспериментальный)

Это основной конвейер HTTP для библиотек JavaScript Azure SDK, которые работают в браузере и Node.js. Эта библиотека в первую очередь предназначена для использования в коде, созданном AutoRest и autorest.typescript.

Начало работы

Требования

Установка

Этот пакет в основном используется в созданном коде и не предназначен для непосредственного использования конечными пользователями.

Основные понятия

PipelineRequest

В PipelineRequest описаны все сведения, необходимые для выполнения запроса к конечной точке REST HTTP.

PipelineResponse

В PipelineResponse описан HTTP-ответ (текст, заголовки и код состояния) из конечной точки REST, возвращенной после выполнения HTTP-запроса.

SendRequest

Метод SendRequest — это метод, который с учетом PipelineRequest может асинхронно возвращать PipelineResponse.

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

HttpsClient

HttpsClient — любой объект, который удовлетворяет следующему интерфейсу для реализации метода SendRequest:

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

Ожидается, что HttpsClient фактически выполнит 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>;
}

Он похож по форме на HttpsClient, но включает имя политики, а также слегка измененную сигнатуру SendRequest, которая позволяет условно вызывать следующую политику в конвейере.

Роль политик можно рассматривать как middleware, концепцию, знакомую разработчикам NodeJS, которые работали с такими платформами, как Express.

Реализация 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(httpsClient: HttpsClient, request: PipelineRequest): Promise<PipelineResponse>;
  getOrderedPolicies(): PipelinePolicy[];
  clone(): Pipeline;
}

Как видно, он позволяет добавлять или удалять политики и слабо связан с HttpsClient для выполнения реального запроса к конечной точке сервера.

Одна из важных концепций для Pipeline заключается в том, что он группирует политики по упорядоченным этапам:

  1. этап сериализации,
  2. политики, не относящиеся к этапу,
  3. этап десериализации,
  4. этап повтора.

Этапы выполняются в указанном выше порядке, при этом политики сериализации применяются в первую очередь, политики повтора — в последнюю. Большинство пользовательских политик попадают во вторую группу и не получают имя этапа.

При добавлении политики в конвейер можно указать не только этап политики, но и наличие у нее зависимостей:

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

beforePolicies — это политики, которые новая политика должна выполнить до, а afterPolicies — политики, после которых должна произойти новая политика. Аналогичным образом afterPhase означает, что политика должна выполняться только после выполнения указанного этапа.

Этот синтаксис позволяет авторам пользовательских политик выражать любые необходимые связи между собственными политиками и встроенными политиками, предоставляемыми @azure/core-https при создании конвейера с помощью createPipelineFromOptions.

Реализующие объекты также могут удалять политики по имени или этапу, если требуется изменить существующий Pipeline, не создавая новый, с помощью createEmptyPipeline. Этот метод clone особенно полезен при повторном создании Pipeline без изменения исходного.

После удовлетворения всех остальных ограничений политики применяются в том порядке, в котором они были добавлены.

Примеры

Примеры можно найти в папке samples.

Дальнейшие действия

Вы можете создавать и запускать тесты локально с помощью команды rushx test. Изучите папку test, чтобы увидеть расширенное использование и поведение открытых классов.

Устранение неполадок

Если при использовании этой библиотеки возникают проблемы, вы можете сообщить о проблеме.

Участие

Если вы хотите вносить изменения в эту библиотеку, ознакомьтесь с руководством по внесению изменений, в котором содержатся сведения о создании и тестировании кода.

Просмотры

  • Last updated on