יצירת מינויים ב-BigQuery

במאמר הזה מוסבר איך ליצור מינוי ל-BigQuery. כדי ליצור מינוי ל-BigQuery, אתם יכולים להשתמש במסוף Google Cloud , ב-Google Cloud CLI, בספריית הלקוח או ב-Pub/Sub API.

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

לפני שאתם קוראים את המאמר הזה, חשוב שתכירו את המושגים הבאים:

• איך פועלים המינויים.

• תהליך העבודה של מינויים ל-BigQuery.

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

בנוסף להיכרות עם Pub/Sub ו-BigQuery, ודאו שאתם עומדים בדרישות המוקדמות הבאות לפני שאתם יוצרים מינוי ל-BigQuery:

• יש טבלה ב-BigQuery. לחלופין, אפשר ליצור מערך נתונים כשיוצרים את המינוי ל-BigQuery, כמו שמתואר בהמשך המאמר.

• תאימות בין הסכימה של נושא Pub/Sub לבין הטבלה ב-BigQuery. אם תוסיפו טבלה לא תואמת ב-BigQuery, תופיע הודעת שגיאה שקשורה לתאימות. מידע נוסף זמין במאמר תאימות סכימה.

תפקידים והרשאות נדרשים

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

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

ההרשאות הנדרשות

כדי ליצור מינוי ל-BigQuery, צריך את ההרשאות הבאות:

• ‫pubsub.subscriptions.create בפרויקט
• ‫pubsub.topics.attachSubscription בנושא

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

מינויים בין פרויקטים

אם אתם יוצרים מינוי בפרויקט אחד לנושא בפרויקט אחר, צריכה להיות לכם הרשאת pubsub.subscriptions.create בפרויקט שבו אתם יוצרים את המינוי, והרשאת pubsub.topics.attachSubscription בנושא.

הקצאת תפקידי IAM לחשבון השירות

ב-Pub/Sub, הגישה למשאבים ב- Google Cloud מתבצעת באמצעות חשבון שירות של ניהול זהויות והרשאות גישה (IAM). כברירת מחדל, נעשה שימוש בסוכן השירות של Pub/Sub‏ (service-PROJECT_NUMBER@gcp-sa-pubsub.).

כדי לאפשר ל-Pub/Sub לכתוב בטבלה ב-BigQuery, חשבון השירות צריך את התפקיד עריכת נתונים ב-BigQuery (roles/bigquery.dataEditor). אתם יכולים לתת לחשבון השירות הרשאות לפרויקט או לטבלה, באופן הבא:

פרויקט

1. נכנסים לדף IAM במסוף Google Cloud .

   כניסה לדף IAM

2. בוחרים באפשרות Include Google-provided role grants.

3. מוצאים את השורה של חשבון השירות Cloud Pub/Sub ולוחצים על Edit principal.

4. לוחצים על Add another role ובוחרים את התפקיד BigQuery Data Editor.

מידע נוסף זמין במאמר הקצאת תפקיד ב-IAM באמצעות המסוף.

טבלה

1. במסוף Google Cloud , נכנסים ל-BigQuery Studio.

   כניסה ל-BigQuery Studio

2. בתיבת החיפוש Filter by name and labels שבחלונית Explorer, מקלידים את שם הטבלה ולוחצים על Enter.

3. בתוצאות החיפוש, לוחצים על שם הטבלה שרוצים לתת לה הרשאה.

4. בחלונית הפרטים, לוחצים על שיתוף > ניהול הרשאות.

5. לוחצים על Add principal ומזינים את מזהה חשבון השירות בפורמט הבא:

   service-PROJECT_NUMBER@gcp-sa-pubsub..

6. ברשימה Assign roles, בוחרים באפשרות BigQuery Data Editor.

7. לוחצים על Save. חשבון המשתמש מקבל את התפקיד במשאב.

שימוש בחשבון שירות בהתאמה אישית

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

כדי להגדיר חשבון שירות בניהול המשתמש לכתיבה ב-BigQuery, נדרשות ההרשאות הבאות:

• לחשבון השירות שמנוהל על ידי המשתמש צריך להיות התפקיד עריכת נתונים ב-BigQuery.

