‫Google משתמשת בטכנולוגיית AI כדי לתרגם תוכן לשפה המועדפת עליך. בתרגומים כאלו עשויות להיות שגיאות.

הגדרת התראות ב-BigQuery

Cloud Build יכול לשלוח לכם התראות על עדכוני build בערוצים ספציפיים, כמו Slack או שרת SMTP. בדף הזה מוסבר איך להגדיר התראות באמצעות BigQuery notifier.

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

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

מפעילים את Cloud Build API,‏ Cloud Run API,‏ Pub/Sub API ו-BigQuery API.
תפקידים שנדרשים להפעלת ממשקי API
כדי להפעיל ממשקי API, נדרשת ההרשאה serviceusage.services.enable. אם יצרתם את הפרויקט, סביר להניח שכבר יש לכם את ההרשאה הזו דרך התפקיד 'בעלים' (roles/owner). אחרת, תוכלו לקבל את ההרשאה הזו דרך התפקיד 'אדמין בממשק Service Usage' (roles/serviceusage.serviceUsageAdmin). איך מקצים תפקידים
הפעלת ממשקי ה-API

מתקינים את Google Cloud CLI.

הגדרת התראות ב-BigQuery

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

כדי להגדיר התראות ב-BigQuery:

נותנים לחשבון השירות של Cloud Run הרשאה ליצור ולכתוב טבלאות ב-BigQuery, הרשאה לאחזר נתונים מ-Artifact Registry שקשורים ל-build, וגישת קריאה וכתיבה לקטגוריות של Cloud Storage:
1. נכנסים לדף IAM במסוף Google Cloud :
  
  פתיחת הדף IAM
2. מאתרים את חשבון השירות של Compute Engine שמוגדר כברירת מחדל שמשויך לפרויקט:
  
  חשבון השירות של Compute Engine שמוגדר כברירת מחדל ייראה בערך כך:
```
PROJECT_NUMBER-compute@developer.gserviceaccount.com
```
3. לוחצים על סמל העיפרון בשורה שמכילה את חשבון השירות של Compute Engine שמוגדר כברירת מחדל. תוצג הכרטיסייה גישת עריכה.
4. לוחצים על הוספת תפקיד נוסף.
5. מוסיפים את התפקידים הבאים:
  - קורא של Artifact Registry
  - עריכה של נתוני BigQuery
  - צפייה באובייקט אחסון
  התפקיד Artifact Registry Reader מאפשר לכם לאחזר נתונים של התמונות. התפקיד BigQuery Data Editor מעניק לכם גישת קריאה וכתיבה לנתונים. התפקיד צפייה באובייקט אחסון מעניק גישת קריאה לאובייקטים של Cloud Storage.
  
  הערה: אם רוצים להעניק הרשאות ברמת הקטגוריה ולא ברמת הפרויקט, צריך להוסיף את התפקיד Storage Legacy Object Owner לקטגוריה כשיוצרים אותה. מידע נוסף זמין במאמר תפקידים ברמת הפרויקט לעומת תפקידים ברמת הקטגוריה.
6. לוחצים על Save.
כותבים קובץ תצורה של כלי ההתראה כדי להגדיר את כלי ההתראה של BigQuery ולסנן אירועים של בנייה:

בדוגמה הבאה של קובץ התצורה של כלי ההתראה, השדה filter משתמש בCommon Expression Language עם המשתנה build כדי לסנן אירועי build עם מזהה טריגר ספציפי:
```
apiVersion: cloud-build-notifiers/v1
kind: BigQueryNotifier
metadata:
  name: example-bigquery-notifier
spec:
  notification:
    filter: build.build_trigger_id == "123e4567-e89b-12d3-a456-426614174000"
    params:
      buildStatus: $(build.status)
    delivery:
      table: projects/PROJECT_ID/datasets/DATASET_NAME/tables/TABLE_NAME
    template:
      type: golang
      uri: gs://BUCKET_NAME/bq.json
```
כאשר:
- ‫buildStatus הוא פרמטר מותאם אישית. הפרמטר הזה מקבל את הערך ${build.status}, שהוא הסטטוס של הבנייה.
- ‫BUCKET_NAME הוא שם הקטגוריה.
- ‫PROJECT_ID הוא מזהה Google Cloud הפרויקט.
- ‫DATASET_NAME הוא השם שרוצים לתת למערך הנתונים.
- ‫TABLE_NAME הוא השם שרוצים לתת לטבלה.
- השדה uri מפנה לקובץ bq.json. הקובץ הזה מפנה לתבנית JSON שמתארחת ב-Cloud Storage ומייצג את המידע שצריך להוסיף לטבלה ב-BigQuery.
  
  ניסיוני — התאמה אישית של התראות באמצעות תבניות
  
  השימוש בתכונה הזו כפוף לתנאי השימוש במוצרים בגרסת טרום-GA, שמפורטים בחלק "תנאי שירות הכלליים" בתנאים הספציפיים של השירות. השימוש בתכונות בגרסת טרום-GA הוא "כפי שהן" (As is), ויכול להיות שהתמיכה בהן תהיה מוגבלת. מידע נוסף זמין בקטע תיאור שלבי ההשקה.
