Adapter properties and commands

This section lists the properties supported by the Google Cloud Pub/Sub adapter.

Credentials File

Specifies the JSON file with credentials of the service account used to access the Cloud Pub/Sub service. When not specified, the authentication is done using the credentials file pointed to by the GOOGLE_APPLICATION_CREDENTIALS environment variable. When running in the Google Cloud environment, where applicable the authentication may be performed automatically by the environment using the default service account for the environment in which the adapter is running. The adapter only supports authentication for Google service accounts. Authentication for Google end-user accounts is not supported.

The corresponding adapter command is -CF (or -CREDENTIALSFILE) credentials_file.

Username

Specifies the username for the connection. This is optional property. For many drivers, you can specify the username as part of the connection string. Some drivers might use authentication other than username and password, and some drivers might not require authentication at all. The corresponding adapter command is -USER user_name.

Project

This property identifies the project that hosts the topics and subscriptions accessed by the adapter. The corresponding adapter command is -P (or -PROJECT) project_id.

Topic

Specifies the topic to which messages are written. When reading messages and creating the subscription automatically. This is the topic for which the subscription is created. The corresponding adapter command is -TP (or -TOPIC)topic_id .

Create Topic

Instructs the adapter to create the specified target topic if the topic does not exist already. This property is applicable only when the adapter is used in target scenario. The corresponding adapter command is -CT (or -CREATETOPIC).

Subscription

This property identifies the subscription from which to read messages. The adapter supports only pull type subscriptions, and it does not support push type subscriptions. When discovering subscriptions, only the subscriptions of pull type are included in the result. The corresponding adapter command is -S subscription_id.

Create Subscription

Instructs the adapter to create the specified subscription if the subscription does not exist already. This property is applicable only when the adapter is used in source scenario. The new subscription is created for the specified topic, and it is created as subscription of pull type.

The corresponding adapter command is -CS (or -CREATESUBSCRIPTION).

Batch Count

Specifies the number of messages to store locally in the Pub/Sub client before flushing the buffer. The default value is 1 which implies immediate flushing of the buffer. The flushing of the batch is controlled using a combination of conditions specified in Batch Count, Batch Size (Bytes) and Batch Delay (Milliseconds) properties. When any of those conditions is met, the buffer is flushed.

The corresponding adapter command is -BC (or -BATCHCOUNT) count.

Batch Size (Bytes)

Specifies the size in bytes of the buffer in which to store messages locally before flushing the buffer. The default value is 1 which implies immediate flushing of the buffer. The flushing of the batch is controlled using a combination of conditions specified in Batch Count, Batch Size (Bytes) and Batch Delay(Milliseconds) properties. When any of these conditions is met, the buffer is flushed.

The corresponding adapter command is -BS (or -BATCHSIZE) size.

Batch Delay (Milliseconds)

Specifies the duration in milliseconds for storing messages locally in a buffer before flushing the buffer. The default value is 1 which implies immediate flushing of the buffer. The flushing of the batch is controlled using a combination of conditions specified in Batch Count, Batch Size (Bytes) and Batch Delay(Milliseconds) properties. When any of those conditions is met, the buffer is flushed.

The corresponding adapter command is -BD (or -BATCHDELAY) delay.

Subscription Deadline (Seconds)

Specifies the deadline in milliseconds to set for the messages on the subscription when the subscription is created by the adapter. This is the interval each subscriber is given to acknowledge the retrieval of a message from the subscription. If the message is not acknowledged during this interval and its deadline is not extended, it is automatically made available for redelivery. The default value is 10 seconds.

The corresponding adapter command is -SD (or -SUBSCRIPTIONDELAY) deadline.

Acknowledgments
Specifies when the adapter should acknowledge retrieved messages. The supported options are:
  • Never - the adapter never sends acknowledgments for the messages. After the deadline for acknowledgment expires, the messages are made available for redelivery. This is the default option. It is case-insensitive. The corresponding adapter command value is never.
  • Immediate - the adapter sends acknowledgment for messages immediately after retrieving them before the messages are processed by the map. It is case-insensitive. The corresponding adapter command value is immediate.
  • Transactional - the adapter acknowledgments the messages as part of committing the source transaction. It is case-insensitive. The corresponding adapter command value is transactional.