• לחשבון השירות של Cloud Pub/Sub צריכה להיות ההרשאה iam.serviceAccounts.getAccessToken בחשבון השירות שמנוהל על ידי המשתמש.

• למשתמש שיוצר את המינוי צריכה להיות ההרשאה iam.serviceAccounts.actAs בחשבון השירות שמנוהל על ידי המשתמש.

כשיוצרים את המינוי, מציינים את חשבון השירות שמנוהל על ידי המשתמש בתור חשבון השירות של המינוי.

מאפייני המינוי ב-BigQuery

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

שימוש בסכימת נושאים

האפשרות הזו מאפשרת ל-Pub/Sub להשתמש בסכימה של נושא Pub/Sub שאליו המינוי מצורף. בנוסף, Pub/Sub כותב את השדות בהודעות לעמודות התואמות בטבלה ב-BigQuery.

זהירות: מחיקה של סכימה או גרסה של סכימה היא פעולה בלתי הפיכה. אם הודעות אומתו מול גרסה שנמחקה של סכימה בזמן הפרסום, אי אפשר לכתוב אותן ב-BigQuery באמצעות מינוי ל-BigQuery כשהאפשרות Use topic schema מופעלת. במקום למחוק סכימה או גרסה, אפשר להחזיר סכימה לגרסה קודמת.

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

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

• כל שדה אופציונלי בסכימת הנושא חייב להיות אופציונלי גם בסכימת BigQuery.

• שדות חובה בסכימה של הנושא לא חייבים להיות שדות חובה בסכימה של BigQuery.

• אם יש שדות ב-BigQuery שלא קיימים בסכימת הנושא, השדות האלה ב-BigQuery חייבים להיות במצב NULLABLE.

• אם בסכימת הנושא יש שדות נוספים שלא קיימים בסכימת BigQuery, ואפשר להשמיט את השדות האלה, בוחרים באפשרות Drop unknown fields.

• אפשר לבחור רק אחד ממאפייני המינוי, Use topic schema או Use table schema.

אם לא בוחרים באפשרות Use topic schema או Use table schema, צריך לוודא שבטבלה ב-BigQuery יש עמודה בשם data מסוג BYTES,‏ STRING או JSON. ‫Pub/Sub כותב את ההודעה בעמודה הזו ב-BigQuery.

יכול להיות שהשינויים בסכימה של נושאי Pub/Sub או בסכימה של הטבלה ב-BigQuery לא יופיעו מיד בהודעות שנכתבו בטבלה ב-BigQuery. לדוגמה, אם האפשרות Drop unknown fields מופעלת ושדה מסוים קיים בסכימה של Pub/Sub אבל לא בסכימה של BigQuery, יכול להיות שההודעות שנכתבות בטבלה של BigQuery עדיין לא יכילו את השדה אחרי שתוסיפו אותו לסכימה של BigQuery. בסופו של דבר, הסכימות מסתנכרנות וההודעות הבאות כוללות את השדה.

כשמשתמשים באפשרות Use topic schema במינוי ל-BigQuery, אפשר גם להשתמש בסימון נתונים שהשתנו (CDC) ב-BigQuery. ב-CDC, הטבלאות ב-BigQuery מתעדכנות על ידי עיבוד השינויים והחלתם על השורות הקיימות.

מידע נוסף על התכונה הזו זמין במאמר העברת עדכונים בטבלה באמצעות סימון נתונים שהשתנו (CDC).

במאמר סימון נתונים שהשתנו (CDC) ב-BigQuery מוסבר איך משתמשים בתכונה הזו במינויים ל-BigQuery.

שימוש בסכמת טבלאות

האפשרות הזו מאפשרת ל-Pub/Sub להשתמש בסכימה של הטבלה ב-BigQuery כדי לכתוב את השדות של הודעת JSON בעמודות המתאימות. אם אתם משתמשים באפשרות הזו, חשוב לזכור לבדוק את הדרישות הנוספות הבאות:

• השמות של כל העמודות בטבלה ב-BigQuery יכולים להכיל רק אותיות (a-z,‏ A-Z), מספרים (0-9) או קווים תחתונים (_).

