הפעלת פונקציות מ-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 פרויקט.

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

    • Select a project: כדי לבחור פרויקט לא צריך תפקיד IAM ספציפי – אפשר לבחור כל פרויקט שקיבלתם בו תפקיד.
    • יצירת פרויקט: כדי ליצור פרויקט, צריך את התפקיד Project Creator (יצירת פרויקטים) (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 פרויקט.

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

    • Select a project: כדי לבחור פרויקט לא צריך תפקיד IAM ספציפי – אפשר לבחור כל פרויקט שקיבלתם בו תפקיד.
    • יצירת פרויקט: כדי ליצור פרויקט, צריך את התפקיד Project Creator (יצירת פרויקטים) (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. אם אתם כפופים למדיניות ארגונית של הגבלת דומיין שמגבילה הפעלות לא מאומתות של הפרויקט, תצטרכו לגשת לשירות הפרוס שלכם כמו שמתואר בקטע בדיקת שירותים פרטיים.

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

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

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

  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' (run.invoker) בפרויקט Google Cloud לחשבון השירות של Compute Engine. ההרשאה הזו ניתנת לכל השירותים והמשימות של 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 (הפעלת Cloud Run), הטריגר נוצר בהצלחה והוא פעיל. עם זאת, הטריגר לא יפעל כמצופה ותופיע הודעה דומה לזו שמופיעה ביומנים:

    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 Publisher (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 או לפני כן, כדי לתמוך בבקשות push מאומתות של 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": ">=16.0.0"
      },
      "scripts": {
        "test": "c8 mocha -p -j 2 test/*.test.js --timeout=60000"
      },
      "dependencies": {
        "@google-cloud/functions-framework": "^3.0.0"
      },
      "devDependencies": {
        "c8": "^10.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 בשם הטריגר.

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