بدء استخدام وظائف Cloud Run المستندة إلى الأحداث

1. مقدمة

نظرة عامة

تعتبر وظائف Cloud Run طريقة جديدة لنشر أعباء العمل باستخدام نماذج أحداث GCF المألوفة وتوقيع الوظائف. بدلاً من استخدام عملية الإنشاء التي تستند إلى رأينا وعمليات ضبط النشر، تمنحك وظائف Cloud Run إمكانية تحكُّم مباشر في "الخدمة" الأساسية التي تم إنشاؤها على Cloud Run.

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

في هذا القسم، ستتعرّف على كيفية تفعيل دالة تعتمد على الأحداث في Node. سيتم تفعيل دالة يتم تشغيلها عند الانتهاء من كائن في حزمة Google Cloud Storage.

يستخدم هذا الدرس التطبيقي حول الترميز نماذج العقدة في الأمثلة أدناه. ومع ذلك، يمكنك استخدام نماذج الرموز من الجيل الثاني لـ Cloud Functions باللغة التي تختارها:

• نماذج لدوال بايثون
• نماذج لدوال Nodejs
• الانتقال إلى نماذج للدوال
• نماذج دوال Java
• نماذج دوال PHP
• نماذج لدوال Ruby
• نماذج لدوال.NET

المعلومات التي ستطّلع عليها

• كيفية نشر دالة Cloud Run مستندة إلى الحدث يتم تشغيلها عند تحميل عنصر إلى حزمة GCS
• كيفية إنشاء حساب خدمة بأدوار مناسبة لاستلام حدث من Cloud Storage واستدعاء دالة Cloud Run

2. إعداد متغيرات البيئة وتفعيل واجهات برمجة التطبيقات

تحديث gcloud CLI

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

gcloud components update

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

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

gcloud services enable run.googleapis.com \
    cloudbuild.googleapis.com \
    storage.googleapis.com \
    artifactregistry.googleapis.com

إعداد متغيرات البيئة

يمكنك ضبط متغيّرات البيئة التي سيتم استخدامها خلال هذا الدرس التطبيقي حول الترميز.

PROJECT_ID=<YOUR_PROJECT_ID>
REGION=<YOUR_REGION, e.g. us-central1>

gcloud config set project $PROJECT_ID
SERVICE_NAME=crf-event-codelab
BUCKET_NAME=$PROJECT_ID-$SERVICE_NAME
TRIGGER_NAME=$SERVICE_NAME-trigger

3- إنشاء حزمة تخزين وحساب خدمة

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

يمكنك إنشاء حزمة على Cloud Storage من خلال تنفيذ الأمر التالي:

gsutil mb -l us-central1 gs://$BUCKET_NAME

إنشاء حساب خدمة

في هذا المثال، عليك إنشاء حساب خدمة يتضمّن أذونات EventArc المطلوبة ودور استدعاء Cloud Run لتلقي حدث من Cloud Storage واستدعاء وظيفة Cloud Run.

أولاً، أنشئ حساب الخدمة.

PROJECT_NUMBER=$(gcloud projects describe $PROJECT_ID --format='value(projectNumber)')

SERVICE_ACCOUNT="cloud-run-functions"
SERVICE_ACCOUNT_ADDRESS=$SERVICE_ACCOUNT@$PROJECT_ID.iam.gserviceaccount.com

gcloud iam service-accounts create $SERVICE_ACCOUNT \
  --display-name="Cloud Run functions Eventarc service account"

بعد ذلك، امنح دور مستلم الأحداث في Eventarc (roles/eventarc.eventReceiver) في المشروع إلى حساب الخدمة المرتبط بمشغِّل Eventarc حتى يتمكّن المشغّل من تلقّي الأحداث من موفّري الأحداث.

gcloud projects add-iam-policy-binding $PROJECT_ID \
  --member serviceAccount:$SERVICE_ACCOUNT_ADDRESS \
  --role=roles/eventarc.eventReceiver

بعد ذلك، امنح حساب الخدمة دور استدعاء تشغيل السحابة الإلكترونية كي يتمكّن من استدعاء الدالة.

gcloud projects add-iam-policy-binding $PROJECT_ID \
  --member serviceAccount:$SERVICE_ACCOUNT_ADDRESS \
  --role=roles/run.invoker

4. إنشاء الدالة ونشرها

أولاً، أنشئ دليلاً لرمز المصدر والقرص المضغوط في هذا الدليل.

mkdir ../$SERVICE_NAME && cd $_

بعد ذلك، أنشِئ ملف package.json يتضمّن المحتوى التالي:

{
    "dependencies": {
        "@google-cloud/functions-framework": "^3.0.0"
    }
}

بعد ذلك، أنشِئ ملف index.js يتضمّن المحتوى التالي:

const functions = require("@google-cloud/functions-framework");

// Register a CloudEvent callback with the Functions Framework that will
// be triggered by Cloud Storage.
functions.cloudEvent("helloGCS", (cloudEvent) => {
    console.log(`Event ID: ${cloudEvent.id}`);
    console.log(`Event Type: ${cloudEvent.type}`);

    const file = cloudEvent.data;
    console.log(`Bucket: ${file.bucket}`);
    console.log(`File: ${file.name}`);
    console.log(`Metageneration: ${file.metageneration}`);
    console.log(`Created: ${file.timeCreated}`);
    console.log(`Updated: ${file.updated}`);
});

