תבנית של נושא או מינוי Pub/Sub לקובצי טקסט ב-Cloud Storage

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

הדרישות לגבי צינורות עיבוד נתונים

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

פרמטרים של תבניות

פרמטרים נדרשים

• ‫outputDirectory: הנתיב והקידומת של שם הקובץ שאליו ייכתבו קובצי הפלט. הערך הזה חייב להסתיים בלוכסן. לדוגמה, gs://your-bucket/your-path/.

פרמטרים אופציונליים

• ‫inputTopic: נושא Pub/Sub שממנו יתבצע קריאת הקלט. אם הפרמטר הזה מסופק, אל תשתמשו ב-inputSubscription. לדוגמה, projects/<PROJECT_ID>/topics/<TOPIC_NAME>.
• ‫inputSubscription: המינוי ל-Pub/Sub שממנו ייקרא הקלט. אם הפרמטר הזה מסופק, אל תשתמשו ב-inputTopic. לדוגמה, projects/<PROJECT_ID>/subscription/<SUBSCRIPTION_NAME>.
• ‫userTempLocation: הספרייה שהמשתמש סיפק כדי להוציא אליה קבצים זמניים. חייב להסתיים בלוכסן.
• ‫outputFilenamePrefix: הקידומת שתוצב בכל קובץ של חלון. לדוגמה, output-. ברירת המחדל היא: output.
• ‫outputFilenameSuffix: הסיומת שתוצב בכל קובץ עם חלון, בדרך כלל סיומת קובץ כמו .txt או .csv. לדוגמה, .txt. ברירת המחדל היא ריקה.
• ‫outputShardTemplate: תבנית השארד מגדירה את החלק הדינמי של כל קובץ עם חלון זמן. כברירת מחדל, צינור הנתונים משתמש בשבר אחד לפלט למערכת הקבצים בכל חלון. כלומר, כל פלט הנתונים נשמר בקובץ יחיד לכל חלון. ערך ברירת המחדל של outputShardTemplate הוא W-P-SS-of-NN, כאשר W הוא טווח התאריכים של החלון, P הוא פרטי החלונית, S הוא מספר הרסיס ו-N הוא מספר הרסיסים. במקרה של קובץ יחיד, החלק SS-of-NN של outputShardTemplate הוא 00-of-01.
• ‫numShards: המספר המקסימלי של רסיסי פלט שנוצרים בזמן כתיבה. מספר גבוה יותר של רסיסים פירושו תפוקה גבוהה יותר לכתיבה ב-Cloud Storage, אבל עלולות להיות עלויות גבוהות יותר של צבירת נתונים ברסיסים כשמעבדים קבצים של פלט Cloud Storage. ברירת המחדל היא 0.
• ‫windowDuration: משך החלון הוא המרווח שבו הנתונים נכתבים לספריית הפלט. הגדרת משך הזמן על סמך קצב העברת הנתונים של צינור עיבוד הנתונים. לדוגמה, כדי להשיג תפוקה גבוהה יותר, יכול להיות שיהיה צורך להקטין את גודל החלון כדי שהנתונים יתאימו לזיכרון. ברירת המחדל היא 5m (5 דקות), והמינימום הוא 1s (שנייה אחת). הפורמטים המותרים הם: [int]s (לשניות, לדוגמה: 5s), [int]m (לדקות, לדוגמה: 12m), [int]h (לשעות, לדוגמה: 2h). לדוגמה: 5m.
• ‫yearPattern: תבנית לעיצוב השנה. הערך חייב להיות אחד או יותר מהערכים הבאים: y או Y. הרישיות לא משנה את השנה. אפשר להוסיף לתבנית תווים שלא אלפאנומריים או את התו של הספרייה (/). ברירת המחדל היא YYYY.
• ‫monthPattern: תבנית לעיצוב החודש. חייב להכיל תו אחד או יותר מתוך M. אפשר להוסיף לתבנית תווים שהם לא אלפאנומריים או את התו של הספרייה (/). ברירת המחדל היא MM.
• ‫dayPattern: תבנית לעיצוב היום. הערך חייב להיות d (יום בחודש) או D (יום בשנה). הרישיות לא משנה את השנה. אפשר להוסיף לתבנית תווים שלא אלפאנומריים או את התו של הספרייה (/). ברירת המחדל היא dd.
• ‫hourPattern: תבנית לפורמט של השעה. חייב להכיל תו אחד או יותר מתוך התווים H. אפשר להוסיף לתבנית תווים שהם לא אלפאנומריים או את התו של הספרייה (/). ברירת המחדל היא HH.
• ‫minutePattern: תבנית לעיצוב הדקה. חייב להכיל תו אחד או יותר מתוך m. אפשר להוסיף לתבנית תווים שהם לא אלפאנומריים או את התו של הספרייה (/). ברירת המחדל היא mm.