• ההודעות שמתפרסמות חייבות להיות בפורמט JSON.

  אם בעמודה בטבלה ב-BigQuery יש את סוג הנתונים JSON, השדה התואם בהודעת Pub/Sub חייב להיות JSON תקין במחרוזת עם תווי בריחה (escape). לדוגמה, לעמודה בשם myData, שדה ההודעה חייב להיות "myData": "{\"key\":\"value\"}". ‫BigQuery דוחה הודעות שלא מכילות JSON תקין.

• אפשר להמיר את קובצי ה-JSON הבאים:

  סוג JSON	סוג הנתונים ב-BigQuery
  string	‫NUMERIC, BIGNUMERIC, DATE, TIME, DATETIME או TIMESTAMP
  number	‫NUMERIC, BIGNUMERIC, DATE, TIME, DATETIME או TIMESTAMP

  • כשמשתמשים ב-number כדי DATE, DATETIME, TIME או TIMESTAMP המרות, המספר חייב להיות תואם לייצוגים הנתמכים.
  • כשמשתמשים בהמרה של number ל-NUMERIC או ל-BIGNUMERIC, הדיוק וטווח הערכים מוגבלים לאלה שמתקבלים על ידי תקן IEEE 754 לאריתמטיקה של נקודה צפה. אם אתם צריכים דיוק גבוה או טווח רחב יותר של ערכים, השתמשו במקום זאת בהמרות של string ל-NUMERIC או BIGNUMERIC.
  • כשמשתמשים ב-string כדי להמיר ל-NUMERIC או ל-BIGNUMERIC, המערכת של Pub/Sub מניחה שהמחרוזת היא מספר שקריא לאנשים (למשל "123.124"). אם עיבוד המחרוזת כמספר שקריא לאנשים נכשל, המערכת של Pub/Sub מתייחסת למחרוזת כבייטים שמקודדים באמצעות BigDecimalByteStringEncoder.

• אם לנושא של המינוי יש סכימה שמשויכת אליו, צריך להגדיר את מאפיין קידוד ההודעה לערך JSON.

• אם יש שדות ב-BigQuery שלא קיימים בהודעות, השדות האלה צריכים להיות במצב NULLABLE.

• אם להודעות יש שדות נוספים שלא קיימים בסכימה של BigQuery ואפשר להשמיט את השדות האלה, בוחרים באפשרות Drop unknown fields.

• אפשר לבחור רק אחד ממאפייני המינוי, Use topic schema או Use table schema.

אם לא בוחרים באפשרות Use topic schema או Use table schema, צריך לוודא שבטבלה ב-BigQuery יש עמודה בשם data מסוג BYTES,‏ STRING או JSON. ‫Pub/Sub כותב את ההודעה בעמודה הזו ב-BigQuery.

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

כשמשתמשים באפשרות Use table schema במינוי ל-BigQuery, אפשר גם להשתמש ב-CDC (סימון נתונים שהשתנו) ב-BigQuery. ב-CDC, הטבלאות ב-BigQuery מתעדכנות על ידי עיבוד ויישום של שינויים בשורות קיימות.

מידע נוסף על התכונה הזו זמין במאמר העברת עדכונים בטבלה באמצעות סימון נתונים שהשתנו (CDC).

במאמר סימון נתונים שהשתנו (CDC) ב-BigQuery מוסבר איך משתמשים בתכונה הזו במינויים ל-BigQuery.

הסרת שדות לא ידועים

האפשרות הזו משמשת עם האפשרות Use topic schema או Use table schema. כשהאפשרות הזו מופעלת, Pub/Sub יכול להשמיט כל שדה שמופיע בסכימת הנושא או בהודעה, אבל לא מופיע בסכימת BigQuery. השדות שלא נכללים בסכימה של BigQuery נמחקים כשכותבים את ההודעה בטבלה ב-BigQuery.

אם לא מגדירים את Drop unknown fields, הודעות עם שדות נוספים לא נכתבות ב-BigQuery ונשארות בצבר המשימות של המינוי, אלא אם מגדירים נושא להודעות ללא מוצא.

