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

1. מבוא

סקירה כללית

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

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

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

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

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

מה תלמדו

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

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

עדכון ה-CLI של gcloud

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

gcloud components update

הפעלת ממשקי API

לפני שתתחילו להשתמש בקודלאב הזה, תצטרכו להפעיל כמה ממשקי API. כדי להשתמש בקוד ה-Lab הזה, צריך להשתמש בממשקי ה-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

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. יצירה ופריסה של הפונקציה

קודם יוצרים ספרייה לקוד המקור ומעבירים את עצמנו לספרייה הזו באמצעות 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 (חדש) משמש להגדרת נקודת הכניסה של השירות החדש כחתימת הפונקציה שרוצים להפעיל
• (אופציונלי) האפשרות –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:// בשם הקטגוריה.

מדריך מפורט להגדרת שירות טריגר מ-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 או באמצעות הכלי CLI של gsutil, למשל:

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 של Cloud Run בכתובת https://console.cloud.google.com/run/ ומוחקים את השירות crf-event-codelab שיצרתם בקודלאב הזה.

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