The corresponding adapter command is -ACK (or -ACKNOWLEDGMENTS)never|immediate|transactional.

Message Deadline (Seconds)

Specifies the deadline in milliseconds to set for the messages retrieved from a subscription. This becomes the new time interval. The adapter has to acknowledge the messages before they are made available for redelivery. When the value is not specified, the default deadline value is -1, which represents the deadline set at the subscription level. The corresponding adapter command is -MD (-MESSAGEDEADLINE) deadline.

Poll Message Count

Specifies the maximum number of messages to poll from the Pub/Sub service per single request. The default value is 1 which effectively disables retrieving messages in batches. When more than one message is retrieved per request, the messages are stored locally, and the adapter polls the subscription for new messages only after it has exhausted all locally stored messages.

The corresponding adapter command is -PMC (-POLLMESSAGECOUNT)count.

Publish Timeout (Seconds)

Specifies the time in milliseconds. The adapter waits for the publish operation to complete, before timing out and reporting error. The default value is -1 which indicates no timeout. The corresponding adapter command is -PT (-PUBLISHTIME) timeout.

Logical Message Mode

Specifies that the adapter will run in a mode in which the payload it exchanges with the framework is assumed to consist of one or more Pub/Sub physical messages. When this mode is not used, each payload the adapter exchanges with the framework corresponds to exactly one Pub/Sub message.

In logical message mode, the payload the adapter exchanges with the framework is in the following format:

32-bit integer representing the total remaining payload size (4 bytes) 32-bit integer representing the size of message 1 (4 bytes) message 1 data 32-bit integer representing size of message 2 (4 bytes) message 2 data.

In target context, a single payload (logical message) provided to the adapter may result in multiple Pub/Sub messages published to the target topic. In source context, multiple Pub/Sub messages retrieved from the subscription may be combined and provided to the framework as a single payload (logical message).

The corresponding adapter command is -LMM (or -LOGICALMESSAGEMODE).

Logical Message Count

Specifies the number of Pub/Sub messages to include in a single logical message when reading messages from the subscription in logical message mode. The default value is 1. The size of the logical message provided by the adapter is controlled by the combination of conditions defined by two properties:

  • Logical Message Count and
  • Logical Message Size (Bytes).

Whichever condition is met first determines the actual size of the logical message.

The corresponding adapter command is -LMC (or -LOGICALMESSAGECOUNT) count.

Logical Message Size (Bytes)

Specifies the size in bytes of a single logical message when reading messages from the subscription in logical message mode. When the total size of messages retrieved from the subscription reaches or exceeds this value, the logical messages is considered complete. The default value is 0. The size of the logical message provided by the adapter is controlled by the combination of conditions defined by two properties:

  • Logical Message Count and
  • Logical Message Size (Bytes).

Whichever condition is met first determines the actual size of the logical message.

The corresponding adapter command is -LMS (or -LOGICALMESSAGESIZE) size.

Limit
Specifies the number of messages to retrieve from the subscription. The default value is 1. The special value "S" indicates all available messages and the value 0 means no wait. The corresponding adapter command is -QTY limit.
Timeout

Specifies the timeout in seconds to wait for a new message to arrive. The default value is "S". This is a special value that indicates unlimited (infinite) wait. The corresponding adapter command is -LSN timeout.

Logging

This property specifies the level of logging to use for the log (trace) file produced by the adapter. The default is Off. The value Information means log informational, the value Errors Only means log error messages only, and the value Verbose means log debug and trace level messages along with the informational and error messages.

The corresponding adapter command is:

-T [E|V] [+] [file_path]

-T -> Log adapter informational messages.

-TE -> Log only adapter errors.

-TV -> Use verbose (debug) logging. The log file records all activity that occurs while the adapter is producing or consuming messages.

+ -> Appends the trace information to the existing log file. Omit this argument to create a new log file.

file_path -> The full path to the adapter trace log. If you omit this keyword, the adapter creates the m4gcpubsub.mtr log file in the map directory.

Append Log

Flag indicating what to do if the specified log file already exists. When set to true, the log messages are appended to the file. When set to false, the file is truncated, and the messages are written to the empty file. The default value is true.