يمكنك الآن نشر دالة Cloud Run من خلال تشغيل الأمر التالي:

gcloud beta run deploy $SERVICE_NAME \
 --source . \
      --function helloGCS \
      --region $REGION \
      --no-allow-unauthenticated

ملاحظات:

• تُستخدَم علامة –source لإخبار Cloud Run بإنشاء الدالة في خدمة مستندة إلى حاوية قابلة للتشغيل
• يتم استخدام علامة –الدالة (جديدة) لضبط نقطة دخول الخدمة الجديدة لتكون توقيع الدالة الذي تريد أن يتم استدعاؤه.
• (اختياري) عدم مصادقة –no-allow، لمنع أن تكون وظيفتك قابلة للاستدعاء بشكل علني

يمكنك الاطّلاع على خدمتك الجديدة "crf-nodejs-event" من خلال تنفيذ الأمر التالي:

gcloud beta run services describe $SERVICE_NAME

5- إنشاء الحدث

يمكننا إنشاء مشغل Eventarc لإرسال رسائل إلى وظيفتنا في كل مرة يتم فيها الانتهاء من كائن في Google Cloud Storage:

BUCKET_REGION=$REGION

gcloud eventarc triggers create $TRIGGER_NAME \
     --location=$REGION \
     --destination-run-service=crf-nodejs-event \
  --destination-run-region=$BUCKET_REGION \
     --event-filters="type=google.cloud.storage.object.v1.finalized" \
     --event-filters="bucket=$BUCKET_NAME" \
     --service-account=$SERVICE_ACCOUNT_ADDRESS

ملاحظات:

• gcs-function-trigger هو اسم المشغل
• crf-nodejs-event هو اسم خدمة Cloud Run حيث تم نشر الدالة
• بالنسبة إلى علامة –event-filters، لا تستخدِم البادئة gs:// في اسم الحزمة.

يمكن العثور على برنامج تعليمي تفصيلي لإعداد خدمة Trigger من Cloud Storage باستخدام Eventarc في مستندات Cloud Run هنا: https://cloud.google.com/run/docs/Tutorials/eventarc.

6- اختبار الدالة

عند اكتمال النشر، سيظهر لك عنوان URL للخدمة. ولاستدعاء الوظيفة، يجب إرسال طلب تمت مصادقته مع رمز الهوية أو رمز الهوية لمبدأ لديه دور "مُستدعي Cloud Runker"، كما هو موضّح أدناه:

# get the Service URL
SERVICE_URL="$(gcloud run services describe crf-nodejs-event --region us-central1 --format 'value(status.url)')"

# invoke the service
curl -H "Authorization: bearer $(gcloud auth print-identity-token)" -X GET $SERVICE_URL

بعد نشر الدالة وإنشاء عامل تشغيل، نكون جاهزين الآن لاستدعاء الدالة.

أنشِئ ملفًا وحمِّله إلى حزمتك على Cloud Storage. يمكنك إجراء ذلك من خلال واجهة الويب لخدمة Cloud Console أو باستخدام أداة gsutil CLI، مثلاً

echo "hello world" > test.txt
gsutil cp test gs://$BUCKET_NAME

عند تحميل الملف بنجاح، سيتم إنشاء حدث وستطبع الدالة بعض المعلومات الأساسية عن الكائن، مثل اسم الملف. يمكنك العثور على هذا الناتج في إدخالات السجلّ الخاصة بالدالة في Cloud Console. بدلاً من ذلك، يمكنك الاستعلام عن هذا الإخراج باستخدام gcloud CLI:

gcloud logging read "resource.labels.service_name=crf-nodejs-event AND textPayload: File" --format=json 

ومن المفترض أن يظهر لك الناتج

"textPayload": "File: test.txt"

7. تهانينا!

تهانينا على إكمال الدرس التطبيقي حول الترميز.

ننصحك بمراجعة مستندات وظائف التشغيل في السحابة الإلكترونية.

النقاط التي تناولناها

• كيفية نشر دالة Cloud Run مستندة إلى الحدث يتم تشغيلها عند تحميل عنصر إلى حزمة GCS
• كيفية إنشاء حساب خدمة بأدوار مناسبة لاستلام حدث من Cloud Storage واستدعاء دالة Cloud Run

8. تَنظيم

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

لحذف خدمات تشغيل السحابة الإلكترونية، انتقِل إلى Cloud Run Console على الرابط https://console.cloud.google.com/run/ واحذف خدمة crf-event-codelab التي أنشأتها في هذا الدرس التطبيقي حول الترميز.

إذا اخترت حذف المشروع بالكامل، يمكنك الانتقال إلى https://console.cloud.google.com/cloud-resource-manager، واختيار المشروع الذي أنشأته في الخطوة الثانية، ثم اختيار "حذف". إذا حذفت المشروع، ستحتاج إلى تغيير المشاريع في حزمة تطوير البرامج (SDK) للسحابة الإلكترونية. يمكنك عرض قائمة بجميع المشاريع المتاحة من خلال تشغيل gcloud projects list.