יצירת מינויים ל-Cloud Storage

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

כדי לאפשר ל-Pub/Sub לכתוב ב-Cloud Storage, צריך להקצות לחשבון השירות את התפקידים הבאים:

• יצירת אובייקטים באחסון (roles/storage.objectCreator)
• קריאה בקטגוריה באחסון מדור קודם (roles/storage.legacyBucketReader)

אפשר לתת לחשבון השירות הרשאות לפרויקט או לקטגוריה של Cloud Storage, באופן הבא:

פרויקט

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

   כניסה לדף Buckets

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

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

4. לוחצים על Add another role ובוחרים את התפקיד Storage Object Creator. חוזרים על השלב הזה לתפקיד Storage Legacy Bucket Reader.

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

קטגוריה של Cloud Storage

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

   כניסה לדף Buckets

2. לוחצים על השם של הקטגוריה ב-Cloud Storage שרוצים להעניק לה הרשאה.

3. בדף Bucket details, לוחצים על הכרטיסייה Permissions.

4. בחלונית Permissions, לוחצים על הכרטיסייה View by principals.

5. לוחצים על הענקת גישה.

6. בשדה New principals, מזינים את מזהה חשבון השירות בפורמט הבא:

   [e-mail].

7. ברשימה Assign roles, בוחרים באפשרות Storage Object Creator.

8. לוחצים על Add another role ובוחרים באפשרות Storage Legacy Bucket Reader.

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

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

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

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

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

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

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

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

מאפייני המינוי ל-Cloud Storage

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

שם הקטגוריה

כדי ליצור מינוי ל-Cloud Storage, צריך קודם ליצור קטגוריה של Cloud Storage.

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

האפשרות מגיש הבקשה משלם צריכה להיות מושבתת בקטגוריה של Cloud Storage.

איך יוצרים קטגוריות ב-Cloud Storage?

קידומת, סיומת ותאריך ושעה של שם הקובץ

קבצי הפלט של Cloud Storage שנוצרו על ידי המינוי ל-Cloud Storage מאוחסנים כאובייקטים בקטגוריה של Cloud Storage. השם של האובייקט שמאוחסן בקטגוריה של Cloud Storage הוא בפורמט הבא: <file-prefix><UTC-date-time>_<uuid><file-suffix>.

הרשימה הבאה כוללת פרטים על פורמט הקובץ ועל השדות שאפשר להתאים אישית:

• ‫<file-prefix> היא קידומת שם הקובץ בהתאמה אישית. השדה הזה אופציונלי.

• ‫<UTC-date-time> היא מחרוזת שנוצרת אוטומטית וניתנת להתאמה אישית על סמך השעה שבה האובייקט נוצר.

• ‫<uuid> היא מחרוזת אקראית שנוצרת אוטומטית לאובייקט.

• ‫<file-suffix> היא סיומת שם הקובץ בהתאמה אישית. זהו שדה אופציונלי. הסיומת של שם הקובץ לא יכולה להסתיים ב-"/".

• אפשר לשנות את הקידומת והסיומת של שם הקובץ:

  • לדוגמה, אם הערך של הקידומת של שם הקובץ הוא prod_ והערך של הסיומת של שם הקובץ הוא _archive, שם אובייקט לדוגמה הוא prod_2023-09-25T04:10:00+00:00_uN1QuE_archive.

  • אם לא מציינים את הקידומת והסיומת של שם הקובץ, שם האובייקט שמאוחסן בקטגוריה של Cloud Storage הוא בפורמט: <UTC-date-time>_<uuid>.

  • הדרישות למתן שמות לאובייקטים ב-Cloud Storage חלות גם על התחילית והסיומת של שם הקובץ. מידע נוסף זמין במאמר הסבר על אובייקטים ב-Cloud Storage.

