مكتبة عميل Azure Core HTTP ل JavaScript - الإصدار 1.0.0-beta.1

(تجريبي)

هذا هو خط أنابيب HTTP الأساسي لمكتبات Azure SDK JavaScript التي تعمل في المتصفح Node.js. تهدف هذه المكتبة في المقام الأول إلى استخدامها في التعليمات البرمجية التي تم إنشاؤها بواسطة AutoRest وautorest.typescript.

الشروع في العمل

المتطلبات

• Node.js الإصدار > 8.x

التثبيت

تستخدم هذه الحزمة في المقام الأول في التعليمات البرمجية التي تم إنشاؤها وليس المقصود أن يستهلكها المستخدمون النهائيون مباشرة.

المفاهيم الرئيسية

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 قليلاً يسمح له باستدعاء السياسة التالية في خط الأنابيب بشكل مشروط.

يمكن للمرء أن ينظر إلى دور السياسات مثل 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 الذي يسجل المعلومات من كل منها.

التدفقات

Pipeline هو كائن يدير مجموعة من الكائنات PipelinePolicy. وتتمثل مهمتها الرئيسية في ضمان تنفيذ السياسات بترتيب متسق ويمكن التنبؤ به.

يمكنك التفكير في السياسات التي تطبع كأنها مكدس (first-in/last-out.) الأول 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 للاطلاع على الاستخدام والسلوك المتقدم للفئات العامة.

استكشاف الأخطاء وإصلاحها

إذا واجهت مشكلات في أثناء استخدام هذه المكتبة، فلا تتردد في تقديم مشكلة.

المساهمة

إذا كنت ترغب في المساهمة في هذه المكتبة، يرجى قراءة دليل المساهمة لمعرفة المزيد حول كيفية إنشاء التعليمات البرمجية واختبارها.