הפעלת פונקציות מ-Cloud Storage באמצעות Eventarc

במדריך הזה נסביר איך לפרוס פונקציה מבוססת-אירועים ב-Cloud Run, ואיך להשתמש ב-Eventarc כדי להפעיל את הפונקציה בתגובה לאירועים ב-Cloud Storage באמצעות Google Cloud CLI.

כשמציינים מסננים לטריגר של Eventarc, אפשר להגדיר את הניתוב של האירועים, כולל מקור האירוע ויעד האירוע. בדוגמה שבמדריך הזה, עדכון של קטגוריה של Cloud Storage מפעיל את האירוע, ובקשה נשלחת לפונקציה שלכם בצורה של בקשת HTTP.

מטרות

במדריך הזה תלמדו:

  1. יצירת קטגוריה של Cloud Storage שתשמש כמקור האירועים.
  2. פריסת פונקציה מבוססת-אירועים.
  3. יוצרים טריגר של Eventarc.
  4. הפעלת הפונקציה על ידי העלאת קובץ ל-Cloud Storage.

עלויות

במסמך הזה משתמשים ברכיבים הבאים של Google Cloud, והשימוש בהם כרוך בתשלום:

בעזרת מחשבון העלויות אתם יכולים להעריך את העלויות בהתאם לשימוש הצפוי.

משתמשים חדשים של Google Cloud ? יכול להיות שאתם זכאים לתקופת ניסיון בחינם.

לפני שמתחילים

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

  1. נכנסים לחשבון Google Cloud . אנחנו ממליצים למשתמשים חדשים ב- Google Cloud ליצור חשבון כדי שיוכלו להעריך את הביצועים של המוצרים שלנו בתרחישים מהעולם האמיתי. לקוחות חדשים מקבלים בחינם גם קרדיט בשווי 300$ להרצה, לבדיקה ולפריסה של עומסי העבודה.
  2. התקינו את ה-CLI של Google Cloud.

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

  4. כדי לאתחל את ה-CLI של gcloud, הריצו את הפקודה הבאה:

    gcloud init
  5. יוצרים או בוחרים פרויקט ב- Google Cloud .

    התפקידים שנדרשים כדי לבחור או ליצור פרויקט

    • בחירת פרויקט: כדי לבחור פרויקט לא נדרש תפקיד IAM ספציפי – אתם יכולים לבחור כל פרויקט שקיבלתם בו תפקיד.
    • יצירת פרויקט: כדי ליצור פרויקט, צריך את התפקיד "יצירת פרויקטים" (roles/resourcemanager.projectCreator), שכולל את ההרשאה resourcemanager.projects.create. איך מקצים תפקידים?
    • יוצרים פרויקט ב- Google Cloud :

      gcloud projects create PROJECT_ID

      מחליפים את PROJECT_ID בשם של הפרויקט ב- Google Cloud שאתם יוצרים.

    • בוחרים את הפרויקט שיצרתם ב- Google Cloud :

      gcloud config set project PROJECT_ID

      מחליפים את PROJECT_ID בשם הפרויקט ב- Google Cloud .

  6. מוודאים שהחיוב מופעל בפרויקט ב- Google Cloud .

  7. התקינו את ה-CLI של Google Cloud.

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

  9. כדי לאתחל את ה-CLI של gcloud, הריצו את הפקודה הבאה:

    gcloud init
  10. יוצרים או בוחרים פרויקט ב- Google Cloud .

    התפקידים שנדרשים כדי לבחור או ליצור פרויקט

    • בחירת פרויקט: כדי לבחור פרויקט לא נדרש תפקיד IAM ספציפי – אתם יכולים לבחור כל פרויקט שקיבלתם בו תפקיד.
    • יצירת פרויקט: כדי ליצור פרויקט, צריך את התפקיד "יצירת פרויקטים" (roles/resourcemanager.projectCreator), שכולל את ההרשאה resourcemanager.projects.create. איך מקצים תפקידים?
    • יוצרים פרויקט ב- Google Cloud :

      gcloud projects create PROJECT_ID

      מחליפים את PROJECT_ID בשם של הפרויקט ב- Google Cloud שאתם יוצרים.

    • בוחרים את הפרויקט שיצרתם ב- Google Cloud :

      gcloud config set project PROJECT_ID

      מחליפים את PROJECT_ID בשם הפרויקט ב- Google Cloud .

  11. מוודאים שהחיוב מופעל בפרויקט ב- Google Cloud .

  12. אם אתם לא משתמשים ב-Cloud Shell, עדכנו את הרכיבים של Google Cloud CLI והתחברו באמצעות החשבון שלכם:
    gcloud components update
    gcloud auth login
  13. מפעילים את ממשקי ה-API:
    gcloud services enable artifactregistry.googleapis.com \
        cloudbuild.googleapis.com \
        eventarc.googleapis.com \
        run.googleapis.com \
        storage.googleapis.com
  14. מגדירים את משתני התצורה שבהם משתמשים במדריך הזה:
    export REGION=us-central1
    gcloud config set run/region ${REGION}
    gcloud config set run/platform managed
    gcloud config set eventarc/location ${REGION}
  15. אם אתם כפופים לכלל מדיניות של הארגון של הגבלה לפי דומיין שמגבילה הפעלות לא מאומתות לפרויקט, תצטרכו לגשת לשירות שנפרס כמו שמתואר בקטע בדיקת שירותים פרטיים.