• אתם יכולים לשנות את האופן שבו התאריך והשעה מוצגים בשם הקובץ:

  • מחפשי התאמה חובה של תאריך ושעה שאפשר להשתמש בהם רק פעם אחת: שנה (YYYY או YY), חודש (MM), יום (DD), שעה (hh), דקה (mm), שנייה (ss). לדוגמה, YY-YYYY או MMM הם מחרוזות לא תקינות.

  • אופציונליים: מפריד של תאריך ושעה (T) והיסט מאזור הזמן (Z או +00:00).

  • רכיבים אופציונליים שאפשר להשתמש בהם כמה פעמים: מקף (-), קו תחתון (_), נקודתיים (:) ולוכסן (/).

  • לדוגמה, אם הערך של פורמט התאריך והשעה של שם הקובץ הוא YYYY-MM-DD/hh_mm_ssZ, שם אובייקט לדוגמה הוא prod_2023-09-25/04_10_00Z_uNiQuE_archive.

  • אם פורמט התאריך והשעה של שם הקובץ מסתיים בתו שאינו תו התאמה, התו הזה יחליף את המפריד בין <UTC-date-time> לבין <uuid>. לדוגמה, אם הערך של פורמט התאריך והשעה של שם הקובץ הוא YYYY-MM-DDThh_mm_ss-, שם אובייקט לדוגמה הוא prod_2023-09-25T04_10_00-uNiQuE_archive.

קיבוץ קבצים

מינויים ל-Cloud Storage מאפשרים לכם להחליט מתי ליצור קובץ פלט חדש שמאוחסן כאובייקט בקטגוריה של Cloud Storage. ‫Pub/Sub כותב קובץ פלט כשמתקיים אחד מתנאי האצווה שצוינו. אלה התנאים ליצירת אצוות ב-Cloud Storage:

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

  • הערך המינימלי הוא דקה אחת
  • ערך ברירת המחדל = 5 דקות
  • הערך המקסימלי הוא 10 דקות

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

  • הערך המינימלי הוא 1KB
  • ערך מקסימלי = 10GiB

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

  • ערך מינימלי = 1000

לדוגמה, אפשר להגדיר את משך הזמן המקסימלי כ-6 דקות ואת גודל הקובץ המקסימלי כ-2GB. אם בדקה הרביעית, גודל קובץ הפלט מגיע ל-2GB, מערכת Pub/Sub מסיימת את הקובץ הקודם ומתחילה לכתוב לקובץ חדש.

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

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

פורמט קובץ

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

• טקסט: ההודעות מאוחסנות כטקסט פשוט. תו מפריד שורה מפריד בין הודעה להודעה הקודמת בקובץ. רק המטען הייעודי (payload) של ההודעות נשמר, לא מאפיינים או מטא-נתונים אחרים.

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

  • כתיבת מטא-נתונים: האפשרות הזו מאפשרת לכם לאחסן את המטא-נתונים של ההודעה יחד עם ההודעה. מטא-נתונים כמו השדות subscription_name, message_id, publish_time ו-attributes נכתבים לשדות ברמה העליונה באובייקט Avro של הפלט, בעוד שכל מאפייני ההודעה האחרים מלבד הנתונים (לדוגמה, ordering_key, אם קיים) מתווספים כרשומות במפה attributes.

    אם האפשרות write metadata (כתיבת מטא-נתונים) מושבתת, רק מטען הייעוד של ההודעה נכתב באובייקט הפלט של Avro. זו סכימת Avro להודעות הפלט עם write metadata (כתיבת מטא-נתונים) מושבת:

    {
      "type": "record",
      "namespace": "com.google.pubsub",
      "name": "PubsubMessage",
      "fields": [
        { "name": "data", "type": "bytes" }
      ]
    }
    

    זו סכמת Avro להודעות הפלט עם האפשרות write metadata (כתיבת מטא-נתונים) מופעלת:

    {
      "type": "record",
      "namespace": "com.google.pubsub",
      "name": "PubsubMessageWithMetadata",
      "fields": [
        { "name": "subscription_name", "type": "string" },
        { "name": "message_id", "type": "string"  },
        { "name": "publish_time", "type": {
            "type": "long",
            "logicalType": "timestamp-micros"
          }
        },
        { "name": "attributes", "type": { "type": "map", "values": "string" } },
        { "name": "data", "type": "bytes" }
      ]
    }
    

  • שימוש בסכימת הנושא: האפשרות הזו מאפשרת ל-Pub/Sub להשתמש בסכימה של נושא ה-Pub/Sub שאליו מצורף המינוי כשכותבים קובצי Avro.

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

    • סכימת הנושא צריכה להיות בפורמט Apache Avro.

    • אם האפשרויות use topic schema ו-write metadata מופעלות, סכימת הנושא חייבת לכלול אובייקט Record ברמה הבסיסית (root). שירות Pub/Sub ירחיב את רשימת השדות של הרשומה כדי לכלול את שדות המטא-נתונים. לכן, הרשומה לא יכולה להכיל שדות עם אותו שם כמו שדות המטא-נתונים (subscription_name,‏ message_id,‏ publish_time או attributes).