ההגדרה Drop unknown fields לא משפיעה על שדות שלא מוגדרים בסכימה של נושא Pub/Sub או בסכימה של טבלה ב-BigQuery. במקרה כזה, הודעת Pub/Sub תקינה נשלחת למינוי. עם זאת, מכיוון שב-BigQuery לא מוגדרות עמודות לשדות הנוספים האלה, הם מושמטים במהלך תהליך הכתיבה ב-BigQuery. כדי למנוע את ההתנהגות הזו, ודאו שכל שדה שכלול בהודעת Pub/Sub כלול גם בסכימת הטבלה ב-BigQuery.

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

כתיבת מטא-נתונים

האפשרות הזו מאפשרת ל-Pub/Sub לכתוב את המטא-נתונים של כל הודעה בעמודות נוספות בטבלה ב-BigQuery. אחרת, המטא-נתונים לא נכתבים בטבלה ב-BigQuery.

אם בוחרים באפשרות Write metadata, צריך לוודא שהטבלה ב-BigQuery כוללת את השדות שמתוארים בטבלה הבאה.

אם לא בוחרים באפשרות Write metadata, הטבלה ב-BigQuery צריכה רק את השדה data, אלא אם הערך של use_topic_schema הוא true. אם בוחרים גם באפשרות Write metadata וגם באפשרות Use topic schema, הסכימה של הנושא לא יכולה להכיל שדות עם שמות שתואמים לאלה של הפרמטרים של המטא-נתונים. המגבלה הזו כוללת גרסאות של הפרמטרים האלה עם אותיות רישיות בתחילת כל מילה (camelcase) במקום קו תחתון בין המילים (snake case).

פרמטרים
subscription_name	מחרוזת שם המינוי.
message_id	מחרוזת מזהה של הודעה
publish_time	TIMESTAMP השעה שבה ההודעה פורסמה.
data	‫BYTES,‏ STRING או JSON גוף ההודעה. השדה data נדרש לכל טבלאות היעד ב-BigQuery שלא נבחרו בהן האפשרויות Use topic schema או Use table schema. אם השדה הוא מסוג JSON, גוף ההודעה חייב להיות בפורמט JSON תקין.
attributes	מחרוזת או JSON אובייקט JSON שמכיל את כל מאפייני ההודעה. הוא מכיל גם שדות נוספים שהם חלק מההודעה של Pub/Sub, כולל מפתח ההזמנה, אם הוא קיים.

חשבון שירות

יש כמה אפשרויות לכתיבת הודעות בטבלה ב-BigQuery:

• להגדיר חשבון שירות בהתאמה אישית, כך שרק משתמשים עם ההרשאה iam.serviceAccounts.actAs בחשבון השירות יוכלו ליצור מינוי שכותב בטבלה. דוגמה לתפקיד שכולל את ההרשאה iam.serviceAccounts.actAs הוא התפקיד משתמש בחשבון שירות (roles/iam.serviceAccountUser).

• משתמשים בסוכן השירות של Pub/Sub שמוגדר כברירת מחדל, שמאפשר לכל משתמש שיכול ליצור מינויים בפרויקט ליצור מינוי שכותב לטבלה. סוכן השירות של Pub/Sub הוא הגדרת ברירת המחדל כשלא מציינים חשבון שירות בהתאמה אישית.

יצירת מינוי ל-BigQuery

כדי ליצור מינוי עם מסירה ל-BigQuery:

המסוף

1. נכנסים לדף Create subscription במסוף Google Cloud .

   אל הדף "מינויים"

2. בשדה Subscription ID, מזינים שם. במאמר הנחיות למתן שם לנושא או למינוי מוסבר איך נותנים שם למינוי.

3. בתיבה Select a Cloud Pub/Sub topic, מקלידים או בוחרים את הנושא שממנו רוצים לקבל הודעות.

4. בקטע Delivery type, בוחרים באפשרות Write to BigQuery.

