النشر إلى مواضيع مساحة الاسم واستهلاك الأحداث في Azure Event Grid

  • مقالة

توفر هذه المقالة مقدمة سريعة لسحب التسليم باستخدام curl أمر bash shell لنشر الأحداث وتلقيها والإقرار بها. يتم إنشاء موارد Event Grid باستخدام أوامر CLI. هذه المقالة مناسبة لاختبار سريع لوظيفة تسليم السحب. للحصول على نموذج التعليمات البرمجية باستخدام حزم SDK لمستوى البيانات، راجع نماذج .NET أو Java. بالنسبة إلى Java، نقدم نموذج التعليمات البرمجية في مقالتين: نشر الأحداث وتلقي البدايات السريعة للأحداث . لمزيد من المعلومات حول نموذج تسليم السحب، راجع المفاهيم ومقالات نظرة عامة على التسليم.

إذا لم يكن لديك اشتراك في Azure، فأنشئ حساب Azure مجاني قبل أن تبدأ.

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

  • تتطلب هذه المقالة الإصدار 2.0.70 أو أحدث من نسخة من Azure CLI. إذا كنت تستخدم Azure Cloud Shell، يتم تثبيت أحدث إصدار بالفعل.

إنشاء مجموعة موارد

أنشئ إحدى مجموعات موارد Azure باستخدام الأمر "az group create". يمكنك استخدام مجموعة الموارد هذه لاحتواء كافة الموارد التي تم إنشاؤها في هذه المقالة.

الخطوات العامة لاستخدام Cloud Shell لتشغيل الأوامر هي:

  • حدد Open Cloud Shell لمشاهدة نافذة Azure Cloud Shell في الجزء الأيمن.
  • انسخ الأمر والصقه في نافذة Azure Cloud Shell.
  • اضغط على ENTER لتشغيل الأمر.

  1. قم بتعريف متغير للاحتفاظ باسم مجموعة موارد Azure. حدد اسما لمجموعة الموارد عن طريق استبدال <your-resource-group-name> بقيمة تريدها.

    resource_group="<your-resource-group-name>"

  2. قم بإنشاء مجموعة موارد. قم بتغيير الموقع كما تراه مناسبا.

    az group create --name $resource_group --location eastus

قم بتمكين مزود موارد Event Grid

  1. إذا لم تكن قد استخدمت Event Grid من قبل في اشتراك Azure، فقد تحتاج إلى تسجيل موفر موارد Event Grid. قم بتشغيل الأمر التالي لتسجيل الموفر :

    az provider register --namespace Microsoft.EventGrid

  2. قد يستغرق التسجيل بعض الوقت. للتحقق من الحالة، قم بتشغيل الأمر التالي:

    az provider show --namespace Microsoft.EventGrid --query "registrationState"

    عندما registrationStateيكونRegistered، كنت على استعداد للمتابعة.

إنشاء مساحة اسم

توفر مساحة اسم Event Grid نقطة نهاية معرفة من قبل المستخدم تقوم بنشر الأحداث إليها. ينشئ المثال التالي مساحة اسم في مجموعة الموارد الخاصة بك باستخدام Bash في Azure Cloud Shell. يجب أن يكون اسم مساحة الاسم فريدا لأنه جزء من إدخال نظام أسماء المجالات (DNS). يجب أن يفي اسم مساحة الاسم بالقواعد التالية:

  • يجب أن يتراوح بين 3-50 حرفا.
  • وينبغي أن تكون فريدة من نوعها إقليميا.
  • الأحرف المسموح بها فقط هي a-z و A-Z و 0-9 و -
  • يجب ألا يبدأ ببادئات الكلمات الرئيسية المحجوزة مثل Microsoft، System أو EventGrid.

  1. قم بتعريف متغير للاحتفاظ باسم مساحة اسم Event Grid. حدد اسما لمساحة الاسم عن طريق استبدال <your-namespace-name> بقيمة تريدها.

    namespace="<your-namespace-name>"

  2. أنشئ مساحة اسم . قد تحتاج إلى تغيير الموقع الذي تم نشره فيه.

    az eventgrid namespace create -g $resource_group -n $namespace -l eastus

إنشاء موضوع مساحة الاسم

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

  1. قم بتعريف متغير للاحتفاظ باسم موضوع مساحة الاسم. حدد اسما لموضوع مساحة الاسم عن طريق استبدال <your-topic-name> بقيمة تريدها.

    topic="<your-topic-name>"

  2. إنشاء موضوع مساحة الاسم:

    az eventgrid namespace topic create -g $resource_group -n $topic --namespace-name $namespace

إنشاء اشتراك حدث

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

  1. قم بتعريف متغير للاحتفاظ باسم اشتراك حدث لموضوع مساحة الاسم. حدد اسما لاشتراك الحدث عن طريق استبدال <your-event-subscription-name> بقيمة تريدها.

    event_subscription="<your-event-subscription-name>"

  2. إنشاء اشتراك حدث لموضوع مساحة الاسم:

    az eventgrid namespace topic event-subscription create -g $resource_group --topic-name $topic -n $event_subscription --namespace-name $namespace --delivery-configuration "{deliveryMode:Queue,queue:{receiveLockDurationInSeconds:300,maxDeliveryCount:4,eventTimeToLive:P1D}}"

