Pustaka klien HTTP Azure Core untuk JavaScript - versi 1.0.0-beta.1

(Eksperimental)

Ini adalah alur HTTP inti untuk pustaka JavaScript Azure SDK yang berfungsi di browser dan Node.js. Pustaka ini terutama ditujukan untuk digunakan dalam kode yang dibuat oleh AutoRest dan autorest.typescript.

Memulai

Persyaratan

• Node.js versi > 8.x

Penginstalan

Paket ini terutama digunakan dalam kode yang dihasilkan dan tidak dimaksudkan untuk dikonsumsi secara langsung oleh pengguna akhir.

Konsep utama

PipelineRequest

PipelineRequest menjelaskan semua informasi yang diperlukan untuk membuat permintaan ke titik akhir HTTP REST.

PipelineResponse

PipelineResponse menjelaskan respons HTTP (isi, header, dan kode status) dari titik akhir REST yang dikembalikan setelah membuat permintaan HTTP.

SendRequest

Metode SendRequest adalah metode yang memberikan PipelineRequest secara asinkron dapat mengembalikan PipelineResponse.

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

HttpsClient

HttpsClient adalah objek apa pun yang memenuhi antarmuka berikut untuk mengimplementasikan metode SendRequest:

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

HttpsClientdiharapkan untuk benar-benar membuat permintaan HTTP ke titik akhir server, menggunakan beberapa mekanisme khusus platform untuk melakukannya.

Kebijakan Alur

PipelinePolicy adalah objek sederhana yang mengimplementasikan antarmuka berikut:

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>;
}

Bentuknya mirip dengan HttpsClient, tetapi menyertakan nama kebijakan serta tanda tangan SendRequest yang sedikit dimodifikasi yang memungkinkannya memanggil kebijakan berikutnya dalam alur.

Seseorang dapat melihat peran kebijakan sebagai middleware, konsep yang akrab bagi pengembang NodeJS yang telah bekerja dengan kerangka kerja seperti Ekspres.

Implementasi sendRequest dapat mengubah permintaan keluar dan juga respons masuk:

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;
  }
};

Sebagian besar kebijakan hanya berkaitan dengan permintaan atau respons, tetapi ada beberapa pengecualian seperti LogPolicy yang mencatat informasi masing-masing.

Pipelines

Pipeline adalah objek yang mengelola sekumpulan objek PipelinePolicy. Fungsi utamanya adalah untuk memastikan bahwa kebijakan dijalankan dalam urutan yang konsisten dan dapat diprediksi.

Anda dapat menganggap kebijakan yang diterapkan seperti tumpukan (masuk pertama/keluar terakhir.) PipelinePolicy pertama dapat mengubah PipelineRequest sebelum kebijakan lainnya, dan juga yang terakhir mengubah PipelineResponse, sehingga menjadikannya yang paling dekat dengan pemanggil. Kebijakan terakhir adalah yang terakhir dapat mengubah permintaan keluar, dan yang pertama menangani respons, menjadikannya yang paling dekat dengan jaringan.

Pipeline memenuhi syarat antarmuka berikut:

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;
}

Seperti yang Anda lihat, ini memungkinkan kebijakan untuk ditambahkan atau dihapus dan secara longgar digabungkan dengan HttpsClient untuk melakukan permintaan sebenarnya ke titik akhir server.

Salah satu konsep penting untuk Pipeline adalah bahwa hal ini mengelompokkan kebijakan ke dalam fase yang berurutan:

1. Fase Serialisasi
2. Kebijakan tidak dalam fase
3. Fase Deserialisasi
4. Fase Coba Lagi

Fase terjadi dalam urutan di atas, dengan kebijakan serialisasi diterapkan terlebih dahulu dan coba lagi kebijakan diterapkan terakhir. Sebagian besar kebijakan khusus termasuk dalam keranjang kedua dan tidak diberi nama fase.

Saat menambahkan kebijakan ke alur, Anda tidak hanya dapat menentukan fase kebijakan, tetapi juga apakah kebijakan tersebut memiliki dependensi:

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

beforePolicies adalah kebijakan yang harus dijalankan oleh kebijakan baru sebelum dan afterPolicies adalah kebijakan yang harus dilakukan setelah kebijakan baru. Demikian pula, afterPhase berarti kebijakan hanya boleh dijalankan setelah fase yang ditentukan telah terjadi.

Sintaksis ini memungkinkan pembuat kebijakan kustom mengungkapkan hubungan yang diperlukan antara kebijakan mereka sendiri dan kebijakan bawaan yang disediakan oleh @azure/core-https saat membuat alur menggunakan createPipelineFromOptions.

Pelaksana juga dapat menghapus kebijakan berdasarkan nama atau fase, jika mereka ingin mengubah Pipeline yang ada tanpa harus membuat yang baru menggunakan createEmptyPipeline. Metode clone sangat berguna saat membuat ulang Pipeline tanpa mengubah aslinya.

Setelah semua kendala lain terpenuhi, kebijakan diterapkan dalam urutan penambahannya.

Contoh

Contoh dapat ditemukan di folder samples.

Langkah berikutnya

Anda dapat membuat dan menjalankan pengujian secara lokal dengan menjalankan rushx test. Jelajahi folder test untuk melihat perilaku dan penggunaan tingkat lanjut kelas publik.

Pemecahan Masalah

Jika Anda mengalami masalah saat menggunakan pustaka ini, jangan ragu untuk mengajukan masalah.

Berkontribusi

Jika Anda ingin berkontribusi pada pustaka ini, baca panduan berkontribusi untuk mempelajari selengkapnya tentang cara membuat dan menguji kode.