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.
// EXPERIMENTAL: 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.
ExpirationPolicy expiration_policy = 11;
// A policy that specifies the conditions for dead lettering messages in
// this subscription. If dead_letter_policy is not set, dead lettering
// is disabled.
//
// The Cloud Pub/Sub service account associated with this subscriptions's
// parent project (i.e.,
// service-{project_number}@gcp-sa-pubsub.iam.gserviceaccount.com) must have
// permission to Acknowledge() messages on this subscription.
// EXPERIMENTAL: 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.
DeadLetterPolicy dead_letter_policy = 13;
}
// Dead lettering is done on a best effort basis. The same message might be
// dead lettered multiple times.
//
// If validation on any of the fields fails at subscription creation/updation,
// the create/update subscription request will fail.
message DeadLetterPolicy {
// The name of the topic to which dead letter messages should be published.
// Format is `projects/{project}/topics/{topic}`.The Cloud Pub/Sub service
// account associated with the enclosing subscription's parent project (i.e.,
// service-{project_number}@gcp-sa-pubsub.iam.gserviceaccount.com) must have
// permission to Publish() to this topic.
//
// The operation will fail if the topic does not exist.
// Users should ensure that there is a subscription attached to this topic
// since messages published to a topic with no subscriptions are lost.
string dead_letter_topic = 1;
// The maximum number of delivery attempts for any message. The value must be
// between 5 and 100.
//
// The number of delivery attempts is defined as 1 + (the sum of number of
// NACKs and number of times the acknowledgement deadline has been exceeded
// for the message).
//
// A NACK is any call to ModifyAckDeadline with a 0 deadline. Note that
// client libraries may automatically extend ack_deadlines.
//
// This field will be honored on a best effort basis.
//
// If this parameter is 0, a default value of 5 is used.
int32 max_delivery_attempts = 2;
}
// 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 {
// 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 RPCs) must
// have the iam.serviceAccounts.actAs permission for the service account.
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 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 that can be used to control different
// aspects of the message delivery.
//
// The only 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).
//
// If not present during the `CreateSubscription` call, it will default to
// the version of the Pub/Sub API used to make such call. If not present in 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 only supported values for the `x-goog-version` 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.
//
// For example:
// attributes { "x-goog-version": "v1" }
map 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.
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;
}
}
// 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;
// Delivery attempt counter is 1 + (the sum of number of NACKs and number of
// ack_deadline exceeds) for this message.
//
// A NACK is any call to ModifyAckDeadline with a 0 deadline. An ack_deadline
// exceeds event is whenever a message is not acknowledged within
// ack_deadline. Note that ack_deadline is initially
// Subscription.ackDeadlineSeconds, but may get extended automatically by
// the client library.
//
// The first delivery of a given message will have this value as 1. The value
// is calculated at best effort and is approximate.
//
// If a DeadLetterPolicy is not set on the subscription, this will be 0.
// EXPERIMENTAL: 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.
int32 delivery_attempt = 3;
}
// 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 to return for this request. Must be a
// positive integer. 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.
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
//
// resource name rules.
// 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 Creating and
// managing labels.
map labels = 3;
}
// Request for the UpdateSnapshot method.
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
// Seek
// 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.
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 Creating and
// managing labels.
map labels = 4;
}
// Request for the GetSnapshot method.
message GetSnapshotRequest {
// The name of the snapshot to get.
// Format is `projects/{project}/snapshots/{snap}`.
string snapshot = 1;
}
// Request for the `ListSnapshots` method.
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.
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.
message DeleteSnapshotRequest {
// The name of the snapshot to delete.
// Format is `projects/{project}/snapshots/{snap}`.
string snapshot = 1;
}
// Request for the `Seek` method.
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 {}