أنشِئ تنسيقًا منسقًا عن طريق الحدث من خلال Eventarc وWorkflows.

1. مقدمة

f2f35f5c40b91a3c.png c637dcc97f298e7e.png c4a9d5b95f111710.png

تسهّل خدمة Eventarc ربط خدمات Cloud Run بالأحداث من مجموعة متنوّعة من المصادر. تتيح لك إنشاء بنى مستندة إلى الأحداث تكون فيها الخدمات المصغّرة غير مرتبطة بشكل وثيق وموزّعة. تتولّى هذه الخدمة عملية استيعاب الأحداث وتسليمها وتوفير الأمان لها ومنح الأذونات والتعامل مع الأخطاء.

مهام سير العمل هي منصة تنظيم مُدارة بالكامل تنفِّذ الخدمات بالترتيب الذي تحدّده: سير العمل. يمكن أن تجمع مسارات العمل هذه بين الخدمات المستضافة على Cloud Run أو Cloud Functions، وخدمات Google Cloud، مثل Cloud Vision AI وBigQuery، وأي واجهة برمجة تطبيقات مستندة إلى HTTP.

في هذا الدرس التطبيقي حول الترميز، ستنشئ تنسيقًا مستندًا إلى الأحداث للخدمات المصغّرة من أجل معالجة الصور. ستستخدم "عمليات سير العمل" لتنظيم ترتيب عمليات معالجة الصور الأربع ونتائجها ومدخلاتها في Cloud Functions. بعد ذلك، ستفعّل التنسيق للاستجابة لأحداث Cloud Storage بطريقة غير محكمة الربط باستخدام Eventarc.

في النهاية، ستحصل على بنية حوسبة بدون خادم مرنة ومنظَّمة لمعالجة الصور.

b75a14a4268cbe73.png

أهداف الدورة التعليمية

  • نظرة عامة على Eventarc وWorkflows
  • كيفية نشر خدمات Cloud Functions
  • كيفية تنظيم الخدمات باستخدام "مهام سير العمل"
  • كيفية جعل Workflows يستجيب لأحداث Cloud Storage باستخدام Eventarc

2. الإعداد والمتطلبات

إعداد البيئة بوتيرة ذاتية

  1. سجِّل الدخول إلى Google Cloud Console وأنشِئ مشروعًا جديدًا أو أعِد استخدام مشروع حالي. إذا لم يكن لديك حساب على Gmail أو Google Workspace، عليك إنشاء حساب.

295004821bab6a87.png

37d264871000675d.png

96d86d3d5655cdbe.png

  • اسم المشروع هو الاسم المعروض للمشاركين في هذا المشروع. وهي سلسلة أحرف لا تستخدمها Google APIs. ويمكنك تعديلها في أي وقت.
  • رقم تعريف المشروع هو معرّف فريد في جميع مشاريع Google Cloud ولا يمكن تغييره بعد ضبطه. تنشئ Cloud Console تلقائيًا سلسلة فريدة، ولا يهمّك عادةً ما هي. في معظم دروس البرمجة، عليك الرجوع إلى رقم تعريف مشروعك (يُشار إليه عادةً باسم PROJECT_ID). إذا لم يعجبك المعرّف الذي تم إنشاؤه، يمكنك إنشاء معرّف عشوائي آخر. يمكنك بدلاً من ذلك تجربة اسم مستخدم من اختيارك ومعرفة ما إذا كان متاحًا. لا يمكن تغيير هذا الخيار بعد هذه الخطوة وسيظل ساريًا طوال مدة المشروع.
  • للعلم، هناك قيمة ثالثة، وهي رقم المشروع، تستخدمها بعض واجهات برمجة التطبيقات. يمكنك الاطّلاع على مزيد من المعلومات عن كل هذه القيم الثلاث في المستندات.
  1. بعد ذلك، عليك تفعيل الفوترة في Cloud Console لاستخدام موارد/واجهات برمجة تطبيقات Cloud. لن تكلفك تجربة هذا الدرس التطبيقي حول الترميز الكثير، إن وُجدت أي تكلفة على الإطلاق. لإيقاف الموارد وتجنُّب تحمّل تكاليف تتجاوز هذا البرنامج التعليمي، يمكنك حذف الموارد التي أنشأتها أو حذف المشروع. يمكن لمستخدمي Google Cloud الجدد الاستفادة من برنامج الفترة التجريبية المجانية بقيمة 300 دولار أمريكي.

بدء Cloud Shell