הגדרת התפקידים הנדרשים

אתם או האדמין שלכם צריכים להקצות את תפקידי ה-IAM הבאים לחשבון הפריסה, לזהות של הטריגר, ולסוכני השירות של Pub/Sub ו-Cloud Storage (אופציונלי).

התפקידים הנדרשים לחשבון הפריסה

  1. אם אתם יוצרי הפרויקט, אתם מקבלים את התפקיד הבסיסי "בעלים" (roles/owner). כברירת מחדל, תפקיד ה-IAM הזה כולל את ההרשאות שנדרשות לגישה מלאה לרוב המשאבים של Google Cloud, ואתם יכולים לדלג על השלב הזה.

    אם אתם לא יוצרי הפרויקט, צריך לתת את ההרשאות הנדרשות בפרויקט לחשבון המשתמש המתאים. לדוגמה, חשבון משתמש יכול להיות חשבון Google (למשתמשי קצה) או חשבון שירות (לאפליקציות ולעומסי עבודה ממוחשבים). מידע נוסף זמין בדף תפקידים והרשאות של יעד האירוע.

    כדי לקבל את ההרשאות שדרושות להשלמת המדריך, בקשו מהאדמין להקצות לכם את התפקידים הבאים ב-IAM בפרויקט:

    להסבר על מתן תפקידים, ראו איך מנהלים את הגישה ברמת הפרויקט, התיקייה והארגון.

    יכול להיות שאפשר לקבל את ההרשאות הנדרשות גם באמצעות תפקידים בהתאמה אישית או תפקידים מוגדרים מראש.

    שימו לב שכברירת מחדל, ההרשאות של Cloud Build כוללות הרשאות להעלאה ולהורדה של פריטי מידע שנוצרו ב-Artifact Registry.