5. בוחרים את הטבלה ב-BigQuery:

   1. בשדה Project, בוחרים את הפרויקט ב- Google Cloud שמכיל את הטבלה ב-BigQuery.

   2. בשדה Dataset, בוחרים מערך נתונים קיים או לוחצים על Create new dataset כדי ליצור מערך נתונים חדש. במאמר יצירת מערכי נתונים מוסבר איך יוצרים מערך נתונים.

   3. בשדה Table, מזינים את שם הטבלה. כדי ליצור טבלה חדשה, לוחצים על הקישור שמעביר לדף Create new table ב-BigQuery. הדף נפתח בכרטיסייה נפרדת. איך יוצרים טבלאות ומשתמשים בהן

6. בקטע Schema Configuration, בוחרים אחת מהאפשרויות הבאות:

   • אל תשתמשו בסכימה. ‫Pub/Sub כותב את הבייטים של ההודעה בעמודה בשם data.

   • שימוש בסכימת נושא. ‫Pub/Sub משתמש בסכימה שמשויכת לנושא. מידע נוסף זמין במאמר שימוש בסכימת נושא.

   • שימוש בסכימת טבלה. ב-Pub/Sub נעשה שימוש בסכימה של הטבלה ב-BigQuery. מידע נוסף זמין במאמר שימוש בסכימת טבלה.

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

8. זה שינוי אופציונלי. כדי להשמיט שדות שלא קיימים בסכימה של הטבלה ב-BigQuery, בוחרים באפשרות Drop unknown fields. מידע נוסף מופיע במאמר השמטת שדות לא ידועים.

9. מגדירים את המאפיינים הנפוצים של המינוי לפי הצורך. מומלץ מאוד להפעיל את האפשרות Dead lettering כדי לטפל בהודעות שנכשלו. למידע נוסף, ראו נושא להודעות ללא מוצא.

10. לוחצים על יצירה.

gcloud

1. מפעילים את Cloud Shell במסוף Google Cloud .

   הפעלת Cloud Shell

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

2. כדי ליצור מינוי ל-Pub/Sub, משתמשים בפקודה gcloud pubsub subscriptions create:

   gcloud pubsub subscriptions create SUBSCRIPTION_ID \
       --topic=TOPIC_ID \
       --bigquery-table=PROJECT_ID.DATASET_ID.TABLE_ID
   

   אם רוצים להשתמש בחשבון שירות בהתאמה אישית, צריך לספק אותו כארגומנט נוסף:

   gcloud pubsub subscriptions create SUBSCRIPTION_ID \
       --topic=TOPIC_ID \
       --bigquery-table=PROJECT_ID.DATASET_ID.TABLE_ID \
       --bigquery-service-account-email=SERVICE_ACCOUNT_NAME
   

   מחליפים את מה שכתוב בשדות הבאים:

   • ‫SUBSCRIPTION_ID: מזהה המינוי.
   • ‫TOPIC_ID: מציין את מזהה הנושא. הנושא דורש סכימה.
   • ‫PROJECT_ID: מזהה הפרויקט.
   • ‫DATASET_ID: מזהה של מערך נתונים קיים. כדי ליצור מערך נתונים, קראו את המאמר יצירת מערכי נתונים.
   • ‫TABLE_ID: מציין את המזהה של טבלה קיימת. אם לנושא אין סכימה, הטבלה צריכה לכלול שדה data. כדי ליצור טבלה, קראו את המאמר יצירת טבלה ריקה עם הגדרת סכימה.
   • ‫SERVICE_ACCOUNT_NAME: מציין את השם של חשבון השירות שמשמש לכתיבה ב-BigQuery.

C++‎

לפני שמנסים את הדוגמה הזו, צריך לפעול לפי הוראות ההגדרה של C++‎ במאמר התחלה מהירה: שימוש בספריות לקוח. מידע נוסף זמין במאמרי העזרה של Pub/Sub C++ API.

namespace pubsub = ::google::cloud::pubsub;
namespace pubsub_admin = ::google::cloud::pubsub_admin;
[](pubsub_admin::SubscriptionAdminClient client,
   std::string const& project_id, std::string const& topic_id,
   std::string const& subscription_id, std::string const& table_id) {
  google::pubsub::v1::Subscription request;
  request.set_name(
      pubsub::Subscription(project_id, subscription_id).FullName());
  request.set_topic(pubsub::Topic(project_id, topic_id).FullName());
  request.mutable_bigquery_config()->set_table(table_id);
  auto sub = client.CreateSubscription(request);
  if (!sub) {
    if (sub.status().code() == google::cloud::StatusCode::kAlreadyExists) {
      std::cout << "The subscription already exists\n";
      return;
    }
    throw std::move(sub).status();
  }

  std::cout << "The subscription was successfully created: "
            << sub->DebugString() << "\n";
}