דוגמה לקובץ תבנית מופיעה בקובץ bq.json במאגר cloud-build-notifiers.

הערך TABLE_NAME בקובץ ההגדרות של כלי ההתראות יכול להתייחס ל:
- טבלה שלא קיימת
- טבלה ריקה ללא סכימה
- טבלה קיימת עם סכימה שתואמת למפרטי הסכימה בהתראה של BigQuery
  
  הערה: הפניות לטבלה קיימת עם מפרט סכימה שלא תואם ל-BigQuery notifier יגרמו לשגיאה.
מומלץ לציין את מזהה טריגר לפיתוח גרסת Build כמסנן, כי ציון מזהה טריגר לפיתוח גרסת Build מאפשר לכם לקשר בין נתוני בנייה לטריגרים. אפשר גם לציין כמה מזהי טריגרים ברשימה: build.build_trigger_id in ["example-id-123", "example-id-456"].

כדי לקבל את מזהה הטריגר, מריצים את הפקודה הבאה, כש-TRIGGER_NAME הוא שם הטריגר:

gcloud builds triggers describe TRIGGER_NAME

הפקודה תציג רשימה של שדות שמשויכים לטריגר, כולל מזהה הטריגר.

הערה: הנתונים מאוחסנים רק לגבי אירועי בנייה עם סטטוס סופי, כמו SUCCESS או FAILURE.

כדי לראות את הדוגמה, אפשר לעיין בקובץ ההגדרות של כלי ההתראות עבור כלי ההתראות של BigQuery.

במאמר על משאב Build מפורטים שדות נוספים שאפשר לסנן לפיהם. דוגמאות נוספות לסינון זמינות במאמר שימוש ב-CEL לסינון אירועי בנייה.
מעלים את קובץ ההגדרות של כלי ההתראה לקטגוריה של Cloud Storage:
1. אם אין לכם קטגוריה של Cloud Storage, מריצים את הפקודה הבאה כדי ליצור קטגוריה, כאשר BUCKET_NAME הוא השם שרוצים לתת לקטגוריה, בכפוף לדרישות למתן שמות.
```
gcloud storage buckets create gs://BUCKET_NAME/
```
2. מעלים את קובץ ההגדרות של כלי ההתראה לקטגוריה:
```
gcloud storage cp CONFIG_FILE_NAME gs://BUCKET_NAME/CONFIG_FILE_NAME
```
  כאשר:
  - ‫BUCKET_NAME הוא שם הקטגוריה.
  - ‫CONFIG_FILE_NAME הוא שם קובץ ההגדרות של כלי ההתראות.
פורסים את כלי ההתראה ב-Cloud Run:
```
 gcloud run deploy SERVICE_NAME \
   --image=us-east1-docker.pkg.dev/gcb-release/cloud-build-notifiers/bigquery:latest \
   --no-allow-unauthenticated \
   --update-env-vars=CONFIG_PATH=CONFIG_PATH,PROJECT_ID=PROJECT_ID
```
כאשר:
- ‫SERVICE_NAME הוא השם של שירות Cloud Run שבו פורסים את האימג'.
- ‫CONFIG_PATH הוא הנתיב לקובץ ההגדרות של כלי ההתראה של BigQuery, ‏ gs://BUCKET_NAME/CONFIG_FILE_NAME.
- ‫PROJECT_ID הוא מזהה Google Cloud הפרויקט.
הפקודה gcloud run deploy שולפת את הגרסה העדכנית של התמונה המתארחת מ-Artifact Registry שבבעלות Cloud Build. ‫Cloud Build תומך בתמונות של כלי התראה למשך תשעה חודשים. אחרי תשעה חודשים, Cloud Build מוחק את גרסת התמונה. אם רוצים להשתמש בגרסה קודמת של תמונה, צריך לציין את הגרסה הסמנטית המלאה של תג התמונה במאפיין image של הפקודה gcloud run deploy. גרסאות קודמות של תמונות ותגים אפשר למצוא ב-Artifact Registry.

