Google Pub/Sub Publisher

Supported pipeline types: Data Collector

The Google Pub/Sub Publisher destination publishes messages to a Google Pub/Sub topic. You can use other destinations to write to Google BigQuery, Google Bigtable, and Google Cloud Storage.

When you configure the destination, you define the Google Pub/Sub topic ID to write messages to. You also define the project and credentials provider to use to connect to Google Pub/Sub. The destination can retrieve credentials from the Google Application Default Credentials or from a Google Cloud service account credentials file.

By default, the Google Pub/Sub Publisher destination writes messages in batches. Using advanced properties, you can configure the conditions that trigger writing a new batch or disable batch processing to write messages individually. You can also configure the action the destination takes when it reads messages faster than it can write messages.

A Google Pub/Sub message contains a payload and optional user-defined attributes that describe the payload content. When records include record header attributes, the Google Pub/Sub Publisher destination includes the record header attributes in message attributes. The destination does not include internal record header attributes in message attributes.

For more information about record header attributes, see Record Header Attributes.

Credentials

When the Google Pub/Sub Publisher destination publishes messages to a Google Pub/Sub topic, it must pass credentials to Google Pub/Sub. Configure the destination to retrieve the credentials from the Google Application Default Credentials or from a Google Cloud service account credentials file.

Default Credentials Provider

When configured to use the Google Application Default Credentials, the destination checks for the credentials file defined in the GOOGLE_APPLICATION_CREDENTIALS environment variable. If the environment variable doesn't exist and Data Collector is running on a virtual machine (VM) in Google Cloud Platform (GCP), the destination uses the built-in service account associated with the virtual machine instance.

For more information about the default credentials, see Google Application Default Credentials in the Google Developer documentation.

Complete the following steps to define the credentials file in the environment variable:

Use the Google Cloud Platform Console or the gcloud command-line tool to create a Google service account and have your application use it for API access.
For example, to use the command line tool, run the following commands:
```
gcloud iam service-accounts create my-account
gcloud iam service-accounts keys create key.json --iam-account=my-account@my-project.iam.gserviceaccount.com
```
Store the generated credentials file on the Data Collector machine.
Add the GOOGLE_APPLICATION_CREDENTIALS environment variable to the appropriate file and point it to the credentials file.
using the method required by your installation type.

Set the environment variable as follows:
```
export GOOGLE_APPLICATION_CREDENTIALS="/var/lib/sdc-resources/keyfile.json"
```
Restart Data Collector to enable the changes.
On the Credentials tab for the stage, select Default Credentials Provider for the credentials provider.

Service Account Credentials File (JSON)

When configured to use the Google Cloud service account credentials file, the destination checks for the file defined in the destination properties.

Complete the following steps to use the service account credentials file:

Generate a service account credentials file in JSON format.
Use the Google Cloud Platform Console or the gcloud command-line tool to generate and download the credentials file. For more information, see generating a service account credential in the Google Cloud Platform documentation.
Store the generated credentials file on the Data Collector machine.
As a best practice, store the file in the Data Collector resources directory, $SDC_RESOURCES.
On the Credentials tab for the stage, select Service Account Credentials File for the credentials provider and enter the path to the credentials file.

Data Formats

Google Pub/Sub Publisher writes data to Google Pub/Sub based on the data format that you select. You can use the following data formats:

Avro

The stage writes records based on the Avro schema. You can use one of the following methods to specify the location of the Avro schema definition:

In Pipeline Configuration - Use the schema that you provide in the stage configuration.
In Record Header - Use the schema included in the avroSchema record header attribute.
Confluent Schema Registry - Retrieve the schema from Confluent Schema Registry. The Confluent Schema Registry is a distributed storage layer for Avro schemas. You can configure the destination to look up the schema in the Confluent Schema Registry by the schema ID or subject.
If using the Avro schema in the stage or in the record header attribute, you can optionally configure the stage to register the Avro schema with the Confluent Schema Registry. You can also optionally include the schema definition in the message. Omitting the schema definition can improve performance, but requires the appropriate schema management to avoid losing track of the schema associated with the data.

You can include the Avro schema in the output.

You can also compress data with an Avro-supported compression codec. When using Avro compression, avoid configuring any other compression properties in the stage.

Binary

The stage writes binary data to a single field in the record.

Delimited

The destination writes records as delimited data. When you use this data format, the root field must be list or list-map.

You can use the following delimited format types:

Default CSV - File that includes comma-separated values. Ignores empty lines in the file.
RFC4180 CSV - Comma-separated file that strictly follows RFC4180 guidelines.
MS Excel CSV - Microsoft Excel comma-separated file.
MySQL CSV - MySQL comma-separated file.
Tab-Separated Values - File that includes tab-separated values.
PostgreSQL CSV - PostgreSQL comma-separated file.
PostgreSQL Text - PostgreSQL text file.
Custom - File that uses user-defined delimiter, escape, and quote characters.
Multi Character Delimited - File that uses multiple user-defined characters to delimit fields and lines, and single user-defined escape and quote characters.