הערה: אם אתם רוצים לכתוב קבצים בפורמט Parquet, הדרך הכי טובה להזרים נתונים מ-Pub/Sub לקבצי Parquet היא באמצעות מינוי ל-BigQuery עם טבלאות ב-BigQuery ל-Apache Iceberg. למידע נוסף, קראו את המאמר מינויים ל-BigQuery עם טבלאות Iceberg.

חשבון שירות

יש לכם את האפשרויות הבאות לכתיבת הודעות לקטגוריה של Cloud Storage:

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

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

יצירת מינוי ל-Cloud Storage

המסוף

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

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

2. לוחצים על יצירת מינוי.

3. בשדה Subscription ID, מזינים שם.

   במאמר הנחיות למתן שמות לנושאים או למינויים מוסבר איך נותנים שם למינוי.

4. בוחרים נושא מהתפריט הנפתח או יוצרים נושא חדש.

   המינוי מקבל הודעות מהנושא.

   במאמר יצירה וניהול של נושאים מוסבר איך יוצרים נושא.

5. בוחרים באפשרות Write to Cloud Storage בתור Delivery type.

6. בקטע קטגוריה של Cloud Storage, לוחצים על Browse.

   • אפשר לבחור מאגר קיים מכל פרויקט מתאים.

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

     אחרי שיוצרים את הקטגוריה, בוחרים את הקטגוריה למינוי Cloud Storage.

     מידע נוסף על יצירת קטגוריה זמין במאמר יצירת קטגוריות.

   כשמציינים את הקטגוריה, Pub/Sub בודק את ההרשאות המתאימות בקטגוריה לסוכן השירות של Pub/Sub. אם יש בעיות בהרשאות, תופיע הודעה דומה להודעה הבאה: Unable to verify if the Pub/Sub service agent has write permissions on this bucket. You may be lacking permissions to view or set permissions.

7. אם יש בעיות בהרשאות, לוחצים על הגדרת הרשאה ופועלים לפי ההוראות במסך.

   אפשר גם לפעול לפי ההוראות שבמאמר הקצאת תפקידים ב-Cloud Storage לסוכן השירות של Pub/Sub.

8. בקטע פורמט קובץ, בוחרים באפשרות טקסט או Avro.

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

   למידע נוסף על שתי האפשרויות, כולל האפשרות של מטא-נתונים של הודעות בפורמט Avro, ראו פורמט קובץ.

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

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

10. בשדה File batching, מציינים את משך הזמן המקסימלי שיחלוף לפני שייווצר קובץ חדש.

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

    מידע נוסף על שתי האפשרויות של אצווה קבצים זמין במאמר בנושא אצווה קבצים.

11. מומלץ מאוד להפעיל את האפשרות Dead lettering כדי לטפל בהודעות שנכשלו.

    מידע נוסף זמין במאמר בנושא נושא של הודעות שלא ניתן להעביר.

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

gcloud

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

   הפעלת Cloud Shell

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

