תחילת העבודה עם פונקציות מבוססות-אירועים ב-Cloud Run

1. מבוא

סקירה כללית

פונקציות Cloud Run הן דרך חדשה לפרוס עומסי עבודה באמצעות פרדיגמות מוכרות של אירועים ושל חתימות פונקציות של GCF. במקום להשתמש בתהליך build ובהגדרות הפריסה המובנות שלנו, פונקציות Cloud Run מאפשרות לכם שליטה ישירה בשירות הבסיסי שנוצר ב-Cloud Run.

עם פונקציות Cloud Run, אנחנו מספקים את חוויית המשתמש הפשוטה של פריסת קוד מקור ב-Cloud Run, ומאפשרים למפתחים שליטה מלאה בעומסי העבודה שלהם באמצעות הגדרות Cloud Run.

בקטע הזה מוסבר איך פורסים פונקציה מבוססת-אירועים ב-Node. תפרסו פונקציה שמופעלת בכל פעם שאובייקט מסתיים בקטגוריה של Google Cloud Storage.

ב-Codelab הזה נעשה שימוש בדוגמאות של nodejs בדוגמאות שבהמשך. עם זאת, אתם יכולים להשתמש בדוגמאות הקוד של Cloud Functions דור שני בשפה שתבחרו:

מה תלמדו

איך פורסים פונקציית Cloud Run מבוססת-אירועים שמופעלת בכל פעם שאובייקט מועלה לקטגוריה של GCS
איך יוצרים חשבון שירות עם התפקידים המתאימים כדי לקבל אירוע מ-Cloud Storage ולהפעיל את פונקציית Cloud Run

2. הגדרת משתני סביבה והפעלת ממשקי API

עדכון ה-CLI של gcloud

כדי להשתמש ב-Codelab הזה, צריך להתקין גרסה עדכנית של ה-CLI של gcloud. אפשר לעדכן את ה-CLI על ידי הרצת הפקודה

gcloud components update

הפעלת ממשקי ה-API

לפני שמתחילים להשתמש ב-codelab הזה, צריך להפעיל כמה ממשקי API. ב-codelab הזה צריך להשתמש בממשקי ה-API הבאים. כדי להפעיל את ממשקי ה-API האלה, מריצים את הפקודה הבאה:

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

הגדרה של משתני סביבה

אתם יכולים להגדיר משתני סביבה שישמשו אתכם לאורך כל ה-codelab הזה.

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 את התפקיד 'מקבל אירועים ב-Eventarc' (roles/eventarc.eventReceiver) בפרויקט, כדי שהטריגר יוכל לקבל אירועים מספקי אירועים.

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

לאחר מכן, מקצים לחשבון השירות את התפקיד Cloud Run Invoker כדי שהוא יוכל להפעיל את הפונקציה.

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 או באמצעות כלי gsutil CLI, למשל:

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

כשהקובץ יועלה בהצלחה, ייווצר אירוע והפונקציה תדפיס מידע בסיסי על האובייקט, למשל שם הקובץ. אפשר למצוא את הפלט הזה ברשומות היומן של הפונקציה ב-Cloud Console. לחלופין, אפשר להריץ שאילתה כדי לקבל את הפלט הזה באמצעות ה-CLI של gcloud:

gcloud logging read "resource.labels.service_name=$SERVICE_NAME 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 שיצרתם ב-codelab הזה.

אם אתם רוצים למחוק את הפרויקט כולו, אתם יכולים להיכנס לכתובת https://console.cloud.google.com/cloud-resource-manager, לבחור את הפרויקט שיצרתם בשלב 2 וללחוץ על 'מחיקה'. אם תמחקו את הפרויקט, תצטרכו לשנות את הפרויקטים ב-Cloud SDK. כדי לראות את רשימת כל הפרויקטים הזמינים, מריצים את הפקודה gcloud projects list.

תחילת העבודה עם פונקציות מבוססות-אירועים ב-Cloud Run קל לארגן דפים בעזרת אוספים אפשר לשמור ולסווג תוכן על סמך ההעדפות שלך.