على الرغم من إمكانية تشغيل Google Cloud عن بُعد من الكمبيوتر المحمول، ستستخدم في هذا الدرس العملي Google Cloud Shell، وهي بيئة سطر أوامر تعمل في السحابة الإلكترونية.

من Google Cloud Console، انقر على رمز Cloud Shell في شريط الأدوات العلوي على يسار الصفحة:

تفعيل Cloud Shell

لن يستغرق توفير البيئة والاتصال بها سوى بضع لحظات. عند الانتهاء، من المفترض أن يظهر لك ما يلي:

لقطة شاشة لواجهة سطر الأوامر في Google Cloud Shell توضّح أنّه تم ربط البيئة

يتم تحميل هذه الآلة الافتراضية مزوّدة بكل أدوات التطوير التي ستحتاج إليها. توفّر هذه الخدمة دليلًا منزليًا ثابتًا بسعة 5 غيغابايت، وتعمل على Google Cloud، ما يؤدي إلى تحسين أداء الشبكة والمصادقة بشكل كبير. يمكن إكمال جميع المهام في هذا الدرس العملي ضمن المتصفّح. لست بحاجة إلى تثبيت أي تطبيق.

إعداد gcloud

في Cloud Shell، اضبط رقم تعريف مشروعك والمنطقة التي تريد نشر تطبيقك فيها. احفظها كمتغيّرات PROJECT_ID وREGION. راجِع مواقع Cloud Functions الجغرافية للاطّلاع على المناطق المتاحة.

PROJECT_ID=your-project-id
gcloud config set project $PROJECT_ID

الحصول على رمز المصدر

يمكنك العثور على الرمز المصدر للتطبيق في المجلد processing-pipelines ضمن مستودع eventarc-samples.

استنسِخ المستودع:

git clone https://github.com/GoogleCloudPlatform/eventarc-samples.git

انتقِل إلى مجلد eventarc-samples/processing-pipelines:

cd eventarc-samples/processing-pipelines

3- نظرة عامة على البنية

تكون بنية التطبيق على النحو التالي:

7b810e1505054c0c.png

  1. يتم حفظ صورة في حزمة إدخال تؤدي إلى إنشاء حدث في Cloud Storage.
  2. تتم قراءة حدث إنشاء Cloud Storage من خلال Eventarc عبر مشغّل Cloud Storage ويتم تمريره إلى Workflows كحدث CloudEvent.
  3. في الخطوة الأولى من سير العمل، الفلترة، تستخدم خدمة Cloud Function واجهة Vision API لتحديد ما إذا كانت الصورة آمنة. إذا كانت الصورة آمنة، ستواصل "مهام سير العمل" تنفيذ الخطوات التالية.
  4. في الخطوة الثانية من سير العمل، المصنّف، تستخرج خدمة Cloud Function تصنيفات الصورة باستخدام Vision API وتحفظها في حزمة الإخراج.
  5. في الخطوة الثالثة، Resizer، وهي خدمة أخرى من Cloud Functions، يتم تغيير حجم الصورة باستخدام ImageSharp وحفظ الصورة التي تم تغيير حجمها في حزمة الإخراج.
  6. في الخطوة الأخيرة، Watermarker، وهي خدمة أخرى من Cloud Functions، تضيف علامة مائية من Labeler إلى الصورة التي تم تغيير حجمها باستخدام ImageSharp وتحفظ الصورة في حزمة الإخراج.

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

4. إنشاء مجموعات

أنشئ حزمة إدخال ليحمّل المستخدمون الصور إليها وحزمة إخراج ليحفظ مسار معالجة الصور الصور المعالَجة فيها.

نفِّذ ما يلي في Cloud Shell:

REGION=us-central1
BUCKET1=$PROJECT_ID-images-input-$RANDOM
BUCKET2=$PROJECT_ID-images-output-$RANDOM

gsutil mb -l $REGION gs://$BUCKET1
gsutil mb -l $REGION gs://$BUCKET2

5- نشر خدمة الفلتر

لنبدأ بنشر الخدمة الأولى. تتلقّى خدمة Cloud Functions هذه معلومات الحزمة والملف، وتحدّد ما إذا كانت الصورة آمنة باستخدام Vision API، ثم تعرض النتيجة.

أولاً، فعِّل الخدمات المطلوبة لـ Cloud Functions gen2 وVision API:

gcloud services enable \
  artifactregistry.googleapis.com \
  cloudbuild.googleapis.com \
  cloudfunctions.googleapis.com \
  run.googleapis.com \
  vision.googleapis.com

