The Pub/Sub to Cloud Storage Text template is a streaming pipeline that reads
records from Pub/Sub topic 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.

## Pipeline requirements

- The Pub/Sub topic 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.

## Template parameters

### Required parameters

- **outputDirectory** : The path and filename prefix for writing output files. For example, `gs://bucket-name/path/`. This value must end in a slash.
- **outputFilenamePrefix** : The prefix to place on each windowed file. For example, `output-`. Defaults to: output.

### Optional parameters

- **inputTopic** : The Pub/Sub topic to read the input from. The topic name should be in the format `projects/<PROJECT_ID>/topics/<TOPIC_NAME>`.
- **userTempLocation**: The user provided directory to output temporary files to. Must end with a slash.
- **outputFilenameSuffix** : The suffix to place on each windowed file. Typically a file extension such as `.txt` or `.csv`. Defaults to empty.
- **outputShardTemplate** : The shard template defines the dynamic portion of each windowed file. By default, the pipeline uses a single shard for output to the file system within each window. Therefore, all data outputs into a single file per window. The `outputShardTemplate` defaults `to W-P-SS-of-NN`, where `W` is the window date range, `P` is the pane info, `S` is the shard number, and `N` is the number of shards. In case of a single file, the `SS-of-NN` portion of the `outputShardTemplate` is `00-of-01`.
- **yearPattern** : Pattern for formatting the year. Must be one or more of `y` or `Y`. Case makes no difference in the year. Optionally, wrap the pattern with characters that aren't alphanumeric or the directory (`/`) character. Defaults to `YYYY`.
- **monthPattern** : Pattern for formatting the month. Must be one or more of the `M` character. Optionally, wrap the pattern with characters that aren't alphanumeric or the directory (`/`) character. Defaults to `MM`.
- **dayPattern** : Pattern for formatting the day. Must be one or more of `d` for day of month or `D` for day of year. Optionally, wrap the pattern with characters that aren't alphanumeric or the directory (`/`) character. Defaults to `dd`.
- **hourPattern** : Pattern for formatting the hour. Must be one or more of the `H` character. Optionally, wrap the pattern with characters that aren't alphanumeric or the directory (`/`) character. Defaults to `HH`.
- **minutePattern** : Pattern for formatting the minute. Must be one or more of the `m` character. Optionally, wrap the pattern with characters that aren't alphanumeric or the directory (`/`) character. Defaults to `mm`.

## Run the template

### Console