C#‎

לפני שמנסים את הדוגמה הזו, צריך לפעול לפי הוראות ההגדרה של C# ‎ במאמר התחלה מהירה: שימוש בספריות לקוח. מידע נוסף מופיע במאמרי העזרה של Pub/Sub C# API.

using Google.Cloud.PubSub.V1;

public class CreateBigQuerySubscriptionSample
{
    public Subscription CreateBigQuerySubscription(string projectId, string topicId, string subscriptionId, string bigqueryTableId)
    {
        SubscriberServiceApiClient subscriber = SubscriberServiceApiClient.Create();
        TopicName topicName = TopicName.FromProjectTopic(projectId, topicId);
        SubscriptionName subscriptionName = SubscriptionName.FromProjectSubscription(projectId, subscriptionId);

        var subscriptionRequest = new Subscription
        {
            SubscriptionName = subscriptionName,
            TopicAsTopicName = topicName,
            BigqueryConfig = new BigQueryConfig
            {
                Table = bigqueryTableId
            }
        };
        var subscription = subscriber.CreateSubscription(subscriptionRequest);
        return subscription;
    }
}

המשך

בדוגמה הבאה נעשה שימוש בגרסה הראשית של ספריית הלקוח של Pub/Sub ב-Go‏ (v2). אם אתם עדיין משתמשים בספרייה של גרסה 1, כדאי לעיין במדריך להעברת נתונים לגרסה 2. כאן תוכלו למצוא רשימה של דוגמאות קוד שהוצאו משימוש בגרסה 1.

לפני שתנסו את הדוגמה הזו, פעלו לפי הוראות ההגדרה של Go במאמר מדריך למתחילים: שימוש בספריות לקוח. מידע נוסף מופיע במסמכי העזר של ה-API של Pub/Sub Go.

import (
	"context"
	"fmt"
	"io"

	"cloud.google.com/go/pubsub/v2"
	"cloud.google.com/go/pubsub/v2/apiv1/pubsubpb"
)

// createBigQuerySubscription creates a Pub/Sub subscription that exports messages to BigQuery.
func createBigQuerySubscription(w io.Writer, projectID, topic, subscription, table string) error {
	// projectID := "my-project"
	// topic := "projects/my-project-id/topics/my-topic"
	// subscription := "projects/my-project/subscriptions/my-sub"
	// table := "my-project-id.dataset_id.table_id"
	ctx := context.Background()
	client, err := pubsub.NewClient(ctx, projectID)
	if err != nil {
		return fmt.Errorf("pubsub.NewClient: %w", err)
	}
	defer client.Close()

	sub, err := client.SubscriptionAdminClient.CreateSubscription(ctx, &pubsubpb.Subscription{
		Name:  subscription,
		Topic: topic,
		BigqueryConfig: &pubsubpb.BigQueryConfig{
			Table:         table,
			WriteMetadata: true,
		},
	})
	if err != nil {
		return fmt.Errorf("failed to create subscription: %w", err)
	}
	fmt.Fprintf(w, "Created BigQuery subscription: %v\n", sub)

	return nil
}

Java

לפני שמנסים את הדוגמה הזו, צריך לפעול לפי הוראות ההגדרה של Java במאמר התחלה מהירה: שימוש בספריות לקוח. מידע נוסף מופיע במאמרי העזרה של Pub/Sub Java API.

import com.google.cloud.pubsub.v1.SubscriptionAdminClient;
import com.google.pubsub.v1.BigQueryConfig;
import com.google.pubsub.v1.ProjectSubscriptionName;
import com.google.pubsub.v1.ProjectTopicName;
import com.google.pubsub.v1.Subscription;
import java.io.IOException;