JSON

The destination writes records as JSON data. You can use one of the following formats:

Array - Each file includes a single array. In the array, each element is a JSON representation of each record.
Multiple objects - Each file includes multiple JSON objects. Each object is a JSON representation of a record.

Protobuf

Writes one record in a message. Uses the user-defined message type and the definition of the message type in the descriptor file to generate the message.

For information about generating the descriptor file, see Protobuf Data Format Prerequisites.

SDC Record

The destination writes records in the SDC Record data format.

Text

The destination writes data from a single text field to the destination system. When you configure the stage, you select the field to use.

You can configure the characters to use as record separators. By default, the destination uses a UNIX-style line ending (\n) to separate records.

When a record does not contain the selected text field, the destination can report the missing field as an error or to ignore the missing field. By default, the destination reports an error.

When configured to ignore a missing text field, the destination can discard the record or write the record separator characters to create an empty line for the record. By default, the destination discards the record.

XML

The destination creates a valid XML document for each record. The destination requires the record to have a single root field that contains the rest of the record data. For details and suggestions for how to accomplish this, see Record Structure Requirement.

The destination can include indentation to produce human-readable documents. It can also validate that the generated XML conforms to the specified schema definition. Records with invalid schemas are handled based on the error handling configured for the destination.

Configuring a Google Pub/Sub Publisher Destination

Configure a Google Pub/Sub Publisher destination to write messages to a Google Pub/Sub topic.

In the Properties panel, on the General tab, configure the following properties:

General Property	Description
Name	Stage name.
Description	Optional description.
Required Fields	Fields that must include data for the record to be passed into the stage. Tip: You might include fields that the stage uses. Records that do not include all required fields are processed based on the error handling configured for the pipeline.
Preconditions	Conditions that must evaluate to TRUE to allow a record to enter the stage for processing. Click Add to create additional preconditions. Records that do not meet all preconditions are processed based on the error handling configured for the stage.
On Record Error	Error record handling for the stage: Discard - Discards the record. Send to Error - Sends the record to the pipeline for error handling. Stop Pipeline - Stops the pipeline. Not valid for cluster pipelines.

On the Pub/Sub tab, configure the following property:

Pub/Sub Property Description

Topic ID Google Pub/Sub topic ID to write messages to.

Pub/Sub Property	Description
Topic ID	Google Pub/Sub topic ID to write messages to.

On the Credentials tab, configure the following properties:

Credentials Property	Description
Project ID	Google Pub/Sub project ID to connect to.
Credentials Provider	Credentials provider to use to connect to Google Pub/Sub: Default credentials provider Service account credentials file (JSON)
Credentials File Path (JSON)	When using a Google Cloud service account credentials file, path to the file that the destination uses to connect to Google Pub/Sub. The credentials file must be a JSON file. Enter a path relative to the Data Collector resources directory, `$SDC_RESOURCES`, or enter an absolute path.

On the Advanced tab, configure the following properties:

Advanced Property	Description
Request Bytes Threshold	Size of accumulated messages that triggers sending messages as a batch. Specify in bytes. Default is 1000.
Messages Count Threshold	Number of accumulated messages that triggers sending messages as a batch. Default is 100.
Default Delay Threshold (ms)	Elapsed time since the arrival of the first message that triggers sending messages as a batch. Specify in milliseconds. Default is 1.
Batch Enabled	Select to have the destination send messages in batches. When disabled, the destination writes each message individually, ignoring threshold properties.
Max Outstanding Message Count	Number of unprocessed messages that the destination stores in memory before taking an action to control the flow of messages. You might want to control the flow of messages when the destination can read messages faster than it can write messages. Set to 0 to never control the flow based on message count. To control the message flow when using batch processing, set to a number larger than the message count threshold.
Max Outstanding Request Bytes	Number of unprocessed bytes that the destination stores in memory before taking an action to control the flow of messages. Set to 0 to never control the flow based on message size. To control the message flow when using batch processing, set to a number larger than the request bytes threshold.
Limit Exceeded Behavior	Action to take when either the count or size of unprocessed messages exceeds the specified limit. Select one of the following options: Throw Exception - Triggers pipeline error processing. Block - Stops processing new messages until stored messages have been successfully written. Ignore - Discards new messages until stored messages have been successfully written.

On the Data Format tab, configure the following property:

Data Format Property	Description
Data Format	Format of data to be written. Use one of the following options: Avro Binary Delimited JSON Protobuf SDC Record Text XML

For Avro data, on the Data Format tab, configure the following properties:

