بدء معالجة الأحداث من "تخزين السحابة الإلكترونية" باستخدام وظائف Eventarc وCloud Run

1. نظرة عامة

في هذا التمرين العملي، ستتعرّف على كيفية استخدام أحداث حاوية Cloud Storage وEventarc لتفعيل معالجة الأحداث. ستستخدم دوال Cloud Run لتحليل البيانات ومعالجة الصور. ستستخدم الدالة Vision API من Google وتحفظ الصورة الناتجة في حزمة Cloud Storage.

ما ستتعلمه

كيفية إنشاء مسار معالجة صور

ضبط حِزم التخزين
إنشاء دوال Cloud Run لقراءة العناصر وكتابتها في Cloud Storage
تفعيل مشغّل Eventarc
دمج Vision API لرصد صور الطعام
اختبار الحلّ المتكامل والتحقّق من صحته

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

يفترض هذا التمرين المعملي أنك على دراية ببيئات Cloud Console وShell.
يُفضّل أن يكون لديك خبرة سابقة في استخدام Cloud Storage أو دوال Cloud Run أو Vision API، ولكنّ ذلك ليس شرطًا.

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

إعداد مشروع على السحابة الإلكترونية

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

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

بعد ذلك، عليك تفعيل الفوترة في Cloud Console لاستخدام موارد/واجهات برمجة تطبيقات Cloud. لن تكلفك تجربة هذا الدرس التطبيقي حول الترميز الكثير، إن وُجدت أي تكلفة على الإطلاق. لإيقاف الموارد وتجنُّب تحمّل تكاليف تتجاوز هذا البرنامج التعليمي، يمكنك حذف الموارد التي أنشأتها أو حذف المشروع. يمكن لمستخدمي Google Cloud الجدد الاستفادة من برنامج الفترة التجريبية المجانية بقيمة 300 دولار أمريكي.

تفعيل Cloud Shell

فعِّل Cloud Shell من خلال النقر على الرمز على يسار شريط البحث.

إعداد البيئة

أنشئ متغيرات بيئية مرتبطة بالمشروع والموارد من خلال تنفيذ الأوامر أدناه في وحدة Cloud Shell الطرفية.

export PROJECT_ID=$(gcloud config get-value project)
export PROJECT_NAME=$(gcloud config get-value project)
export PROJECT_NUMBER=$(gcloud projects describe $PROJECT_ID --format='value(projectNumber)')
export REGION=us-east1 
export UPLOAD_BUCKET_NAME=menu-item-uploads-$PROJECT_ID
export UPLOAD_BUCKET=gs://menu-item-uploads-$PROJECT_ID
export BUCKET_THUMBNAILS=gs://menu-item-thumbnails-$PROJECT_ID
export MENU_SERVICE_NAME=menu-service
export USER_EMAIL=$(gcloud config list account --format "value(core.account)")

تفعيل واجهات برمجة التطبيقات المطلوبة للميزة الاختبارية

gcloud services enable \
    vision.googleapis.com \
    cloudfunctions.googleapis.com \
    pubsub.googleapis.com \
    cloudbuild.googleapis.com \
    logging.googleapis.com \
    eventarc.googleapis.com \
    artifactregistry.googleapis.com \
    run.googleapis.com \
    --quiet

إنشاء نسخة طبق الأصل من المستودع

git clone https://github.com/GoogleCloudPlatform/cymbal-eats.git && cd cymbal-eats/cloud-functions

3- إعداد حِزم Cloud Storage

إنشاء حِزم تخزين

أنشئ حِزم Cloud Storage للتحميل والصور المصغّرة من أجل مسار معالجة الصور.

استخدِم الأمر gsutil mb واسمًا فريدًا لإنشاء حزمتَين:

تحميل الحزمة التي سيتم تحميل الصور إليها أولاً
حزمة الصور المصغّرة لتخزين الصور المصغّرة التي تم إنشاؤها

أنشئ حزمة لتحميل صور جديدة:

gsutil mb -p $PROJECT_ID -l $REGION $UPLOAD_BUCKET

مثال على الناتج:

Creating gs://menu-item-uploads-cymbal-eats-8399-3119/...

