1. نظرة عامة
في هذا التمرين، ستتعرّف على كيفية استخدام أحداث حِزم Cloud Storage وEventarc لبدء معالجة الأحداث. ستستخدم وظائف Cloud Run لتحليل البيانات ومعالجة الصور. ستستخدم الدالة Google Vision API وتحفظ الصورة الناتجة مرة أخرى في حزمة 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. ويمكنك تعديلها في أي وقت.
- يكون معرّف المشروع فريدًا في جميع مشاريع 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"
امنح دور 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 إلى إشعارات Pub/Sub من Cloud Storage وتتيح أنواع الأحداث المشابهة التالية:
في هذا الدرس العملي، ستنشر دالة وتبدأ تشغيلها عند الانتهاء من تحميل عنصر في Cloud Storage.
إكمال العنصر
يتم بدء أحداث إنهاء العناصر عند إكمال عملية "الكتابة" لعنصر في 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 الذي ستشغّله خدمة 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 API، يتم تحميل الملفات على أجزاء وتجميعها ككائن واحد. بالنسبة إلى الأجسام الأصغر حجمًا، استخدِم عمليات التحميل التي تتم من خلال طلب واحد.
يعمل الرمز البرمجي أدناه على تحميل صورة إلى مساحة التخزين في السحابة الإلكترونية باستخدام عملية تحميل واحدة.
index.js
const thumbnailImage = await thumbBucket.upload(thumbFile);
7- دمج واجهة برمجة التطبيقات Vision API
تتيح ميزة Cloud Vision للمطوّرين دمج ميزات رصد الرؤية بسهولة في التطبيقات، بما في ذلك تصنيف الصور ورصد الوجوه والمعالم والتعرّف البصري على الأحرف (OCR) ووضع علامات على المحتوى الفاضح.
تثبيت مكتبة البرامج
تتوفّر مكتبات برامج العملاء في السحابة الإلكترونية بعدّة لغات برمجة شائعة. لبدء استخدام المكتبات، عليك تثبيت مكتبة العميل.
إنشاء عميل لتطبيق "تعليقات توضيحية للصور"
للوصول إلى 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
في وحدة طرفية Cloudshell، نفِّذ الأمر أدناه لنشر وظائف 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، راجِع موضوع والاشتراك في 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:
- بدء سير عمل Cloud باستخدام Eventarc
- الاتصال بخدمة CloudSQL الخاصة من Cloud Run
- الاتصال بقواعد البيانات المُدارة بالكامل من Cloud Run
- تطبيق آمن بدون خادم باستخدام "الوكيل المدرك للهوية" (IAP)
- بدء مهام Cloud Run باستخدام Cloud Scheduler
- النشر بأمان على Cloud Run
- تأمين حركة مرور الإدخال في Cloud Run
- الاتصال بخدمة AlloyDB الخاصة من GKE Autopilot
تَنظيم
لتجنُّب تحصيل رسوم من حسابك على Google Cloud مقابل الموارد المستخدَمة في هذا الدليل التعليمي، يمكنك إما حذف المشروع الذي يحتوي على الموارد أو الاحتفاظ بالمشروع وحذف الموارد الفردية.
حذف المشروع
إنّ أسهل طريقة لإيقاف الفوترة هي حذف المشروع الذي أنشأته للدليل التعليمي.