مكتبة عميل Azure Event Grid ل JavaScript - الإصدار 5.5.1

Azure Event Grid هي خدمة مستندة إلى السحابة توفر تسليم حدث موثوق به على نطاق واسع.

استخدم مكتبة العميل من أجل:

• إرسال الأحداث إلى Event Grid باستخدام إما Event Grid أو Cloud Events 1.0 أو مخطط مخصص
• فك ترميز الأحداث التي تم تسليمها إلى معالج Event Grid ومعالجتها
• إنشاء توقيعات الوصول المشترك لموضوعات شبكة الأحداث

الارتباطات الرئيسية:

• التعليمات البرمجية المصدر
• حزمة (NPM)
• الوثائق المرجعية لواجهة برمجة التطبيقات
• وثائق Product
• عينات

الشروع

البيئات المدعومة حاليا

• إصدارات LTS من Node.js
• أحدث إصدارات Safari وChrome وEdge وFirefox.

راجع نهج دعم للحصول على مزيد من التفاصيل.

المتطلبات المسبقه

• اشتراك Azure .
• موضوع أو مجال Event Grid موجود. إذا كنت بحاجة إلى إنشاء المورد، يمكنك استخدام مدخل Azure أو Azure CLI.

إذا كنت تستخدم Azure CLI، فاستبدل <your-resource-group-name><your-resource-name> بأسماء فريدة خاصة بك:

إنشاء موضوع شبكة الأحداث

az eventgrid topic create --location <location> --resource-group <your-resource-group-name> --name <your-resource-name>

إنشاء مجال شبكة الأحداث

az eventgrid domain create --location <location> --resource-group <your-resource-group-name> --name <your-resource-name>

تثبيت حزمة @azure/eventgrid

تثبيت مكتبة عميل Azure Event Grid ل JavaScript مع npm:

npm install @azure/eventgrid

إنشاء EventGridPublisherClient ومصادقته

لإنشاء كائن عميل للوصول إلى واجهة برمجة تطبيقات شبكة الأحداث، ستحتاج إلى endpoint لموضوع Event Grid الخاص بك credential. يمكن لعميل Event Grid استخدام مفتاح الوصول أو توقيع الوصول المشترك (SAS) الذي تم إنشاؤه من مفتاح وصول.

يمكنك العثور على نقطة النهاية لموضوع Event Grid إما في مدخل Azure أو باستخدام القصاصة البرمجية Azure CLI أدناه:

az eventgrid topic show --name <your-resource-name> --resource-group <your-resource-group-name> --query "endpoint"

استخدام مفتاح الوصول

استخدم مدخل Azure للاستعراض وصولا إلى مورد شبكة الأحداث واسترداد مفتاح الوصول، أو استخدم مقتطف Azure CLI أدناه:

az eventgrid topic key list --resource-group <your-resource-group-name> --name <your-event-grid-topic-name>

بمجرد أن يكون لديك مفتاح واجهة برمجة التطبيقات ونقطة النهاية، يمكنك استخدام فئة AzureKeyCredential لمصادقة العميل كما يلي:

const { EventGridPublisherClient, AzureKeyCredential } = require("@azure/eventgrid");

const client = new EventGridPublisherClient(
  "<endpoint>",
  "<endpoint schema>",
  new AzureKeyCredential("<Access Key>")
);

استخدام رمز SAS المميز

مثل مفتاح الوصول، يسمح رمز SAS المميز بالوصول إلى إرسال الأحداث إلى موضوع Event Grid. على عكس مفتاح الوصول، الذي يمكن استخدامه حتى يتم إعادة إنشائه، يحتوي رمز SAS المميز على وقت إخراج، وعند هذه النقطة لم يعد صالحا. لاستخدام رمز SAS المميز للمصادقة، استخدم AzureSASCredential كما يلي:

const { EventGridPublisherClient, AzureSASCredential } = require("@azure/eventgrid");

const client = new EventGridPublisherClient(
  "<endpoint>",
  "<endpoint schema>",
  new AzureSASCredential("<SAS Token>")
);

يمكنك إنشاء رمز SAS المميز باستخدام الدالة generateSharedAccessSigniture.

const { generateSharedAccessSignature, AzureKeyCredential } = require("@azure/eventgrid");

// Create a SAS Token which expires on 2020-01-01 at Midnight.
const token = generateSharedAccessSignature(
  "<endpoint>",
  new AzureKeyCredential("<API key>"),
  new Date("2020-01-01T00:00:00")
);

استخدام Azure Active Directory (AAD)

يوفر Azure EventGrid التكامل مع Azure Active Directory (Azure AD) للمصادقة المستندة إلى الهوية للطلبات. باستخدام Azure AD، يمكنك استخدام التحكم في الوصول استنادا إلى الدور (RBAC) لمنح الوصول إلى موارد Azure Event Grid للمستخدمين أو المجموعات أو التطبيقات.

