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

1. מבוא

סקירה כללית

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

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

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

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

• דוגמאות של פונקציות Python
• דוגמאות של פונקציות של Nodejs
• דוגמאות של פונקציות Go
• דוגמאות של פונקציות Java
• דוגמאות של פונקציות PHP
• דוגמאות של פונקציות Ruby
• דוגמאות של פונקציות.NET

מה תלמדו

• איך פורסים פונקציית 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 Event Acceptr (roles/eventarc.eventReceiver) בפרויקט לחשבון השירות שמשויך לטריגר Eventarc כדי שהטריגר יוכל לקבל אירועים מספקי האירועים.

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

לאחר מכן, מקצים לחשבון השירות את התפקיד 'invoker' של 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 ליצור את הפונקציה בשירות מבוסס קונטיינר שניתן להריץ
• דגל הפונקציה (חדש) משמש להגדרת נקודת הכניסה של השירות החדש כחתימת הפונקציה הרצויה.
• (אופציונלי) -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 Invoker, כמו בדוגמה הבאה:

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

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

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

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 שיצרתם ב-Codelab הזה.

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