داخل مجلد المستوى الأعلى processing-pipelines، نفِّذ الخطوات التالية لنشر الخدمة:

SERVICE_NAME=filter

gcloud functions deploy $SERVICE_NAME \
  --gen2 \
  --allow-unauthenticated \
  --runtime dotnet3 \
  --trigger-http \
  --region=$REGION \
  --entry-point Filter.Function \
  --set-build-env-vars GOOGLE_BUILDABLE=image-v3/filter/csharp

بعد نشر الدالة، اضبط عنوان URL للخدمة في متغير، وسنحتاج إليه لاحقًا:

FILTER_URL=$(gcloud functions describe $SERVICE_NAME --region=$REGION --gen2 --format 'value(serviceConfig.uri)')

6. نشر خدمة تصنيف

تتلقّى خدمة Cloud Functions الثانية معلومات الحزمة والملف، وتستخرج تصنيفات الصورة باستخدام Vision API، وتحفظ التصنيفات في حزمة الإخراج.

داخل مجلد المستوى الأعلى processing-pipelines، نفِّذ الخطوات التالية لنشر الخدمة:

SERVICE_NAME=labeler

gcloud functions deploy $SERVICE_NAME \
  --gen2 \
  --allow-unauthenticated \
  --runtime dotnet3 \
  --trigger-http \
  --region=$REGION \
  --set-env-vars BUCKET=$BUCKET2 \
  --entry-point Labeler.Function \
  --set-build-env-vars GOOGLE_BUILDABLE=image-v2/labeler/csharp

بعد نشر الدالة، اضبط عنوان URL للخدمة في متغير، وسنحتاج إليه لاحقًا:

LABELER_URL=$(gcloud functions describe $SERVICE_NAME --region=$REGION --gen2 --format 'value(serviceConfig.uri)')

7. نشر خدمة تغيير الحجم

تتلقّى خدمة Cloud Functions هذه معلومات الحزمة والملف، وتغيّر حجم الصورة باستخدام ImageSharp وتحفظ الصورة في حزمة الإخراج.

داخل مجلد المستوى الأعلى processing-pipelines، نفِّذ الخطوات التالية لنشر الخدمة:

SERVICE_NAME=resizer

gcloud functions deploy $SERVICE_NAME \
  --gen2 \
  --allow-unauthenticated \
  --runtime dotnet3 \
  --trigger-http \
  --region=$REGION \
  --set-env-vars BUCKET=$BUCKET2 \
  --entry-point Resizer.Function \
  --set-build-env-vars GOOGLE_BUILDABLE=image-v2/resizer/csharp \
  --timeout=120s

لاحظ قيمة timeout البالغة دقيقتَين للسماح لوظيفة تغيير الحجم بوقت إضافي للمعالجة.

بعد نشر الدالة، اضبط عنوان URL للخدمة في متغير، وسنحتاج إليه لاحقًا:

RESIZER_URL=$(gcloud functions describe $SERVICE_NAME --region=$REGION --gen2 --format 'value(serviceConfig.uri)')

8. نشر خدمة إضافة العلامات المائية

تتلقّى خدمة Cloud Functions هذه معلومات الحزمة والملف والتصنيفات، وتقرأ الملف، وتضيف التصنيفات كعلامة مائية إلى الصورة باستخدام ImageSharp، وتحفظ الصورة في حزمة الإخراج.

داخل مجلد المستوى الأعلى processing-pipelines، نفِّذ الخطوات التالية لنشر الخدمة:

SERVICE_NAME=watermarker

gcloud functions deploy $SERVICE_NAME \
  --gen2 \
  --allow-unauthenticated \
  --runtime dotnet3 \
  --trigger-http \
  --region=$REGION \
  --set-env-vars BUCKET=$BUCKET2 \
  --entry-point Watermarker.Function \
  --set-build-env-vars GOOGLE_BUILDABLE=image-v2/watermarker/csharp

بعد نشر الدالة، اضبط عنوان URL للخدمة في متغير، وسنحتاج إليه لاحقًا:

WATERMARKER_URL=$(gcloud functions describe $SERVICE_NAME --region=$REGION --gen2 --format 'value(serviceConfig.uri)')

في هذه المرحلة، يجب أن يتم نشر جميع دوال Cloud Functions الأربع وتشغيلها:

fe662925cb0121e9.png

9- تحديد سير العمل ونشره

استخدِم "سير العمل" لدمج خدمات الفلترة والتصنيف وتغيير الحجم وإضافة العلامات المائية في سير عمل واحد. ستنسّق سير العمل عملية استدعاء هذه الخدمات بالترتيب وبالمَعلمات التي نحدّدها.