public class CreateBigQuerySubscriptionExample {
  public static void main(String... args) throws Exception {
    // TODO(developer): Replace these variables before running the sample.
    String projectId = "your-project-id";
    String topicId = "your-topic-id";
    String subscriptionId = "your-subscription-id";
    String bigqueryTableId = "your-project.your-dataset.your-table";

    createBigQuerySubscription(projectId, topicId, subscriptionId, bigqueryTableId);
  }

  public static void createBigQuerySubscription(
      String projectId, String topicId, String subscriptionId, String bigqueryTableId)
      throws IOException {
    try (SubscriptionAdminClient subscriptionAdminClient = SubscriptionAdminClient.create()) {

      ProjectTopicName topicName = ProjectTopicName.of(projectId, topicId);
      ProjectSubscriptionName subscriptionName =
          ProjectSubscriptionName.of(projectId, subscriptionId);

      BigQueryConfig bigqueryConfig =
          BigQueryConfig.newBuilder().setTable(bigqueryTableId).setWriteMetadata(true).build();

      Subscription subscription =
          subscriptionAdminClient.createSubscription(
              Subscription.newBuilder()
                  .setName(subscriptionName.toString())
                  .setTopic(topicName.toString())
                  .setBigqueryConfig(bigqueryConfig)
                  .build());

      System.out.println("Created a BigQuery subscription: " + subscription.getAllFields());
    }
  }
}

Node.js

לפני שמנסים את הדוגמה הזו, צריך לפעול לפי הוראות ההגדרה של Node.js במאמר מדריך למתחילים: שימוש בספריות לקוח. מידע נוסף מופיע במאמרי העזרה של Pub/Sub Node.js API.

/**
 * TODO(developer): Uncomment these variables before running the sample.
 */
// const topicNameOrId = 'YOUR_TOPIC_NAME_OR_ID';
// const subscriptionNameOrId = 'YOUR_SUBSCRIPTION_NAME_OR_ID';
// const bigqueryTableId = 'YOUR_TABLE_ID';

// Imports the Google Cloud client library
const {PubSub} = require('@google-cloud/pubsub');

// Creates a client; cache this for further use
const pubSubClient = new PubSub();

async function createBigQuerySubscription(
  topicNameOrId,
  subscriptionNameOrId,
  bigqueryTableId,
) {
  const options = {
    bigqueryConfig: {
      table: bigqueryTableId,
      writeMetadata: true,
    },
  };

  await pubSubClient
    .topic(topicNameOrId)
    .createSubscription(subscriptionNameOrId, options);

  console.log(`Subscription ${subscriptionNameOrId} created.`);
}

Node.ts

לפני שמנסים את הדוגמה הזו, צריך לפעול לפי הוראות ההגדרה של Node.js במאמר מדריך למתחילים: שימוש בספריות לקוח. מידע נוסף מופיע במאמרי העזרה של Pub/Sub Node.js API.

/**
 * TODO(developer): Uncomment these variables before running the sample.
 */
// const topicNameOrId = 'YOUR_TOPIC_NAME_OR_ID';
// const subscriptionNameOrId = 'YOUR_SUBSCRIPTION_NAME_OR_ID';
// const bigqueryTableId = 'YOUR_TABLE_ID';

// Imports the Google Cloud client library
import {PubSub, CreateSubscriptionOptions} from '@google-cloud/pubsub';

// Creates a client; cache this for further use
const pubSubClient = new PubSub();

async function createBigQuerySubscription(
  topicNameOrId: string,
  subscriptionNameOrId: string,
  bigqueryTableId: string,
) {
  const options: CreateSubscriptionOptions = {
    bigqueryConfig: {
      table: bigqueryTableId,
      writeMetadata: true,
    },
  };

  await pubSubClient
    .topic(topicNameOrId)
    .createSubscription(subscriptionNameOrId, options);

  console.log(`Subscription ${subscriptionNameOrId} created.`);
}

PHP

לפני שמנסים את הדוגמה הזו, צריך לפעול לפי הוראות ההגדרה של PHP במאמר מדריך למתחילים: שימוש בספריות לקוח. מידע נוסף מופיע במאמרי העזרה של Pub/Sub PHP API.

