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

1. مقدمة

cb762f29e9183a3f.png 1c05e3d0c2bd2b45.png a03f943ca09ac4c.png

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

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

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

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

e372ceed8c26c5fb.png

ما ستتعرَّف عليه

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

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

إعداد بيئة ذاتية

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

b35bf95b8bf3d5d8.png

a99b7ace416376c4.png

bd84a6d3004737c5.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 في شريط الأدوات العلوي الأيسر:

55efc1aaa7a4d3ad.png

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

7ffe5cbb04455448.png

يتم تحميل هذه الآلة الافتراضية مزوّدة بكل أدوات التطوير التي ستحتاج إليها. وتوفّر هذه الشبكة دليلاً رئيسيًا دائمًا بسعة 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- نظرة عامة على الهندسة

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

6aa6fbc7721dd6b6.png

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

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

4. إنشاء الحِزم

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

شغِّل ما يلي في Cloud Shell:

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

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)')

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

76a218568982c90c.png

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

استخدِم Workflows لدمج خدمات الفلاتر والتصنيفات وأدوات تغيير الحجم والعلامات المائية معًا في سير العمل. ستنسق سير العمل استدعاء هذه الخدمات بالترتيب باستخدام المعلمات التي نحددها.

أولاً، قم بتمكين الخدمات المطلوبة لسير العمل:

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

تعريف

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

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، تُجري Workflows مكالمة مع خدمة الفلترة التي نشرناها سابقًا. وبعد ذلك، يسجِّل البرنامج ويتحقّق من أمان الملفات:

  - 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، تعرض Workflows رمز حالة 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

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

92cf4e758bdc3dde.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" حتى يمكن استخدام حساب الخدمة لاستدعاء "سير العمل" من 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

امنح الدور "pubsub.publisher" إلى حساب خدمة Cloud Storage. هذا الإجراء مطلوب لتشغيل 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:

14330c4fa2451bc0.png

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

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

gsutil cp beach.jpg gs://$BUCKET1

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

36d07cb63c39e7d9.png

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

229200c79d989c25.png

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

gsutil ls gs://$BUCKET2

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

للتحقّق مرة أخرى، يمكنك فتح الصورة التي تم تغيير حجمها والعلامة المائية لرؤية النتيجة:

75f3c0019ca842ce.jpeg

12. تهانينا

تهانينا، لقد أنهيت الدرس التطبيقي حول الترميز.

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

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