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

1. مقدمة

نظرة عامة

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

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

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

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

ما ستتعلمه

  • كيفية نشر دالة 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- إنشاء حزمة Storage وحساب خدمة

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

يمكنك إنشاء حزمة 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

بعد ذلك، امنح حساب الخدمة دور "منفّذ Cloud Run" ليتمكّن من استدعاء الدالة.

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 بإنشاء الدالة في خدمة مستندة إلى حاوية قابلة للتشغيل
  • يتم استخدام العلامة ‎--function (جديدة) لضبط نقطة دخول الخدمة الجديدة لتكون توقيع الدالة التي تريد استدعاءها
  • (اختياري) ‎–no-allow-unauthenticated لمنع استدعاء وظيفتك بشكل علني

يمكنك عرض خدمتك الجديدة crf-event-codelab من خلال تنفيذ الأمر التالي:

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=$SERVICE_NAME \
  --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-event-codelab هو اسم خدمة Cloud Run التي تم نشر الدالة عليها
  • بالنسبة إلى العلامة ‎–event-filters، لا تستخدِم البادئة gs:// في اسم الحزمة.

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

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

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

# get the Service URL
SERVICE_URL="$(gcloud run services describe $SERVICE_NAME --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، على سبيل المثال:

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

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

gcloud logging read "resource.labels.service_name=$SERVICE_NAME AND textPayload: File" --format=json

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

"textPayload": "File: test.txt"

7. تهانينا!

تهانينا على إكمال هذا الدرس العملي.

ننصحك بمراجعة مستندات دوال Cloud Run.

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

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

8. تَنظيم

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

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

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