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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

מינויים חוצי-פרויקטים

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

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

‫Pub/Sub משתמש בחשבון שירות של ניהול זהויות והרשאות גישה (IAM) כדי לגשת למשאבים של Google Cloud . כברירת מחדל, המערכת משתמשת בסוכן השירות של Pub/Sub‏ ([e-mail]).

כדי לאפשר ל-Pub/Sub לכתוב לטבלה ב-BigQuery, לחשבון השירות צריך להיות תפקיד BigQuery Data Editor (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. בתיבת החיפוש בחלונית 'סייר' שנקראת סינון לפי שם ותוויות, מקלידים את שם הטבלה ומקישים על Enter.

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

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

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

   [e-mail].

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

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

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

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

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

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

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

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

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

נכסי מינוי ב-BigQuery

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

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

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

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

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

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

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

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

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

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

• אפשר לבחור רק אחד ממאפייני המינוי: Use topic schema (שימוש בסכימת נושא) או Use table schema (שימוש בסכימת טבלה).

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

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

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

מידע נוסף על התכונה הזו מפורט במאמר עדכונים של טבלאות בסטרימינג באמצעות סימון נתונים שהשתנו (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 שלא מופיעים בהודעות, השדות האלה ב-BigQuery צריכים להיות במצב NULLABLE.

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

• אפשר לבחור רק אחד ממאפייני המינוי: Use topic schema (שימוש בסכימת נושא) או Use table schema (שימוש בסכימת טבלה).

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

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

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

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

מידע על שימוש בתכונה הזו עם מינויים ל-BigQuery זמין במאמר BigQuery change data capture.

הסרת שדות לא מוכרים

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

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

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

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

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

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

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

אם לא בוחרים באפשרות כתיבת מטא-נתונים, בטבלת היעד ב-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 שלא נבחרה בהן האפשרות שימוש בסכמת הנושא או שימוש בסכמת הטבלה. אם השדה הוא מסוג 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. בקטע סוג המסירה, בוחרים באפשרות כתיבה ל-BigQuery.

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

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

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

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

6. בקטע הגדרת סכימה, בוחרים באחת מהאפשרויות הבאות:

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

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

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

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

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

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

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

gcloud

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

   הפעלת 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;
    }
}

המשך

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

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

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

בדוגמה הבאה נעשה שימוש בספריית הלקוח של Pub/Sub ב-Ruby, גרסה 3. אם אתם עדיין משתמשים בספרייה 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 והתיאורים שלהם מופיעה במסמכי התיעוד בנושא מעקב אחרי Pub/Sub.

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

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

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