2. כדי ליצור מינוי ל-Cloud Storage, מריצים את הפקודה gcloud pubsub subscriptions create.

   gcloud pubsub subscriptions create SUBSCRIPTION_ID \
       --topic=TOPIC_ID \
       --cloud-storage-bucket=BUCKET_NAME \
       --cloud-storage-file-prefix=CLOUD_STORAGE_FILE_PREFIX \
       --cloud-storage-file-suffix=CLOUD_STORAGE_FILE_SUFFIX \
       --cloud-storage-file-datetime-format=CLOUD_STORAGE_FILE_DATETIME_FORMAT \
       --cloud-storage-max-duration=CLOUD_STORAGE_MAX_DURATION \
       --cloud-storage-max-bytes=CLOUD_STORAGE_MAX_BYTES \
       --cloud-storage-max-messages=CLOUD_STORAGE_MAX_MESSAGES \
       --cloud-storage-output-format=CLOUD_STORAGE_OUTPUT_FORMAT \
       --cloud-storage-write-metadata
       --cloud-storage-use-topic-schema

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

   gcloud pubsub subscriptions create SUBSCRIPTION_ID \
       --topic=TOPIC_ID \
       --cloud-storage-bucket=BUCKET_NAME \
       --cloud-storage-file-prefix=CLOUD_STORAGE_FILE_PREFIX \
       --cloud-storage-file-suffix=CLOUD_STORAGE_FILE_SUFFIX \
       --cloud-storage-file-datetime-format=CLOUD_STORAGE_FILE_DATETIME_FORMAT \
       --cloud-storage-max-duration=CLOUD_STORAGE_MAX_DURATION \
       --cloud-storage-max-bytes=CLOUD_STORAGE_MAX_BYTES \
       --cloud-storage-max-messages=CLOUD_STORAGE_MAX_MESSAGES \
       --cloud-storage-output-format=CLOUD_STORAGE_OUTPUT_FORMAT \
       --cloud-storage-write-metadata
       --cloud-storage-use-topic-schema
       --cloud-storage-service-account-email=SERVICE_ACCOUNT_NAME
       

   בפקודה, נדרשים רק SUBSCRIPTION_ID, הדגל --topic והדגל --cloud-storage-bucket. הדגלים הנותרים הם אופציונליים ואפשר להשמיט אותם.

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

   • ‫SUBSCRIPTION_ID: השם או המזהה של המינוי החדש ל-Cloud Storage.
   • ‫TOPIC_ID: השם או המזהה של הנושא.
   • ‫BUCKET_NAME: מציין את השם של קטגוריה קיימת. לדוגמה, prod_bucket. שם הקטגוריה לא יכול לכלול את מזהה הפרויקט. במאמר יצירת קטגוריות מוסבר איך ליצור קטגוריה.
   • ‫CLOUD_STORAGE_FILE_PREFIX: מציין את הקידומת של שם הקובץ ב-Cloud Storage. לדוגמה, log_events_.
   • ‫CLOUD_STORAGE_FILE_SUFFIX: הסיומת של שם הקובץ ב-Cloud Storage. לדוגמה, .txt.
   • ‫CLOUD_STORAGE_FILE_DATETIME_FORMAT: מציין את פורמט התאריך והשעה של שם הקובץ ב-Cloud Storage. לדוגמה, YYYY-MM-DD/hh_mm_ssZ.
   • ‫CLOUD_STORAGE_MAX_DURATION: משך הזמן המקסימלי שיכול לעבור לפני שנוצר קובץ חדש ב-Cloud Storage. הערך צריך להיות בין 1 ל-10 דקות. לדוגמה, 5m.
   • ‫CLOUD_STORAGE_MAX_BYTES: מספר הבייטים המקסימלי שאפשר לכתוב לקובץ Cloud Storage לפני שנוצר קובץ חדש. הערך צריך להיות בין 1KB ל-10GB. לדוגמה, 20MB.
   • ‫CLOUD_STORAGE_MAX_MESSAGES: המספר המקסימלי של הודעות שאפשר לכתוב לקובץ Cloud Storage לפני שנוצר קובץ חדש. הערך חייב להיות שווה ל-1,000 או גדול ממנו. לדוגמה, 100000.
   • ‫CLOUD_STORAGE_OUTPUT_FORMAT: פורמט הפלט של הנתונים שנכתבים ב-Cloud Storage. הערכים הם:
     • ‫text: ההודעות נכתבות כטקסט גולמי, מופרדות בשורה חדשה.
     • ‫avro: ההודעות נכתבות כקובץ בינארי של Avro. הפרמטרים --cloud-storage-write-metadata ו---cloud-storage-use-topic-schema משפיעים רק על מינויים עם פורמט פלט avro.
   • ‫SERVICE_ACCOUNT_NAME: השם של חשבון השירות שמשמש לכתיבה ב-Cloud Storage.

C++

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