הרצת התבנית

המסוף

1. עוברים לדף Create job from template (יצירת משימה מתבנית) ב-Dataflow.
כניסה לדף Create job from template
2. בשדה שם המשימה, מזינים שם ייחודי למשימה.
3. אופציונלי: בשדה Regional endpoint (נקודת קצה אזורית), בוחרים ערך מהתפריט הנפתח. אזור ברירת המחדל הוא us-central1.

   רשימה של אזורים שבהם אפשר להריץ משימת Dataflow מופיעה במאמר מיקומי Dataflow.

4. בתפריט הנפתח Dataflow template (תבנית Dataflow), בוחרים בתבנית Pub/Sub Topic or Subscription to Text Files on Cloud Storage (נושא או מינוי Pub/Sub לקובצי טקסט ב-Cloud Storage).
5. בשדות הפרמטרים שמופיעים, מזינים את ערכי הפרמטרים.
6. לוחצים על הפעלת העבודה.

gcloud

הערה: כדי להשתמש ב-Google Cloud CLI להפעלת תבניות flex צריך להשתמש בגרסה 284.0.0 או בגרסה מאוחרת יותר של Google Cloud CLI.

במעטפת או בטרמינל, מריצים את התבנית:

gcloud dataflow flex-template run JOB_NAME \
    --project=YOUR_PROJECT_ID \
    --region REGION_NAME \
    --template-file-gcs-location gs://dataflow-templates/VERSION/flex/Cloud_PubSub_to_GCS_Text_Flex \
    --parameters \
inputSubscription=projects/PROJECT_ID/subscriptions/SUBSCRIPTION_NAME,\
outputDirectory=gs://BUCKET_NAME/output/,\
outputFilenamePrefix=output-,\
outputFilenameSuffix=.txt

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

• ‫JOB_NAME: שם ייחודי של המשימה לפי בחירתכם
• ‫REGION_NAME: האזור שבו רוצים לפרוס את עבודת Dataflow, לדוגמה: us-central1
• ‫VERSION: הגרסה של התבנית שרוצים להשתמש בה

  אפשר להשתמש בערכים הבאים:

  • latest כדי להשתמש בגרסה העדכנית של התבנית, שזמינה בתיקיית ההורה ללא תאריך בדלי – gs://dataflow-templates/latest/
  • שם הגרסה, כמו 2023-09-12-00_RC00, כדי להשתמש בגרסה ספציפית של התבנית. אפשר למצוא את הגרסה הזו בתיקיית ההורה המתאימה עם התאריך בדלי – gs://dataflow-templates/
  זהירות: יכול להיות שעדכונים בגרסה העדכנית של התבניות יגרמו לשינויים שישברו את התאימות לאחור. כדי שהשינויים האלה לא ישפיעו על תהליכי העבודה שלכם בסביבת הייצור, בסביבות הייצור צריך להשתמש בתבניות שנשמרות בתיקייה הראשית עם תאריך העדכנית ביותר.