لإرسال الأحداث إلى موضوع أو مجال مع TokenCredential، يجب أن يكون للهوية المصادق عليها دور "EventGrid Data Sender" المعين.

باستخدام حزمة @azure/identity، يمكنك تخويل الطلبات بسلاسة في كل من بيئات التطوير والإنتاج. لمعرفة المزيد حول Azure Active Directory، راجع @azure/identity README.

على سبيل المثال، يمكن استخدام DefaultAzureCredential لإنشاء عميل يقوم بالمصادقة باستخدام Azure Active Directory:

const { EventGridPublisherClient } = require("@azure/eventgrid");
const { DefaultAzureCredential } = require("@azure/identity");

const client = new EventGridPublisherClient(
  "<endpoint>",
  "<endpoint schema>",
  new DefaultAzureCredential()
);

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

EventGridPublisherClient

يتم استخدام EventGridPublisherClient لإرسال الأحداث إلى موضوع شبكة الأحداث أو مجال شبكة الأحداث.

مخططات الأحداث

تدعم Event Grid مخططات متعددة لترميز الأحداث. عند إنشاء موضوع مخصص أو مجال، يمكنك تحديد المخطط الذي سيتم استخدامه عند نشر الأحداث. بينما يمكنك تكوين الموضوع لاستخدام مخطط مخصص من الشائع استخدام مخطط شبكة الأحداث المحدد مسبقا أو مخطط CloudEvents 1.0. CloudEvents هو مشروع Cloud Native Computing Foundation الذي ينتج مواصفات لوصف بيانات الحدث بطريقة مشتركة. عند إنشاء EventGridPublisherClient، يجب تحديد المخطط الذي تم تكوين موضوعك لاستخدامه:

إذا تم تكوين الموضوع لاستخدام مخطط شبكة الأحداث، فقم بتعيين "EventGrid" كنوع المخطط:

const client = new EventGridPublisherClient(
  "<endpoint>",
  "EventGrid",
  new AzureKeyCredential("<API Key>")
);

إذا تم تكوين الموضوع لاستخدام مخطط أحداث السحابة، فقم بتعيين "CloudEvent" كنوع المخطط:

const client = new EventGridPublisherClient(
  "<endpoint>",
  "CloudEvent",
  new AzureKeyCredential("<API Key>")
);

إذا تم تكوين الموضوع لاستخدام مخطط حدث مخصص، فقم بتعيين "مخصص" كنوع المخطط:

const client = new EventGridPublisherClient(
  "<endpoint>",
  "Custom",
  new AzureKeyCredential("<API Key>")
);

سيؤدي إنشاء العميل بمخطط مختلف عما تم تكوين الموضوع لتوقعه إلى حدوث خطأ من الخدمة ولن يتم نشر الأحداث الخاصة بك.

يمكنك معرفة مخطط الإدخال الذي تم تكوينه لموضوع Event Grid باستخدام مقتطف Azure CLI أدناه:

az eventgrid topic show --name <your-resource-name> --resource-group <your-resource-group-name> --query "inputSchema"

EventGridDeserializer

يتم تسليم الأحداث التي يتم تسليمها إلى المستهلكين بواسطة Event Grid ك JSON. اعتمادا على نوع المستهلك الذي يتم تسليمه، قد تقدم خدمة Event Grid حدثا واحدا أو أكثر كجزء من حمولة واحدة. بينما قد يتم إلغاء تسلسل هذه الأحداث باستخدام أساليب JavaScript العادية مثل JSON.parse، تقدم هذه المكتبة نوعا مساعدا لإلغاء تسلسل الأحداث، يسمى EventGridDeserializer.

مقارنة باستخدام JSON.parse مباشرة، يقوم EventGridDeserializer ببعض التحويلات الإضافية أثناء إلغاء تسلسل الأحداث:

1. يتحقق EventGridDeserializer من وجود الخصائص المطلوبة لحدث ما وهي الأنواع الصحيحة.
2. يحول EventGridDeserializer خاصية وقت الحدث إلى كائن Date JavaScript.
3. عند استخدام أحداث السحابة، يمكن استخدام البيانات الثنائية لخاصية بيانات الحدث (باستخدام Uint8Array). عند إرسال الحدث من خلال Event Grid، يتم ترميزه في Base 64. سيقوم EventGridDeserializer بفك تشفير هذه البيانات مرة أخرى إلى مثيل Uint8Array.
4. عند إلغاء حدث نظام (حدث تم إنشاؤه بواسطة خدمة Azure أخرى)، سيقوم بتحويلات إضافية بحيث يطابق كائن الواجهة المقابلة التي تصف بياناته. عند استخدام TypeScript، تضمن هذه الواجهات أن لديك كتابة قوية عند الوصول إلى خصائص كائن البيانات لحدث نظام.

عند إنشاء مثيل EventGridDeserializer يمكنك توفير أدوات إلغاء تسلسل مخصصة تستخدم لتحويل الكائن data بشكل أكبر.