כדי לבצע אימות ב-Pub/Sub, צריך להגדיר את Application Default Credentials. מידע נוסף זמין במאמר הגדרת אימות לספריות לקוח.

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& bucket) {
  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_cloud_storage_config()->set_bucket(bucket);
  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 באמצעות ספריות לקוח. מידע נוסף מופיע במאמרי העזרה של Pub/Sub C# API.

כדי לבצע אימות ב-Pub/Sub, צריך להגדיר את Application Default Credentials. מידע נוסף זמין במאמר הגדרת אימות לספריות לקוח.

using Google.Cloud.PubSub.V1;
using Google.Protobuf.WellKnownTypes;
using System;

public class CreateCloudStorageSubscriptionSample
{
    public Subscription CreateCloudStorageSubscription(string projectId, string topicId, string subscriptionId,
        string bucket, string filenamePrefix, string filenameSuffix, TimeSpan maxDuration)
    {
        SubscriberServiceApiClient subscriber = SubscriberServiceApiClient.Create();
        TopicName topicName = TopicName.FromProjectTopic(projectId, topicId);
        SubscriptionName subscriptionName = SubscriptionName.FromProjectSubscription(projectId, subscriptionId);

        var subscriptionRequest = new Subscription
        {
            SubscriptionName = subscriptionName,
            TopicAsTopicName = topicName,
            CloudStorageConfig = new CloudStorageConfig
            {
                Bucket = bucket,
                FilenamePrefix = filenamePrefix,
                FilenameSuffix = filenameSuffix,
                MaxDuration = Duration.FromTimeSpan(maxDuration)
            }
        };
        var subscription = subscriber.CreateSubscription(subscriptionRequest);
        return subscription;
    }
}

Go

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

כדי לבצע אימות ב-Pub/Sub, צריך להגדיר את Application Default Credentials. מידע נוסף זמין במאמר הגדרת אימות לספריות לקוח.

import (
	"context"
	"fmt"
	"io"
	"time"

	"cloud.google.com/go/pubsub/v2"
	"cloud.google.com/go/pubsub/v2/apiv1/pubsubpb"
	"google.golang.org/protobuf/types/known/durationpb"
)

// createCloudStorageSubscription creates a Pub/Sub subscription that exports messages to Cloud Storage.
func createCloudStorageSubscription(w io.Writer, projectID, topic, subscription, bucket string) error {
	// projectID := "my-project-id"
	// topic := "projects/my-project-id/topics/my-topic"
	// subscription := "projects/my-project/subscriptions/my-sub"
	// bucket := "my-bucket" // bucket must not have the gs:// prefix
	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,
		CloudStorageConfig: &pubsubpb.CloudStorageConfig{
			Bucket:         bucket,
			FilenamePrefix: "log_events_",
			FilenameSuffix: ".avro",
			OutputFormat: &pubsubpb.CloudStorageConfig_AvroConfig_{
				AvroConfig: &pubsubpb.CloudStorageConfig_AvroConfig{
					WriteMetadata: true,
				},
			},
			MaxDuration: durationpb.New(1 * time.Minute),
			MaxBytes:    1e8,
		},
	})
	if err != nil {
		return fmt.Errorf("failed to create cloud storage sub: %w", err)
	}
	fmt.Fprintf(w, "Created Cloud Storage subscription: %v\n", sub)

	return nil
}

Java

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

כדי לבצע אימות ב-Pub/Sub, צריך להגדיר את Application Default Credentials. מידע נוסף זמין במאמר הגדרת אימות לספריות לקוח.

import com.google.cloud.pubsub.v1.SubscriptionAdminClient;
import com.google.protobuf.Duration;
import com.google.pubsub.v1.CloudStorageConfig;
import com.google.pubsub.v1.ProjectSubscriptionName;
import com.google.pubsub.v1.ProjectTopicName;
import com.google.pubsub.v1.Subscription;
import java.io.IOException;

public class CreateCloudStorageSubscriptionExample {
  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 bucket = "your-bucket";
    String filenamePrefix = "log_events_";
    String filenameSuffix = ".text";
    Duration maxDuration = Duration.newBuilder().setSeconds(300).build();