أنشئ حزمة لتخزين الصور المصغّرة التي تم إنشاؤها:

gsutil mb -p $PROJECT_ID -l $REGION $BUCKET_THUMBNAILS

مثال على الناتج:

Creating gs://menu-item-thumbnails-cymbal-eats-8399-3119/...

تعديل أذونات الحزمة

عدِّل أذونات حزمة التخزين للسماح للمستخدمين بالحصول على أذونات القراءة.

استخدِم الأمر gsutil iam ch لمنح الإذن بقراءة العناصر وكتابتها في الحزمة:

gsutil iam ch allUsers:objectViewer $UPLOAD_BUCKET
gsutil iam ch allUsers:objectViewer $BUCKET_THUMBNAILS

مثال على الناتج

Updated IAM policy for project [cymbal-eats-8399-3119].
[...]

4. ضبط حسابات الخدمة

أنشئ حساب خدمة مخصّصًا لـ Cloud Function من أجل معالجة الصور المصغّرة:

export CF_SERVICE_ACCOUNT=thumbnail-service-sa
gcloud iam service-accounts create ${CF_SERVICE_ACCOUNT}

امنح دور artifactregistry.reader للسماح بعمليات القراءة من Artifact Registry:

gcloud projects add-iam-policy-binding $PROJECT_ID \
  --member "serviceAccount:${CF_SERVICE_ACCOUNT}@${PROJECT_ID}.iam.gserviceaccount.com" \
  --role "roles/artifactregistry.reader"

امنح دور storage.objectCreator للسماح بتخزين الصور التي تم إنشاؤها في حزمة الصور المصغّرة:

gcloud projects add-iam-policy-binding $PROJECT_ID \
  --member "serviceAccount:${CF_SERVICE_ACCOUNT}@${PROJECT_ID}.iam.gserviceaccount.com" \
  --role "roles/storage.objectCreator"

امنح دور run.invoker للسماح باستدعاء خدمة Cloud Run:

gcloud projects add-iam-policy-binding $PROJECT_ID \
  --member "serviceAccount:${CF_SERVICE_ACCOUNT}@${PROJECT_ID}.iam.gserviceaccount.com" \
  --role "roles/run.invoker"

امنح الدور eventarc.eventReceiver للسماح بتلقّي الأحداث من مقدّمي الخدمات:

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

امنح حساب خدمة Cloud Storage الدور pubsub.publisher. سيسمح ذلك لحساب الخدمة بنشر الأحداث عند تحميل الصور إلى الحزمة.

GCS_SERVICE_ACCOUNT=$(gsutil kms serviceaccount -p $PROJECT_NUMBER)

gcloud projects add-iam-policy-binding $PROJECT_NUMBER \
    --member "serviceAccount:$GCS_SERVICE_ACCOUNT" \
    --role "roles/pubsub.publisher"

5- نظرة عامة على وظيفة معالجة الصور

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

تشغيل دالة

تستند وظائف Cloud Storage إلى إشعارات Pub/Sub من Cloud Storage وتتيح أنواع الأحداث المشابهة:

في هذا الدرس التطبيقي، ستنفّذ دالة وتفعّلها عند الانتهاء من معالجة عنصر في Cloud Storage.

Object Finalize

يتم تشغيل أحداث إنهاء الكائن عند الانتهاء بنجاح من "كتابة" كائن Cloud Storage. على وجه الخصوص، يعني هذا أنّ إنشاء عنصر جديد أو الكتابة فوق عنصر حالي يؤدي إلى تشغيل هذا الحدث. يتجاهل هذا المشغّل عمليات الأرشفة وتعديل البيانات الوصفية.

6. دمج Cloud Storage

‫Cloud Storage هي خدمة لتخزين العناصر في Google Cloud. العنصر هو جزء غير قابل للتغيير من البيانات يتألف من ملف بأي تنسيق. يمكنك تخزين الكائنات في حاويات تُعرف باسم الحِزم. ترتبط جميع الحِزم بمشروع، ويمكنك تجميع مشاريعك ضمن مؤسسة. تسهّل مكتبات البرامج وواجهات برمجة التطبيقات عملية الدمج مع Cloud Storage