إرسال الأحداث إلى موضوعك

الآن، أرسل نموذج حدث إلى موضوع مساحة الاسم باتباع الخطوات الواردة في هذا القسم.

قائمة مفاتيح الوصول إلى مساحة الاسم

  1. احصل على مفاتيح الوصول المقترنة بمساحة الاسم التي أنشأتها. يمكنك استخدام أحدها للمصادقة عند نشر الأحداث. لسرد المفاتيح الخاصة بك، تحتاج إلى معرف مورد مساحة الاسم الكامل أولا. احصل عليه عن طريق تشغيل الأمر التالي:

    namespace_resource_id=$(az eventgrid namespace show -g $resource_group -n $namespace --query "id" --output tsv)

  2. احصل على المفتاح الأول من مساحة الاسم:

    key=$(az eventgrid namespace list-key -g $resource_group --namespace-name $namespace --query "key1" --output tsv)

نشر حدث

  1. استرداد اسم مضيف مساحة الاسم. يمكنك استخدامه لإنشاء نقطة نهاية HTTP لمساحة الاسم التي يتم إرسال الأحداث إليها. كانت العمليات التالية متوفرة أولا مع إصدار 2023-06-01-previewواجهة برمجة التطبيقات .

    publish_operation_uri="https://"$(az eventgrid namespace show -g $resource_group -n $namespace --query "topicsConfiguration.hostname" --output tsv)"/topics/"$topic:publish?api-version=2023-06-01-preview

  2. إنشاء نموذج حدث متوافق مع CloudEvents :

    event=' { "specversion": "1.0", "id": "'"$RANDOM"'", "type": "com.yourcompany.order.ordercreatedV2", "source" : "/mycontext", "subject": "orders/O-234595", "time": "'`date +%Y-%m-%dT%H:%M:%SZ`'", "datacontenttype" : "application/json", "data":{ "orderId": "O-234595", "url": "https://yourcompany.com/orders/o-234595"}} '

    data العنصر هو حمولة الحدث الخاص بك. يمكن لأي JSON تم تشكيله بشكل جيد أن يذهب في هذا المجال. لمزيد من المعلومات حول الخصائص (المعروفة أيضا باسم سمات السياق) التي يمكن أن تنتقل في حدث ما، راجع مواصفات CloudEvents .

  3. استخدم CURL لإرسال الحدث إلى الموضوع. CURL هي أداة مساعدة ترسل طلبات HTTP.

    curl -X POST -H "Content-Type: application/cloudevents+json" -H "Authorization:SharedAccessKey $key" -d "$event" $publish_operation_uri

تلقي الحدث

تتلقى الأحداث من Event Grid باستخدام نقطة نهاية تشير إلى اشتراك حدث.

  1. قم بإنشاء نقطة النهاية هذه عن طريق تشغيل الأمر التالي:

    receive_operation_uri="https://"$(az eventgrid namespace show -g $resource_group -n $namespace --query "topicsConfiguration.hostname" --output tsv)"/topics/"$topic/eventsubscriptions/$event_subscription:receive?api-version=2023-06-01-preview

  2. إرسال طلب لاستهلاك الحدث:

    curl -X POST -H "Content-Type: application/json" -H "Authorization:SharedAccessKey $key" $receive_operation_uri

الإقرار بحدث

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

  1. في الخطوة السابقة، يجب أن تكون قد تلقيت استجابة تتضمن كائنا brokerProperties بخاصية lockToken . انسخ قيمة رمز التأمين المميز وقم بتعيينها على متغير بيئة:

    lockToken="<paste-the-lock-token-here>"

  2. الآن، أنشئ حمولة عملية الإقرار، والتي تحدد رمز التأمين المميز للحدث الذي تريد الاعتراف به.

    acknowledge_request_payload=' { "lockTokens": ["'$lockToken'"]} '

  3. تابع إنشاء السلسلة باستخدام URI لعملية الإقرار:

    acknowledge_operation_uri="https://"$(az eventgrid namespace show -g $resource_group -n $namespace --query "topicsConfiguration.hostname" --output tsv)"/topics/"$topic/eventsubscriptions/$event_subscription:acknowledge?api-version=2023-06-01-preview

  4. وأخيرا، أرسل طلبا للإقرار بالحدث الذي تم تلقيه:

    curl -X POST -H "Content-Type: application/json" -H "Authorization:SharedAccessKey $key" -d "$acknowledge_request_payload" $acknowledge_operation_uri

    إذا تم تنفيذ عملية الإقرار قبل انتهاء صلاحية رمز التأمين المميز (300 ثانية كما هو محدد عند إنشاء اشتراك الحدث)، يجب أن تشاهد استجابة مثل المثال التالي:

    {"succeededLockTokens":["CiYKJDQ4NjY5MDEyLTk1OTAtNDdENS1BODdCLUYyMDczNTYxNjcyMxISChDZae43pMpE8J8ovYMSQBZS"],"failedLockTokens":[]}

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

لمعرفة المزيد حول نموذج تسليم السحب، راجع نظرة عامة على تسليم السحب.