مشاركة عبر

مكتبة عميل Azure Event Grid ل JavaScript - الإصدار 5.1.0-beta.1

  • مقالة

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

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

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

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

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

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

راجع سياسة الدعم الخاصة بنا لمزيد من التفاصيل.

المتطلبات الأساسية

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

إنشاء ⁧⁩Event Grid Topic⁧⁩

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

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

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

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

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

استخدم مدخل Microsoft Azure للاستعراض وصولا إلى مورد Event Grid واسترداد مفتاح الوصول، أو استخدم قصاصة برمجية 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" المعين.

باستخدام الحزمة @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 مخططات متعددة لترميز الأحداث. عند إنشاء موضوع مخصص أو مجال، يمكنك تحديد المخطط الذي سيتم استخدامه عند نشر الأحداث. بينما يمكنك تكوين الموضوع لاستخدام مخطط مخصص ، فمن الشائع استخدام مخطط 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 يقوم ببعض التحويلات الإضافية أثناء أحداث deserializng:

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

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

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

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

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

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

المساهمة

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

مرات الظهور