شروع به کار با عملکردهای اجرای ابری رویداد محور

۱. مقدمه

نمای کلی

توابع Cloud Run روشی جدید برای استقرار بارهای کاری با استفاده از الگوهای رویدادگذاری GCF و امضای تابع است. به جای استفاده از فرآیند ساخت و پیکربندی‌های استقرار دلخواه ما، توابع Cloud Run به شما امکان کنترل مستقیم بر سرویس زیربنایی ایجاد شده در Cloud Run را می‌دهد.

با قابلیت‌های Cloud Run، ما تجربه کاربری ساده‌ای از پیاده‌سازی منبع Cloud Run را ارائه می‌دهیم و به توسعه‌دهندگان کنترل کاملی بر حجم کاری خود با استفاده از پیکربندی‌های Cloud Run می‌دهیم.

در این بخش، یاد خواهید گرفت که چگونه یک تابع رویدادمحور را در Node مستقر کنید. شما تابعی را مستقر خواهید کرد که هر زمان یک شیء در یک مخزن ذخیره‌سازی ابری گوگل نهایی می‌شود، فعال می‌شود.

این آزمایشگاه کد در مثال‌های زیر از نمونه‌های nodejs استفاده می‌کند. با این حال، شما می‌توانید از نمونه‌های کد نسل دوم Cloud Functions به زبان دلخواه خود استفاده کنید:

آنچه یاد خواهید گرفت

  • نحوه‌ی پیاده‌سازی یک تابع Cloud Run مبتنی بر رویداد که هر زمان یک شیء در یک سطل GCS آپلود می‌شود، فعال می‌شود
  • نحوه ایجاد یک حساب کاربری سرویس با نقش‌های مناسب برای دریافت رویداد از Cloud Storage و فراخوانی تابع Cloud Run

۲. متغیرهای محیطی را تنظیم کنید و APIها را فعال کنید

به‌روزرسانی رابط خط فرمان gcloud

این آزمایشگاه کد به نصب آخرین نسخه رابط خط فرمان gcloud نیاز دارد. می‌توانید با اجرای دستور زیر، رابط خط فرمان را به‌روزرسانی کنید:

gcloud components update

فعال کردن APIها

قبل از اینکه بتوانید از این codelab استفاده کنید، باید چندین API را فعال کنید. این codelab به استفاده از APIهای زیر نیاز دارد. می‌توانید با اجرای دستور زیر این APIها را فعال کنید:

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

۳. یک Storage Bucket و یک Service Account ایجاد کنید

یک سطل ذخیره‌سازی ایجاد کنید

با اجرای دستور زیر می‌توانید یک فضای ذخیره‌سازی ابری ایجاد کنید:

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

۴. تابع را ایجاد و مستقر کنید

ابتدا، یک دایرکتوری برای کد منبع ایجاد کنید و با دستور 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-event-codelab خود را با اجرای دستور زیر مشاهده کنید: 

gcloud beta run services describe $SERVICE_NAME

۵. رویداد را ایجاد کنید

می‌توانیم یک تریگر 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 از فضای ذخیره‌سازی ابری با استفاده از Eventarc را می‌توانید در مستندات Cloud Run اینجا بیابید: https://cloud.google.com/run/docs/tutorials/eventarc

۶. تابع را آزمایش کنید

پس از اتمام استقرار، URL سرویس را مشاهده خواهید کرد. برای فراخوانی تابع، باید یک درخواست احراز هویت شده با توکن هویت خود یا توکن هویت اصلی که نقش فراخوانی کننده Cloud Run را دارد، ارسال کنید، همانطور که در زیر نشان داده شده است: 

# 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

با استقرار تابع و ایجاد یک تریگر، اکنون آماده‌ایم تا تابع را فراخوانی کنیم.

یک فایل ایجاد کنید و آن را در فضای ذخیره‌سازی ابری خود آپلود کنید. می‌توانید این کار را از طریق رابط وب کنسول ابری یا با استفاده از ابزار gsutil CLI انجام دهید، مثلاً 

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

وقتی فایل با موفقیت آپلود شود، یک رویداد ایجاد می‌شود و تابع شما اطلاعات اولیه‌ای در مورد شیء، مثلاً نام فایل، چاپ می‌کند. می‌توانید این خروجی را در ورودی‌های لاگ تابع در کنسول ابری پیدا کنید. همچنین می‌توانید با استفاده از رابط خط فرمان gcloud، این خروجی را جستجو کنید: 

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

و باید خروجی زیر را ببینید 

"textPayload": "File: test.txt"

۷. تبریک می‌گویم!

تبریک می‌گویم که آزمایشگاه کد را تمام کردید!

توصیه می‌کنیم مستندات مربوط به عملکردهای Cloud Run را بررسی کنید.

آنچه ما پوشش داده‌ایم

  • نحوه‌ی پیاده‌سازی یک تابع Cloud Run مبتنی بر رویداد که هر زمان یک شیء در یک سطل GCS آپلود می‌شود، فعال می‌شود
  • نحوه ایجاد یک حساب کاربری سرویس با نقش‌های مناسب برای دریافت رویداد از Cloud Storage و فراخوانی تابع Cloud Run

۸. تمیز کردن

برای جلوگیری از هزینه‌های ناخواسته، (برای مثال، اگر این سرویس Cloud Run سهواً بیشتر از تخصیص فراخوانی ماهانه Cloud Run شما در سطح رایگان فراخوانی شود)، می‌توانید سرویس Cloud Run یا پروژه‌ای را که در مرحله 2 ایجاد کرده‌اید، حذف کنید.

برای حذف سرویس‌های Cloud Run، به کنسول ابری Cloud Run در آدرس https://console.cloud.google.com/run/ بروید و سرویس crf-event-codelab که در این codelab ایجاد کرده‌اید را حذف کنید.

اگر تصمیم به حذف کل پروژه دارید، می‌توانید به آدرس https://console.cloud.google.com/cloud-resource-manager بروید، پروژه‌ای را که در مرحله ۲ ایجاد کرده‌اید انتخاب کنید و گزینه Delete را انتخاب کنید. اگر پروژه را حذف کنید، باید پروژه‌ها را در Cloud SDK خود تغییر دهید. می‌توانید با اجرای gcloud projects list لیست تمام پروژه‌های موجود را مشاهده کنید.