• ‫SUBSCRIPTION_NAME: השם של המינוי שלכם ל-Pub/Sub
• ‫BUCKET_NAME: שם הקטגוריה של Cloud Storage

API

כדי להפעיל את התבנית באמצעות API בארכיטקטורת REST, שולחים בקשת HTTP POST. מידע נוסף על ה-API ועל היקפי ההרשאות שלו זמין במאמר projects.templates.launch.

POST https://dataflow.googleapis.com/v1b3/projects/PROJECT_ID/locations/LOCATION/flexTemplates:launch
{
  "launch_parameter": {
    "jobName": "JOB_NAME",
    "parameters": {
       "inputSubscription": "projects/PROJECT_ID/subscriptions/SUBSCRIPTION_NAME"
       "outputDirectory": "gs://BUCKET_NAME/output/",
       "outputFilenamePrefix": "output-",
       "outputFilenameSuffix": ".txt",
    },
    "containerSpecGcsPath": "gs://dataflow-templates/VERSION/flex/Cloud_PubSub_to_GCS_Text_Flex",
  }
}

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

• ‫PROJECT_ID: מזהה הפרויקט שבו רוצים להריץ את משימת Google Cloud Dataflow
• ‫JOB_NAME: שם ייחודי של המשימה לפי בחירתכם
• ‫LOCATION: האזור שבו רוצים לפרוס את עבודת Dataflow, לדוגמה: us-central1
• ‫VERSION: הגרסה של התבנית שרוצים להשתמש בה

  אפשר להשתמש בערכים הבאים:

  • latest כדי להשתמש בגרסה העדכנית של התבנית, שזמינה בתיקיית ההורה ללא תאריך בדלי – gs://dataflow-templates/latest/
  • שם הגרסה, כמו 2023-09-12-00_RC00, כדי להשתמש בגרסה ספציפית של התבנית. אפשר למצוא את הגרסה הזו בתיקיית ההורה המתאימה עם התאריך בדלי – gs://dataflow-templates/
  זהירות: יכול להיות שעדכונים בגרסה העדכנית של התבניות יגרמו לשינויים שישברו את התאימות לאחור. כדי שהשינויים האלה לא ישפיעו על תהליכי העבודה שלכם בסביבת הייצור, בסביבות הייצור צריך להשתמש בתבניות שנשמרות בתיקייה הראשית עם תאריך העדכנית ביותר.
• ‫SUBSCRIPTION_NAME: השם של המינוי שלכם ל-Pub/Sub
• ‫BUCKET_NAME: שם הקטגוריה של Cloud Storage

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

קוד המקור של התבנית

Java

/*
 * Copyright (C) 2022 Google LLC
 *
 * Licensed under the Apache License, Version 2.0 (the "License"); you may not
 * use this file except in compliance with the License. You may obtain a copy of
 * the License at
 *
 *   http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
 * WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
 * License for the specific language governing permissions and limitations under
 * the License.
 */
package com.google.cloud.teleport.v2.templates.pubsubtotext;

import com.google.cloud.teleport.metadata.Template;
import com.google.cloud.teleport.metadata.TemplateCategory;
import com.google.cloud.teleport.metadata.TemplateParameter;
import com.google.cloud.teleport.v2.common.UncaughtExceptionLogger;
import com.google.cloud.teleport.v2.io.WindowedFilenamePolicy;
import com.google.cloud.teleport.v2.options.WindowedFilenamePolicyOptions;
import com.google.cloud.teleport.v2.templates.pubsubtotext.PubsubToText.Options;
import com.google.cloud.teleport.v2.utils.DurationUtils;
import com.google.common.base.Strings;
import org.apache.beam.sdk.Pipeline;
import org.apache.beam.sdk.PipelineResult;
import org.apache.beam.sdk.io.FileBasedSink;
import org.apache.beam.sdk.io.TextIO;
import org.apache.beam.sdk.io.gcp.pubsub.PubsubIO;
import org.apache.beam.sdk.options.Default;
import org.apache.beam.sdk.options.PipelineOptions;
import org.apache.beam.sdk.options.PipelineOptionsFactory;
import org.apache.beam.sdk.options.StreamingOptions;
import org.apache.beam.sdk.options.Validation.Required;
import org.apache.beam.sdk.transforms.windowing.FixedWindows;
import org.apache.beam.sdk.transforms.windowing.Window;
import org.apache.beam.sdk.values.PCollection;

