REST Resource: projects.topics

Resource: Topic

A topic resource.

JSON representation 
{
  "name": string,
  "labels": {
    string: string,
    ...
  },
  "messageStoragePolicy": {
    object (MessageStoragePolicy)
  },
  "kmsKeyName": string,
  "schemaSettings": {
    object (SchemaSettings)
  },
  "satisfiesPzs": boolean,
  "messageRetentionDuration": string,
  "state": enum (State),
  "ingestionDataSourceSettings": {
    object (IngestionDataSourceSettings)
  }
}
Fields
name

string

Required. Name of the topic. Format is projects/{project}/topics/{topic}.
labels

map (key: string, value: string)

Optional. See Creating and managing labels.

An object containing a list of "key": value pairs. Example: { "name": "wrench", "mass": "1.3kg", "count": "3" }.
messageStoragePolicy

object (MessageStoragePolicy)

Optional. Policy constraining the set of Google Cloud Platform regions where messages published to the topic may be stored. If not present, then no constraints are in effect.
kmsKeyName

string

Optional. The resource name of the Cloud KMS CryptoKey to be used to protect access to messages published on this topic.

The expected format is projects/*/locations/*/keyRings/*/cryptoKeys/*.
schemaSettings

object (SchemaSettings)

Optional. Settings for validating messages published against a schema.
satisfiesPzs

boolean

Optional. Reserved for future use. This field is set only in responses from the server; it is ignored if it is set in any requests.
messageRetentionDuration

string (Duration format)

Optional. Indicates the minimum duration to retain a message after it is published to the topic. If this field is set, messages published to the topic in the last messageRetentionDuration are always available to subscribers. For instance, it allows any attached subscription to seek to a timestamp that is up to messageRetentionDuration in the past. If this field is not set, message retention is controlled by settings on individual subscriptions. Cannot be more than 31 days or less than 10 minutes.

A duration in seconds with up to nine fractional digits, ending with 's'. Example: "3.5s".
state

enum (State)

Output only. An output-only field indicating the state of the topic.
ingestionDataSourceSettings

object (IngestionDataSourceSettings)

Optional. Settings for ingestion from a data source into this topic.

MessageStoragePolicy

A policy constraining the storage of messages published to the topic.

JSON representation 
{
  "allowedPersistenceRegions": [
    string
  ],
  "enforceInTransit": boolean
}
Fields
allowedPersistenceRegions[]

string

Optional. A list of IDs of Google Cloud regions where messages that are published to the topic may be persisted in storage. Messages published by publishers running in non-allowed Google Cloud regions (or running outside of Google Cloud altogether) are routed for storage in one of the allowed regions. An empty list means that no regions are allowed, and is not a valid configuration.
enforceInTransit

boolean

Optional. If true, allowedPersistenceRegions is also used to enforce in-transit guarantees for messages. That is, Pub/Sub will fail topics.publish operations on this topic and subscribe operations on any subscription attached to this topic in any region that is not in allowedPersistenceRegions.

SchemaSettings

Settings for validating messages published against a schema.

JSON representation 
{
  "schema": string,
  "encoding": enum (Encoding),
  "firstRevisionId": string,
  "lastRevisionId": string
}
Fields
schema

string

Required. The name of the schema that messages published should be validated against. Format is projects/{project}/schemas/{schema}. The value of this field will be _deleted-schema_ if the schema has been deleted.
encoding

enum (Encoding)

Optional. The encoding of messages validated against schema.
firstRevisionId

string

Optional. The minimum (inclusive) revision allowed for validating messages. If empty or not present, allow any revision to be validated against last_revision or any revision created before.
lastRevisionId

string

Optional. The maximum (inclusive) revision allowed for validating messages. If empty or not present, allow any revision to be validated against first_revision or any revision created after.

Encoding

Possible encoding types for messages.

Enums
ENCODING_UNSPECIFIED Unspecified
JSON JSON encoding
BINARY Binary encoding, as defined by the schema type. For some schema types, binary encoding may not be available.

State

The state of the topic.

Enums
STATE_UNSPECIFIED Default value. This value is unused.
ACTIVE The topic does not have any persistent errors.
INGESTION_RESOURCE_ERROR Ingestion from the data source has encountered a permanent error. See the more detailed error state in the corresponding ingestion source configuration.

IngestionDataSourceSettings

Settings for an ingestion data source on a topic.

JSON representation 
{

  // Union field source can be only one of the following:
  "awsKinesis": {
    object (AwsKinesis)
  }
  // End of list of possible types for union field source.
}
Fields
Union field source. Only one source type can have settings set. source can be only one of the following:
awsKinesis

object (AwsKinesis)

Optional. Amazon Kinesis Data Streams.

AwsKinesis

Ingestion settings for Amazon Kinesis Data Streams.

JSON representation 
{
  "state": enum (State),
  "streamArn": string,
  "consumerArn": string,
  "awsRoleArn": string,
  "gcpServiceAccount": string
}
Fields
state

enum (State)

Output only. An output-only field that indicates the state of the Kinesis ingestion source.
streamArn

string

Required. The Kinesis stream ARN to ingest data from.
consumerArn

string

Required. The Kinesis consumer ARN to used for ingestion in Enhanced Fan-Out mode. The consumer must be already created and ready to be used.
awsRoleArn

string

Required. AWS role ARN to be used for Federated Identity authentication with Kinesis. Check the Pub/Sub docs for how to set up this role and the required permissions that need to be attached to it.
gcpServiceAccount

string

Required. The GCP service account to be used for Federated Identity authentication with Kinesis (via a AssumeRoleWithWebIdentity call for the provided role). The awsRoleArn must be set up with accounts.google.com:sub equals to this service account number.

State

Possible states for ingestion from Amazon Kinesis Data Streams.

Enums
STATE_UNSPECIFIED Default value. This value is unused.
ACTIVE Ingestion is active.
KINESIS_PERMISSION_DENIED Permission denied encountered while consuming data from Kinesis. This can happen if: - The provided awsRoleArn does not exist or does not have the appropriate permissions attached. - The provided awsRoleArn is not set up properly for Identity Federation using gcpServiceAccount. - The Pub/Sub SA is not granted the iam.serviceAccounts.getOpenIdToken permission on gcpServiceAccount.
PUBLISH_PERMISSION_DENIED Permission denied encountered while publishing to the topic. This can happen if the Pub/Sub SA has not been granted the appropriate publish permissions
STREAM_NOT_FOUND The Kinesis stream does not exist.
CONSUMER_NOT_FOUND The Kinesis consumer does not exist.

Methods

create

 Creates the given topic with the given name.

delete

 Deletes the topic with the given name.

get

 Gets the configuration of a topic.

getIamPolicy

 Gets the access control policy for a resource.

list

 Lists matching topics.

patch

 Updates an existing topic by updating the fields specified in the update mask.

publish

 Adds one or more messages to the topic.

setIamPolicy

 Sets the access control policy on the specified resource.

testIamPermissions

 Returns permissions that a caller has on the specified resource.