تمت ترجمة هذه الصفحة بواسطة Cloud Translation API‏.

بدء معالجة الأحداث من Cloud Storage باستخدام Eventarc وCloud Functions (الجيل الثاني)

1. نظرة عامة

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

ما سوف تتعلمه

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

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

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

يفترض هذا التمرين المعملي الإلمام ببيئتي Cloud Console وطبقة الغلاف.
توفّر لك تجربة استخدام Cloud Storage أو دوال Cloud أو Vision API السابقة معلومات مفيدة ولكنّها ليست مطلوبة.

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

إعداد مشروع Cloud

سجِّل الدخول إلى 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=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

تمكين واجهات برمجة التطبيقات المطلوبة للدرس. (خطوة محدّدة لمنصة Qwiklabs)

gcloud services disable cloudfunctions.googleapis.com
gcloud services enable cloudfunctions.googleapis.com

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

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 لمعالجة الصور المصغّرة:

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"

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

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 إلى إشعارات النشر/الاشتراكات من Cloud Storage وتوفِّر أنواع أحداث مشابهة:

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

إنهاء العنصر

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

6- دمج Cloud Storage

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

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

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

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

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

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

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

index.js

const thumbnailImage = await thumbBucket.upload(thumbFile);

7. دمج Vision API

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

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

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

إنشاء برنامج تعليقات توضيحية للصور

للوصول إلى Google APIs باستخدام حِزم تطوير البرامج (SDK) الرسمية للعميل، يمكنك إنشاء عنصر خدمة استنادًا إلى مستند Discovery المتعلق بواجهة برمجة التطبيقات الذي يصف واجهة برمجة التطبيقات في حزمة تطوير البرامج (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. تفعيل دالة السحابة الإلكترونية

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

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

وظيفة السحابة الإلكترونية
خدمة تشغيل السحابة الإلكترونية
مشغِّل Eventarc
الاشتراك وموضوع النشر/الاشتراك

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

gcloud functions deploy process-thumbnails \
  --gen2 \
  --runtime=nodejs16 \
  --source=thumbnail \
  --region=$REGION \
  --project=$PROJECT_ID \
  --entry-point=process-thumbnails \
  --trigger-bucket=$UPLOAD_BUCKET \
  --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

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

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

Deploying function (may take a while - up to 2 minutes)...done.
[...]

في Cloud Console، راجِع Cloud Function التي تم إنشاؤها:

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

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

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

9. اختبار الحل الشامل والتحقّق من صحته

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

تحميل صورة مناسبة

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

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

تحميل صورة غير متعلقة بالطعام

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

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

10. تهانينا!

تهانينا، لقد أنهيت التمرين المعملي.

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

اطّلع على الدروس التطبيقية الأخرى حول الترميز في Cymbal Eats:

تَنظيم

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

حذف المشروع

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