/**
 * This pipeline ingests incoming data from a Cloud Pub/Sub topic and outputs the raw data into
 * windowed files at the specified output directory.
 *
 * <p>Check out <a
 * href="https://github.com/GoogleCloudPlatform/DataflowTemplates/blob/main/v2/googlecloud-to-googlecloud/README_Cloud_PubSub_to_GCS_Text_Flex.md">README</a>
 * for instructions on how to use or modify this template.
 */
@Template(
    name = "Cloud_PubSub_to_GCS_Text_Flex",
    category = TemplateCategory.STREAMING,
    displayName = "Pub/Sub Subscription or Topic to Text Files on Cloud Storage",
    description =
        "The Pub/Sub Topic or Subscription to Cloud Storage Text template is a streaming pipeline that reads records "
            + "from Pub/Sub and saves them as a series of Cloud Storage files in text format. The template can be used as a quick way to save data in Pub/Sub for future use. By default, the template generates a new file every 5 minutes.",
    optionsClass = Options.class,
    flexContainerName = "googlecloud-to-googlecloud",
    documentation =
        "https://cloud.google.com/dataflow/docs/guides/templates/provided/pubsub-topic-subscription-to-text",
    contactInformation = "https://cloud.google.com/support",
    requirements = {
      "The Pub/Sub topic or subscription must exist prior to execution.",
      "The messages published to the topic must be in text format.",
      "The messages published to the topic must not contain any newlines. Note that each Pub/Sub message is saved as a single line in the output file."
    },
    streaming = true,
    supportsAtLeastOnce = true)
public class PubsubToText {

  /**
   * Options supported by the pipeline.
   *
   * <p>Inherits standard configuration options.
   */
  public interface Options
      extends PipelineOptions, StreamingOptions, WindowedFilenamePolicyOptions {

    @TemplateParameter.PubsubTopic(
        order = 1,
        groupName = "Source",
        optional = true,
        description = "Pub/Sub input topic",
        helpText =
            "The Pub/Sub topic to read the input from. If this parameter is provided "
                + "don't use `inputSubscription`.",
        example = "projects/<PROJECT_ID>/topics/<TOPIC_NAME>")
    String getInputTopic();

    void setInputTopic(String value);

    @TemplateParameter.PubsubSubscription(
        order = 2,
        groupName = "Source",
        optional = true,
        description = "Pub/Sub input subscription",
        helpText =
            "The Pub/Sub subscription to read the input from. If this parameter is "
                + "provided, don't use `inputTopic`.",
        example = "projects/<PROJECT_ID>/subscription/<SUBSCRIPTION_NAME>")
    String getInputSubscription();

    void setInputSubscription(String value);

    @TemplateParameter.GcsWriteFolder(
        order = 3,
        groupName = "Target",
        description = "Output file directory in Cloud Storage",
        helpText =
            "The path and filename prefix to write write output files to. "
                + "This value must end in a slash.",
        example = "gs://your-bucket/your-path/")
    @Required
    String getOutputDirectory();

    void setOutputDirectory(String value);

    @TemplateParameter.GcsWriteFolder(
        order = 4,
        optional = true,
        description = "User provided temp location",
        helpText =
            "The user provided directory to output temporary files to. Must end with a slash.")
    String getUserTempLocation();

    void setUserTempLocation(String value);

    @TemplateParameter.Text(
        order = 5,
        groupName = "Target",
        optional = true,
        description = "Output filename prefix of the files to write",
        helpText = "The prefix to place on each windowed file.",
        example = "output-")
    @Default.String("output")
    @Required
    String getOutputFilenamePrefix();

    void setOutputFilenamePrefix(String value);

    @TemplateParameter.Text(
        order = 6,
        groupName = "Target",
        optional = true,
        description = "Output filename suffix of the files to write",
        helpText =
            "The suffix to place on each windowed file, typically a file extension such as `.txt` or `.csv`.",
        example = ".txt")
    @Default.String("")
    String getOutputFilenameSuffix();

    void setOutputFilenameSuffix(String value);
  }