הערה: במהלך הפעלת הפקודה הזו, יכול להיות שתתבקשו לציין ארגומנטים נוספים כמו --region או --platform. מידע נוסף על הפרמטרים שאפשר להעביר לפקודה gcloud run deploy זמין במאמר פריסה ב-Cloud Run. אם אין לכם אפשרות לפרוס את כלי ההתראה באמצעות הפקודה הזו, תוכלו לעיין במדריך לפתרון בעיות ב-Cloud Run כדי לקבל פתרונות לשגיאות פריסה.
יוצרים חשבון שירות שייצג את הזהות של המינוי ל-Pub/Sub:
```
gcloud iam service-accounts create SUB_IDENTITY_SERVICE_ACCOUNT \
  --display-name "SUB_IDENTITY_SERVICE_ACCOUNT_DISPLAY_NAME"
```
כאשר:
- ‫SUB_IDENTITY_SERVICE_ACCOUNT הוא שם לחשבון השירות.
- ‫SUB_IDENTITY_SERVICE_ACCOUNT_DISPLAY_NAME הוא השם המוצג של חשבון השירות.
הערה: חשבון השירות הזה שונה מחשבון השירות של Pub/Sub, שנוצר כש Google Cloud יוצרים מינוי ל-Pub/Sub בפעם הראשונה. כתובת חשבון השירות של Pub/Sub היא service-PROJECT_NUMBER@gcp-sa-pubsub.iam.gserviceaccount.com.
נותנים לחשבון השירות של זהות המנוי ב-Pub/Sub את ההרשאות שנדרשות ליצירת אסימוני אימות בGoogle Cloud פרויקט.
```
gcloud iam service-accounts add-iam-policy-binding \
    SUB_IDENTITY_SERVICE_ACCOUNT@PROJECT_ID.iiam.gserviceaccount.com \
    --member=serviceAccount:service-PROJECT_NUMBER@gcp-sa-pubsub.iam.gserviceaccount.com \
    --role=roles/iam.serviceAccountTokenCreator
```
כאשר:
- ‫PROJECT_ID הוא מזהה Google Cloud הפרויקט.
- ‫PROJECT_NUMBER הוא מספר הפרויקט Google Cloud .
נותנים לחשבון השירות SUB_IDENTITY_SERVICE_ACCOUNT את התפקיד Invoker ב-Cloud Run:
```
gcloud run services add-iam-policy-binding SERVICE_NAME \
   --member=serviceAccount:SUB_IDENTITY_SERVICE_ACCOUNT@PROJECT_ID.iam.gserviceaccount.com \
   --role=roles/run.invoker
```
כאשר:
- ‫SERVICE_NAME הוא השם של שירות Cloud Run שבו פורסים את האימג'.
- ‫PROJECT_ID הוא מזהה Google Cloud הפרויקט.
יוצרים את הנושא cloud-builds כדי לקבל הודעות עדכון לגבי הגרסה של כלי ההתראות:
```
gcloud pubsub topics create cloud-builds
```
אפשר גם להגדיר שם נושא מותאם אישית בקובץ תצורת ה-build כדי שההודעות יישלחו לנושא המותאם אישית במקום זאת. במקרה כזה, יוצרים נושא עם אותו שם נושא מותאם אישית:
```
gcloud pubsub topics create topic-name
```
מידע נוסף זמין במאמר בנושא נושאי Pub/Sub להתראות על בנייה.
יוצרים מנוי Pub/Sub מסוג push עבור כלי ההתראה:

     gcloud pubsub subscriptions create subscriber-id \
       --topic=cloud-builds \
       --push-endpoint=SERVICE_URL \
       --push-auth-service-account=SUB_IDENTITY_SERVICE_ACCOUNT@PROJECT_ID.iam.gserviceaccount.com

כאשר: + SUBSCRIBER_ID הוא השם שרוצים לתת למינוי. ‫+ SERVICE_URL היא כתובת ה-URL שנוצרה על ידי Cloud Run עבור השירות החדש. ‫+ PROJECT_ID הוא מזהה הפרויקט. Google Cloud

