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

1. مقدمة

نظرة عامة

دوالّ Cloud Run هي طريقة جديدة لنشر أعباء العمل باستخدام نماذج أحداث GCF وتوقيع الدالة المألوفين. بدلاً من استخدام عملية الإنشاء وإعدادات النشر التي ننصحك بها، تمنحك وظائف 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 CLI. يمكنك تعديل وحدة تحكّم سطر الأوامر من خلال تشغيل

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 Event Receiver (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. إنشاء الدالة ونشرها

أولاً، أنشئ دليلاً لرمز المصدر وانتقِل إليه باستخدام الأمر cd.

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 (new) لضبط نقطة دخول الخدمة الجديدة لتكون توقيع الدالة الذي تريد استدعائه.
  • (اختياري) العنصر -no-allow-unauthenticated لمنع إمكانية استدعاء وظيفتك بشكل علني

يمكنك عرض خدمتك الجديدة 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 Run"، كما هو موضّح أدناه:

# 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، على سبيل المثال:

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- تهانينا!

تهانينا على إكمال دورة codelab.

ننصحك بمراجعة مستندات وظائف 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.