    createCloudStorageSubscription(
        projectId, topicId, subscriptionId, bucket, filenamePrefix, filenameSuffix, maxDuration);
  }

  public static void createCloudStorageSubscription(
      String projectId,
      String topicId,
      String subscriptionId,
      String bucket,
      String filenamePrefix,
      String filenameSuffix,
      Duration maxDuration)
      throws IOException {
    try (SubscriptionAdminClient subscriptionAdminClient = SubscriptionAdminClient.create()) {

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

      CloudStorageConfig cloudStorageConfig =
          CloudStorageConfig.newBuilder()
              .setBucket(bucket)
              .setFilenamePrefix(filenamePrefix)
              .setFilenameSuffix(filenameSuffix)
              .setMaxDuration(maxDuration)
              .build();

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

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

Node.js

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

כדי לבצע אימות ב-Pub/Sub, צריך להגדיר את Application Default Credentials. מידע נוסף זמין במאמר הגדרת אימות לספריות לקוח.

/**
 * TODO(developer): Uncomment these variables before running the sample.
 */
// const topicName = 'YOUR_TOPIC_NAME';
// const subscriptionName = 'YOUR_SUBSCRIPTION_NAME';
// const bucket = 'YOUR_BUCKET_ID';
// const filenamePrefix = 'YOUR_FILENAME_PREFIX';
// const filenameSuffix = 'YOUR_FILENAME_SUFFIX';
// const maxDuration = 60;

// 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 createCloudStorageSubscription(
  topicName,
  subscriptionName,
  bucket,
  filenamePrefix,
  filenameSuffix,
  maxDuration,
) {
  const options = {
    cloudStorageConfig: {
      bucket,
      filenamePrefix,
      filenameSuffix,
      maxDuration: {
        seconds: maxDuration,
      },
    },
  };

  await pubSubClient
    .topic(topicName)
    .createSubscription(subscriptionName, options);

  console.log(
    `Created subscription ${subscriptionName} with a cloud storage configuration.`,
  );
}

Node.js

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

כדי לבצע אימות ב-Pub/Sub, צריך להגדיר את Application Default Credentials. מידע נוסף זמין במאמר הגדרת אימות לספריות לקוח.

/**
 * TODO(developer): Uncomment these variables before running the sample.
 */
// const topicName = 'YOUR_TOPIC_NAME';
// const subscriptionName = 'YOUR_SUBSCRIPTION_NAME';
// const bucket = 'YOUR_BUCKET_ID';
// const filenamePrefix = 'YOUR_FILENAME_PREFIX';
// const filenameSuffix = 'YOUR_FILENAME_SUFFIX';
// const maxDuration = 60;

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

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

async function createCloudStorageSubscription(
  topicName: string,
  subscriptionName: string,
  bucket: string,
  filenamePrefix: string,
  filenameSuffix: string,
  maxDuration: number,
) {
  const options: CreateSubscriptionOptions = {
    cloudStorageConfig: {
      bucket,
      filenamePrefix,
      filenameSuffix,
      maxDuration: {
        seconds: maxDuration,
      },
    },
  };

  await pubSubClient
    .topic(topicName)
    .createSubscription(subscriptionName, options);

  console.log(
    `Created subscription ${subscriptionName} with a cloud storage configuration.`,
  );
}

PHP

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

כדי לבצע אימות ב-Pub/Sub, צריך להגדיר את Application Default Credentials. מידע נוסף זמין במאמר הגדרת אימות לספריות לקוח.

use Google\Cloud\PubSub\PubSubClient;

/**
 * Creates a Pub/Sub GCS 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 $bucket The Cloud Storage bucket name without any prefix like "gs://".
 */
function create_cloud_storage_subscription($projectId, $topicName, $subscriptionName, $bucket)
{
    $pubsub = new PubSubClient([
        'projectId' => $projectId,
    ]);
    $topic = $pubsub->topic($topicName);
    $subscription = $topic->subscription($subscriptionName);
    $config = ['bucket' => $bucket];
    $subscription->create([
        'cloudStorageConfig' => $config
    ]);

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

Python

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

כדי לבצע אימות ב-Pub/Sub, צריך להגדיר את Application Default Credentials. מידע נוסף זמין במאמר הגדרת אימות לספריות לקוח.

from google.cloud import pubsub_v1
from google.protobuf import duration_pb2

# TODO(developer)
# project_id = "your-project-id"
# topic_id = "your-topic-id"
# subscription_id = "your-subscription-id"
# bucket = "my-bucket"

filename_prefix = "log_events_"
filename_suffix = ".avro"
# Either CloudStorageConfig.AvroConfig or CloudStorageConfig.TextConfig
# defaults to TextConfig
avro_config = pubsub_v1.types.CloudStorageConfig.AvroConfig(write_metadata=True)

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)
max_duration = duration_pb2.Duration()
max_duration.FromSeconds(300)

cloudstorage_config = pubsub_v1.types.CloudStorageConfig(
    bucket=bucket,
    filename_prefix=filename_prefix,
    filename_suffix=filename_suffix,
    avro_config=avro_config,
    # Min 1 minutes, max 10 minutes
    max_duration=max_duration,
    # Min 1 KB, max 10 GiB
    max_bytes=10000000,
)

# 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,
            "cloud_storage_config": cloudstorage_config,
        }
    )

print(f"CloudStorage subscription created: {subscription}.")
print(f"Bucket for subscription is: {bucket}")
print(f"Prefix is: {filename_prefix}")
print(f"Suffix is: {filename_suffix}")

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

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

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

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

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

• פתרון בעיות במינוי ל-Cloud Storage.

• מידע על Cloud Storage

• כדאי לעיין בתמחור של Pub/Sub, כולל מינוי ל-Cloud Storage.