أولاً، فعِّل الخدمات المطلوبة لـ "مهام سير العمل":

gcloud services enable \
  workflows.googleapis.com \
  workflowexecutions.googleapis.com

تعريف

تتلقّى Workflows حدث CloudEvent كمعلَمة. سيتم الحصول على هذا المعرّف من Eventarc بعد إنشاء مشغّل. في الخطوتَين الأوليَين، تسجّل "سير العمل" الحدث وتستخرج معلومات الحزمة والملف من الحدث:

main:
  params: [event]
  steps:
  - log_event:
      call: sys.log
      args:
          text: ${event}
          severity: INFO
  - extract_bucket_and_file:
      assign:
      - bucket: ${event.data.bucket}
      - file: ${event.data.name}

في الخطوة filter، تنفّذ "مهام سير العمل" طلبًا إلى خدمة الفلترة التي نشرناها سابقًا. بعد ذلك، يتم تسجيل حالة أمان الملف والتحقّق منها:

  - filter:
      call: http.post
      args:
        url: FILTER_URL # TODO: Replace
        auth:
          type: OIDC
        body:
            bucket: ${bucket}
            file: ${file}
      result: filterResponse
  - log_safety:
      call: sys.log
      args:
          text: ${filterResponse.body.safe}
          severity: INFO
  - check_safety:
      switch:
        - condition: ${filterResponse.body.safe == true}
          next: label
      next: end

في الخطوة label، يطلب Workflows من خدمة تصنيف الصور الحصول على الردّ (أهم 3 تصنيفات):

  - label:
      call: http.post
      args:
        url: LABELER_URL # TODO: Replace
        auth:
          type: OIDC
        body:
            bucket: ${bucket}
            file: ${file}
      result: labelResponse

في الخطوة resize، تنفّذ Workflows طلبًا إلى خدمة تغيير الحجم وتلتقط الردّ (الحزمة والملف الخاصان بالصورة التي تم تغيير حجمها):

  - resize:
      call: http.post
      args:
        url: RESIZER_URL # TODO: Replace
        auth:
          type: OIDC
        body:
            bucket: ${bucket}
            file: ${file}
      result: resizeResponse

في الخطوة watermark، تستدعي Workflows خدمة وضع العلامات المائية مع الصورة التي تم تغيير حجمها والتصنيفات، وتسجّل النتيجة (الصورة التي تم تغيير حجمها والتي تحمل العلامة المائية):

  - watermark:
      call: http.post
      args:
        url: WATERMARKER_URL # TODO: Replace
        auth:
          type: OIDC
        body:
            bucket: ${resizeResponse.body.bucket}
            file: ${resizeResponse.body.file}
            labels: ${labelResponse.body.labels}
      result: watermarkResponse

في الخطوة final، تعرض "مهام سير العمل" رمز حالة HTTP من خدمات وضع التصنيفات وتغيير الحجم ووضع العلامات المائية:

  - final:
      return:
        label: ${labelResponse.code}
        resize: ${resizeResponse.code}
        watermark: ${watermarkResponse.code}

النشر

قبل نشر سير العمل، تأكَّد من استبدال عناوين URL للخدمة بعناوين URL للدوال المنشورة إما يدويًا أو باستخدام sed:

داخل المجلد ذي المستوى الأعلى processing-pipelines، انتقِل إلى المجلد image-v3 حيث يقع الملف workflows.yaml:

cd image-v3/

نفِّذ الأمر sed لاستبدال عناوين URL للعناصر النائبة بعناوين URL الفعلية للخدمات التي تم نشرها:

sed -i -e "s|FILTER_URL|${FILTER_URL}|" workflow.yaml
sed -i -e "s|LABELER_URL|${LABELER_URL}|" workflow.yaml
sed -i -e "s|RESIZER_URL|${RESIZER_URL}|" workflow.yaml
sed -i -e "s|WATERMARKER_URL|${WATERMARKER_URL}|" workflow.yaml

نشر أداة سير العمل:

WORKFLOW_NAME=image-processing

gcloud workflows deploy $WORKFLOW_NAME \
    --source=workflow.yaml \
    --location=$REGION

بعد بضع ثوانٍ، من المفترض أن يظهر سير العمل الذي تم نشره في وحدة التحكّم:

a5f537f2b3f3bd3.png

10. إنشاء مشغِّل