التتبع الموزع وأحداث السحابة

تدعم هذه المكتبة التتبع الموزع باستخدام @azure/core-tracing. عند استخدام التتبع الموزع، ستقوم هذه المكتبة بإنشاء امتداد أثناء عملية send. بالإضافة إلى ذلك، عند إرسال الأحداث باستخدام مخطط Cloud Events 1.0، ستضيف SDK بيانات تعريف التتبع الموزعة إلى الأحداث باستخدام ملحق التتبع الموزع . تتوافق قيم خصائص ملحق traceparenttracestate مع traceparent ورؤوس tracestate من طلب HTTP الذي يرسل الأحداث. إذا كان الحدث يحتوي بالفعل على خاصية ملحق traceparent، فلن يتم تحديثه.

Event Grid على Kubernetes

تم اختبار هذه المكتبة والتحقق من صحتها على Kubernetes باستخدام Azure Arc.

امثله

نشر حدث مخصص إلى موضوع شبكة الأحداث باستخدام مخطط شبكة الأحداث

const { EventGridPublisherClient, AzureKeyCredential } = require("@azure/eventgrid");

const client = new EventGridPublisherClient(
  "<endpoint>",
  "EventGrid",
  new AzureKeyCredential("<API key>")
);

await client.send([
  {
    eventType: "Azure.Sdk.SampleEvent",
    subject: "Event Subject",
    dataVersion: "1.0",
    data: {
      hello: "world",
    },
  },
]);

نشر حدث مخصص إلى موضوع في مجال شبكة الأحداث باستخدام مخطط شبكة الأحداث

يشبه نشر الأحداث إلى مجال شبكة الأحداث النشر إلى موضوع شبكة الأحداث، باستثناء أنه عند استخدام مخطط شبكة الأحداث للأحداث، يجب تضمين الخاصية topic. عند نشر الأحداث في مخطط Cloud Events 1.0، يتم استخدام خاصية source المطلوبة كاسم للموضوع في المجال للنشر إلى:

const { EventGridPublisherClient, AzureKeyCredential } = require("@azure/eventgrid");

const client = new EventGridPublisherClient(
  "<endpoint>",
  "EventGrid",
  new AzureKeyCredential("<API key>")
);

await client.send([
  {
    topic: "my-sample-topic",
    eventType: "Azure.Sdk.SampleEvent",
    subject: "Event Subject",
    dataVersion: "1.0",
    data: {
      hello: "world",
    },
  },
]);

إلغاء تسلسل حدث

يمكن استخدام EventGridDeserializer لإلغاء تسلسل الأحداث التي تم تسليمها بواسطة Event Grid. في هذا المثال لدينا حدث سحابة يتم إلغاء تسلسله باستخدام EventGridDeserializer واستخدام isSystemEvent للكشف عن نوع الأحداث التي هي.

const { EventGridDeserializer, isSystemEvent } = require("@azure/eventgrid");

async function main() {
  const deserializer = new EventGridDeserializer();
  const message = {
    id: "5bc888aa-c2f4-11ea-b3de-0242ac130004",
    source:
      "/subscriptions/<subscriptionid>/resourceGroups/dummy-rg/providers/Microsoft.EventGrid/topics/dummy-topic",
    specversion: "1.0",
    type: "Microsoft.ContainerRegistry.ImagePushed",
    subject: "Test Subject",
    time: "2020-07-10T21:27:12.925Z",
    data: {
      hello: "world",
    },
  };
  const deserializedMessage = await deserializer.deserializeCloudEvents(message);
  console.log(deserializedMessage);

  if (
    deserializedMessage != null &&
    deserializedMessage.length !== 0 &&
    isSystemEvent("Microsoft.ContainerRegistry.ImagePushed", deserializedMessage[0])
  ) {
    console.log("This is a Microsoft.ContainerRegistry.ImagePushed event");
  }
}

main();

استكشاف الاخطاء

تسجيل

قد يساعد تمكين التسجيل في الكشف عن معلومات مفيدة حول حالات الفشل. لمشاهدة سجل طلبات واستجابات HTTP، قم بتعيين متغير البيئة AZURE_LOG_LEVEL إلى info. بدلا من ذلك، يمكن تمكين التسجيل في وقت التشغيل عن طريق استدعاء setLogLevel في @azure/logger:

const { setLogLevel } = require("@azure/logger");

setLogLevel("info");

للحصول على إرشادات أكثر تفصيلا حول كيفية تمكين السجلات، يمكنك إلقاء نظرة على مستندات حزمة @azure/المسجل.

الخطوات التالية

يرجى إلقاء نظرة على نماذج الدليل للحصول على أمثلة مفصلة حول كيفية استخدام هذه المكتبة.

المساهمه

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

المشاريع ذات الصلة

• Microsoft Azure SDK ل Javascript

مرات الظهور