use Google\Cloud\PubSub\PubSubClient;
use Google\Cloud\PubSub\V1\BigQueryConfig;

/**
 * Creates a Pub/Sub BigQuery subscription.
 *
 * @param string $projectId  The Google project ID.
 * @param string $topicName  The Pub/Sub topic name.
 * @param string $subscriptionName  The Pub/Sub subscription name.
 * @param string $table      The BigQuery table to which to write.
 */
function create_bigquery_subscription($projectId, $topicName, $subscriptionName, $table)
{
    $pubsub = new PubSubClient([
        'projectId' => $projectId,
    ]);
    $topic = $pubsub->topic($topicName);
    $subscription = $topic->subscription($subscriptionName);
    $config = new BigQueryConfig(['table' => $table]);
    $subscription->create([
        'bigqueryConfig' => $config
    ]);

    printf('Subscription created: %s' . PHP_EOL, $subscription->name());
}

Python

לפני שמנסים את הדוגמה הזו, צריך לפעול לפי הוראות ההגדרה של Python במאמר התחלה מהירה: שימוש בספריות לקוח. מידע נוסף מופיע במאמרי העזרה של ה-API בשפת Python של Pub/Sub.

from google.cloud import pubsub_v1

# TODO(developer)
# project_id = "your-project-id"
# topic_id = "your-topic-id"
# subscription_id = "your-subscription-id"
# bigquery_table_id = "your-project.your-dataset.your-table"

publisher = pubsub_v1.PublisherClient()
subscriber = pubsub_v1.SubscriberClient()
topic_path = publisher.topic_path(project_id, topic_id)
subscription_path = subscriber.subscription_path(project_id, subscription_id)

bigquery_config = pubsub_v1.types.BigQueryConfig(
    table=bigquery_table_id, write_metadata=True
)

# Wrap the subscriber in a 'with' block to automatically call close() to
# close the underlying gRPC channel when done.
with subscriber:
    subscription = subscriber.create_subscription(
        request={
            "name": subscription_path,
            "topic": topic_path,
            "bigquery_config": bigquery_config,
        }
    )

print(f"BigQuery subscription created: {subscription}.")
print(f"Table for subscription is: {bigquery_table_id}")

Ruby

בדוגמה הבאה נעשה שימוש בגרסה 3 של ספריית הלקוח של Pub/Sub ב-Ruby. אם אתם עדיין משתמשים בספרייה v2, עיינו במדריך להעברת נתונים (מיגרציה) ל-v3. לרשימה של דוגמאות קוד ב-Ruby v2, עיינו ב דוגמאות הקוד שהוצאו משימוש.

לפני שתנסו את הדוגמה הזו, פעלו לפי הוראות ההגדרה של Ruby במאמר התחלה מהירה: שימוש בספריות לקוח. מידע נוסף מופיע במאמרי העזרה של Pub/Sub Ruby API.

# project_id = "your-project-id"
# topic_id = "your-topic-id"
# subscription_id = "your-subscription-id"
# bigquery_table_id = "my-project:dataset-id.table-id"

pubsub = Google::Cloud::PubSub.new project_id: project_id
subscription_admin = pubsub.subscription_admin

subscription = subscription_admin.create_subscription \
  name: pubsub.subscription_path(subscription_id),
  topic: pubsub.topic_path(topic_id),
  bigquery_config: {
    table: bigquery_table_id,
    write_metadata: true
  }

puts "BigQuery subscription created: #{subscription_id}."
puts "Table for subscription is: #{bigquery_table_id}"

מעקב אחרי מינוי ל-BigQuery

ב-Cloud Monitoring יש כמה מדדים למעקב אחרי מינויים.

רשימה של כל המדדים שזמינים ל-Pub/Sub והתיאורים שלהם מופיעה במסמכי התיעוד של Monitoring ל-Pub/Sub.

אפשר גם לעקוב אחרי מינויים בתוך Pub/Sub.

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

• ליצור או לשנות מינוי באמצעות פקודות gcloud.
• יוצרים או משנים מינוי באמצעות ממשקי API בארכיטקטורת REST.
• פתרון בעיות במינוי ל-BigQuery.