بعد نشر سير العمل، الخطوة الأخيرة هي ربطه بأحداث Cloud Storage باستخدام مشغّل Eventarc.

الإعداد مرة واحدة

أولاً، فعِّل الخدمات المطلوبة لـ Eventarc:

gcloud services enable \
 eventarc.googleapis.com

أنشئ حساب خدمة ستستخدمه في مشغّل Eventarc.

SERVICE_ACCOUNT=eventarc-trigger-imageproc-sa

gcloud iam service-accounts create $SERVICE_ACCOUNT \
  --display-name="Eventarc trigger image processing service account"

امنح دور workflows.invoker، حتى يمكن استخدام حساب الخدمة لتفعيل Workflows من Eventarc:

gcloud projects add-iam-policy-binding $PROJECT_ID \
  --role roles/workflows.invoker \
  --member serviceAccount:$SERVICE_ACCOUNT@$PROJECT_ID.iam.gserviceaccount.com

امنح حساب الخدمة الدور eventarc.eventReceiver، حتى يمكن استخدامه في

مشغّل Cloud Storage:

gcloud projects add-iam-policy-binding $PROJECT_ID \
  --role roles/eventarc.eventReceiver \
  --member serviceAccount:$SERVICE_ACCOUNT@$PROJECT_ID.iam.gserviceaccount.com

امنح حساب خدمة Cloud Storage الدور pubsub.publisher. هذا الإذن مطلوب لمشغّل Cloud Storage في Eventarc:

STORAGE_SERVICE_ACCOUNT="$(gsutil kms serviceaccount -p $PROJECT_ID)"

gcloud projects add-iam-policy-binding $PROJECT_ID \
    --member serviceAccount:$STORAGE_SERVICE_ACCOUNT \
    --role roles/pubsub.publisher

إنشاء

نفِّذ الأمر التالي لإنشاء مشغّل. يتم تفعيل هذا المشغّل عند إنشاء ملف جديد في حزمة Cloud Storage المُدخَلة، ويتم تمرير الملف إلى سير العمل الذي حدّدناه سابقًا:

TRIGGER_NAME=trigger-image-processing

gcloud eventarc triggers create $TRIGGER_NAME \
  --location=$REGION \
  --destination-workflow=$WORKFLOW_NAME \
  --destination-workflow-location=$REGION \
  --event-filters="type=google.cloud.storage.object.v1.finalized" \
  --event-filters="bucket=$BUCKET1" \
  --service-account=$SERVICE_ACCOUNT@$PROJECT_ID.iam.gserviceaccount.com

يمكنك الاطّلاع على المشغّل الذي تم إنشاؤه وهو جاهز في قسم Eventarc في Cloud Console:

a5f4301863d7d9e4.png

11. اختبار مسار العرض

أصبحت سلسلة معالجة الصور جاهزة لتلقّي الأحداث من Cloud Storage. لاختبار مسار العرض، حمِّل صورة إلى حزمة الإدخال:

gsutil cp beach.jpg gs://$BUCKET1

بعد تحميل الصورة مباشرةً، من المفترض أن يظهر تنفيذ "سير العمل" في الحالة النشطة:

2c914341950b5fde.png

بعد دقيقة أو نحو ذلك، من المفترض أن تظهر لك رسالة تفيد بنجاح التنفيذ. يمكنك أيضًا الاطّلاع على مدخلات ومخرجات سير العمل:

9abba6c28c51a9b5.png

إذا أدرجت محتوى حزمة الإخراج، من المفترض أن تظهر لك الصورة التي تم تغيير حجمها والصورة التي تم تغيير حجمها وإضافة علامة مائية إليها وتصنيفات الصورة:

gsutil ls gs://$BUCKET2

gs://$PROJECT_ID-images-output-$RANDOM/beach-400x400-watermark.jpeg
gs://$PROJECT_ID-images-output-$RANDOM/beach-400x400.png
gs://$PROJECT_ID-images-output-$RANDOM/beach-labels.txt

للتأكّد من ذلك، يمكنك فتح الصورة التي تم تغيير حجمها وإضافة علامة مائية إليها للاطّلاع على النتيجة:

46d375cb05a8aae4.jpeg

12. تهانينا

تهانينا، لقد أكملت درس البرمجة.

المواضيع التي تناولناها

  • نظرة عامة على Eventarc وWorkflows
  • كيفية نشر خدمات Cloud Functions
  • كيفية تنظيم الخدمات باستخدام "مهام سير العمل"
  • كيفية جعل Workflows يستجيب لأحداث Cloud Storage باستخدام Eventarc