Avro Property	Description
Avro Schema Location	Location of the Avro schema definition to use when writing data: In Pipeline Configuration - Use the schema that you provide in the stage configuration. In Record Header - Use the schema in the avroSchema record header attribute. Use only when the avroSchema attribute is defined for all records. Confluent Schema Registry - Retrieve the schema from the Confluent Schema Registry.
Avro Schema	Avro schema definition used to write the data. You can optionally use the runtime:loadResource function to use a schema definition stored in a runtime resource file.
Register Schema	Select to register a new Avro schema with the Confluent Schema Registry.
Schema Registry URLs	Confluent Schema Registry URLs used to look up the schema or to register a new schema. To add a URL, click Add. Use the following format to enter the URL: `http://<host name>:<port number>`
Look Up Schema By	Method used to look up the schema in the Confluent Schema Registry: Subject - Look up the specified Avro schema subject. Schema ID - Look up the specified Avro schema ID.
Schema Subject	Avro schema subject to look up or to register in the Confluent Schema Registry. If the specified subject to look up has multiple schema versions, the origin uses the latest schema version for that subject. To use an older version, find the corresponding schema ID, and then set the Look Up Schema By property to Schema ID.
Schema ID	Avro schema ID to look up in the Confluent Schema Registry.
Include Schema	Includes the schema in each message. Note: Omitting the schema definition can improve performance, but requires the appropriate schema management to avoid losing track of the schema associated with the data.
Avro Compression Codec	The Avro compression type to use. When using Avro compression, do not enable other compression available in the destination.

For binary data, on the Data Format tab, configure the following property:

Binary Property Description

Binary Field Path Field that contains the binary data.

Binary Property	Description
Binary Field Path	Field that contains the binary data.

For delimited data, on the Data Format tab, configure the following properties:

Delimited Property	Description
Delimiter Format	Format for delimited data: Default CSV - File that includes comma-separated values. Ignores empty lines in the file. RFC4180 CSV - Comma-separated file that strictly follows RFC4180 guidelines. MS Excel CSV - Microsoft Excel comma-separated file. MySQL CSV - MySQL comma-separated file. Tab-Separated Values - File that includes tab-separated values. PostgreSQL CSV - PostgreSQL comma-separated file. PostgreSQL Text - PostgreSQL text file. Custom - File that uses user-defined delimiter, escape, and quote characters.
Header Line	Indicates whether to create a header line.
Replace New Line Characters	Replaces new line characters with the configured string. Recommended when writing data as a single line of text.
New Line Character Replacement	String to replace each new line character. For example, enter a space to replace each new line character with a space. Leave empty to remove the new line characters.
Delimiter Character	Delimiter character for a custom delimiter format. Select one of the available options or use Other to enter a custom character. You can enter a Unicode control character using the format \uNNNN, where N is a hexadecimal digit from the numbers 0-9 or the letters A-F. For example, enter \u0000 to use the null character as the delimiter or \u2028 to use a line separator as the delimiter. Default is the pipe character ( \| ).
Escape Character	Escape character for a custom delimiter format. Select one of the available options or use Other to enter a custom character. Default is the backslash character ( \ ).
Quote Character	Quote character for a custom delimiter format. Select one of the available options or use Other to enter a custom character. Default is the quotation mark character ( " ).
Charset	Character set to use when writing data.

For JSON data, on the Data Format tab, configure the following property:

JSON Property	Description
JSON Content	Determines how JSON data is written: JSON Array of Objects - Each file includes a single array. In the array, each element is a JSON representation of each record. Multiple JSON Objects - Each file includes multiple JSON objects. Each object is a JSON representation of a record.
Charset	Character set to use when writing data.

For protobuf data, on the Data Format tab, configure the following properties:

Protobuf Property	Description
Protobuf Descriptor File	Descriptor file (.desc) to use. The descriptor file must be in the Data Collector resources directory, `$SDC_RESOURCES`. For more information about environment variables, see Data Collector Environment Configuration in the Data Collector documentation. For information about generating the descriptor file, see Protobuf Data Format Prerequisites.
Message Type	The fully-qualified name for the message type to use when writing data. Use the following format: `<package name>.<message type>`. Use a message type defined in the descriptor file.
Write Delimiter	Writes a delimiter after each message.

For text data, on the Data Format tab, configure the following properties:

Text Property	Description
Text Field Path	Field that contains the text data to be written. All data must be incorporated into the specified field.
Record Separator	Characters to use to separate records. Use any valid Java string literal. For example, when writing to Windows, you might use `\r\n` to separate records. By default, the destination uses `\n`.
On Missing Field	When a record does not include the text field, determines whether the destination reports the missing field as an error or ignores the missing field.
Insert Record Separator if No Text	When configured to ignore a missing text field, inserts the configured record separator string to create an empty line. When not selected, discards records without the text field.
Charset	Character set to use when writing data.

For XML data, on the Data Format tab, configure the following properties:

XML Property	Description
Pretty Format	Adds indentation to make the resulting XML document easier to read. Increases the record size accordingly.
Validate Schema	Validates that the generated XML conforms to the specified schema definition. Records with invalid schemas are handled based on the error handling configured for the destination. Important: Regardless of whether you validate the XML schema, the destination requires the record in a specific format. For more information, see Record Structure Requirement.
XML Schema	The XML schema to use to validate records.