התפקידים הנדרשים לזהות הטריגר

  1. שימו לב לחשבון השירות שמוגדר כברירת מחדל ב-Compute Engine, כי תצטרכו לצרף אותו לטריגר של Eventarc כדי לייצג את הזהות של הטריגר לצורכי בדיקה. חשבון השירות הזה נוצר באופן אוטומטי אחרי שמפעילים שירות של Google Cloud שמשתמש ב-Compute Engine, או משתמשים בשירות כזה. כתובת האימייל שלו היא בפורמט הבא:

    PROJECT_NUMBER-compute@developer.gserviceaccount.com

    מחליפים את PROJECT_NUMBER במספר הפרויקט ב- Google Cloud. אפשר לראות את מספר הפרויקט בדף Welcome במסוף Google Cloud , או להריץ את הפקודה הבאה:

    gcloud projects describe PROJECT_ID --format='value(projectNumber)'

    בסביבות ייצור, מומלץ מאוד ליצור חשבון שירות חדש ולהקצות לו תפקיד אחד או יותר ב-IAM, שמכילים את ההרשאות המינימליות הנדרשות ופועלים לפי העיקרון של הרשאות מינימליות.

  2. כברירת מחדל, רק בעלי פרויקטים, עורכי פרויקטים, אדמינים של Cloud Run ומפעילים של Cloud Run יכולים להפעיל שירותי Cloud Run. אתם יכולים לשלוט בגישה לכל שירות בנפרד, אבל למטרות בדיקה, כדאי לתת לחשבון השירות של Compute Engine את התפקיד "מפעיל Cloud Run" (run.invoker) בפרויקט Google Cloud . כך מקצים את התפקיד בכל השירותים והמשימות של Cloud Run בפרויקט.
    gcloud projects add-iam-policy-binding PROJECT_ID \
        --member=serviceAccount:PROJECT_NUMBER-compute@developer.gserviceaccount.com \
        --role=roles/run.invoker

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

    The request was not authenticated. Either allow public access or set the proper Authorization header.
  3. מקצים את התפקיד "מקבל אירועים ב-Eventarc" (roles/eventarc.eventReceiver) בפרויקט לחשבון השירות שמוגדר כברירת מחדל ב-Compute Engine, כדי שהטריגר של Eventarc יוכל לקבל אירועים מספקי אירועים.
    gcloud projects add-iam-policy-binding PROJECT_ID \
        --member=serviceAccount:PROJECT_NUMBER-compute@developer.gserviceaccount.com \
        --role=roles/eventarc.eventReceiver

תפקיד אופציונלי לסוכן השירות של Cloud Storage

  • לפני שיוצרים טריגר לאירועים ישירים מ-Cloud Storage, צריך לתת לסוכן השירות של Cloud Storage את התפקיד "פרסום הודעות ב-Pub/Sub" (roles/pubsub.publisher):

    SERVICE_ACCOUNT="$(gcloud storage service-agent --project=PROJECT_ID)"
    
    gcloud projects add-iam-policy-binding PROJECT_ID \
        --member="serviceAccount:${SERVICE_ACCOUNT}" \
        --role='roles/pubsub.publisher'

תפקיד אופציונלי לסוכן השירות של Pub/Sub

  • אם הפעלתם את סוכן השירות של Cloud Pub/Sub ב-8 באפריל 2021 או לפני כן, כדי לתמוך בבקשות דחיפה מאומתות של Pub/Sub, צריך להקצות לסוכן השירות את התפקיד "יצירת אסימונים בחשבון שירות" (roles/iam.serviceAccountTokenCreator). אחרת, התפקיד הזה מוקצה כברירת מחדל:
    gcloud projects add-iam-policy-binding PROJECT_ID \
        --member=serviceAccount:service-PROJECT_NUMBER@gcp-sa-pubsub.iam.gserviceaccount.com \
        --role=roles/iam.serviceAccountTokenCreator

יצירת קטגוריה של Cloud Storage

יוצרים קטגוריה של Cloud Storage שתשמש כמקור האירועים:

gcloud storage buckets create -l us-central1 gs://PROJECT_ID-bucket/

כתיבת פונקציה מבוססת-אירועים

כדי לכתוב פונקציה מבוססת-אירועים:

Node.js

  1. יוצרים ספרייה חדשה בשם helloGCS ועוברים אליה:

       mkdir helloGCS
       cd helloGCS
    

  2. יוצרים קובץ package.json בספרייה helloGCS כדי לציין את יחסי התלות של Node.js:

    {
      "name": "nodejs-docs-samples-functions-v2-storage",
      "version": "0.0.1",
      "private": true,
      "license": "Apache-2.0",
      "author": "Google LLC",
      "repository": {
        "type": "git",
        "url": "https://github.com/GoogleCloudPlatform/nodejs-docs-samples.git"
      },
      "engines": {
        "node": ">=20.0.0"
      },
      "scripts": {
        "test": "c8 mocha -p -j 2 test/*.test.js --timeout=60000"
      },
      "dependencies": {
        "@google-cloud/functions-framework": "^5.0.0"
      },
      "devDependencies": {
        "c8": "^12.0.0",
        "mocha": "^10.0.0",
        "sinon": "^18.0.0",
        "supertest": "^7.0.0"
      }
    }
    
  3. יוצרים קובץ index.js בספרייה helloGCS עם הקוד הבא לדוגמה ב-Node.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}`);
    });

Python

  1. יוצרים ספרייה חדשה בשם helloGCS ועוברים אליה:

       mkdir helloGCS
       cd helloGCS
    

  2. יוצרים קובץ requirements.txt בספרייה helloGCS כדי לציין את יחסי התלות של Python:

    functions-framework==3.9.2
    cloudevents==1.11.0

    הפעולה הזו מוסיפה חבילות שנדרשות לדוגמה.

  3. יוצרים קובץ main.py בספרייה helloGCS עם הקוד הבא ב-Python:

    from cloudevents.http import CloudEvent
    
    import functions_framework
    
    
    # Triggered by a change in a storage bucket
    @functions_framework.cloud_event
    def hello_gcs(cloud_event: CloudEvent) -> tuple:
        """This function is triggered by a change in a storage bucket.
    
        Args:
            cloud_event: The CloudEvent that triggered this function.
        Returns:
            The event ID, event type, bucket, name, metageneration, and timeCreated.
        """
        data = cloud_event.data
    
        event_id = cloud_event["id"]
        event_type = cloud_event["type"]
    
        bucket = data["bucket"]
        name = data["name"]
        metageneration = data["metageneration"]
        timeCreated = data["timeCreated"]
        updated = data["updated"]
    
        print(f"Event ID: {event_id}")
        print(f"Event type: {event_type}")
        print(f"Bucket: {bucket}")
        print(f"File: {name}")
        print(f"Metageneration: {metageneration}")
        print(f"Created: {timeCreated}")
        print(f"Updated: {updated}")
    
        return event_id, event_type, bucket, name, metageneration, timeCreated, updated
    
    

פריסת פונקציה מבוססת-אירועים

כדי לפרוס את הפונקציה helloworld-events, מריצים את הפקודה הבאה בספרייה שמכילה את הקוד לדוגמה:

Node.js

gcloud run deploy helloworld-events \
      --source . \
      --function helloGCS \
      --base-image BASE_IMAGE \
      --region us-central1

מחליפים את BASE_IMAGE בסביבת קובץ האימג' הבסיסי של הפונקציה, לדוגמה nodejs24. למידע נוסף על קובצי אימג' בסיסיים ועל החבילות שכלולות בכל קובץ אימג', קראו את המאמר סביבות זמן ריצה של שפות נתמכות וקובצי אימג' בסיסיים.

Python

gcloud run deploy helloworld-events \
      --source . \
      --function hello_gcs \
      --base-image BASE_IMAGE \
      --region us-central1

מחליפים את BASE_IMAGE בסביבת קובץ האימג' הבסיסי של הפונקציה, לדוגמה python314. למידע נוסף על קובצי אימג' בסיסיים ועל החבילות שכלולות בכל קובץ אימג', קראו את המאמר סביבות זמן ריצה של שפות נתמכות וקובצי אימג' בסיסיים.

בסיום הפריסה, ב-Google Cloud CLI תוצג כתובת ה-URL שבה השירות פועל.

יצירת טריגר של Eventarc

הטריגר של Eventarc שולח אירועים מהקטגוריה של Cloud Storage לשירות helloworld-events ב-Cloud Run.

  1. יוצרים טריגר שמסנן אירועים של Cloud Storage:

    gcloud eventarc triggers create TRIGGER_NAME  \
        --location=${REGION} \
        --destination-run-service=helloworld-events  \
        --destination-run-region=${REGION} \
        --event-filters="type=google.cloud.storage.object.v1.finalized" \
        --event-filters="bucket=PROJECT_ID-bucket" \
        --service-account=PROJECT_NUMBER-compute@developer.gserviceaccount.com

    מחליפים את:

    • TRIGGER_NAME בשם של הטריגר.
    • ‫PROJECT_ID במזהה הפרויקט ב- Google Cloud .
    • ‫PROJECT_NUMBER במספר הפרויקט ב- Google Cloud .

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

  2. מוודאים שהטריגר נוצר בהצלחה. שימו לב: למרות שהטריגר נוצר באופן מיידי, יכול להיות שיעברו עד שתי דקות עד שהוא יפעל באופן מלא.

    gcloud eventarc triggers list --location=${REGION}

    הפלט אמור להיראות כך:

    NAME: helloworld-events
    TYPE: google.cloud.storage.object.v1.finalized
    DESTINATION: Cloud Run service: helloworld-events
    ACTIVE: Yes
    LOCATION: us-central1
    

יצירה וצפייה באירוע

מעלים קובץ טקסט לקטגוריה של Cloud Storage כדי ליצור אירוע שמנותב לפונקציה. פונקציית Cloud Run מתעדת את האירוע ביומני השירות.

  1. מעלים קובץ טקסט ל-Cloud Storage כדי ליצור אירוע:

     echo "Hello World" > random.txt
     gcloud storage cp random.txt gs://PROJECT_ID-bucket/random.txt
    

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

  2. כדי לראות את הרשומה ביומן:

    1. מסננים את רשומות היומן ומחזירים את הפלט בפורמט JSON:

      gcloud logging read "resource.labels.service_name=helloworld-events AND textPayload:random.txt" --format=json
      
    2. מחפשים רשומה ביומן שדומה לזו:

      [
        {
         ....
          "resource": {
            "labels": {
              ....
              "location": "us-central1",
              .....
              "service_name": "helloworld-events"
            },
          },
          "textPayload": "File: random.txt",
           .....
        }
      ]
      

      יכול להיות שייקח ליומנים כמה דקות להופיע. אם אתם לא רואים אותם מיד, נסו שוב אחרי דקה.

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

הסרת המשאבים

אם יצרתם פרויקט חדש בשביל המדריך הזה, מחקו את הפרויקט. אם השתמשתם בפרויקט קיים ואתם רוצים לשמור אותו בלי השינויים שנוספו במדריך הזה, מחקו את המשאבים שנוצרו בשביל המדריך.

מחיקת הפרויקט

הדרך הקלה ביותר לבטל את החיוב היא למחוק את הפרויקט שיצרתם בשביל המדריך הזה.

כדי למחוק את הפרויקט:

  1. במסוף Google Cloud , נכנסים לדף Manage resources.

    כניסה לדף Manage resources

  2. ברשימת הפרויקטים, בוחרים את הפרויקט שרוצים למחוק ולוחצים על Delete.
  3. כדי למחוק את הפרויקט, כותבים את מזהה הפרויקט בתיבת הדו-שיח ולוחצים על Shut down.

מחיקת משאבי המדריך

  1. מוחקים את השירות ב-Cloud Run שפרסתם במדריך הזה:

    gcloud run services delete SERVICE_NAME

    כאשר SERVICE_NAME הוא שם השירות שבחרתם.

    אפשר גם למחוק שירותי Cloud Run ממסוףGoogle Cloud .

  2. מסירים את כל הגדרות ברירת המחדל של ה-CLI של gcloud שהוספתם במהלך ההגדרה של המדריך.

    לדוגמה:

    gcloud config unset run/region

    או

    gcloud config unset project

  3. מוחקים משאבים אחרים של Google Cloud שנוצרו במדריך הזה:

    • מוחקים את הטריגר של Eventarc:
      gcloud eventarc triggers delete TRIGGER_NAME
      
      מחליפים את TRIGGER_NAME בשם הטריגר.

המאמרים הבאים