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

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

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

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

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

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

כדי לקבל את ההרשאות שנדרשות ליצירת מינוי לנפח אחסון ב-Cloud Storage, צריך לבקש מהאדמין להקצות לכם את תפקיד ה-IAM‏ Pub/Sub Editor (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, צריך את ההרשאות הבאות:

• לחשבון השירות בניהול המשתמש צריכים להיות התפקידים Storage Object Creator ו-Storage Legacy Bucket Reader.

• לחשבון השירות של 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:

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

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

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

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

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

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

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

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

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

יצירת מינוי לנפח אחסון

המסוף

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

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

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

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

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

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

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

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

5. בוחרים באפשרות סוג המשלוח בתור כתיבה אל Cloud Storage.

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. מומלץ מאוד להפעיל העברה לתיבת דואר להודעות שלא נמסרו כדי לטפל בכשלים במסירת הודעות.

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

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

gcloud

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

   הפעלת 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. הערך צריך להיות בין דקה אחת ל-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 Monitoring יש מספר מדדים למעקב אחרי מינויים.

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

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

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

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

• מידע על Cloud Storage

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