Клиентская библиотека HTTP Azure Core для JavaScript версии 1.18.0

Статья
11/16/2024

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

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

Требования

Поддерживаемые в настоящее время среды

версии LTS Node.js
Последние версии Safari, Chrome, Edge и Firefox.

Дополнительные сведения см. в политике поддержки .

Установка

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

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

PipelineRequest

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

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, чтобы просмотреть расширенное использование и поведение общедоступных классов.

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

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

Способствует

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

впечатлений

Поделиться через