1. Go to the Dataflow **Create job from template** page.
[Go to Create job from template](https://console.cloud.google.com/dataflow/createjob)
2. In the **Job name** field, enter a unique job name.
3. Optional: For **Regional endpoint** , select a value from the drop-down menu. The default region is `us-central1`.


   For a list of regions where you can run a Dataflow job, see
   [Dataflow locations](https://docs.cloud.google.com/dataflow/docs/resources/locations).
4. From the **Dataflow template** drop-down menu, select the **Pub/Sub to Text Files on Cloud Storage** template.
5. In the provided parameter fields, enter your parameter values.
6. Optional: To switch from exactly-once processing to [at-least-once streaming mode](https://docs.cloud.google.com/dataflow/docs/guides/streaming-modes), select **At Least Once**.
7. Click **Run job**.

### gcloud

> [!NOTE]
> **Note:** To use the Google Cloud CLI to run classic templates, you must have [Google Cloud CLI](https://docs.cloud.google.com/sdk/docs/install) version 138.0.0 or later.

In your shell or terminal, run the template:

```bash
gcloud dataflow jobs run JOB_NAME \
    --gcs-location gs://dataflow-templates/VERSION/Cloud_PubSub_to_GCS_Text \
    --region REGION_NAME \
    --staging-location STAGING_LOCATION \
    --parameters \
inputTopic=projects/PROJECT_ID/topics/TOPIC_NAME,\
outputDirectory=gs://BUCKET_NAME/output/,\
outputFilenamePrefix=output-,\
outputFilenameSuffix=.txt
```

Replace the following:

- `JOB_NAME`: a unique job name of your choice
- `REGION_NAME`: the [region](https://docs.cloud.google.com/dataflow/docs/resources/locations) where you want to deploy your Dataflow job---for example, `us-central1`
- `VERSION`: the version of the template that you want to use

  You can use the following values:
  - `latest` to use the latest version of the template, which is available in the **non-dated** parent folder in the bucket--- [gs://dataflow-templates/latest/](https://console.cloud.google.com/storage/browser/dataflow-templates/latest)
  - the version name, like `2023-09-12-00_RC00`, to use a specific version of the template, which can be found nested in the respective dated parent folder in the bucket--- [gs://dataflow-templates/](https://console.cloud.google.com/storage/browser/dataflow-templates)

  > [!CAUTION]
  > **Caution:** The **latest** version of templates might update with breaking changes. Your production environments should use templates kept in the most recent **dated** parent folder to prevent these breaking changes from affecting your production workflows.

- `STAGING_LOCATION`: the location for staging local files (for example, `gs://your-bucket/staging`)
- `TOPIC_NAME`: your Pub/Sub topic name
- `BUCKET_NAME`: the name of your Cloud Storage bucket

### API

To run the template using the REST API, send an HTTP POST request. For more information on the
API and its authorization scopes, see
[`projects.templates.launch`](https://docs.cloud.google.com/dataflow/docs/reference/rest/v1b3/projects.templates/launch).

```json
POST https://dataflow.googleapis.com/v1b3/projects/PROJECT_ID/locations/LOCATION/templates:launch?gcsPath=gs://dataflow-templates/VERSION/Cloud_PubSub_to_GCS_Text
{
   "jobName": "JOB_NAME",
   "environment": {
       "ipConfiguration": "WORKER_IP_UNSPECIFIED",
       "additionalExperiments": []
    },
   "parameters": {
       "inputTopic": "projects/PROJECT_ID/topics/TOPIC_NAME"
       "outputDirectory": "gs://BUCKET_NAME/output/",
       "outputFilenamePrefix": "output-",
       "outputFilenameSuffix": ".txt",
   }
}
```

Replace the following:

- `PROJECT_ID`: the Google Cloud project ID where you want to run the Dataflow job
- `JOB_NAME`: a unique job name of your choice
- `LOCATION`: the [region](https://docs.cloud.google.com/dataflow/docs/resources/locations) where you want to deploy your Dataflow job---for example, `us-central1`
- `VERSION`: the version of the template that you want to use

  You can use the following values:
  - `latest` to use the latest version of the template, which is available in the **non-dated** parent folder in the bucket--- [gs://dataflow-templates/latest/](https://console.cloud.google.com/storage/browser/dataflow-templates/latest)
  - the version name, like `2023-09-12-00_RC00`, to use a specific version of the template, which can be found nested in the respective dated parent folder in the bucket--- [gs://dataflow-templates/](https://console.cloud.google.com/storage/browser/dataflow-templates)

  > [!CAUTION]
  > **Caution:** The **latest** version of templates might update with breaking changes. Your production environments should use templates kept in the most recent **dated** parent folder to prevent these breaking changes from affecting your production workflows.

- `STAGING_LOCATION`: the location for staging local files (for example, `gs://your-bucket/staging`)
- `TOPIC_NAME`: your Pub/Sub topic name
- `BUCKET_NAME`: the name of your Cloud Storage bucket

> [!NOTE]
> This template uses a fixed window, and data that arrives outside of the window might be discarded. To modify the template to change this behavior, see [Extend templates](https://docs.cloud.google.com/dataflow/docs/concepts/dataflow-templates#extend).

## Template source code

### Java

    /*
     * Copyright (C) 2018 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.templates;

    import com.google.cloud.teleport.io.WindowedFilenamePolicy;
    import com.google.cloud.teleport.metadata.Template;
    import com.google.cloud.teleport.metadata.TemplateCategory;
    import com.google.cloud.teleport.metadata.TemplateCreationParameter;
    import com.google.cloud.teleport.metadata.TemplateParameter;
    import com.google.cloud.teleport.options.WindowedFilenamePolicyOptions;
    import com.google.cloud.teleport.templates.PubsubToText.Options;
    import com.google.cloud.teleport.util.DualInputNestedValueProvider;
    import com.google.cloud.teleport.util.DualInputNestedValueProvider.TranslatorInput;
    import com.google.cloud.teleport.util.DurationUtils;
    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.fs.ResourceId;
    import org.apache.beam.sdk.io.gcp.pubsub.PubsubIO;
    import org.apache.beam.sdk.options.Default;
    import org.apache.beam.sdk.options.Description;
    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.options.ValueProvider;
    import org.apache.beam.sdk.options.ValueProvider.NestedValueProvider;
    import org.apache.beam.sdk.transforms.SerializableFunction;
    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/v1/README_Cloud_PubSub_to_GCS_Text.md">README</a>
     * for instructions on how to use or modify this template.
     */
    @Template(
        name = "Cloud_PubSub_to_GCS_Text",
        category = TemplateCategory.STREAMING,
        displayName = "Pub/Sub to Text Files on Cloud Storage",
        description =
            "The Pub/Sub to Cloud Storage Text template is a streaming pipeline that reads records from Pub/Sub topic 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,
        skipOptions = {"inputSubscription"},
        documentation =
            "https://cloud.google.com/dataflow/docs/guides/templates/provided/pubsub-topic-to-text",
        contactInformation = "https://cloud.google.com/support",
        requirements = {
          "The Pub/Sub topic 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,
        supportsExactlyOnce = true)
    public class PubsubToText {

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

        @TemplateParameter.PubsubSubscription(
            order = 1,
            groupName = "Source",
            optional = true,
            description = "Pub/Sub input subscription",
            helpText =
                "Pub/Sub subscription to read the input from, in the format of"
                    + " 'projects/your-project-id/subscriptions/your-subscription-name'",
            example = "projects/your-project-id/subscriptions/your-subscription-name")
        ValueProvider<String> getInputSubscription();

        void setInputSubscription(ValueProvider<String> value);

        @TemplateParameter.PubsubTopic(
            order = 2,
            groupName = "Source",
            optional = true,
            description = "Pub/Sub input topic",
            helpText =
                "The Pub/Sub topic to read the input from. The topic name should be in the format "
                    + "`projects/<PROJECT_ID>/topics/<TOPIC_NAME>`.")
        ValueProvider<String> getInputTopic();

        void setInputTopic(ValueProvider<String> value);

        @TemplateCreationParameter(value = "false")
        @Description(
            "This determines whether the template reads from a Pub/Sub subscription or a topic")
        @Default.Boolean(false)
        Boolean getUseSubscription();

        void setUseSubscription(Boolean value);

        @TemplateParameter.GcsWriteFolder(
            order = 3,
            groupName = "Target",
            description = "Output file directory in Cloud Storage",
            helpText =
                "The path and filename prefix for writing output files. For example, `gs://bucket-name/path/`. This value must end in a slash.")
        @Required
        ValueProvider<String> getOutputDirectory();

        void setOutputDirectory(ValueProvider<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.")
        ValueProvider<String> getUserTempLocation();

        void setUserTempLocation(ValueProvider<String> value);

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

        void setOutputFilenamePrefix(ValueProvider<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`.")
        @Default.String("")
        ValueProvider<String> getOutputFilenameSuffix();

        void setOutputFilenameSuffix(ValueProvider<String> value);
      }

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

        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) {
        // 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 (options.getUseSubscription()) {
          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. Use a NestedValueProvider because the filename
            // policy requires a resourceId generated from the input value at runtime.
            .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(
                        NestedValueProvider.of(
                            maybeUseUserTempLocation(
                                options.getUserTempLocation(), options.getOutputDirectory()),
                            (SerializableFunction<String, ResourceId>)
                                input -> FileBasedSink.convertToFileResourceIfPossible(input))));

        // 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 ValueProvider<String> maybeUseUserTempLocation(
          ValueProvider<String> userTempLocation, ValueProvider<String> outputLocation) {
        return DualInputNestedValueProvider.of(
            userTempLocation,
            outputLocation,
            new SerializableFunction<TranslatorInput<String, String>, String>() {
              @Override
              public String apply(TranslatorInput<String, String> input) {
                return (input.getX() != null) ? input.getX() : input.getY();
              }
            });
      }
    }

## What's next

- Learn about [Dataflow templates](https://docs.cloud.google.com/dataflow/docs/concepts/dataflow-templates).
- See the list of [Google-provided templates](https://docs.cloud.google.com/dataflow/docs/guides/templates/provided-templates).

<br />

<br />