JavaScript용 Azure Core HTTP 클라이언트 라이브러리 - 버전 1.0.0-beta.1

(실험적)

브라우저 및 Node.js에서 작동하는 Azure SDK JavaScript 라이브러리에 대한 핵심 HTTP 파이프라인입니다. 이 라이브러리는 주로 AutoRest 및 autorest.typescript에 의해 생성된 코드에서 사용하기 위한 것입니다.

시작

요구 사항

설치

이 패키지는 주로 생성된 코드에서 사용되며 최종 사용자가 직접 사용할 수 없습니다.

주요 개념

PipelineRequest

PipelineRequest는 HTTP REST 엔드포인트에 요청하는 데 필요한 모든 정보를 설명합니다.

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 서명과 정책 이름을 포함합니다.

정책의 역할은 Express와 같은 프레임워크로 작업한 NodeJS 개발자에게 익숙한 개념인 middleware의 역할로 볼 수 있습니다.

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는 정책이 지정된 단계가 발생한 후에만 실행되어야 함을 의미합니다.

이 구문을 사용하면 사용자 지정 정책 작성자가 고유한 정책과 createPipelineFromOptions를 사용하여 파이프라인을 만들 때 @azure/core-https에서 제공하는 기본 제공 정책 간에 필요한 관계를 표현할 수 있습니다.

또한 구현자는 createEmptyPipeline를 사용하여 새 정책을 만들 필요 없이 기존 Pipeline을 수정하려는 경우 이름 또는 단계별로 정책을 제거할 수 있습니다. 이 clone 메서드는 원본을 수정하지 않고 Pipeline을 다시 만들 때 특히 유용합니다.

다른 모든 제약 조건이 충족되면 정책이 추가된 순서대로 적용됩니다.

예제

예제는 samples 폴더에서 찾을 수 있습니다.

다음 단계

rushx test를 실행하여 로컬에서 테스트를 빌드하고 실행할 수 있습니다. test 폴더를 탐색하여 퍼블릭 클래스의 고급 사용 및 동작을 확인합니다.

문제 해결

이 라이브러리를 사용하는 동안 문제가 발생하면 자유롭게 문제를 제기하세요.

참여

이 라이브러리에 기여하려면 기여 가이드 를 참조하여 코드를 빌드하고 테스트하는 방법에 대해 자세히 알아보세요.

Impressions

  • Last updated on