  /**
   * Main entry point for executing the pipeline.
   *
   * @param args The command-line arguments to the pipeline.
   */
  public static void main(String[] args) {
    UncaughtExceptionLogger.register();

    Options options = PipelineOptionsFactory.fromArgs(args).withValidation().as(Options.class);

    options.setStreaming(true);

    run(options);
  }

  /**
   * Runs the pipeline with the supplied options.
   *
   * @param options The execution parameters to the pipeline.
   * @return The result of the pipeline execution.
   */
  public static PipelineResult run(Options options) {
    boolean useInputSubscription = !Strings.isNullOrEmpty(options.getInputSubscription());
    boolean useInputTopic = !Strings.isNullOrEmpty(options.getInputTopic());
    if (useInputSubscription == useInputTopic) {
      throw new IllegalArgumentException(
          "Either input topic or input subscription must be provided, but not both.");
    }

    // Create the pipeline
    Pipeline pipeline = Pipeline.create(options);

    PCollection<String> messages = null;

    /*
     * Steps:
     *   1) Read string messages from PubSub
     *   2) Window the messages into minute intervals specified by the executor.
     *   3) Output the windowed files to GCS
     */
    if (useInputSubscription) {
      messages =
          pipeline.apply(
              "Read PubSub Events",
              PubsubIO.readStrings().fromSubscription(options.getInputSubscription()));
    } else {
      messages =
          pipeline.apply(
              "Read PubSub Events", PubsubIO.readStrings().fromTopic(options.getInputTopic()));
    }
    messages
        .apply(
            options.getWindowDuration() + " Window",
            Window.into(FixedWindows.of(DurationUtils.parseDuration(options.getWindowDuration()))))

        // Apply windowed file writes
        .apply(
            "Write File(s)",
            TextIO.write()
                .withWindowedWrites()
                .withNumShards(options.getNumShards())
                .to(
                    WindowedFilenamePolicy.writeWindowedFiles()
                        .withOutputDirectory(options.getOutputDirectory())
                        .withOutputFilenamePrefix(options.getOutputFilenamePrefix())
                        .withShardTemplate(options.getOutputShardTemplate())
                        .withSuffix(options.getOutputFilenameSuffix())
                        .withYearPattern(options.getYearPattern())
                        .withMonthPattern(options.getMonthPattern())
                        .withDayPattern(options.getDayPattern())
                        .withHourPattern(options.getHourPattern())
                        .withMinutePattern(options.getMinutePattern()))
                .withTempDirectory(
                    FileBasedSink.convertToFileResourceIfPossible(
                        maybeUseUserTempLocation(
                            options.getUserTempLocation(), options.getOutputDirectory()))));

    // Execute the pipeline and return the result.
    return pipeline.run();
  }

  /**
   * Utility method for using optional parameter userTempLocation as TempDirectory. This is useful
   * when output bucket is locked and temporary data cannot be deleted.
   *
   * @param userTempLocation user provided temp location
   * @param outputLocation user provided outputDirectory to be used as the default temp location
   * @return userTempLocation if available, otherwise outputLocation is returned.
   */
  private static String maybeUseUserTempLocation(String userTempLocation, String outputLocation) {
    return !Strings.isNullOrEmpty(userTempLocation) ? userTempLocation : outputLocation;
  }
}

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

• מידע נוסף על תבניות Dataflow
• כאן אפשר לעיין ברשימת התבניות ש-Google סיפקה.