diff options
Diffstat (limited to 'google/pubsub/v1/pubsub.proto')
| -rw-r--r-- | google/pubsub/v1/pubsub.proto | 1057 |
1 files changed, 1057 insertions, 0 deletions
diff --git a/google/pubsub/v1/pubsub.proto b/google/pubsub/v1/pubsub.proto new file mode 100644 index 000000000..715af9c18 --- /dev/null +++ b/google/pubsub/v1/pubsub.proto @@ -0,0 +1,1057 @@ +// Copyright 2019 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. +// + +syntax = "proto3"; + +package google.pubsub.v1; + +import "google/api/annotations.proto"; +import "google/protobuf/duration.proto"; +import "google/protobuf/empty.proto"; +import "google/protobuf/field_mask.proto"; +import "google/protobuf/timestamp.proto"; + +option cc_enable_arenas = true; +option csharp_namespace = "Google.Cloud.PubSub.V1"; +option go_package = "google.golang.org/genproto/googleapis/pubsub/v1;pubsub"; +option java_multiple_files = true; +option java_outer_classname = "PubsubProto"; +option java_package = "com.google.pubsub.v1"; +option php_namespace = "Google\\Cloud\\PubSub\\V1"; +option ruby_package = "Google::Cloud::PubSub::V1"; + +// The service that an application uses to manipulate topics, and to send +// messages to a topic. +service Publisher { + // Creates the given topic with the given name. See the + // <a href="https://cloud.google.com/pubsub/docs/admin#resource_names"> + // resource name rules</a>. + rpc CreateTopic(Topic) returns (Topic) { + option (google.api.http) = { + put: "/v1/{name=projects/*/topics/*}" + body: "*" + }; + } + + // Updates an existing topic. Note that certain properties of a + // topic are not modifiable. + rpc UpdateTopic(UpdateTopicRequest) returns (Topic) { + option (google.api.http) = { + patch: "/v1/{topic.name=projects/*/topics/*}" + body: "*" + }; + } + + // Adds one or more messages to the topic. Returns `NOT_FOUND` if the topic + // does not exist. + rpc Publish(PublishRequest) returns (PublishResponse) { + option (google.api.http) = { + post: "/v1/{topic=projects/*/topics/*}:publish" + body: "*" + }; + } + + // Gets the configuration of a topic. + rpc GetTopic(GetTopicRequest) returns (Topic) { + option (google.api.http) = { + get: "/v1/{topic=projects/*/topics/*}" + }; + } + + // Lists matching topics. + rpc ListTopics(ListTopicsRequest) returns (ListTopicsResponse) { + option (google.api.http) = { + get: "/v1/{project=projects/*}/topics" + }; + } + + // Lists the names of the subscriptions on this topic. + rpc ListTopicSubscriptions(ListTopicSubscriptionsRequest) + returns (ListTopicSubscriptionsResponse) { + option (google.api.http) = { + get: "/v1/{topic=projects/*/topics/*}/subscriptions" + }; + } + + // Lists the names of the snapshots on this topic. Snapshots are used in + // <a href="https://cloud.google.com/pubsub/docs/replay-overview">Seek</a> + // operations, which allow + // you to manage message acknowledgments in bulk. That is, you can set the + // acknowledgment state of messages in an existing subscription to the state + // captured by a snapshot.<br><br> + // <b>BETA:</b> This feature is part of a beta release. This API might be + // changed in backward-incompatible ways and is not recommended for production + // use. It is not subject to any SLA or deprecation policy. + rpc ListTopicSnapshots(ListTopicSnapshotsRequest) + returns (ListTopicSnapshotsResponse) { + option (google.api.http) = { + get: "/v1/{topic=projects/*/topics/*}/snapshots" + }; + } + + // Deletes the topic with the given name. Returns `NOT_FOUND` if the topic + // does not exist. After a topic is deleted, a new topic may be created with + // the same name; this is an entirely new topic with none of the old + // configuration or subscriptions. Existing subscriptions to this topic are + // not deleted, but their `topic` field is set to `_deleted-topic_`. + rpc DeleteTopic(DeleteTopicRequest) returns (google.protobuf.Empty) { + option (google.api.http) = { + delete: "/v1/{topic=projects/*/topics/*}" + }; + } +} + +// The service that an application uses to manipulate subscriptions and to +// consume messages from a subscription via the `Pull` method or by +// establishing a bi-directional stream using the `StreamingPull` method. +service Subscriber { + // Creates a subscription to a given topic. See the + // <a href="https://cloud.google.com/pubsub/docs/admin#resource_names"> + // resource name rules</a>. + // If the subscription already exists, returns `ALREADY_EXISTS`. + // If the corresponding topic doesn't exist, returns `NOT_FOUND`. + // + // If the name is not provided in the request, the server will assign a random + // name for this subscription on the same project as the topic, conforming + // to the + // [resource name + // format](https://cloud.google.com/pubsub/docs/admin#resource_names). The + // generated name is populated in the returned Subscription object. Note that + // for REST API requests, you must specify a name in the request. + rpc CreateSubscription(Subscription) returns (Subscription) { + option (google.api.http) = { + put: "/v1/{name=projects/*/subscriptions/*}" + body: "*" + }; + } + + // Gets the configuration details of a subscription. + rpc GetSubscription(GetSubscriptionRequest) returns (Subscription) { + option (google.api.http) = { + get: "/v1/{subscription=projects/*/subscriptions/*}" + }; + } + + // Updates an existing subscription. Note that certain properties of a + // subscription, such as its topic, are not modifiable. + rpc UpdateSubscription(UpdateSubscriptionRequest) returns (Subscription) { + option (google.api.http) = { + patch: "/v1/{subscription.name=projects/*/subscriptions/*}" + body: "*" + }; + } + + // Lists matching subscriptions. + rpc ListSubscriptions(ListSubscriptionsRequest) + returns (ListSubscriptionsResponse) { + option (google.api.http) = { + get: "/v1/{project=projects/*}/subscriptions" + }; + } + + // Deletes an existing subscription. All messages retained in the subscription + // are immediately dropped. Calls to `Pull` after deletion will return + // `NOT_FOUND`. After a subscription is deleted, a new one may be created with + // the same name, but the new one has no association with the old + // subscription or its topic unless the same topic is specified. + rpc DeleteSubscription(DeleteSubscriptionRequest) + returns (google.protobuf.Empty) { + option (google.api.http) = { + delete: "/v1/{subscription=projects/*/subscriptions/*}" + }; + } + + // Modifies the ack deadline for a specific message. This method is useful + // to indicate that more time is needed to process a message by the + // subscriber, or to make the message available for redelivery if the + // processing was interrupted. Note that this does not modify the + // subscription-level `ackDeadlineSeconds` used for subsequent messages. + rpc ModifyAckDeadline(ModifyAckDeadlineRequest) + returns (google.protobuf.Empty) { + option (google.api.http) = { + post: "/v1/{subscription=projects/*/subscriptions/*}:modifyAckDeadline" + body: "*" + }; + } + + // Acknowledges the messages associated with the `ack_ids` in the + // `AcknowledgeRequest`. The Pub/Sub system can remove the relevant messages + // from the subscription. + // + // Acknowledging a message whose ack deadline has expired may succeed, + // but such a message may be redelivered later. Acknowledging a message more + // than once will not result in an error. + rpc Acknowledge(AcknowledgeRequest) returns (google.protobuf.Empty) { + option (google.api.http) = { + post: "/v1/{subscription=projects/*/subscriptions/*}:acknowledge" + body: "*" + }; + } + + // Pulls messages from the server. The server may return `UNAVAILABLE` if + // there are too many concurrent pull requests pending for the given + // subscription. + rpc Pull(PullRequest) returns (PullResponse) { + option (google.api.http) = { + post: "/v1/{subscription=projects/*/subscriptions/*}:pull" + body: "*" + }; + } + + // Establishes a stream with the server, which sends messages down to the + // client. The client streams acknowledgements and ack deadline modifications + // back to the server. The server will close the stream and return the status + // on any error. The server may close the stream with status `UNAVAILABLE` to + // reassign server-side resources, in which case, the client should + // re-establish the stream. Flow control can be achieved by configuring the + // underlying RPC channel. + rpc StreamingPull(stream StreamingPullRequest) + returns (stream StreamingPullResponse) {} + + // Modifies the `PushConfig` for a specified subscription. + // + // This may be used to change a push subscription to a pull one (signified by + // an empty `PushConfig`) or vice versa, or change the endpoint URL and other + // attributes of a push subscription. Messages will accumulate for delivery + // continuously through the call regardless of changes to the `PushConfig`. + rpc ModifyPushConfig(ModifyPushConfigRequest) + returns (google.protobuf.Empty) { + option (google.api.http) = { + post: "/v1/{subscription=projects/*/subscriptions/*}:modifyPushConfig" + body: "*" + }; + } + + // Gets the configuration details of a snapshot. Snapshots are used in + // <a href="https://cloud.google.com/pubsub/docs/replay-overview">Seek</a> + // operations, which allow you to manage message acknowledgments in bulk. That + // is, you can set the acknowledgment state of messages in an existing + // subscription to the state captured by a snapshot.<br><br> + // <b>BETA:</b> This feature is part of a beta release. This API might be + // changed in backward-incompatible ways and is not recommended for production + // use. It is not subject to any SLA or deprecation policy. + rpc GetSnapshot(GetSnapshotRequest) returns (Snapshot) { + option (google.api.http) = { + get: "/v1/{snapshot=projects/*/snapshots/*}" + }; + } + + // Lists the existing snapshots. Snapshots are used in + // <a href="https://cloud.google.com/pubsub/docs/replay-overview">Seek</a> + // operations, which allow + // you to manage message acknowledgments in bulk. That is, you can set the + // acknowledgment state of messages in an existing subscription to the state + // captured by a snapshot.<br><br> + // <b>BETA:</b> This feature is part of a beta release. This API might be + // changed in backward-incompatible ways and is not recommended for production + // use. It is not subject to any SLA or deprecation policy. + rpc ListSnapshots(ListSnapshotsRequest) returns (ListSnapshotsResponse) { + option (google.api.http) = { + get: "/v1/{project=projects/*}/snapshots" + }; + } + + // Creates a snapshot from the requested subscription. Snapshots are used in + // <a href="https://cloud.google.com/pubsub/docs/replay-overview">Seek</a> + // operations, which allow + // you to manage message acknowledgments in bulk. That is, you can set the + // acknowledgment state of messages in an existing subscription to the state + // captured by a snapshot. + // <br><br> + // <b>BETA:</b> This feature is part of a beta release. This API might be + // changed in backward-incompatible ways and is not recommended for production + // use. It is not subject to any SLA or deprecation policy.<br><br> + // If the snapshot already exists, returns `ALREADY_EXISTS`. + // If the requested subscription doesn't exist, returns `NOT_FOUND`. + // If the backlog in the subscription is too old -- and the resulting snapshot + // would expire in less than 1 hour -- then `FAILED_PRECONDITION` is returned. + // See also the `Snapshot.expire_time` field. If the name is not provided in + // the request, the server will assign a random + // name for this snapshot on the same project as the subscription, conforming + // to the + // [resource name + // format](https://cloud.google.com/pubsub/docs/admin#resource_names). The + // generated name is populated in the returned Snapshot object. Note that for + // REST API requests, you must specify a name in the request. + rpc CreateSnapshot(CreateSnapshotRequest) returns (Snapshot) { + option (google.api.http) = { + put: "/v1/{name=projects/*/snapshots/*}" + body: "*" + }; + } + + // Updates an existing snapshot. Snapshots are used in + // <a href="https://cloud.google.com/pubsub/docs/replay-overview">Seek</a> + // operations, which allow + // you to manage message acknowledgments in bulk. That is, you can set the + // acknowledgment state of messages in an existing subscription to the state + // captured by a snapshot.<br><br> + // <b>BETA:</b> This feature is part of a beta release. This API might be + // changed in backward-incompatible ways and is not recommended for production + // use. It is not subject to any SLA or deprecation policy. + // Note that certain properties of a snapshot are not modifiable. + rpc UpdateSnapshot(UpdateSnapshotRequest) returns (Snapshot) { + option (google.api.http) = { + patch: "/v1/{snapshot.name=projects/*/snapshots/*}" + body: "*" + }; + } + + // Removes an existing snapshot. Snapshots are used in + // <a href="https://cloud.google.com/pubsub/docs/replay-overview">Seek</a> + // operations, which allow + // you to manage message acknowledgments in bulk. That is, you can set the + // acknowledgment state of messages in an existing subscription to the state + // captured by a snapshot.<br><br> + // <b>BETA:</b> This feature is part of a beta release. This API might be + // changed in backward-incompatible ways and is not recommended for production + // use. It is not subject to any SLA or deprecation policy. + // When the snapshot is deleted, all messages retained in the snapshot + // are immediately dropped. After a snapshot is deleted, a new one may be + // created with the same name, but the new one has no association with the old + // snapshot or its subscription, unless the same subscription is specified. + rpc DeleteSnapshot(DeleteSnapshotRequest) returns (google.protobuf.Empty) { + option (google.api.http) = { + delete: "/v1/{snapshot=projects/*/snapshots/*}" + }; + } + + // Seeks an existing subscription to a point in time or to a given snapshot, + // whichever is provided in the request. Snapshots are used in + // <a href="https://cloud.google.com/pubsub/docs/replay-overview">Seek</a> + // operations, which allow + // you to manage message acknowledgments in bulk. That is, you can set the + // acknowledgment state of messages in an existing subscription to the state + // captured by a snapshot. Note that both the subscription and the snapshot + // must be on the same topic.<br><br> + // <b>BETA:</b> This feature is part of a beta release. This API might be + // changed in backward-incompatible ways and is not recommended for production + // use. It is not subject to any SLA or deprecation policy. + rpc Seek(SeekRequest) returns (SeekResponse) { + option (google.api.http) = { + post: "/v1/{subscription=projects/*/subscriptions/*}:seek" + body: "*" + }; + } +} + +message MessageStoragePolicy { + // The list of GCP region IDs where messages that are published to the topic + // may be persisted in storage. Messages published by publishers running in + // non-allowed GCP regions (or running outside of GCP altogether) will be + // routed for storage in one of the allowed regions. An empty list indicates a + // misconfiguration at the project or organization level, which will result in + // all Publish operations failing. + repeated string allowed_persistence_regions = 1; +} + +// A topic resource. +message Topic { + // The name of the topic. It must have the format + // `"projects/{project}/topics/{topic}"`. `{topic}` must start with a letter, + // and contain only letters (`[A-Za-z]`), numbers (`[0-9]`), dashes (`-`), + // underscores (`_`), periods (`.`), tildes (`~`), plus (`+`) or percent + // signs (`%`). It must be between 3 and 255 characters in length, and it + // must not start with `"goog"`. + string name = 1; + + // See <a href="https://cloud.google.com/pubsub/docs/labels"> Creating and + // managing labels</a>. + map<string, string> labels = 2; + + // Policy constraining how messages published to the topic may be stored. It + // is determined when the topic is created based on the policy configured at + // the project level. It must not be set by the caller in the request to + // CreateTopic or to UpdateTopic. This field will be populated in the + // responses for GetTopic, CreateTopic, and UpdateTopic: if not present in the + // response, then no constraints are in effect. + MessageStoragePolicy message_storage_policy = 3; +} + +// A message that is published by publishers and consumed by subscribers. The +// message must contain either a non-empty data field or at least one attribute. +// Note that client libraries represent this object differently +// depending on the language. See the corresponding +// <a href="https://cloud.google.com/pubsub/docs/reference/libraries">client +// library documentation</a> for more information. See +// <a href="https://cloud.google.com/pubsub/quotas">Quotas and limits</a> +// for more information about message limits. +message PubsubMessage { + // The message data field. If this field is empty, the message must contain + // at least one attribute. + bytes data = 1; + + // Optional attributes for this message. + map<string, string> attributes = 2; + + // ID of this message, assigned by the server when the message is published. + // Guaranteed to be unique within the topic. This value may be read by a + // subscriber that receives a `PubsubMessage` via a `Pull` call or a push + // delivery. It must not be populated by the publisher in a `Publish` call. + string message_id = 3; + + // The time at which the message was published, populated by the server when + // it receives the `Publish` call. It must not be populated by the + // publisher in a `Publish` call. + google.protobuf.Timestamp publish_time = 4; + + // Identifies related messages for which publish order should be respected. + // If a `Subscription` has `enable_message_ordering` set to `true`, messages + // published with the same `ordering_key` value will be delivered to + // subscribers in the order in which they are received by the Pub/Sub system. + // <b>EXPERIMENTAL:</b> This feature is part of a closed alpha release. This + // API might be changed in backward-incompatible ways and is not recommended + // for production use. It is not subject to any SLA or deprecation policy. + string ordering_key = 5; +} + +// Request for the GetTopic method. +message GetTopicRequest { + // The name of the topic to get. + // Format is `projects/{project}/topics/{topic}`. + string topic = 1; +} + +// Request for the UpdateTopic method. +message UpdateTopicRequest { + // The updated topic object. + Topic topic = 1; + + // Indicates which fields in the provided topic to update. Must be specified + // and non-empty. Note that if `update_mask` contains + // "message_storage_policy" then the new value will be determined based on the + // policy configured at the project or organization level. The + // `message_storage_policy` must not be set in the `topic` provided above. + google.protobuf.FieldMask update_mask = 2; +} + +// Request for the Publish method. +message PublishRequest { + // The messages in the request will be published on this topic. + // Format is `projects/{project}/topics/{topic}`. + string topic = 1; + + // The messages to publish. + repeated PubsubMessage messages = 2; +} + +// Response for the `Publish` method. +message PublishResponse { + // The server-assigned ID of each published message, in the same order as + // the messages in the request. IDs are guaranteed to be unique within + // the topic. + repeated string message_ids = 1; +} + +// Request for the `ListTopics` method. +message ListTopicsRequest { + // The name of the project in which to list topics. + // Format is `projects/{project-id}`. + string project = 1; + + // Maximum number of topics to return. + int32 page_size = 2; + + // The value returned by the last `ListTopicsResponse`; indicates that this is + // a continuation of a prior `ListTopics` call, and that the system should + // return the next page of data. + string page_token = 3; +} + +// Response for the `ListTopics` method. +message ListTopicsResponse { + // The resulting topics. + repeated Topic topics = 1; + + // If not empty, indicates that there may be more topics that match the + // request; this value should be passed in a new `ListTopicsRequest`. + string next_page_token = 2; +} + +// Request for the `ListTopicSubscriptions` method. +message ListTopicSubscriptionsRequest { + // The name of the topic that subscriptions are attached to. + // Format is `projects/{project}/topics/{topic}`. + string topic = 1; + + // Maximum number of subscription names to return. + int32 page_size = 2; + + // The value returned by the last `ListTopicSubscriptionsResponse`; indicates + // that this is a continuation of a prior `ListTopicSubscriptions` call, and + // that the system should return the next page of data. + string page_token = 3; +} + +// Response for the `ListTopicSubscriptions` method. +message ListTopicSubscriptionsResponse { + // The names of the subscriptions that match the request. + repeated string subscriptions = 1; + + // If not empty, indicates that there may be more subscriptions that match + // the request; this value should be passed in a new + // `ListTopicSubscriptionsRequest` to get more subscriptions. + string next_page_token = 2; +} + +// Request for the `ListTopicSnapshots` method. <br><br> +// <b>BETA:</b> This feature is part of a beta release. This API might be +// changed in backward-incompatible ways and is not recommended for production +// use. It is not subject to any SLA or deprecation policy. +message ListTopicSnapshotsRequest { + // The name of the topic that snapshots are attached to. + // Format is `projects/{project}/topics/{topic}`. + string topic = 1; + + // Maximum number of snapshot names to return. + int32 page_size = 2; + + // The value returned by the last `ListTopicSnapshotsResponse`; indicates + // that this is a continuation of a prior `ListTopicSnapshots` call, and + // that the system should return the next page of data. + string page_token = 3; +} + +// Response for the `ListTopicSnapshots` method.<br><br> +// <b>BETA:</b> This feature is part of a beta release. This API might be +// changed in backward-incompatible ways and is not recommended for production +// use. It is not subject to any SLA or deprecation policy. +message ListTopicSnapshotsResponse { + // The names of the snapshots that match the request. + repeated string snapshots = 1; + + // If not empty, indicates that there may be more snapshots that match + // the request; this value should be passed in a new + // `ListTopicSnapshotsRequest` to get more snapshots. + string next_page_token = 2; +} + +// Request for the `DeleteTopic` method. +message DeleteTopicRequest { + // Name of the topic to delete. + // Format is `projects/{project}/topics/{topic}`. + string topic = 1; +} + +// A subscription resource. +message Subscription { + // The name of the subscription. It must have the format + // `"projects/{project}/subscriptions/{subscription}"`. `{subscription}` must + // start with a letter, and contain only letters (`[A-Za-z]`), numbers + // (`[0-9]`), dashes (`-`), underscores (`_`), periods (`.`), tildes (`~`), + // plus (`+`) or percent signs (`%`). It must be between 3 and 255 characters + // in length, and it must not start with `"goog"`. + string name = 1; + + // The name of the topic from which this subscription is receiving messages. + // Format is `projects/{project}/topics/{topic}`. + // The value of this field will be `_deleted-topic_` if the topic has been + // deleted. + string topic = 2; + + // If push delivery is used with this subscription, this field is + // used to configure it. An empty `pushConfig` signifies that the subscriber + // will pull and ack messages using API methods. + PushConfig push_config = 4; + + // The approximate amount of time (on a best-effort basis) Pub/Sub waits for + // the subscriber to acknowledge receipt before resending the message. In the + // interval after the message is delivered and before it is acknowledged, it + // is considered to be <i>outstanding</i>. During that time period, the + // message will not be redelivered (on a best-effort basis). + // + // For pull subscriptions, this value is used as the initial value for the ack + // deadline. To override this value for a given message, call + // `ModifyAckDeadline` with the corresponding `ack_id` if using + // non-streaming pull or send the `ack_id` in a + // `StreamingModifyAckDeadlineRequest` if using streaming pull. + // The minimum custom deadline you can specify is 10 seconds. + // The maximum custom deadline you can specify is 600 seconds (10 minutes). + // If this parameter is 0, a default value of 10 seconds is used. + // + // For push delivery, this value is also used to set the request timeout for + // the call to the push endpoint. + // + // If the subscriber never acknowledges the message, the Pub/Sub + // system will eventually redeliver the message. + int32 ack_deadline_seconds = 5; + + // Indicates whether to retain acknowledged messages. If true, then + // messages are not expunged from the subscription's backlog, even if they are + // acknowledged, until they fall out of the `message_retention_duration` + // window. This must be true if you would like to + // <a + // href="https://cloud.google.com/pubsub/docs/replay-overview#seek_to_a_time"> + // Seek to a timestamp</a>. + // <br><br> + // <b>BETA:</b> This feature is part of a beta release. This API might be + // changed in backward-incompatible ways and is not recommended for production + // use. It is not subject to any SLA or deprecation policy. + bool retain_acked_messages = 7; + + // How long to retain unacknowledged messages in the subscription's backlog, + // from the moment a message is published. + // If `retain_acked_messages` is true, then this also configures the retention + // of acknowledged messages, and thus configures how far back in time a `Seek` + // can be done. Defaults to 7 days. Cannot be more than 7 days or less than 10 + // minutes.<br><br> + // <b>BETA:</b> This feature is part of a beta release. This API might be + // changed in backward-incompatible ways and is not recommended for production + // use. It is not subject to any SLA or deprecation policy. + google.protobuf.Duration message_retention_duration = 8; + + // See <a href="https://cloud.google.com/pubsub/docs/labels"> Creating and + // managing labels</a>. + map<string, string> labels = 9; + + // If true, messages published with the same `ordering_key` in `PubsubMessage` + // will be delivered to the subscribers in the order in which they + // are received by the Pub/Sub system. Otherwise, they may be delivered in + // any order. + // <b>EXPERIMENTAL:</b> This feature is part of a closed alpha release. This + // API might be changed in backward-incompatible ways and is not recommended + // for production use. It is not subject to any SLA or deprecation policy. + bool enable_message_ordering = 10; + + // A policy that specifies the conditions for this subscription's expiration. + // A subscription is considered active as long as any connected subscriber is + // successfully consuming messages from the subscription or is issuing + // operations on the subscription. If `expiration_policy` is not set, a + // *default policy* with `ttl` of 31 days will be used. The minimum allowed + // value for `expiration_policy.ttl` is 1 day. + // <b>BETA:</b> This feature is part of a beta release. This API might be + // changed in backward-incompatible ways and is not recommended for production + // use. It is not subject to any SLA or deprecation policy. + ExpirationPolicy expiration_policy = 11; +} + +// A policy that specifies the conditions for resource expiration (i.e., +// automatic resource deletion). +message ExpirationPolicy { + // Specifies the "time-to-live" duration for an associated resource. The + // resource expires if it is not active for a period of `ttl`. The definition + // of "activity" depends on the type of the associated resource. The minimum + // and maximum allowed values for `ttl` depend on the type of the associated + // resource, as well. If `ttl` is not set, the associated resource never + // expires. + google.protobuf.Duration ttl = 1; +} + +// Configuration for a push delivery endpoint. +message PushConfig { + // A URL locating the endpoint to which messages should be pushed. + // For example, a Webhook endpoint might use "https://example.com/push". + string push_endpoint = 1; + + // Endpoint configuration attributes. + // + // Every endpoint has a set of API supported attributes that can be used to + // control different aspects of the message delivery. + // + // The currently supported attribute is `x-goog-version`, which you can + // use to change the format of the pushed message. This attribute + // indicates the version of the data expected by the endpoint. This + // controls the shape of the pushed message (i.e., its fields and metadata). + // The endpoint version is based on the version of the Pub/Sub API. + // + // If not present during the `CreateSubscription` call, it will default to + // the version of the API used to make such call. If not present during a + // `ModifyPushConfig` call, its value will not be changed. `GetSubscription` + // calls will always return a valid version, even if the subscription was + // created without this attribute. + // + // The possible values for this attribute are: + // + // * `v1beta1`: uses the push format defined in the v1beta1 Pub/Sub API. + // * `v1` or `v1beta2`: uses the push format defined in the v1 Pub/Sub API. + map<string, string> attributes = 2; + + // An authentication method used by push endpoints to verify the source of + // push requests. This can be used with push endpoints that are private by + // default to allow requests only from the Cloud Pub/Sub system, for example. + // This field is optional and should be set only by users interested in + // authenticated push. + // <b>EXPERIMENTAL:</b> This field a part of a closed alpha that may not be + // accessible to all users. It may be changed in backward-incompatible ways + // and is not subject to any SLA or deprecation policy. It is not recommended + // for production use. + oneof authentication_method { + // If specified, Pub/Sub will generate and attach an OIDC JWT token as an + // `Authorization` header in the HTTP request for every pushed message. + OidcToken oidc_token = 3; + } + + // Contains information needed for generating an + // [OpenID Connect + // token](https://developers.google.com/identity/protocols/OpenIDConnect). + message OidcToken { + // [Service account + // email](https://cloud.google.com/iam/docs/service-accounts) + // to be used for generating the OIDC token. The caller (for + // CreateSubscription, UpdateSubscription, and ModifyPushConfig calls) must + // have the iam.serviceAccounts.actAs permission for the service account. + // See https://cloud.google.com/iam/docs/understanding-roles#service-accounts-roles. + string service_account_email = 1; + + // Audience to be used when generating OIDC token. The audience claim + // identifies the recipients that the JWT is intended for. The audience + // value is a single case-sensitive string. Having multiple values (array) + // for the audience field is not supported. More info about the OIDC JWT + // token audience here: https://tools.ietf.org/html/rfc7519#section-4.1.3 + // Note: if not specified, the Push endpoint URL will be used. + string audience = 2; + } +} + +// A message and its corresponding acknowledgment ID. +message ReceivedMessage { + // This ID can be used to acknowledge the received message. + string ack_id = 1; + + // The message. + PubsubMessage message = 2; +} + +// Request for the GetSubscription method. +message GetSubscriptionRequest { + // The name of the subscription to get. + // Format is `projects/{project}/subscriptions/{sub}`. + string subscription = 1; +} + +// Request for the UpdateSubscription method. +message UpdateSubscriptionRequest { + // The updated subscription object. + Subscription subscription = 1; + + // Indicates which fields in the provided subscription to update. + // Must be specified and non-empty. + google.protobuf.FieldMask update_mask = 2; +} + +// Request for the `ListSubscriptions` method. +message ListSubscriptionsRequest { + // The name of the project in which to list subscriptions. + // Format is `projects/{project-id}`. + string project = 1; + + // Maximum number of subscriptions to return. + int32 page_size = 2; + + // The value returned by the last `ListSubscriptionsResponse`; indicates that + // this is a continuation of a prior `ListSubscriptions` call, and that the + // system should return the next page of data. + string page_token = 3; +} + +// Response for the `ListSubscriptions` method. +message ListSubscriptionsResponse { + // The subscriptions that match the request. + repeated Subscription subscriptions = 1; + + // If not empty, indicates that there may be more subscriptions that match + // the request; this value should be passed in a new + // `ListSubscriptionsRequest` to get more subscriptions. + string next_page_token = 2; +} + +// Request for the DeleteSubscription method. +message DeleteSubscriptionRequest { + // The subscription to delete. + // Format is `projects/{project}/subscriptions/{sub}`. + string subscription = 1; +} + +// Request for the ModifyPushConfig method. +message ModifyPushConfigRequest { + // The name of the subscription. + // Format is `projects/{project}/subscriptions/{sub}`. + string subscription = 1; + + // The push configuration for future deliveries. + // + // An empty `pushConfig` indicates that the Pub/Sub system should + // stop pushing messages from the given subscription and allow + // messages to be pulled and acknowledged - effectively pausing + // the subscription if `Pull` or `StreamingPull` is not called. + PushConfig push_config = 2; +} + +// Request for the `Pull` method. +message PullRequest { + // The subscription from which messages should be pulled. + // Format is `projects/{project}/subscriptions/{sub}`. + string subscription = 1; + + // If this field set to true, the system will respond immediately even if + // it there are no messages available to return in the `Pull` response. + // Otherwise, the system may wait (for a bounded amount of time) until at + // least one message is available, rather than returning no messages. + bool return_immediately = 2; + + // The maximum number of messages returned for this request. The Pub/Sub + // system may return fewer than the number specified. + int32 max_messages = 3; +} + +// Response for the `Pull` method. +message PullResponse { + // Received Pub/Sub messages. The list will be empty if there are no more + // messages available in the backlog. For JSON, the response can be entirely + // empty. The Pub/Sub system may return fewer than the `maxMessages` requested + // even if there are more messages available in the backlog. + repeated ReceivedMessage received_messages = 1; +} + +// Request for the ModifyAckDeadline method. +message ModifyAckDeadlineRequest { + // The name of the subscription. + // Format is `projects/{project}/subscriptions/{sub}`. + string subscription = 1; + + // List of acknowledgment IDs. + repeated string ack_ids = 4; + + // The new ack deadline with respect to the time this request was sent to + // the Pub/Sub system. For example, if the value is 10, the new + // ack deadline will expire 10 seconds after the `ModifyAckDeadline` call + // was made. Specifying zero might immediately make the message available for + // delivery to another subscriber client. This typically results in an + // increase in the rate of message redeliveries (that is, duplicates). + // The minimum deadline you can specify is 0 seconds. + // The maximum deadline you can specify is 600 seconds (10 minutes). + int32 ack_deadline_seconds = 3; +} + +// Request for the Acknowledge method. +message AcknowledgeRequest { + // The subscription whose message is being acknowledged. + // Format is `projects/{project}/subscriptions/{sub}`. + string subscription = 1; + + // The acknowledgment ID for the messages being acknowledged that was returned + // by the Pub/Sub system in the `Pull` response. Must not be empty. + repeated string ack_ids = 2; +} + +// Request for the `StreamingPull` streaming RPC method. This request is used to +// establish the initial stream as well as to stream acknowledgements and ack +// deadline modifications from the client to the server. +message StreamingPullRequest { + // The subscription for which to initialize the new stream. This must be + // provided in the first request on the stream, and must not be set in + // subsequent requests from client to server. + // Format is `projects/{project}/subscriptions/{sub}`. + string subscription = 1; + + // List of acknowledgement IDs for acknowledging previously received messages + // (received on this stream or a different stream). If an ack ID has expired, + // the corresponding message may be redelivered later. Acknowledging a message + // more than once will not result in an error. If the acknowledgement ID is + // malformed, the stream will be aborted with status `INVALID_ARGUMENT`. + repeated string ack_ids = 2; + + // The list of new ack deadlines for the IDs listed in + // `modify_deadline_ack_ids`. The size of this list must be the same as the + // size of `modify_deadline_ack_ids`. If it differs the stream will be aborted + // with `INVALID_ARGUMENT`. Each element in this list is applied to the + // element in the same position in `modify_deadline_ack_ids`. The new ack + // deadline is with respect to the time this request was sent to the Pub/Sub + // system. Must be >= 0. For example, if the value is 10, the new ack deadline + // will expire 10 seconds after this request is received. If the value is 0, + // the message is immediately made available for another streaming or + // non-streaming pull request. If the value is < 0 (an error), the stream will + // be aborted with status `INVALID_ARGUMENT`. + repeated int32 modify_deadline_seconds = 3; + + // List of acknowledgement IDs whose deadline will be modified based on the + // corresponding element in `modify_deadline_seconds`. This field can be used + // to indicate that more time is needed to process a message by the + // subscriber, or to make the message available for redelivery if the + // processing was interrupted. + repeated string modify_deadline_ack_ids = 4; + + // The ack deadline to use for the stream. This must be provided in the + // first request on the stream, but it can also be updated on subsequent + // requests from client to server. The minimum deadline you can specify is 10 + // seconds. The maximum deadline you can specify is 600 seconds (10 minutes). + int32 stream_ack_deadline_seconds = 5; +} + +// Response for the `StreamingPull` method. This response is used to stream +// messages from the server to the client. +message StreamingPullResponse { + // Received Pub/Sub messages. This will not be empty. + repeated ReceivedMessage received_messages = 1; +} + +// Request for the `CreateSnapshot` method.<br><br> +// <b>BETA:</b> This feature is part of a beta release. This API might be +// changed in backward-incompatible ways and is not recommended for production +// use. It is not subject to any SLA or deprecation policy. +message CreateSnapshotRequest { + // Optional user-provided name for this snapshot. + // If the name is not provided in the request, the server will assign a random + // name for this snapshot on the same project as the subscription. + // Note that for REST API requests, you must specify a name. See the + // <a href="https://cloud.google.com/pubsub/docs/admin#resource_names"> + // resource name rules</a>. + // Format is `projects/{project}/snapshots/{snap}`. + string name = 1; + + // The subscription whose backlog the snapshot retains. + // Specifically, the created snapshot is guaranteed to retain: + // (a) The existing backlog on the subscription. More precisely, this is + // defined as the messages in the subscription's backlog that are + // unacknowledged upon the successful completion of the + // `CreateSnapshot` request; as well as: + // (b) Any messages published to the subscription's topic following the + // successful completion of the CreateSnapshot request. + // Format is `projects/{project}/subscriptions/{sub}`. + string subscription = 2; + + // See <a href="https://cloud.google.com/pubsub/docs/labels"> Creating and + // managing labels</a>. + map<string, string> labels = 3; +} + +// Request for the UpdateSnapshot method.<br><br> +// <b>BETA:</b> This feature is part of a beta release. This API might be +// changed in backward-incompatible ways and is not recommended for production +// use. It is not subject to any SLA or deprecation policy. +message UpdateSnapshotRequest { + // The updated snapshot object. + Snapshot snapshot = 1; + + // Indicates which fields in the provided snapshot to update. + // Must be specified and non-empty. + google.protobuf.FieldMask update_mask = 2; +} + +// A snapshot resource. Snapshots are used in +// <a href="https://cloud.google.com/pubsub/docs/replay-overview">Seek</a> +// operations, which allow +// you to manage message acknowledgments in bulk. That is, you can set the +// acknowledgment state of messages in an existing subscription to the state +// captured by a snapshot.<br><br> +// <b>BETA:</b> This feature is part of a beta release. This API might be +// changed in backward-incompatible ways and is not recommended for production +// use. It is not subject to any SLA or deprecation policy. +message Snapshot { + // The name of the snapshot. + string name = 1; + + // The name of the topic from which this snapshot is retaining messages. + string topic = 2; + + // The snapshot is guaranteed to exist up until this time. + // A newly-created snapshot expires no later than 7 days from the time of its + // creation. Its exact lifetime is determined at creation by the existing + // backlog in the source subscription. Specifically, the lifetime of the + // snapshot is `7 days - (age of oldest unacked message in the subscription)`. + // For example, consider a subscription whose oldest unacked message is 3 days + // old. If a snapshot is created from this subscription, the snapshot -- which + // will always capture this 3-day-old backlog as long as the snapshot + // exists -- will expire in 4 days. The service will refuse to create a + // snapshot that would expire in less than 1 hour after creation. + google.protobuf.Timestamp expire_time = 3; + + // See <a href="https://cloud.google.com/pubsub/docs/labels"> Creating and + // managing labels</a>. + map<string, string> labels = 4; +} + +// Request for the GetSnapshot method.<br><br> +// <b>BETA:</b> This feature is part of a beta release. This API might be +// changed in backward-incompatible ways and is not recommended for production +// use. It is not subject to any SLA or deprecation policy. +message GetSnapshotRequest { + // The name of the snapshot to get. + // Format is `projects/{project}/snapshots/{snap}`. + string snapshot = 1; +} + +// Request for the `ListSnapshots` method.<br><br> +// <b>BETA:</b> This feature is part of a beta release. This API might be +// changed in backward-incompatible ways and is not recommended for production +// use. It is not subject to any SLA or deprecation policy. +message ListSnapshotsRequest { + // The name of the project in which to list snapshots. + // Format is `projects/{project-id}`. + string project = 1; + + // Maximum number of snapshots to return. + int32 page_size = 2; + + // The value returned by the last `ListSnapshotsResponse`; indicates that this + // is a continuation of a prior `ListSnapshots` call, and that the system + // should return the next page of data. + string page_token = 3; +} + +// Response for the `ListSnapshots` method.<br><br> +// <b>BETA:</b> This feature is part of a beta release. This API might be +// changed in backward-incompatible ways and is not recommended for production +// use. It is not subject to any SLA or deprecation policy. +message ListSnapshotsResponse { + // The resulting snapshots. + repeated Snapshot snapshots = 1; + + // If not empty, indicates that there may be more snapshot that match the + // request; this value should be passed in a new `ListSnapshotsRequest`. + string next_page_token = 2; +} + +// Request for the `DeleteSnapshot` method.<br><br> +// <b>BETA:</b> This feature is part of a beta release. This API might be +// changed in backward-incompatible ways and is not recommended for production +// use. It is not subject to any SLA or deprecation policy. +message DeleteSnapshotRequest { + // The name of the snapshot to delete. + // Format is `projects/{project}/snapshots/{snap}`. + string snapshot = 1; +} + +// Request for the `Seek` method. <br><br> +// <b>BETA:</b> This feature is part of a beta release. This API might be +// changed in backward-incompatible ways and is not recommended for production +// use. It is not subject to any SLA or deprecation policy. +message SeekRequest { + // The subscription to affect. + string subscription = 1; + + oneof target { + // The time to seek to. + // Messages retained in the subscription that were published before this + // time are marked as acknowledged, and messages retained in the + // subscription that were published after this time are marked as + // unacknowledged. Note that this operation affects only those messages + // retained in the subscription (configured by the combination of + // `message_retention_duration` and `retain_acked_messages`). For example, + // if `time` corresponds to a point before the message retention + // window (or to a point before the system's notion of the subscription + // creation time), only retained messages will be marked as unacknowledged, + // and already-expunged messages will not be restored. + google.protobuf.Timestamp time = 2; + + // The snapshot to seek to. The snapshot's topic must be the same as that of + // the provided subscription. + // Format is `projects/{project}/snapshots/{snap}`. + string snapshot = 3; + } +} + +// Response for the `Seek` method (this response is empty). +message SeekResponse {} |