Note: By default, [subscriptions expire after 31 days of inactivity](/pubsub/docs/subscription-overview#lifecycle).
You can adjust or disable the expiration period by including the
[`--expiration-period` flag](/sdk/gcloud/reference/pubsub/subscriptions/create#--expiration-period)
when creating the subscription.

ההתראות על הפרויקט שלכם ב-Cloud Build מוגדרות עכשיו.

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

הצגת נתוני בנייה

כדי לראות את נתוני הבנייה ב-BigQuery:

פותחים את הדף במסוף BigQuery:

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

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

גישה לנתוני בנייה

אפשר להריץ שאילתות על הנתונים בטבלה באמצעות כלי שורת הפקודה bq או מסוף BigQuery.

CLI

כדי לשלוח שאילתה לנתונים בטבלה באמצעות כלי שורת הפקודה bq, מריצים את הפקודה הבאה בטרמינל, כאשר SQL_QUERY היא השאילתה:

bq query SQL_QUERY

אם אתם מתכננים להשתמש בדוגמאות לשאילתות שמופיעות בדף הזה, הקפידו לציין את הדגל --nouse_legacy_sql בפקודה. בכלי שורת הפקודה bq נעשה שימוש ב-SQL מדור קודם, אבל בשאילתות לדוגמה לא. כדי להריץ שאילתות על נתונים בלי להשתמש ב-SQL מדור קודם, מריצים את הפקודה הבאה בטרמינל:

bq query SQL_QUERY --nouse_legacy_sql

המסוף

כדי להריץ שאילתה על הנתונים בטבלה באמצעות מסוף BigQuery:

פותחים את הדף במסוף BigQuery:

פתיחת הדף של BigQuery
בקטע משאבים, לוחצים על שם הטבלה שרוצים לשלוח אליה שאילתה.
כותבים את שאילתת ה-SQL בעורך השאילתות.

שימוש בשאילתות כדי לגשת לנתוני בנייה

בדוגמאות הבאות לשאילתות אפשר לראות איך ניגשים לנתוני בנייה של אירוע בנייה אחרי שמגדירים את כלי ההתראה של BigQuery:

היסטוריית הבנייה הכוללת

SELECT * FROM `projectID.datasetName.tableName`

יצירת ספירות של קמפיינים לפי סטטוס

SELECT STATUS, COUNT(*)
FROM `projectID.datasetName.tableName`
GROUP BY STATUS

תדירות הפריסה היומית בשבוע הנוכחי

SELECT DAY, COUNT(STATUS) AS Deployments
FROM (SELECT DATETIME_TRUNC(CreateTime, WEEK) AS WEEK,
      DATETIME_TRUNC(CreateTime, DAY) AS DAY,
      STATUS
      FROM `projectID.datasetName.tableName`
      WHERE STATUS="SUCCESS")
WHERE WEEK = DATETIME_TRUNC(CURRENT_DATETIME(), WEEK)
GROUP BY DAY

דוגמאות נוספות לשאילתות מופיעות בקובץ Cloud Build BigQuery Notifier README במאגר cloud-build-notifiers ב-GitHub. במאמר שליחת שאילתות לנתונים וצפייה בהם מוסבר איך לשלוח שאילתות לנתונים באמצעות BigQuery.

שימוש ב-CEL לסינון אירועים של בנייה

‫Cloud Build משתמש ב-CEL עם המשתנה build בשדות שמופיעים במשאב Build כדי לגשת לשדות שמשויכים לאירוע הבנייה, כמו מזהה הטריגר, רשימת התמונות או ערכי ההחלפה. אפשר להשתמש במחרוזת filter כדי לסנן אירועי בנייה בקובץ ההגדרות של הבנייה באמצעות כל שדה שמופיע במשאב Build. כדי למצוא את התחביר המדויק שמשויך לשדה, אפשר לעיין בקובץ cloudbuild.proto.

סינון לפי מזהה טריגר

כדי לסנן לפי מזהה טריגר, מציינים את ערך מזהה הטריגר בשדה filter באמצעות build.build_trigger_id, כאשר trigger-id הוא מזהה הטריגר כמחרוזת:

filter: build.build_trigger_id == trigger-id

סינון לפי סטטוס

כדי לסנן לפי סטטוס, מציינים את סטטוס הבנייה שרוצים לסנן לפיו בשדה filter באמצעות build.status.

בדוגמה הבאה אפשר לראות איך מסננים אירועי build עם סטטוס SUCCESS באמצעות השדה filter:

filter: build.status == Build.Status.SUCCESS

אפשר גם לסנן את הגרסאות עם סטטוסים שונים. בדוגמה הבאה מוצג סינון של אירועי בנייה עם סטטוס SUCCESS, FAILURE או TIMEOUT באמצעות השדה filter:

filter: build.status in [Build.Status.SUCCESS, Build.Status.FAILURE, Build.Status.TIMEOUT]

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

סינון לפי תג

כדי לסנן לפי תג, מציינים את הערך של התג בשדה filter באמצעות build.tags, כאשר tag-name הוא השם של התג:

filter: tag-name in build.tags

אפשר לסנן לפי מספר התגים שצוינו באירוע הבנייה באמצעות size. בדוגמה הבאה, השדה filter מסנן אירועי build שיש להם בדיוק שני תגים, כאשר אחד מהתגים הוא v1:

filter: size(build.tags) == 2 && "v1" in build.tags

סינון לפי תמונות

כדי לסנן לפי תמונות, מציינים את הערך של התמונה בשדה filter באמצעות build.images, כאשר image-name הוא השם המלא של התמונה כפי שמופיע ב-Artifact Registry, למשל us-east1-docker.pkg.dev/my-project/docker-repo/image-one:

filter: image-name in build.images

בדוגמה הבאה, המסנן filter פועל על אירועי בנייה שבהם us-east1-docker.pkg.dev/my-project/docker-repo/image-one או us-east1-docker.pkg.dev/my-project/docker-repo/image-two מצוינים כשמות תמונות:

filter: "us-east1-docker.pkg.dev/my-project/docker-repo/image-one" in build.images || "us-east1-docker.pkg.dev/my-project/docker-repo/image-one" in build.images

סינון לפי שעה

אפשר לסנן אירועים של בנייה לפי זמן היצירה, זמן ההתחלה או זמן הסיום של הבנייה. כדי לעשות זאת, צריך לציין אחת מהאפשרויות הבאות בשדה filter: build.create_time,‏ build.start_time או build.finish_time.

בדוגמה הבאה, השדה filter משתמש ב-timestamp כדי לסנן אירועי בנייה עם זמן בקשה ליצירת הבנייה ב-20 ביולי 2020 בשעה 6:00 בבוקר:

filter: build.create_time == timestamp("2020-07-20:T06:00:00Z")

אפשר גם לסנן אירועי בנייה לפי השוואות בין תקופות. בדוגמה הבאה, השדה filter משתמש ב-timestamp כדי לסנן אירועי בנייה עם שעת התחלה בין 20 ביולי 2020 בשעה 6:00 לבין 30 ביולי 2020 בשעה 6:00.

filter: timestamp("2020-07-20:T06:00:00Z") >= build.start_time && build.start_time <= timestamp("2020-07-30:T06:00:00Z")

מידע נוסף על האופן שבו אזורי זמן מבוטאים ב-CEL זמין בהגדרת השפה של אזורי זמן.

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

filter: build.finish_time - build.start_time >= duration("5m")

סינון לפי החלפה

כדי לסנן לפי החלפה, מציינים את משתנה ההחלפה בשדה filter באמצעות build.substitutions. בדוגמה הבאה, השדה filter מפרט את הגרסאות שמכילות את משתנה ההחלפה substitution-variable, ובודק אם substitution-variable תואם ל-substitution-value שצוין:

filter: build.substitutions[substitution-variable] == substitution-value

כאשר:

‫substitution-variable הוא השם של משתנה ההחלפה.
‫substitution-value הוא השם של ערך ההחלפה.

אפשר גם לסנן לפי ערכי ברירת מחדל של משתני החלפה. בדוגמה הבאה, השדה filter מציג גרסאות build עם שם הענף master וגרסאות build עם שם המאגר github.com/user/my-example-repo. משתני ההחלפה שמוגדרים כברירת מחדל, BRANCH_NAME ו-REPO_NAME, מועברים כמפתחות אל build.substitutions:

filter: build.substitutions["BRANCH_NAME"] == "master" && build.substitutions["REPO_NAME"] == "github.com/user/my-example-repo"

אם רוצים לסנן מחרוזות באמצעות ביטויים רגולריים, אפשר להשתמש בפונקציה המובנית matches. בדוגמה שלמטה, השדה filter מסנן גרסאות build עם סטטוס FAILURE או TIMEOUT, וגם גרסאות build עם משתנה החלפה TAG_NAME עם ערך שתואם לביטוי הרגולרי v{DIGIT}.{DIGIT}.{3 DIGITS}).

filter: build.status in [Build.Status.FAILURE, Build.Status.TIMEOUT] && build.substitutions["TAG_NAME"].matches("^v\\d{1}\\.\\d{1}\\.\\d{3}$")

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

הגדרת התראות ב-BigQuery קל לארגן דפים בעזרת אוספים אפשר לשמור ולסווג תוכן על סמך ההעדפות שלך.

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

הגדרת התראות ב-BigQuery

הצגת נתוני בנייה

גישה לנתוני בנייה

CLI

המסוף

שימוש בשאילתות כדי לגשת לנתוני בנייה

שימוש ב-CEL לסינון אירועים של בנייה

סינון לפי מזהה טריגר

סינון לפי סטטוס

סינון לפי תג

סינון לפי תמונות

סינון לפי שעה

סינון לפי החלפה

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

הגדרת התראות ב-BigQuery