في هذا التمرين العملي، ستستخدم مكتبة البرامج لقراءة الكائنات وكتابتها في Cloud Storage.

تثبيت مكتبة البرامج

تتوفّر مكتبات البرامج على السحابة الإلكترونية بلغات برمجة شائعة عديدة. لبدء استخدام المكتبات، عليك تثبيت مكتبة البرامج.

استخدام مكتبة البرامج

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

package.json

{
    "name": "thumbnail-service",
    "version": "0.1.0",
    "dependencies": {
      "@google-cloud/functions-framework": "^3.0.0",
      "@google-cloud/storage": "^5.18.2",
      "@google-cloud/vision": "^2.4.2",
        ...
    }
  }

تسجيل معاودة الاتصال في CloudEvent

سجِّل دالة ردّ اتصال CloudEvent باستخدام Functions Framework سيتم تشغيلها من خلال Cloud Storage عند تحميل صورة جديدة إلى الحزمة.

index.js

functions.cloudEvent('process-thumbnails', async (cloudEvent) => {
    console.log(`Event ID: ${cloudEvent.id}`);
    console.log(`Event Type: ${cloudEvent.type}`);
    ...

إنشاء كائن مرجعي للتخزين

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

index.js

const storage = new Storage();
const bucket = storage.bucket(file.bucket);
const thumbBucket = storage.bucket(process.env.BUCKET_THUMBNAILS);

تنزيل عناصر Cloud Storage

index.js

await bucket.file(file.name).download({
            destination: originalFile
        });

تحميل عناصر إلى Cloud Storage

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

يحمّل الرمز البرمجي أدناه صورة إلى التخزين في السحابة الإلكترونية باستخدام عملية تحميل بطلب واحد.

index.js

const thumbnailImage = await thumbBucket.upload(thumbFile);

7. دمج Vision API

تتيح خدمة Cloud Vision للمطوّرين دمج ميزات التعرّف البصري بسهولة في التطبيقات، بما في ذلك تصنيف الصور، والتعرّف على الوجوه والمعالم، والتعرّف البصري على الأحرف (OCR)، ووضع علامات على المحتوى الفاضح.

تثبيت مكتبة البرامج

إنشاء عميل Image Annotator

للوصول إلى Google APIs باستخدام حِزم SDK الرسمية للعملاء، عليك إنشاء عنصر خدمة استنادًا إلى مستند وصف واجهة برمجة التطبيقات، والذي يصف واجهة برمجة التطبيقات لحزمة SDK. عليك استردادها من خدمة الاكتشاف في Vision API باستخدام بيانات الاعتماد الخاصة بك.

index.js

const client = new vision.ImageAnnotatorClient();

إنشاء طلب بيانات من Vision API

يمكن لواجهة Vision API رصد الميزات في ملف صورة من خلال إرسال محتوى ملف الصورة كسلسلة مشفرة بترميز base64 في نص الطلب.

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

بيانات الصورة المشفّرة باستخدام Base64
قائمة بالميزات التي تريد إضافة تعليقات توضيحية إليها بشأن تلك الصورة

index.js

        const client = new vision.ImageAnnotatorClient();
        const visionRequest = {
            image: { source: { imageUri: `gs://${file.bucket}/${file.name}` } },
            features: [
                { type: 'LABEL_DETECTION' },
            ]
        };
        const visionPromise = client.annotateImage(visionRequest);

8. نشر دوال Cloud Run

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

سيتم إنشاء المكوّنات التالية أثناء نشر الدالة:

دوال Cloud Run
مشغّل Eventarc
موضوع واشتراك Pub/Sub

في وحدة Cloud Shell الطرفية، نفِّذ الأمر أدناه لنشر دوال Cloud Run باستخدام حزمة مشغّلة على menu-item-uploads-$PROJECT_ID:

لنشر إحدى دوال Cloud Run مباشرةً على Cloud Run، عليك أولاً نشر الدالة ثم إنشاء مشغّل لها.

انشر دوال Cloud Run:

gcloud beta run deploy process-thumbnails \
      --source=thumbnail \
      --function process-thumbnails \
      --region $REGION \
      --base-image google-22-full/nodejs20 \
      --no-allow-unauthenticated \
      --project=$PROJECT_ID \
--service-account="${CF_SERVICE_ACCOUNT}@${PROJECT_ID}.iam.gserviceaccount.com" \
--set-env-vars=BUCKET_THUMBNAILS=$BUCKET_THUMBNAILS,MENU_SERVICE_URL=$MENU_SERVICE_URL \
  --max-instances=1 \
  --quiet

مثال على الناتج:

Done.                                                                                                                                                                                    
Service [process-thumbnails] revision [process-thumbnails-00001-abc] has been deployed and is serving 100 percent of traffic.
Service URL: https://process-thumbnails-000000000.us-east1.run.app

إنشاء المشغّل:

gcloud eventarc triggers create process-thumbnails-trigger \
     --location=$REGION \
     --destination-run-service=process-thumbnails \
    --destination-run-region=$REGION \
     --event-filters="type=google.cloud.storage.object.v1.finalized" \
     --event-filters="bucket=$UPLOAD_BUCKET_NAME" \
     --service-account="${CF_SERVICE_ACCOUNT}@${PROJECT_ID}.iam.gserviceaccount.com"

مثال على الناتج:

Creating trigger [process-thumbnails-trigger] in project [qwiklabs-gcp-02-53f8532696e1], location [us-east1]...done.                                                                     
WARNING: It may take up to 2 minutes for the new trigger to become active.

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

مثال على نتيجة الخطأ:

...If you recently started to use Eventarc, it may take a few minutes before all necessary permissions are propagated to the Service Agent...
[...]

في Cloud Console، راجِع خدمة Cloud Run التي تم إنشاؤها للدالة:

في Cloud Console، راجِع مشغّل Eventarc الذي تم إنشاؤه للدالة:

في Cloud Console، راجِع الموضوع والاشتراك في Pub/Sub اللذين تم إنشاؤهما لمشغّل Eventarc:

9- اختبار الحلّ المتكامل والتحقّق من صحته

حمِّل صورة جديدة إلى Cloud Storage وتتبَّع مستوى تقدّم عملية المعالجة أثناء تحليل الصور. ستختبر الحلّ المتكامل من خلال رصد سجلّات الوظائف السحابية.

تحميل صورة

حفظ هذه الصورة على جهازك
أعِد تسمية الملف 1.jpg
افتح وحدة تحكّم Cloud Storage
انقر على حزمة menu-item-uploads-....
انقر على تحميل الملفات.
حمِّل الملف 1.jpg إلى حزمة التخزين.
في Cloud Console، انتقِل إلى Cloud Run.
انقر على process-thumbails
انقر على علامة التبويب السجلات.

انتقِل إلى حزمة menu-item-thumbnails-$PROJECT_ID Cloud Storage
التأكّد من إنشاء الصورة المصغّرة في حزمة الصور المصغّرة

تحميل صورة غير غذائية

للتحقّق من أنّ الوظيفة تعمل بشكل صحيح، عليك تحميل صورة لا تحتوي على عنصر يمكن تصنيفه كـ "طعام".

حفظ هذه الصورة على جهازك
أعِد تسمية الملف إلى 2.jpg
افتح وحدة تحكّم Cloud Storage
انقر على حزمة menu-item-uploads-....
انقر على تحميل الملفات
حمِّل الملف 2.jpg إلى حزمة التخزين
في Cloud Console، انتقِل إلى Cloud Run.
انقر على process-thumbails
انقر على علامة التبويب السجلات.

10. تهانينا!

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

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

استكشِف دروسًا تطبيقية أخرى حول Cymbal Eats:

تَنظيم

لتجنُّب تحمّل رسوم في حسابك على Google Cloud مقابل الموارد المستخدَمة في هذا البرنامج التعليمي، احذف المشروع الذي يحتوي على الموارد أو احتفظ بالمشروع واحذف الموارد الفردية.

حذف المشروع

أسهل طريقة لإيقاف الفوترة هي حذف المشروع الذي أنشأته لتنفيذ البرنامج التعليمي.