diff --git a/.gitignore b/.gitignore index a75287041..65267c8e5 100644 --- a/.gitignore +++ b/.gitignore @@ -1,3 +1,4 @@ OWNERS README.google google/internal +google/protobuf diff --git a/google/datastore/v1beta3/datastore.proto b/google/datastore/v1beta3/datastore.proto index beeb13882..6f6aedb39 100644 --- a/google/datastore/v1beta3/datastore.proto +++ b/google/datastore/v1beta3/datastore.proto @@ -27,7 +27,10 @@ option java_package = "com.google.datastore.v1beta3"; // Each RPC normalizes the partition IDs of the keys in its input entities, // and always returns entities with keys with normalized partition IDs. -// This applies to all keys and entities, including those in values. +// This applies to all keys and entities, including those in values, except keys +// with both an empty path and an empty or unset partition ID. Normalization of +// input keys sets the project ID (if not already set) to the project ID from +// the request. // service Datastore { // Look up entities by key. @@ -65,8 +68,7 @@ service Datastore { // The request for [google.datastore.v1beta3.Datastore.Lookup][google.datastore.v1beta3.Datastore.Lookup]. message LookupRequest { - // Project ID against which to make the request. Not required if the request - // is made over HTTP. + // Project ID against which to make the request. string project_id = 8; // Options for this lookup request. @@ -96,15 +98,13 @@ message LookupResponse { // The request for [google.datastore.v1beta3.Datastore.RunQuery][google.datastore.v1beta3.Datastore.RunQuery]. message RunQueryRequest { - // Project ID against which to make the request. Not required if the request - // is made over HTTP. + // Project ID against which to make the request. string project_id = 8; // Entities are partitioned into subsets, identified by a partition ID. // Queries are scoped to a single partition. // This partition ID is normalized with the standard default context - // partition ID, but all other partition IDs in `RunQueryRequest` are - // normalized with this partition ID as the context partition ID. + // partition ID. PartitionId partition_id = 2; // The options for this query. @@ -131,8 +131,7 @@ message RunQueryResponse { // The request for [google.datastore.v1beta3.Datastore.BeginTransaction][google.datastore.v1beta3.Datastore.BeginTransaction]. message BeginTransactionRequest { - // Project ID against which to make the request. Not required if the request - // is made over HTTP. + // Project ID against which to make the request. string project_id = 8; } @@ -144,8 +143,7 @@ message BeginTransactionResponse { // The request for [google.datastore.v1beta3.Datastore.Rollback][google.datastore.v1beta3.Datastore.Rollback]. message RollbackRequest { - // Project ID against which to make the request. Not required if the request - // is made over HTTP. + // Project ID against which to make the request. string project_id = 8; // The transaction identifier, returned by a call to @@ -173,19 +171,30 @@ message CommitRequest { NON_TRANSACTIONAL = 2; } - // Project ID against which to make the request. Not required if the request - // is made over HTTP. + // Project ID against which to make the request. string project_id = 8; // The type of commit to perform. Defaults to `TRANSACTIONAL`. Mode mode = 5; - // The transaction identifier, returned by a call to - // [google.datastore.v1beta3.Datastore.BeginTransaction][google.datastore.v1beta3.Datastore.BeginTransaction]. // Must be set when mode is `TRANSACTIONAL`. - bytes transaction = 1; + oneof transaction_selector { + // The transaction in which to write. + bytes transaction = 1; + } // The mutations to perform. + // + // When mode is `TRANSACTIONAL`, mutations affecting a single entity are + // applied in order. The following sequences of mutations affecting a single + // entity are not permitted in a single `Commit` request: + // - `insert` followed by `insert` + // - `update` followed by `insert` + // - `upsert` followed by `insert` + // - `delete` followed by `update` + // + // When mode is `NON_TRANSACTIONAL`, no two mutations may affect a single + // entity. repeated Mutation mutations = 6; } @@ -201,8 +210,7 @@ message CommitResponse { // The request for [google.datastore.v1beta3.Datastore.AllocateIds][google.datastore.v1beta3.Datastore.AllocateIds]. message AllocateIdsRequest { - // Project ID against which to make the request. Not required if the request - // is made over HTTP. + // Project ID against which to make the request. string project_id = 8; // A list of keys with incomplete key paths for which to allocate IDs. @@ -275,7 +283,7 @@ message ReadOptions { // Cannot be set to `STRONG` for global queries. ReadConsistency read_consistency = 1; - // The transaction identifier to use. + // The transaction in which to read. bytes transaction = 2; } } diff --git a/google/datastore/v1beta3/entity.proto b/google/datastore/v1beta3/entity.proto index 8406bb86d..12423eb41 100644 --- a/google/datastore/v1beta3/entity.proto +++ b/google/datastore/v1beta3/entity.proto @@ -32,13 +32,17 @@ option java_package = "com.google.datastore.v1beta3"; // A partition ID contains several dimensions: // project ID and namespace ID. // Partition dimensions: -// A dimension may be `""`. -// A dimension must be valid UTF-8 bytes. -// A dimension's value must match regex `[A-Za-z\d\.\-_]{1,100}` +// - A dimension may be `""`. +// - A dimension must be valid UTF-8 bytes. +// - A dimension's value must match regex `[A-Za-z\d\.\-_]{1,100}` // If the value of any dimension matches regex `__.*__`, the partition is // reserved/read-only. // A reserved/read-only partition ID is forbidden in certain documented // contexts. +// +// Foreign partition IDs (in which the project ID does +// not match the context project ID ) are discouraged. +// Reads and writes of foreign partition IDs may fail if the project is not in an active state. message PartitionId { // Project ID. string project_id = 2; @@ -101,6 +105,8 @@ message Key { // An array value. message ArrayValue { // Values in the array. + // The order of this array may not be preserved if it contains a mix of + // indexed and unindexed values. repeated Value values = 1; } @@ -139,6 +145,7 @@ message Value { // A blob value. // May have at most 1,000,000 bytes. // When `exclude_from_indexes` is false, may have at most 1500 bytes. + // In JSON requests, must be base64-encoded. bytes blob_value = 18; // A geo point value representing a point on the surface of Earth. diff --git a/google/datastore/v1beta3/query.proto b/google/datastore/v1beta3/query.proto index b95ff63e3..80cbb2045 100644 --- a/google/datastore/v1beta3/query.proto +++ b/google/datastore/v1beta3/query.proto @@ -247,7 +247,7 @@ message QueryResultBatch { // Unspecified. This value is never used. MORE_RESULTS_TYPE_UNSPECIFIED = 0; - // There are additional batches to fetch from this query. + // There may be additional batches to fetch from this query. NOT_FINISHED = 1; // The query is finished, but there may be more results after the limit. diff --git a/google/pubsub/v1/pubsub.proto b/google/pubsub/v1/pubsub.proto index d3a28a20b..e2a2509e7 100644 --- a/google/pubsub/v1/pubsub.proto +++ b/google/pubsub/v1/pubsub.proto @@ -18,6 +18,7 @@ package google.pubsub.v1; import "google/api/annotations.proto"; import "google/protobuf/empty.proto"; +import "google/protobuf/timestamp.proto"; option java_multiple_files = true; option java_outer_classname = "PubsubProto"; @@ -25,11 +26,11 @@ option java_package = "com.google.pubsub.v1"; // The service that an application uses to manipulate subscriptions and to -// consume messages from a subscription via the Pull method. +// consume messages from a subscription via the `Pull` method. service Subscriber { // Creates a subscription to a given topic for a given subscriber. - // If the subscription already exists, returns ALREADY_EXISTS. - // If the corresponding topic doesn't exist, returns NOT_FOUND. + // 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. @@ -48,24 +49,24 @@ service Subscriber { } // Deletes an existing subscription. All pending messages 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 + // 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. + // 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. 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 tokens in the - // AcknowledgeRequest. The Pub/Sub system can remove the relevant messages + // 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, @@ -76,20 +77,19 @@ service Subscriber { } // Pulls messages from the server. Returns an empty list if there are no - // messages available in the backlog. The server may return UNAVAILABLE if + // messages available in the backlog. 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: "*" }; } - // Modifies the PushConfig for a specified subscription. + // 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. + // 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: "*" }; } @@ -103,9 +103,9 @@ service Publisher { option (google.api.http) = { put: "/v1/{name=projects/*/topics/*}" body: "*" }; } - // Adds one or more messages to the topic. Returns NOT_FOUND if the topic does - // not exist. The message payload must not be empty; it must contain either a - // non-empty data field, or at least one attribute. + // Adds one or more messages to the topic. Returns `NOT_FOUND` if the topic + // does not exist. The message payload must not be empty; it must contain + // either a non-empty data field, or at least one attribute. rpc Publish(PublishRequest) returns (PublishResponse) { option (google.api.http) = { post: "/v1/{topic=projects/*/topics/*}:publish" body: "*" }; } @@ -125,9 +125,9 @@ service Publisher { option (google.api.http) = { get: "/v1/{topic=projects/*/topics/*}/subscriptions" }; } - // 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 + // 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) { @@ -156,11 +156,16 @@ message PubsubMessage { // Optional attributes for this message. map attributes = 2; - // ID of this message assigned by the server at publication time. 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 a publisher in a Publish call. + // 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; } // Request for the GetTopic method. @@ -178,7 +183,7 @@ message PublishRequest { repeated PubsubMessage messages = 2; } -// Response for the Publish method. +// 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 @@ -186,7 +191,7 @@ message PublishResponse { repeated string message_ids = 1; } -// Request for the ListTopics method. +// Request for the `ListTopics` method. message ListTopicsRequest { // The name of the cloud project that topics belong to. string project = 1; @@ -194,23 +199,23 @@ message ListTopicsRequest { // 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 + // 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. +// 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. + // request; this value should be passed in a new `ListTopicsRequest`. string next_page_token = 2; } -// Request for the ListTopicSubscriptions method. +// Request for the `ListTopicSubscriptions` method. message ListTopicSubscriptionsRequest { // The name of the topic that subscriptions are attached to. string topic = 1; @@ -218,24 +223,24 @@ message ListTopicSubscriptionsRequest { // 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 + // 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. +// 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. + // `ListTopicSubscriptionsRequest` to get more subscriptions. string next_page_token = 2; } -// Request for the DeleteTopic method. +// Request for the `DeleteTopic` method. message DeleteTopicRequest { // Name of the topic to delete. string topic = 1; @@ -257,7 +262,7 @@ message Subscription { 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 + // used to configure it. An empty `pushConfig` signifies that the subscriber // will pull and ack messages using API methods. PushConfig push_config = 4; @@ -267,9 +272,10 @@ message Subscription { // acknowledged, it is an outstanding message and will not be delivered // again during that time (on a best-effort basis). // - // For pull delivery this value is used as the initial value for the ack + // 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. + // `ModifyAckDeadline` with the corresponding `ack_id` if using + // pull. // // For push delivery, this value is also used to set the request timeout for // the call to the push endpoint. @@ -299,9 +305,9 @@ message PushConfig { // The endpoint version is based on the version of the Pub/Sub // API. // - // If not present during the CreateSubscription call, it will default to + // 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 + // `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. // @@ -327,7 +333,7 @@ message GetSubscriptionRequest { string subscription = 1; } -// Request for the ListSubscriptions method. +// Request for the `ListSubscriptions` method. message ListSubscriptionsRequest { // The name of the cloud project that subscriptions belong to. string project = 1; @@ -335,20 +341,20 @@ message ListSubscriptionsRequest { // 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 + // 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. +// 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. + // the request; this value should be passed in a new + // `ListSubscriptionsRequest` to get more subscriptions. string next_page_token = 2; } @@ -365,20 +371,20 @@ message ModifyPushConfigRequest { // The push configuration for future deliveries. // - // An empty pushConfig indicates that the Pub/Sub system should + // 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 is not called. + // the subscription if `Pull` is not called. PushConfig push_config = 2; } -// Request for the Pull method. +// Request for the `Pull` method. message PullRequest { // The subscription from which messages should be pulled. string subscription = 1; // If this is specified as true the system will respond immediately even if - // it is not able to return a message in the Pull response. Otherwise the + // it is not able to return a message in the `Pull` response. Otherwise the // system is allowed to wait until at least one message is available rather // than returning no messages. The client may cancel the request if it does // not wish to wait any longer for the response. @@ -389,11 +395,11 @@ message PullRequest { int32 max_messages = 3; } -// Response for the Pull method. +// Response for the `Pull` method. message PullResponse { // Received Pub/Sub messages. The Pub/Sub system will return zero messages if // there are no more available in the backlog. The Pub/Sub system may return - // fewer than the maxMessages requested even if there are more messages + // fewer than the `maxMessages` requested even if there are more messages // available in the backlog. repeated ReceivedMessage received_messages = 1; } @@ -406,11 +412,11 @@ message ModifyAckDeadlineRequest { // 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. Must be >= 0. For example, if the value is 10, the new ack - // deadline will expire 10 seconds after the ModifyAckDeadline call was made. - // Specifying zero may immediately make the message available for another pull - // request. + // The new ack deadline 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 the `ModifyAckDeadline` call + // was made. Specifying zero may immediately make the message available for + // another pull request. int32 ack_deadline_seconds = 3; } @@ -420,6 +426,6 @@ message AcknowledgeRequest { 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. + // by the Pub/Sub system in the `Pull` response. Must not be empty. repeated string ack_ids = 2; }