diff --git a/packages/logging/src/v2/doc/doc_google_api_label.js b/packages/logging/src/v2/doc/doc_google_api_label.js new file mode 100644 index 00000000000..64701d613ac --- /dev/null +++ b/packages/logging/src/v2/doc/doc_google_api_label.js @@ -0,0 +1,38 @@ +/* + * Copyright 2017, Google Inc. All rights reserved. + * + * 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. + */ + +/* + * Note: this file is purely for documentation. Any contents are not expected + * to be loaded as the JS file. + */ + +/** + * A description of a label. + * + * @external "google.api.LabelDescriptor" + * @property {string} key + * The label key. + * + * @property {number} valueType + * The type of data that can be assigned to the label. + * + * The number should be among the values of [google.api.LabelDescriptor.ValueType]{@link external:"google.api.LabelDescriptor.ValueType"} + * + * @property {string} description + * A human-readable description for the label. + * + * @see [google.api.LabelDescriptor definition in proto format]{@link https://github.com/googleapis/googleapis/blob/master/google/api/label.proto} + */ \ No newline at end of file diff --git a/packages/logging/src/v2/doc/doc_google_api_monitored_resource.js b/packages/logging/src/v2/doc/doc_google_api_monitored_resource.js new file mode 100644 index 00000000000..bb2c3107f8f --- /dev/null +++ b/packages/logging/src/v2/doc/doc_google_api_monitored_resource.js @@ -0,0 +1,94 @@ +/* + * Copyright 2017, Google Inc. All rights reserved. + * + * 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. + */ + +/* + * Note: this file is purely for documentation. Any contents are not expected + * to be loaded as the JS file. + */ + +/** + * An object that describes the schema of a {@link MonitoredResource} object using a + * type name and a set of labels. For example, the monitored resource + * descriptor for Google Compute Engine VM instances has a type of + * `"gce_instance"` and specifies the use of the labels `"instance_id"` and + * `"zone"` to identify particular VM instances. + * + * Different APIs can support different monitored resource types. APIs generally + * provide a `list` method that returns the monitored resource descriptors used + * by the API. + * + * @external "google.api.MonitoredResourceDescriptor" + * @property {string} name + * Optional. The resource name of the monitored resource descriptor: + * `"projects/{project_id}/monitoredResourceDescriptors/{type}"` where + * {type} is the value of the `type` field in this object and + * {project_id} is a project ID that provides API-specific context for + * accessing the type. APIs that do not use project information can use the + * resource name format `"monitoredResourceDescriptors/{type}"`. + * + * @property {string} type + * Required. The monitored resource type. For example, the type + * `"cloudsql_database"` represents databases in Google Cloud SQL. + * The maximum length of this value is 256 characters. + * + * @property {string} displayName + * Optional. A concise name for the monitored resource type that might be + * displayed in user interfaces. It should be a Title Cased Noun Phrase, + * without any article or other determiners. For example, + * `"Google Cloud SQL Database"`. + * + * @property {string} description + * Optional. A detailed description of the monitored resource type that might + * be used in documentation. + * + * @property {Object[]} labels + * Required. A set of labels used to describe instances of this monitored + * resource type. For example, an individual Google Cloud SQL database is + * identified by values for the labels `"database_id"` and `"zone"`. + * + * This object should have the same structure as [google.api.LabelDescriptor]{@link external:"google.api.LabelDescriptor"} + * + * @see [google.api.MonitoredResourceDescriptor definition in proto format]{@link https://github.com/googleapis/googleapis/blob/master/google/api/monitored_resource.proto} + */ + +/** + * An object representing a resource that can be used for monitoring, logging, + * billing, or other purposes. Examples include virtual machine instances, + * databases, and storage devices such as disks. The `type` field identifies a + * {@link MonitoredResourceDescriptor} object that describes the resource's + * schema. Information in the `labels` field identifies the actual resource and + * its attributes according to the schema. For example, a particular Compute + * Engine VM instance could be represented by the following object, because the + * {@link MonitoredResourceDescriptor} for `"gce_instance"` has labels + * `"instance_id"` and `"zone"`: + * + * { "type": "gce_instance", + * "labels": { "instance_id": "12345678901234", + * "zone": "us-central1-a" }} + * + * @external "google.api.MonitoredResource" + * @property {string} type + * Required. The monitored resource type. This field must match + * the `type` field of a {@link MonitoredResourceDescriptor} object. For + * example, the type of a Cloud SQL database is `"cloudsql_database"`. + * + * @property {Object.} labels + * Required. Values for all of the labels listed in the associated monitored + * resource descriptor. For example, Cloud SQL databases use the labels + * `"database_id"` and `"zone"`. + * + * @see [google.api.MonitoredResource definition in proto format]{@link https://github.com/googleapis/googleapis/blob/master/google/api/monitored_resource.proto} + */ \ No newline at end of file diff --git a/packages/logging/src/v2/doc/doc_google_logging_type_http_request.js b/packages/logging/src/v2/doc/doc_google_logging_type_http_request.js new file mode 100644 index 00000000000..c424c34a7cd --- /dev/null +++ b/packages/logging/src/v2/doc/doc_google_logging_type_http_request.js @@ -0,0 +1,87 @@ +/* + * Copyright 2017, Google Inc. All rights reserved. + * + * 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. + */ + +/* + * Note: this file is purely for documentation. Any contents are not expected + * to be loaded as the JS file. + */ + +/** + * A common proto for logging HTTP requests. Only contains semantics + * defined by the HTTP specification. Product-specific logging + * information MUST be defined in a separate message. + * + * @external "google.logging.type.HttpRequest" + * @property {string} requestMethod + * The request method. Examples: `"GET"`, `"HEAD"`, `"PUT"`, `"POST"`. + * + * @property {string} requestUrl + * The scheme (http, https), the host name, the path and the query + * portion of the URL that was requested. + * Example: `"http://example.com/some/info?color=red"`. + * + * @property {number} requestSize + * The size of the HTTP request message in bytes, including the request + * headers and the request body. + * + * @property {number} status + * The response code indicating the status of response. + * Examples: 200, 404. + * + * @property {number} responseSize + * The size of the HTTP response message sent back to the client, in bytes, + * including the response headers and the response body. + * + * @property {string} userAgent + * The user agent sent by the client. Example: + * `"Mozilla/4.0 (compatible; MSIE 6.0; Windows 98; Q312461; .NET CLR 1.0.3705)"`. + * + * @property {string} remoteIp + * The IP address (IPv4 or IPv6) of the client that issued the HTTP + * request. Examples: `"192.168.1.1"`, `"FE80::0202:B3FF:FE1E:8329"`. + * + * @property {string} serverIp + * The IP address (IPv4 or IPv6) of the origin server that the request was + * sent to. + * + * @property {string} referer + * The referer URL of the request, as defined in + * [HTTP/1.1 Header Field Definitions](http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html). + * + * @property {Object} latency + * The request processing latency on the server, from the time the request was + * received until the response was sent. + * + * This object should have the same structure as [google.protobuf.Duration]{@link external:"google.protobuf.Duration"} + * + * @property {boolean} cacheLookup + * Whether or not a cache lookup was attempted. + * + * @property {boolean} cacheHit + * Whether or not an entity was served from cache + * (with or without validation). + * + * @property {boolean} cacheValidatedWithOriginServer + * Whether or not the response was validated with the origin server before + * being served from cache. This field is only meaningful if `cache_hit` is + * True. + * + * @property {number} cacheFillBytes + * The number of HTTP response bytes inserted into cache. Set only when a + * cache fill was attempted. + * + * @see [google.logging.type.HttpRequest definition in proto format]{@link https://github.com/googleapis/googleapis/blob/master/google/logging/type/http_request.proto} + */ \ No newline at end of file diff --git a/packages/logging/src/v2/doc/doc_google_protobuf_any.js b/packages/logging/src/v2/doc/doc_google_protobuf_any.js new file mode 100644 index 00000000000..0697ec15814 --- /dev/null +++ b/packages/logging/src/v2/doc/doc_google_protobuf_any.js @@ -0,0 +1,121 @@ +/* + * Copyright 2017, Google Inc. All rights reserved. + * + * 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. + */ + +/* + * Note: this file is purely for documentation. Any contents are not expected + * to be loaded as the JS file. + */ + +/** + * `Any` contains an arbitrary serialized protocol buffer message along with a + * URL that describes the type of the serialized message. + * + * Protobuf library provides support to pack/unpack Any values in the form + * of utility functions or additional generated methods of the Any type. + * + * Example 1: Pack and unpack a message in C++. + * + * Foo foo = ...; + * Any any; + * any.PackFrom(foo); + * ... + * if (any.UnpackTo(&foo)) { + * ... + * } + * + * Example 2: Pack and unpack a message in Java. + * + * Foo foo = ...; + * Any any = Any.pack(foo); + * ... + * if (any.is(Foo.class)) { + * foo = any.unpack(Foo.class); + * } + * + * Example 3: Pack and unpack a message in Python. + * + * foo = Foo(...) + * any = Any() + * any.Pack(foo) + * ... + * if any.Is(Foo.DESCRIPTOR): + * any.Unpack(foo) + * ... + * + * The pack methods provided by protobuf library will by default use + * 'type.googleapis.com/full.type.name' as the type URL and the unpack + * methods only use the fully qualified type name after the last '/' + * in the type URL, for example "foo.bar.com/x/y.z" will yield type + * name "y.z". + * + * + * # JSON + * + * The JSON representation of an `Any` value uses the regular + * representation of the deserialized, embedded message, with an + * additional field `@type` which contains the type URL. Example: + * + * package google.profile; + * message Person { + * string first_name = 1; + * string last_name = 2; + * } + * + * { + * "@type": "type.googleapis.com/google.profile.Person", + * "firstName": , + * "lastName": + * } + * + * If the embedded message type is well-known and has a custom JSON + * representation, that representation will be embedded adding a field + * `value` which holds the custom JSON in addition to the `@type` + * field. Example (for message {@link google.protobuf.Duration}): + * + * { + * "@type": "type.googleapis.com/google.protobuf.Duration", + * "value": "1.212s" + * } + * + * @external "google.protobuf.Any" + * @property {string} typeUrl + * A URL/resource name whose content describes the type of the + * serialized protocol buffer message. + * + * For URLs which use the scheme `http`, `https`, or no scheme, the + * following restrictions and interpretations apply: + * + * * If no scheme is provided, `https` is assumed. + * * The last segment of the URL's path must represent the fully + * qualified name of the type (as in `path/google.protobuf.Duration`). + * The name should be in a canonical form (e.g., leading "." is + * not accepted). + * * An HTTP GET on the URL must yield a {@link google.protobuf.Type} + * value in binary format, or produce an error. + * * Applications are allowed to cache lookup results based on the + * URL, or have them precompiled into a binary to avoid any + * lookup. Therefore, binary compatibility needs to be preserved + * on changes to types. (Use versioned type names to manage + * breaking changes.) + * + * Schemes other than `http`, `https` (or the empty scheme) might be + * used with implementation specific semantics. + * + * @property {string} value + * Must be a valid serialized protocol buffer of the above specified type. + * + * @see [google.protobuf.Any definition in proto format]{@link https://github.com/google/protobuf/blob/master/src/google/protobuf/any.proto} + */ \ No newline at end of file diff --git a/packages/logging/src/v2/doc/doc_google_protobuf_duration.js b/packages/logging/src/v2/doc/doc_google_protobuf_duration.js new file mode 100644 index 00000000000..b81fd71f130 --- /dev/null +++ b/packages/logging/src/v2/doc/doc_google_protobuf_duration.js @@ -0,0 +1,84 @@ +/* + * Copyright 2017, Google Inc. All rights reserved. + * + * 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. + */ + +/* + * Note: this file is purely for documentation. Any contents are not expected + * to be loaded as the JS file. + */ + +/** + * A Duration represents a signed, fixed-length span of time represented + * as a count of seconds and fractions of seconds at nanosecond + * resolution. It is independent of any calendar and concepts like "day" + * or "month". It is related to Timestamp in that the difference between + * two Timestamp values is a Duration and it can be added or subtracted + * from a Timestamp. Range is approximately +-10,000 years. + * + * Example 1: Compute Duration from two Timestamps in pseudo code. + * + * Timestamp start = ...; + * Timestamp end = ...; + * Duration duration = ...; + * + * duration.seconds = end.seconds - start.seconds; + * duration.nanos = end.nanos - start.nanos; + * + * if (duration.seconds < 0 && duration.nanos > 0) { + * duration.seconds += 1; + * duration.nanos -= 1000000000; + * } else if (durations.seconds > 0 && duration.nanos < 0) { + * duration.seconds -= 1; + * duration.nanos += 1000000000; + * } + * + * Example 2: Compute Timestamp from Timestamp + Duration in pseudo code. + * + * Timestamp start = ...; + * Duration duration = ...; + * Timestamp end = ...; + * + * end.seconds = start.seconds + duration.seconds; + * end.nanos = start.nanos + duration.nanos; + * + * if (end.nanos < 0) { + * end.seconds -= 1; + * end.nanos += 1000000000; + * } else if (end.nanos >= 1000000000) { + * end.seconds += 1; + * end.nanos -= 1000000000; + * } + * + * Example 3: Compute Duration from datetime.timedelta in Python. + * + * td = datetime.timedelta(days=3, minutes=10) + * duration = Duration() + * duration.FromTimedelta(td) + * + * @external "google.protobuf.Duration" + * @property {number} seconds + * Signed seconds of the span of time. Must be from -315,576,000,000 + * to +315,576,000,000 inclusive. + * + * @property {number} nanos + * Signed fractions of a second at nanosecond resolution of the span + * of time. Durations less than one second are represented with a 0 + * `seconds` field and a positive or negative `nanos` field. For durations + * of one second or more, a non-zero value for the `nanos` field must be + * of the same sign as the `seconds` field. Must be from -999,999,999 + * to +999,999,999 inclusive. + * + * @see [google.protobuf.Duration definition in proto format]{@link https://github.com/google/protobuf/blob/master/src/google/protobuf/duration.proto} + */ \ No newline at end of file diff --git a/packages/logging/src/v2/doc/doc_google_protobuf_timestamp.js b/packages/logging/src/v2/doc/doc_google_protobuf_timestamp.js new file mode 100644 index 00000000000..ed8fc627b92 --- /dev/null +++ b/packages/logging/src/v2/doc/doc_google_protobuf_timestamp.js @@ -0,0 +1,88 @@ +/* + * Copyright 2017, Google Inc. All rights reserved. + * + * 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. + */ + +/* + * Note: this file is purely for documentation. Any contents are not expected + * to be loaded as the JS file. + */ + +/** + * A Timestamp represents a point in time independent of any time zone + * or calendar, represented as seconds and fractions of seconds at + * nanosecond resolution in UTC Epoch time. It is encoded using the + * Proleptic Gregorian Calendar which extends the Gregorian calendar + * backwards to year one. It is encoded assuming all minutes are 60 + * seconds long, i.e. leap seconds are "smeared" so that no leap second + * table is needed for interpretation. Range is from + * 0001-01-01T00:00:00Z to 9999-12-31T23:59:59.999999999Z. + * By restricting to that range, we ensure that we can convert to + * and from RFC 3339 date strings. + * See [https://www.ietf.org/rfc/rfc3339.txt](https://www.ietf.org/rfc/rfc3339.txt). + * + * Example 1: Compute Timestamp from POSIX `time()`. + * + * Timestamp timestamp; + * timestamp.set_seconds(time(NULL)); + * timestamp.set_nanos(0); + * + * Example 2: Compute Timestamp from POSIX `gettimeofday()`. + * + * struct timeval tv; + * gettimeofday(&tv, NULL); + * + * Timestamp timestamp; + * timestamp.set_seconds(tv.tv_sec); + * timestamp.set_nanos(tv.tv_usec * 1000); + * + * Example 3: Compute Timestamp from Win32 `GetSystemTimeAsFileTime()`. + * + * FILETIME ft; + * GetSystemTimeAsFileTime(&ft); + * UINT64 ticks = (((UINT64)ft.dwHighDateTime) << 32) | ft.dwLowDateTime; + * + * // A Windows tick is 100 nanoseconds. Windows epoch 1601-01-01T00:00:00Z + * // is 11644473600 seconds before Unix epoch 1970-01-01T00:00:00Z. + * Timestamp timestamp; + * timestamp.set_seconds((INT64) ((ticks / 10000000) - 11644473600LL)); + * timestamp.set_nanos((INT32) ((ticks % 10000000) * 100)); + * + * Example 4: Compute Timestamp from Java `System.currentTimeMillis()`. + * + * long millis = System.currentTimeMillis(); + * + * Timestamp timestamp = Timestamp.newBuilder().setSeconds(millis / 1000) + * .setNanos((int) ((millis % 1000) * 1000000)).build(); + * + * + * Example 5: Compute Timestamp from current time in Python. + * + * timestamp = Timestamp() + * timestamp.GetCurrentTime() + * + * @external "google.protobuf.Timestamp" + * @property {number} seconds + * Represents seconds of UTC time since Unix epoch + * 1970-01-01T00:00:00Z. Must be from 0001-01-01T00:00:00Z to + * 9999-12-31T23:59:59Z inclusive. + * + * @property {number} nanos + * Non-negative fractions of a second at nanosecond resolution. Negative + * second values with fractions must still have non-negative nanos values + * that count forward in time. Must be from 0 to 999,999,999 + * inclusive. + * + * @see [google.protobuf.Timestamp definition in proto format]{@link https://github.com/google/protobuf/blob/master/src/google/protobuf/timestamp.proto} + */ \ No newline at end of file diff --git a/packages/logging/src/v2/doc/doc_log_entry.js b/packages/logging/src/v2/doc/doc_log_entry.js new file mode 100644 index 00000000000..194223b50f2 --- /dev/null +++ b/packages/logging/src/v2/doc/doc_log_entry.js @@ -0,0 +1,183 @@ +/* + * Copyright 2017, Google Inc. All rights reserved. + * + * 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. + */ + +/* + * Note: this file is purely for documentation. Any contents are not expected + * to be loaded as the JS file. + */ + +/** + * An individual entry in a log. + * + * @property {string} logName + * Required. The resource name of the log to which this log entry belongs: + * + * "projects/[PROJECT_ID]/logs/[LOG_ID]" + * "organizations/[ORGANIZATION_ID]/logs/[LOG_ID]" + * "billingAccounts/[BILLING_ACCOUNT_ID]/logs/[LOG_ID]" + * "folders/[FOLDER_ID]/logs/[LOG_ID]" + * + * `[LOG_ID]` must be URL-encoded within `log_name`. Example: + * `"organizations/1234567890/logs/cloudresourcemanager.googleapis.com%2Factivity"`. + * `[LOG_ID]` must be less than 512 characters long and can only include the + * following characters: upper and lower case alphanumeric characters, + * forward-slash, underscore, hyphen, and period. + * + * For backward compatibility, if `log_name` begins with a forward-slash, such + * as `/projects/...`, then the log entry is ingested as usual but the + * forward-slash is removed. Listing the log entry will not show the leading + * slash and filtering for a log name with a leading slash will never return + * any results. + * + * @property {Object} resource + * Required. The monitored resource associated with this log entry. + * Example: a log entry that reports a database error would be + * associated with the monitored resource designating the particular + * database that reported the error. + * + * This object should have the same structure as [google.api.MonitoredResource]{@link external:"google.api.MonitoredResource"} + * + * @property {Object} protoPayload + * The log entry payload, represented as a protocol buffer. Some + * Google Cloud Platform services use this field for their log + * entry payloads. + * + * This object should have the same structure as [google.protobuf.Any]{@link external:"google.protobuf.Any"} + * + * @property {string} textPayload + * The log entry payload, represented as a Unicode string (UTF-8). + * + * @property {Object} jsonPayload + * The log entry payload, represented as a structure that is + * expressed as a JSON object. + * + * This object should have the same structure as [google.protobuf.Struct]{@link external:"google.protobuf.Struct"} + * + * @property {Object} timestamp + * Optional. The time the event described by the log entry occurred. If + * omitted in a new log entry, Stackdriver Logging will insert the time the + * log entry is received. Stackdriver Logging might reject log entries whose + * time stamps are more than a couple of hours in the future. Log entries + * with time stamps in the past are accepted. + * + * This object should have the same structure as [google.protobuf.Timestamp]{@link external:"google.protobuf.Timestamp"} + * + * @property {Object} receiveTimestamp + * Output only. The time the log entry was received by Stackdriver Logging. + * + * This object should have the same structure as [google.protobuf.Timestamp]{@link external:"google.protobuf.Timestamp"} + * + * @property {number} severity + * Optional. The severity of the log entry. The default value is + * `LogSeverity.DEFAULT`. + * + * The number should be among the values of [google.logging.type.LogSeverity]{@link external:"google.logging.type.LogSeverity"} + * + * @property {string} insertId + * Optional. A unique identifier for the log entry. If you provide a value, + * then Stackdriver Logging considers other log entries in the same project, + * with the same `timestamp`, and with the same `insert_id` to be duplicates + * which can be removed. If omitted in new log entries, then Stackdriver + * Logging will insert its own unique identifier. The `insert_id` is used + * to order log entries that have the same `timestamp` value. + * + * @property {Object} httpRequest + * Optional. Information about the HTTP request associated with this + * log entry, if applicable. + * + * This object should have the same structure as [google.logging.type.HttpRequest]{@link external:"google.logging.type.HttpRequest"} + * + * @property {Object.} labels + * Optional. A set of user-defined (key, value) data that provides additional + * information about the log entry. + * + * @property {Object} operation + * Optional. Information about an operation associated with the log entry, if + * applicable. + * + * This object should have the same structure as [LogEntryOperation]{@link LogEntryOperation} + * + * @property {string} trace + * Optional. Resource name of the trace associated with the log entry, if any. + * If it contains a relative resource name, the name is assumed to be relative + * to `//tracing.googleapis.com`. Example: + * `projects/my-projectid/traces/06796866738c859f2f19b7cfb3214824` + * + * @property {Object} sourceLocation + * Optional. Source code location information associated with the log entry, + * if any. + * + * This object should have the same structure as [LogEntrySourceLocation]{@link LogEntrySourceLocation} + * + * @class + * @see [google.logging.v2.LogEntry definition in proto format]{@link https://github.com/googleapis/googleapis/blob/master/google/logging/v2/log_entry.proto} + */ +var LogEntry = { + // This is for documentation. Actual contents will be loaded by gRPC. +}; + +/** + * Additional information about a potentially long-running operation with which + * a log entry is associated. + * + * @property {string} id + * Optional. An arbitrary operation identifier. Log entries with the + * same identifier are assumed to be part of the same operation. + * + * @property {string} producer + * Optional. An arbitrary producer identifier. The combination of + * `id` and `producer` must be globally unique. Examples for `producer`: + * `"MyDivision.MyBigCompany.com"`, `"github.com/MyProject/MyApplication"`. + * + * @property {boolean} first + * Optional. Set this to True if this is the first log entry in the operation. + * + * @property {boolean} last + * Optional. Set this to True if this is the last log entry in the operation. + * + * @class + * @see [google.logging.v2.LogEntryOperation definition in proto format]{@link https://github.com/googleapis/googleapis/blob/master/google/logging/v2/log_entry.proto} + */ +var LogEntryOperation = { + // This is for documentation. Actual contents will be loaded by gRPC. +}; + +/** + * Additional information about the source code location that produced the log + * entry. + * + * @property {string} file + * Optional. Source file name. Depending on the runtime environment, this + * might be a simple name or a fully-qualified name. + * + * @property {number} line + * Optional. Line within the source file. 1-based; 0 indicates no line number + * available. + * + * @property {string} function + * Optional. Human-readable name of the function or method being invoked, with + * optional context such as the class or package name. This information may be + * used in contexts such as the logs viewer, where a file and line number are + * less meaningful. The format can vary by language. For example: + * `qual.if.ied.Class.method` (Java), `dir/package.func` (Go), `function` + * (Python). + * + * @class + * @see [google.logging.v2.LogEntrySourceLocation definition in proto format]{@link https://github.com/googleapis/googleapis/blob/master/google/logging/v2/log_entry.proto} + */ +var LogEntrySourceLocation = { + // This is for documentation. Actual contents will be loaded by gRPC. +}; \ No newline at end of file diff --git a/packages/logging/src/v2/doc/doc_logging.js b/packages/logging/src/v2/doc/doc_logging.js new file mode 100644 index 00000000000..a74b92ed98b --- /dev/null +++ b/packages/logging/src/v2/doc/doc_logging.js @@ -0,0 +1,314 @@ +/* + * Copyright 2017, Google Inc. All rights reserved. + * + * 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. + */ + +/* + * Note: this file is purely for documentation. Any contents are not expected + * to be loaded as the JS file. + */ + +/** + * The parameters to DeleteLog. + * + * @property {string} logName + * Required. The resource name of the log to delete: + * + * "projects/[PROJECT_ID]/logs/[LOG_ID]" + * "organizations/[ORGANIZATION_ID]/logs/[LOG_ID]" + * "billingAccounts/[BILLING_ACCOUNT_ID]/logs/[LOG_ID]" + * "folders/[FOLDER_ID]/logs/[LOG_ID]" + * + * `[LOG_ID]` must be URL-encoded. For example, + * `"projects/my-project-id/logs/syslog"`, + * `"organizations/1234567890/logs/cloudresourcemanager.googleapis.com%2Factivity"`. + * For more information about log names, see + * {@link LogEntry}. + * + * @class + * @see [google.logging.v2.DeleteLogRequest definition in proto format]{@link https://github.com/googleapis/googleapis/blob/master/google/logging/v2/logging.proto} + */ +var DeleteLogRequest = { + // This is for documentation. Actual contents will be loaded by gRPC. +}; + +/** + * The parameters to WriteLogEntries. + * + * @property {string} logName + * Optional. A default log resource name that is assigned to all log entries + * in `entries` that do not specify a value for `log_name`: + * + * "projects/[PROJECT_ID]/logs/[LOG_ID]" + * "organizations/[ORGANIZATION_ID]/logs/[LOG_ID]" + * "billingAccounts/[BILLING_ACCOUNT_ID]/logs/[LOG_ID]" + * "folders/[FOLDER_ID]/logs/[LOG_ID]" + * + * `[LOG_ID]` must be URL-encoded. For example, + * `"projects/my-project-id/logs/syslog"` or + * `"organizations/1234567890/logs/cloudresourcemanager.googleapis.com%2Factivity"`. + * For more information about log names, see + * {@link LogEntry}. + * + * @property {Object} resource + * Optional. A default monitored resource object that is assigned to all log + * entries in `entries` that do not specify a value for `resource`. Example: + * + * { "type": "gce_instance", + * "labels": { + * "zone": "us-central1-a", "instance_id": "00000000000000000000" }} + * + * See {@link LogEntry}. + * + * This object should have the same structure as [google.api.MonitoredResource]{@link external:"google.api.MonitoredResource"} + * + * @property {Object.} labels + * Optional. Default labels that are added to the `labels` field of all log + * entries in `entries`. If a log entry already has a label with the same key + * as a label in this parameter, then the log entry's label is not changed. + * See {@link LogEntry}. + * + * @property {Object[]} entries + * Required. The log entries to write. Values supplied for the fields + * `log_name`, `resource`, and `labels` in this `entries.write` request are + * inserted into those log entries in this list that do not provide their own + * values. + * + * Stackdriver Logging also creates and inserts values for `timestamp` and + * `insert_id` if the entries do not provide them. The created `insert_id` for + * the N'th entry in this list will be greater than earlier entries and less + * than later entries. Otherwise, the order of log entries in this list does + * not matter. + * + * To improve throughput and to avoid exceeding the + * [quota limit](https://cloud.google.com/logging/quota-policy) for calls to `entries.write`, + * you should write multiple log entries at once rather than + * calling this method for each individual log entry. + * + * This object should have the same structure as [LogEntry]{@link LogEntry} + * + * @property {boolean} partialSuccess + * Optional. Whether valid entries should be written even if some other + * entries fail due to INVALID_ARGUMENT or PERMISSION_DENIED errors. If any + * entry is not written, then the response status is the error associated + * with one of the failed entries and the response includes error details + * keyed by the entries' zero-based index in the `entries.write` method. + * + * @class + * @see [google.logging.v2.WriteLogEntriesRequest definition in proto format]{@link https://github.com/googleapis/googleapis/blob/master/google/logging/v2/logging.proto} + */ +var WriteLogEntriesRequest = { + // This is for documentation. Actual contents will be loaded by gRPC. +}; + +/** + * Result returned from WriteLogEntries. + * empty + * @class + * @see [google.logging.v2.WriteLogEntriesResponse definition in proto format]{@link https://github.com/googleapis/googleapis/blob/master/google/logging/v2/logging.proto} + */ +var WriteLogEntriesResponse = { + // This is for documentation. Actual contents will be loaded by gRPC. +}; + +/** + * Error details for WriteLogEntries with partial success. + * + * @property {Object.} logEntryErrors + * When `WriteLogEntriesRequest.partial_success` is true, records the error + * status for entries that were not written due to a permanent error, keyed + * by the entry's zero-based index in `WriteLogEntriesRequest.entries`. + * + * Failed requests for which no entries are written will not include + * per-entry errors. + * + * @class + * @see [google.logging.v2.WriteLogEntriesPartialErrors definition in proto format]{@link https://github.com/googleapis/googleapis/blob/master/google/logging/v2/logging.proto} + */ +var WriteLogEntriesPartialErrors = { + // This is for documentation. Actual contents will be loaded by gRPC. +}; + +/** + * The parameters to `ListLogEntries`. + * + * @property {string[]} projectIds + * Deprecated. Use `resource_names` instead. One or more project identifiers + * or project numbers from which to retrieve log entries. Example: + * `"my-project-1A"`. If present, these project identifiers are converted to + * resource name format and added to the list of resources in + * `resource_names`. + * + * @property {string[]} resourceNames + * Required. Names of one or more parent resources from which to + * retrieve log entries: + * + * "projects/[PROJECT_ID]" + * "organizations/[ORGANIZATION_ID]" + * "billingAccounts/[BILLING_ACCOUNT_ID]" + * "folders/[FOLDER_ID]" + * + * Projects listed in the `project_ids` field are added to this list. + * + * @property {string} filter + * Optional. A filter that chooses which log entries to return. See [Advanced + * Logs Filters](https://cloud.google.com/logging/docs/view/advanced_filters). Only log entries that + * match the filter are returned. An empty filter matches all log entries in + * the resources listed in `resource_names`. Referencing a parent resource + * that is not listed in `resource_names` will cause the filter to return no + * results. + * The maximum length of the filter is 20000 characters. + * + * @property {string} orderBy + * Optional. How the results should be sorted. Presently, the only permitted + * values are `"timestamp asc"` (default) and `"timestamp desc"`. The first + * option returns entries in order of increasing values of + * `LogEntry.timestamp` (oldest first), and the second option returns entries + * in order of decreasing timestamps (newest first). Entries with equal + * timestamps are returned in order of their `insert_id` values. + * + * @property {number} pageSize + * Optional. The maximum number of results to return from this request. + * Non-positive values are ignored. The presence of `next_page_token` in the + * response indicates that more results might be available. + * + * @property {string} pageToken + * Optional. If present, then retrieve the next batch of results from the + * preceding call to this method. `page_token` must be the value of + * `next_page_token` from the previous response. The values of other method + * parameters should be identical to those in the previous call. + * + * @class + * @see [google.logging.v2.ListLogEntriesRequest definition in proto format]{@link https://github.com/googleapis/googleapis/blob/master/google/logging/v2/logging.proto} + */ +var ListLogEntriesRequest = { + // This is for documentation. Actual contents will be loaded by gRPC. +}; + +/** + * Result returned from `ListLogEntries`. + * + * @property {Object[]} entries + * A list of log entries. + * + * This object should have the same structure as [LogEntry]{@link LogEntry} + * + * @property {string} nextPageToken + * If there might be more results than those appearing in this response, then + * `nextPageToken` is included. To get the next set of results, call this + * method again using the value of `nextPageToken` as `pageToken`. + * + * If a value for `next_page_token` appears and the `entries` field is empty, + * it means that the search found no log entries so far but it did not have + * time to search all the possible log entries. Retry the method with this + * value for `page_token` to continue the search. Alternatively, consider + * speeding up the search by changing your filter to specify a single log name + * or resource type, or to narrow the time range of the search. + * + * @class + * @see [google.logging.v2.ListLogEntriesResponse definition in proto format]{@link https://github.com/googleapis/googleapis/blob/master/google/logging/v2/logging.proto} + */ +var ListLogEntriesResponse = { + // This is for documentation. Actual contents will be loaded by gRPC. +}; + +/** + * The parameters to ListMonitoredResourceDescriptors + * + * @property {number} pageSize + * Optional. The maximum number of results to return from this request. + * Non-positive values are ignored. The presence of `nextPageToken` in the + * response indicates that more results might be available. + * + * @property {string} pageToken + * Optional. If present, then retrieve the next batch of results from the + * preceding call to this method. `pageToken` must be the value of + * `nextPageToken` from the previous response. The values of other method + * parameters should be identical to those in the previous call. + * + * @class + * @see [google.logging.v2.ListMonitoredResourceDescriptorsRequest definition in proto format]{@link https://github.com/googleapis/googleapis/blob/master/google/logging/v2/logging.proto} + */ +var ListMonitoredResourceDescriptorsRequest = { + // This is for documentation. Actual contents will be loaded by gRPC. +}; + +/** + * Result returned from ListMonitoredResourceDescriptors. + * + * @property {Object[]} resourceDescriptors + * A list of resource descriptors. + * + * This object should have the same structure as [google.api.MonitoredResourceDescriptor]{@link external:"google.api.MonitoredResourceDescriptor"} + * + * @property {string} nextPageToken + * If there might be more results than those appearing in this response, then + * `nextPageToken` is included. To get the next set of results, call this + * method again using the value of `nextPageToken` as `pageToken`. + * + * @class + * @see [google.logging.v2.ListMonitoredResourceDescriptorsResponse definition in proto format]{@link https://github.com/googleapis/googleapis/blob/master/google/logging/v2/logging.proto} + */ +var ListMonitoredResourceDescriptorsResponse = { + // This is for documentation. Actual contents will be loaded by gRPC. +}; + +/** + * The parameters to ListLogs. + * + * @property {string} parent + * Required. The resource name that owns the logs: + * + * "projects/[PROJECT_ID]" + * "organizations/[ORGANIZATION_ID]" + * "billingAccounts/[BILLING_ACCOUNT_ID]" + * "folders/[FOLDER_ID]" + * + * @property {number} pageSize + * Optional. The maximum number of results to return from this request. + * Non-positive values are ignored. The presence of `nextPageToken` in the + * response indicates that more results might be available. + * + * @property {string} pageToken + * Optional. If present, then retrieve the next batch of results from the + * preceding call to this method. `pageToken` must be the value of + * `nextPageToken` from the previous response. The values of other method + * parameters should be identical to those in the previous call. + * + * @class + * @see [google.logging.v2.ListLogsRequest definition in proto format]{@link https://github.com/googleapis/googleapis/blob/master/google/logging/v2/logging.proto} + */ +var ListLogsRequest = { + // This is for documentation. Actual contents will be loaded by gRPC. +}; + +/** + * Result returned from ListLogs. + * + * @property {string[]} logNames + * A list of log names. For example, + * `"projects/my-project/syslog"` or + * `"organizations/123/cloudresourcemanager.googleapis.com%2Factivity"`. + * + * @property {string} nextPageToken + * If there might be more results than those appearing in this response, then + * `nextPageToken` is included. To get the next set of results, call this + * method again using the value of `nextPageToken` as `pageToken`. + * + * @class + * @see [google.logging.v2.ListLogsResponse definition in proto format]{@link https://github.com/googleapis/googleapis/blob/master/google/logging/v2/logging.proto} + */ +var ListLogsResponse = { + // This is for documentation. Actual contents will be loaded by gRPC. +}; \ No newline at end of file diff --git a/packages/logging/src/v2/doc/doc_logging_config.js b/packages/logging/src/v2/doc/doc_logging_config.js new file mode 100644 index 00000000000..547b2dc54bc --- /dev/null +++ b/packages/logging/src/v2/doc/doc_logging_config.js @@ -0,0 +1,314 @@ +/* + * Copyright 2017, Google Inc. All rights reserved. + * + * 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. + */ + +/* + * Note: this file is purely for documentation. Any contents are not expected + * to be loaded as the JS file. + */ + +/** + * Describes a sink used to export log entries to one of the following + * destinations in any project: a Cloud Storage bucket, a BigQuery dataset, or a + * Cloud Pub/Sub topic. A logs filter controls which log entries are + * exported. The sink must be created within a project, organization, billing + * account, or folder. + * + * @property {string} name + * Required. The client-assigned sink identifier, unique within the + * project. Example: `"my-syslog-errors-to-pubsub"`. Sink identifiers are + * limited to 100 characters and can include only the following characters: + * upper and lower-case alphanumeric characters, underscores, hyphens, and + * periods. + * + * @property {string} destination + * Required. The export destination: + * + * "storage.googleapis.com/[GCS_BUCKET]" + * "bigquery.googleapis.com/projects/[PROJECT_ID]/datasets/[DATASET]" + * "pubsub.googleapis.com/projects/[PROJECT_ID]/topics/[TOPIC_ID]" + * + * The sink's `writer_identity`, set when the sink is created, must + * have permission to write to the destination or else the log + * entries are not exported. For more information, see + * [Exporting Logs With Sinks](https://cloud.google.com/logging/docs/api/tasks/exporting-logs). + * + * @property {string} filter + * Optional. + * An [advanced logs filter](https://cloud.google.com/logging/docs/view/advanced_filters). The only + * exported log entries are those that are in the resource owning the sink and + * that match the filter. The filter must use the log entry format specified + * by the `output_version_format` parameter. For example, in the v2 format: + * + * logName="projects/[PROJECT_ID]/logs/[LOG_ID]" AND severity>=ERROR + * + * @property {number} outputVersionFormat + * Optional. The log entry format to use for this sink's exported log + * entries. The v2 format is used by default. + * **The v1 format is deprecated** and should be used only as part of a + * migration effort to v2. + * See [Migration to the v2 API](https://cloud.google.com/logging/docs/api/v2/migration-to-v2). + * + * The number should be among the values of [VersionFormat]{@link VersionFormat} + * + * @property {string} writerIdentity + * Output only. An IAM identity—a service account or group—under + * which Stackdriver Logging writes the exported log entries to the sink's + * destination. This field is set by + * [sinks.create](https://cloud.google.com/logging/docs/api/reference/rest/v2/projects.sinks/create) + * and + * [sinks.update](https://cloud.google.com/logging/docs/api/reference/rest/v2/projects.sinks/update), + * based on the setting of `unique_writer_identity` in those methods. + * + * Until you grant this identity write-access to the destination, log entry + * exports from this sink will fail. For more information, + * see [Granting access for a + * resource](https://cloud.google.com/iam/docs/granting-roles-to-service-accounts#granting_access_to_a_service_account_for_a_resource). + * Consult the destination service's documentation to determine the + * appropriate IAM roles to assign to the identity. + * + * @property {boolean} includeChildren + * Optional. This field applies only to sinks owned by organizations and + * folders. If the field is false, the default, only the logs owned by the + * sink's parent resource are available for export. If the field is true, then + * logs from all the projects, folders, and billing accounts contained in the + * sink's parent resource are also available for export. Whether a particular + * log entry from the children is exported depends on the sink's filter + * expression. For example, if this field is true, then the filter + * `resource.type=gce_instance` would export all Compute Engine VM instance + * log entries from all projects in the sink's parent. To only export entries + * from certain child projects, filter on the project part of the log name: + * + * logName:("projects/test-project1/" OR "projects/test-project2/") AND + * resource.type=gce_instance + * + * @property {Object} startTime + * Optional. The time at which this sink will begin exporting log entries. + * Log entries are exported only if their timestamp is not earlier than the + * start time. The default value of this field is the time the sink is + * created or updated. + * + * This object should have the same structure as [google.protobuf.Timestamp]{@link external:"google.protobuf.Timestamp"} + * + * @property {Object} endTime + * Optional. The time at which this sink will stop exporting log entries. Log + * entries are exported only if their timestamp is earlier than the end time. + * If this field is not supplied, there is no end time. If both a start time + * and an end time are provided, then the end time must be later than the + * start time. + * + * This object should have the same structure as [google.protobuf.Timestamp]{@link external:"google.protobuf.Timestamp"} + * + * @class + * @see [google.logging.v2.LogSink definition in proto format]{@link https://github.com/googleapis/googleapis/blob/master/google/logging/v2/logging_config.proto} + */ +var LogSink = { + // This is for documentation. Actual contents will be loaded by gRPC. + + /** + * Available log entry formats. Log entries can be written to Stackdriver + * Logging in either format and can be exported in either format. + * Version 2 is the preferred format. + * + * @enum {number} + */ + VersionFormat: { + + /** + * An unspecified format version that will default to V2. + */ + VERSION_FORMAT_UNSPECIFIED: 0, + + /** + * `LogEntry` version 2 format. + */ + V2: 1, + + /** + * `LogEntry` version 1 format. + */ + V1: 2 + } +}; + +/** + * The parameters to `ListSinks`. + * + * @property {string} parent + * Required. The parent resource whose sinks are to be listed: + * + * "projects/[PROJECT_ID]" + * "organizations/[ORGANIZATION_ID]" + * "billingAccounts/[BILLING_ACCOUNT_ID]" + * "folders/[FOLDER_ID]" + * + * @property {string} pageToken + * Optional. If present, then retrieve the next batch of results from the + * preceding call to this method. `pageToken` must be the value of + * `nextPageToken` from the previous response. The values of other method + * parameters should be identical to those in the previous call. + * + * @property {number} pageSize + * Optional. The maximum number of results to return from this request. + * Non-positive values are ignored. The presence of `nextPageToken` in the + * response indicates that more results might be available. + * + * @class + * @see [google.logging.v2.ListSinksRequest definition in proto format]{@link https://github.com/googleapis/googleapis/blob/master/google/logging/v2/logging_config.proto} + */ +var ListSinksRequest = { + // This is for documentation. Actual contents will be loaded by gRPC. +}; + +/** + * Result returned from `ListSinks`. + * + * @property {Object[]} sinks + * A list of sinks. + * + * This object should have the same structure as [LogSink]{@link LogSink} + * + * @property {string} nextPageToken + * If there might be more results than appear in this response, then + * `nextPageToken` is included. To get the next set of results, call the same + * method again using the value of `nextPageToken` as `pageToken`. + * + * @class + * @see [google.logging.v2.ListSinksResponse definition in proto format]{@link https://github.com/googleapis/googleapis/blob/master/google/logging/v2/logging_config.proto} + */ +var ListSinksResponse = { + // This is for documentation. Actual contents will be loaded by gRPC. +}; + +/** + * The parameters to `GetSink`. + * + * @property {string} sinkName + * Required. The resource name of the sink: + * + * "projects/[PROJECT_ID]/sinks/[SINK_ID]" + * "organizations/[ORGANIZATION_ID]/sinks/[SINK_ID]" + * "billingAccounts/[BILLING_ACCOUNT_ID]/sinks/[SINK_ID]" + * "folders/[FOLDER_ID]/sinks/[SINK_ID]" + * + * Example: `"projects/my-project-id/sinks/my-sink-id"`. + * + * @class + * @see [google.logging.v2.GetSinkRequest definition in proto format]{@link https://github.com/googleapis/googleapis/blob/master/google/logging/v2/logging_config.proto} + */ +var GetSinkRequest = { + // This is for documentation. Actual contents will be loaded by gRPC. +}; + +/** + * The parameters to `CreateSink`. + * + * @property {string} parent + * Required. The resource in which to create the sink: + * + * "projects/[PROJECT_ID]" + * "organizations/[ORGANIZATION_ID]" + * "billingAccounts/[BILLING_ACCOUNT_ID]" + * "folders/[FOLDER_ID]" + * + * Examples: `"projects/my-logging-project"`, `"organizations/123456789"`. + * + * @property {Object} sink + * Required. The new sink, whose `name` parameter is a sink identifier that + * is not already in use. + * + * This object should have the same structure as [LogSink]{@link LogSink} + * + * @property {boolean} uniqueWriterIdentity + * Optional. Determines the kind of IAM identity returned as `writer_identity` + * in the new sink. If this value is omitted or set to false, and if the + * sink's parent is a project, then the value returned as `writer_identity` is + * the same group or service account used by Stackdriver Logging before the + * addition of writer identities to this API. The sink's destination must be + * in the same project as the sink itself. + * + * If this field is set to true, or if the sink is owned by a non-project + * resource such as an organization, then the value of `writer_identity` will + * be a unique service account used only for exports from the new sink. For + * more information, see `writer_identity` in {@link LogSink}. + * + * @class + * @see [google.logging.v2.CreateSinkRequest definition in proto format]{@link https://github.com/googleapis/googleapis/blob/master/google/logging/v2/logging_config.proto} + */ +var CreateSinkRequest = { + // This is for documentation. Actual contents will be loaded by gRPC. +}; + +/** + * The parameters to `UpdateSink`. + * + * @property {string} sinkName + * Required. The full resource name of the sink to update, including the + * parent resource and the sink identifier: + * + * "projects/[PROJECT_ID]/sinks/[SINK_ID]" + * "organizations/[ORGANIZATION_ID]/sinks/[SINK_ID]" + * "billingAccounts/[BILLING_ACCOUNT_ID]/sinks/[SINK_ID]" + * "folders/[FOLDER_ID]/sinks/[SINK_ID]" + * + * Example: `"projects/my-project-id/sinks/my-sink-id"`. + * + * @property {Object} sink + * Required. The updated sink, whose name is the same identifier that appears + * as part of `sink_name`. If `sink_name` does not exist, then + * this method creates a new sink. + * + * This object should have the same structure as [LogSink]{@link LogSink} + * + * @property {boolean} uniqueWriterIdentity + * Optional. See + * [sinks.create](https://cloud.google.com/logging/docs/api/reference/rest/v2/projects.sinks/create) + * for a description of this field. When updating a sink, the effect of this + * field on the value of `writer_identity` in the updated sink depends on both + * the old and new values of this field: + * + * + If the old and new values of this field are both false or both true, + * then there is no change to the sink's `writer_identity`. + * + If the old value is false and the new value is true, then + * `writer_identity` is changed to a unique service account. + * + It is an error if the old value is true and the new value is false. + * + * @class + * @see [google.logging.v2.UpdateSinkRequest definition in proto format]{@link https://github.com/googleapis/googleapis/blob/master/google/logging/v2/logging_config.proto} + */ +var UpdateSinkRequest = { + // This is for documentation. Actual contents will be loaded by gRPC. +}; + +/** + * The parameters to `DeleteSink`. + * + * @property {string} sinkName + * Required. The full resource name of the sink to delete, including the + * parent resource and the sink identifier: + * + * "projects/[PROJECT_ID]/sinks/[SINK_ID]" + * "organizations/[ORGANIZATION_ID]/sinks/[SINK_ID]" + * "billingAccounts/[BILLING_ACCOUNT_ID]/sinks/[SINK_ID]" + * "folders/[FOLDER_ID]/sinks/[SINK_ID]" + * + * Example: `"projects/my-project-id/sinks/my-sink-id"`. + * + * @class + * @see [google.logging.v2.DeleteSinkRequest definition in proto format]{@link https://github.com/googleapis/googleapis/blob/master/google/logging/v2/logging_config.proto} + */ +var DeleteSinkRequest = { + // This is for documentation. Actual contents will be loaded by gRPC. +}; \ No newline at end of file diff --git a/packages/logging/src/v2/doc/doc_logging_metrics.js b/packages/logging/src/v2/doc/doc_logging_metrics.js new file mode 100644 index 00000000000..b76532ab87f --- /dev/null +++ b/packages/logging/src/v2/doc/doc_logging_metrics.js @@ -0,0 +1,208 @@ +/* + * Copyright 2017, Google Inc. All rights reserved. + * + * 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. + */ + +/* + * Note: this file is purely for documentation. Any contents are not expected + * to be loaded as the JS file. + */ + +/** + * Describes a logs-based metric. The value of the metric is the + * number of log entries that match a logs filter in a given time interval. + * + * @property {string} name + * Required. The client-assigned metric identifier. + * Examples: `"error_count"`, `"nginx/requests"`. + * + * Metric identifiers are limited to 100 characters and can include + * only the following characters: `A-Z`, `a-z`, `0-9`, and the + * special characters `_-.,+!*',()%/`. The forward-slash character + * (`/`) denotes a hierarchy of name pieces, and it cannot be the + * first character of the name. + * + * The metric identifier in this field must not be + * [URL-encoded](https://en.wikipedia.org/wiki/Percent-encoding). + * However, when the metric identifier appears as the `[METRIC_ID]` + * part of a `metric_name` API parameter, then the metric identifier + * must be URL-encoded. Example: + * `"projects/my-project/metrics/nginx%2Frequests"`. + * + * @property {string} description + * Optional. A description of this metric, which is used in documentation. + * + * @property {string} filter + * Required. An [advanced logs filter](https://cloud.google.com/logging/docs/view/advanced_filters) + * which is used to match log entries. + * Example: + * + * "resource.type=gae_app AND severity>=ERROR" + * + * The maximum length of the filter is 20000 characters. + * + * @property {number} version + * Output only. The API version that created or updated this metric. + * The version also dictates the syntax of the filter expression. When a value + * for this field is missing, the default value of V2 should be assumed. + * + * The number should be among the values of [ApiVersion]{@link ApiVersion} + * + * @class + * @see [google.logging.v2.LogMetric definition in proto format]{@link https://github.com/googleapis/googleapis/blob/master/google/logging/v2/logging_metrics.proto} + */ +var LogMetric = { + // This is for documentation. Actual contents will be loaded by gRPC. + + /** + * Stackdriver Logging API version. + * + * @enum {number} + */ + ApiVersion: { + + /** + * Stackdriver Logging API v2. + */ + V2: 0, + + /** + * Stackdriver Logging API v1. + */ + V1: 1 + } +}; + +/** + * The parameters to ListLogMetrics. + * + * @property {string} parent + * Required. The name of the project containing the metrics: + * + * "projects/[PROJECT_ID]" + * + * @property {string} pageToken + * Optional. If present, then retrieve the next batch of results from the + * preceding call to this method. `pageToken` must be the value of + * `nextPageToken` from the previous response. The values of other method + * parameters should be identical to those in the previous call. + * + * @property {number} pageSize + * Optional. The maximum number of results to return from this request. + * Non-positive values are ignored. The presence of `nextPageToken` in the + * response indicates that more results might be available. + * + * @class + * @see [google.logging.v2.ListLogMetricsRequest definition in proto format]{@link https://github.com/googleapis/googleapis/blob/master/google/logging/v2/logging_metrics.proto} + */ +var ListLogMetricsRequest = { + // This is for documentation. Actual contents will be loaded by gRPC. +}; + +/** + * Result returned from ListLogMetrics. + * + * @property {Object[]} metrics + * A list of logs-based metrics. + * + * This object should have the same structure as [LogMetric]{@link LogMetric} + * + * @property {string} nextPageToken + * If there might be more results than appear in this response, then + * `nextPageToken` is included. To get the next set of results, call this + * method again using the value of `nextPageToken` as `pageToken`. + * + * @class + * @see [google.logging.v2.ListLogMetricsResponse definition in proto format]{@link https://github.com/googleapis/googleapis/blob/master/google/logging/v2/logging_metrics.proto} + */ +var ListLogMetricsResponse = { + // This is for documentation. Actual contents will be loaded by gRPC. +}; + +/** + * The parameters to GetLogMetric. + * + * @property {string} metricName + * The resource name of the desired metric: + * + * "projects/[PROJECT_ID]/metrics/[METRIC_ID]" + * + * @class + * @see [google.logging.v2.GetLogMetricRequest definition in proto format]{@link https://github.com/googleapis/googleapis/blob/master/google/logging/v2/logging_metrics.proto} + */ +var GetLogMetricRequest = { + // This is for documentation. Actual contents will be loaded by gRPC. +}; + +/** + * The parameters to CreateLogMetric. + * + * @property {string} parent + * The resource name of the project in which to create the metric: + * + * "projects/[PROJECT_ID]" + * + * The new metric must be provided in the request. + * + * @property {Object} metric + * The new logs-based metric, which must not have an identifier that + * already exists. + * + * This object should have the same structure as [LogMetric]{@link LogMetric} + * + * @class + * @see [google.logging.v2.CreateLogMetricRequest definition in proto format]{@link https://github.com/googleapis/googleapis/blob/master/google/logging/v2/logging_metrics.proto} + */ +var CreateLogMetricRequest = { + // This is for documentation. Actual contents will be loaded by gRPC. +}; + +/** + * The parameters to UpdateLogMetric. + * + * @property {string} metricName + * The resource name of the metric to update: + * + * "projects/[PROJECT_ID]/metrics/[METRIC_ID]" + * + * The updated metric must be provided in the request and it's + * `name` field must be the same as `[METRIC_ID]` If the metric + * does not exist in `[PROJECT_ID]`, then a new metric is created. + * + * @property {Object} metric + * The updated metric. + * + * This object should have the same structure as [LogMetric]{@link LogMetric} + * + * @class + * @see [google.logging.v2.UpdateLogMetricRequest definition in proto format]{@link https://github.com/googleapis/googleapis/blob/master/google/logging/v2/logging_metrics.proto} + */ +var UpdateLogMetricRequest = { + // This is for documentation. Actual contents will be loaded by gRPC. +}; + +/** + * The parameters to DeleteLogMetric. + * + * @property {string} metricName + * The resource name of the metric to delete: + * + * "projects/[PROJECT_ID]/metrics/[METRIC_ID]" + * + * @class + * @see [google.logging.v2.DeleteLogMetricRequest definition in proto format]{@link https://github.com/googleapis/googleapis/blob/master/google/logging/v2/logging_metrics.proto} + */ +var DeleteLogMetricRequest = { + // This is for documentation. Actual contents will be loaded by gRPC. +}; \ No newline at end of file diff --git a/packages/pubsub/src/v1/doc/doc_google_protobuf_duration.js b/packages/pubsub/src/v1/doc/doc_google_protobuf_duration.js new file mode 100644 index 00000000000..b81fd71f130 --- /dev/null +++ b/packages/pubsub/src/v1/doc/doc_google_protobuf_duration.js @@ -0,0 +1,84 @@ +/* + * Copyright 2017, Google Inc. All rights reserved. + * + * 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. + */ + +/* + * Note: this file is purely for documentation. Any contents are not expected + * to be loaded as the JS file. + */ + +/** + * A Duration represents a signed, fixed-length span of time represented + * as a count of seconds and fractions of seconds at nanosecond + * resolution. It is independent of any calendar and concepts like "day" + * or "month". It is related to Timestamp in that the difference between + * two Timestamp values is a Duration and it can be added or subtracted + * from a Timestamp. Range is approximately +-10,000 years. + * + * Example 1: Compute Duration from two Timestamps in pseudo code. + * + * Timestamp start = ...; + * Timestamp end = ...; + * Duration duration = ...; + * + * duration.seconds = end.seconds - start.seconds; + * duration.nanos = end.nanos - start.nanos; + * + * if (duration.seconds < 0 && duration.nanos > 0) { + * duration.seconds += 1; + * duration.nanos -= 1000000000; + * } else if (durations.seconds > 0 && duration.nanos < 0) { + * duration.seconds -= 1; + * duration.nanos += 1000000000; + * } + * + * Example 2: Compute Timestamp from Timestamp + Duration in pseudo code. + * + * Timestamp start = ...; + * Duration duration = ...; + * Timestamp end = ...; + * + * end.seconds = start.seconds + duration.seconds; + * end.nanos = start.nanos + duration.nanos; + * + * if (end.nanos < 0) { + * end.seconds -= 1; + * end.nanos += 1000000000; + * } else if (end.nanos >= 1000000000) { + * end.seconds += 1; + * end.nanos -= 1000000000; + * } + * + * Example 3: Compute Duration from datetime.timedelta in Python. + * + * td = datetime.timedelta(days=3, minutes=10) + * duration = Duration() + * duration.FromTimedelta(td) + * + * @external "google.protobuf.Duration" + * @property {number} seconds + * Signed seconds of the span of time. Must be from -315,576,000,000 + * to +315,576,000,000 inclusive. + * + * @property {number} nanos + * Signed fractions of a second at nanosecond resolution of the span + * of time. Durations less than one second are represented with a 0 + * `seconds` field and a positive or negative `nanos` field. For durations + * of one second or more, a non-zero value for the `nanos` field must be + * of the same sign as the `seconds` field. Must be from -999,999,999 + * to +999,999,999 inclusive. + * + * @see [google.protobuf.Duration definition in proto format]{@link https://github.com/google/protobuf/blob/master/src/google/protobuf/duration.proto} + */ \ No newline at end of file diff --git a/packages/pubsub/src/v1/doc/doc_google_protobuf_field_mask.js b/packages/pubsub/src/v1/doc/doc_google_protobuf_field_mask.js new file mode 100644 index 00000000000..db0cea463fe --- /dev/null +++ b/packages/pubsub/src/v1/doc/doc_google_protobuf_field_mask.js @@ -0,0 +1,230 @@ +/* + * Copyright 2017, Google Inc. All rights reserved. + * + * 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. + */ + +/* + * Note: this file is purely for documentation. Any contents are not expected + * to be loaded as the JS file. + */ + +/** + * `FieldMask` represents a set of symbolic field paths, for example: + * + * paths: "f.a" + * paths: "f.b.d" + * + * Here `f` represents a field in some root message, `a` and `b` + * fields in the message found in `f`, and `d` a field found in the + * message in `f.b`. + * + * Field masks are used to specify a subset of fields that should be + * returned by a get operation or modified by an update operation. + * Field masks also have a custom JSON encoding (see below). + * + * # Field Masks in Projections + * + * When used in the context of a projection, a response message or + * sub-message is filtered by the API to only contain those fields as + * specified in the mask. For example, if the mask in the previous + * example is applied to a response message as follows: + * + * f { + * a : 22 + * b { + * d : 1 + * x : 2 + * } + * y : 13 + * } + * z: 8 + * + * The result will not contain specific values for fields x,y and z + * (their value will be set to the default, and omitted in proto text + * output): + * + * + * f { + * a : 22 + * b { + * d : 1 + * } + * } + * + * A repeated field is not allowed except at the last position of a + * paths string. + * + * If a FieldMask object is not present in a get operation, the + * operation applies to all fields (as if a FieldMask of all fields + * had been specified). + * + * Note that a field mask does not necessarily apply to the + * top-level response message. In case of a REST get operation, the + * field mask applies directly to the response, but in case of a REST + * list operation, the mask instead applies to each individual message + * in the returned resource list. In case of a REST custom method, + * other definitions may be used. Where the mask applies will be + * clearly documented together with its declaration in the API. In + * any case, the effect on the returned resource/resources is required + * behavior for APIs. + * + * # Field Masks in Update Operations + * + * A field mask in update operations specifies which fields of the + * targeted resource are going to be updated. The API is required + * to only change the values of the fields as specified in the mask + * and leave the others untouched. If a resource is passed in to + * describe the updated values, the API ignores the values of all + * fields not covered by the mask. + * + * If a repeated field is specified for an update operation, the existing + * repeated values in the target resource will be overwritten by the new values. + * Note that a repeated field is only allowed in the last position of a `paths` + * string. + * + * If a sub-message is specified in the last position of the field mask for an + * update operation, then the existing sub-message in the target resource is + * overwritten. Given the target message: + * + * f { + * b { + * d : 1 + * x : 2 + * } + * c : 1 + * } + * + * And an update message: + * + * f { + * b { + * d : 10 + * } + * } + * + * then if the field mask is: + * + * paths: "f.b" + * + * then the result will be: + * + * f { + * b { + * d : 10 + * } + * c : 1 + * } + * + * However, if the update mask was: + * + * paths: "f.b.d" + * + * then the result would be: + * + * f { + * b { + * d : 10 + * x : 2 + * } + * c : 1 + * } + * + * In order to reset a field's value to the default, the field must + * be in the mask and set to the default value in the provided resource. + * Hence, in order to reset all fields of a resource, provide a default + * instance of the resource and set all fields in the mask, or do + * not provide a mask as described below. + * + * If a field mask is not present on update, the operation applies to + * all fields (as if a field mask of all fields has been specified). + * Note that in the presence of schema evolution, this may mean that + * fields the client does not know and has therefore not filled into + * the request will be reset to their default. If this is unwanted + * behavior, a specific service may require a client to always specify + * a field mask, producing an error if not. + * + * As with get operations, the location of the resource which + * describes the updated values in the request message depends on the + * operation kind. In any case, the effect of the field mask is + * required to be honored by the API. + * + * ## Considerations for HTTP REST + * + * The HTTP kind of an update operation which uses a field mask must + * be set to PATCH instead of PUT in order to satisfy HTTP semantics + * (PUT must only be used for full updates). + * + * # JSON Encoding of Field Masks + * + * In JSON, a field mask is encoded as a single string where paths are + * separated by a comma. Fields name in each path are converted + * to/from lower-camel naming conventions. + * + * As an example, consider the following message declarations: + * + * message Profile { + * User user = 1; + * Photo photo = 2; + * } + * message User { + * string display_name = 1; + * string address = 2; + * } + * + * In proto a field mask for `Profile` may look as such: + * + * mask { + * paths: "user.display_name" + * paths: "photo" + * } + * + * In JSON, the same mask is represented as below: + * + * { + * mask: "user.displayName,photo" + * } + * + * # Field Masks and Oneof Fields + * + * Field masks treat fields in oneofs just as regular fields. Consider the + * following message: + * + * message SampleMessage { + * oneof test_oneof { + * string name = 4; + * SubMessage sub_message = 9; + * } + * } + * + * The field mask can be: + * + * mask { + * paths: "name" + * } + * + * Or: + * + * mask { + * paths: "sub_message" + * } + * + * Note that oneof type names ("test_oneof" in this case) cannot be used in + * paths. + * + * @external "google.protobuf.FieldMask" + * @property {string[]} paths + * The set of field mask paths. + * + * @see [google.protobuf.FieldMask definition in proto format]{@link https://github.com/google/protobuf/blob/master/src/google/protobuf/field_mask.proto} + */ \ No newline at end of file diff --git a/packages/pubsub/src/v1/doc/doc_google_protobuf_timestamp.js b/packages/pubsub/src/v1/doc/doc_google_protobuf_timestamp.js new file mode 100644 index 00000000000..ed8fc627b92 --- /dev/null +++ b/packages/pubsub/src/v1/doc/doc_google_protobuf_timestamp.js @@ -0,0 +1,88 @@ +/* + * Copyright 2017, Google Inc. All rights reserved. + * + * 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. + */ + +/* + * Note: this file is purely for documentation. Any contents are not expected + * to be loaded as the JS file. + */ + +/** + * A Timestamp represents a point in time independent of any time zone + * or calendar, represented as seconds and fractions of seconds at + * nanosecond resolution in UTC Epoch time. It is encoded using the + * Proleptic Gregorian Calendar which extends the Gregorian calendar + * backwards to year one. It is encoded assuming all minutes are 60 + * seconds long, i.e. leap seconds are "smeared" so that no leap second + * table is needed for interpretation. Range is from + * 0001-01-01T00:00:00Z to 9999-12-31T23:59:59.999999999Z. + * By restricting to that range, we ensure that we can convert to + * and from RFC 3339 date strings. + * See [https://www.ietf.org/rfc/rfc3339.txt](https://www.ietf.org/rfc/rfc3339.txt). + * + * Example 1: Compute Timestamp from POSIX `time()`. + * + * Timestamp timestamp; + * timestamp.set_seconds(time(NULL)); + * timestamp.set_nanos(0); + * + * Example 2: Compute Timestamp from POSIX `gettimeofday()`. + * + * struct timeval tv; + * gettimeofday(&tv, NULL); + * + * Timestamp timestamp; + * timestamp.set_seconds(tv.tv_sec); + * timestamp.set_nanos(tv.tv_usec * 1000); + * + * Example 3: Compute Timestamp from Win32 `GetSystemTimeAsFileTime()`. + * + * FILETIME ft; + * GetSystemTimeAsFileTime(&ft); + * UINT64 ticks = (((UINT64)ft.dwHighDateTime) << 32) | ft.dwLowDateTime; + * + * // A Windows tick is 100 nanoseconds. Windows epoch 1601-01-01T00:00:00Z + * // is 11644473600 seconds before Unix epoch 1970-01-01T00:00:00Z. + * Timestamp timestamp; + * timestamp.set_seconds((INT64) ((ticks / 10000000) - 11644473600LL)); + * timestamp.set_nanos((INT32) ((ticks % 10000000) * 100)); + * + * Example 4: Compute Timestamp from Java `System.currentTimeMillis()`. + * + * long millis = System.currentTimeMillis(); + * + * Timestamp timestamp = Timestamp.newBuilder().setSeconds(millis / 1000) + * .setNanos((int) ((millis % 1000) * 1000000)).build(); + * + * + * Example 5: Compute Timestamp from current time in Python. + * + * timestamp = Timestamp() + * timestamp.GetCurrentTime() + * + * @external "google.protobuf.Timestamp" + * @property {number} seconds + * Represents seconds of UTC time since Unix epoch + * 1970-01-01T00:00:00Z. Must be from 0001-01-01T00:00:00Z to + * 9999-12-31T23:59:59Z inclusive. + * + * @property {number} nanos + * Non-negative fractions of a second at nanosecond resolution. Negative + * second values with fractions must still have non-negative nanos values + * that count forward in time. Must be from 0 to 999,999,999 + * inclusive. + * + * @see [google.protobuf.Timestamp definition in proto format]{@link https://github.com/google/protobuf/blob/master/src/google/protobuf/timestamp.proto} + */ \ No newline at end of file diff --git a/packages/pubsub/src/v1/doc/doc_pubsub.js b/packages/pubsub/src/v1/doc/doc_pubsub.js new file mode 100644 index 00000000000..bd0c11239ec --- /dev/null +++ b/packages/pubsub/src/v1/doc/doc_pubsub.js @@ -0,0 +1,757 @@ +/* + * Copyright 2017, Google Inc. All rights reserved. + * + * 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. + */ + +/* + * Note: this file is purely for documentation. Any contents are not expected + * to be loaded as the JS file. + */ + +/** + * A topic resource. + * + * @property {string} name + * 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"`. + * + * @class + * @see [google.pubsub.v1.Topic definition in proto format]{@link https://github.com/googleapis/googleapis/blob/master/google/pubsub/v1/pubsub.proto} + */ +var Topic = { + // This is for documentation. Actual contents will be loaded by gRPC. +}; + +/** + * A message data and its attributes. The message payload must not be empty; + * it must contain either a non-empty data field, or at least one attribute. + * + * @property {string} data + * The message payload. + * + * @property {Object.} attributes + * Optional attributes for this message. + * + * @property {string} messageId + * 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. + * + * @property {Object} publishTime + * 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. + * + * This object should have the same structure as [google.protobuf.Timestamp]{@link external:"google.protobuf.Timestamp"} + * + * @class + * @see [google.pubsub.v1.PubsubMessage definition in proto format]{@link https://github.com/googleapis/googleapis/blob/master/google/pubsub/v1/pubsub.proto} + */ +var PubsubMessage = { + // This is for documentation. Actual contents will be loaded by gRPC. +}; + +/** + * Request for the GetTopic method. + * + * @property {string} topic + * The name of the topic to get. + * Format is `projects/{project}/topics/{topic}`. + * + * @class + * @see [google.pubsub.v1.GetTopicRequest definition in proto format]{@link https://github.com/googleapis/googleapis/blob/master/google/pubsub/v1/pubsub.proto} + */ +var GetTopicRequest = { + // This is for documentation. Actual contents will be loaded by gRPC. +}; + +/** + * Request for the Publish method. + * + * @property {string} topic + * The messages in the request will be published on this topic. + * Format is `projects/{project}/topics/{topic}`. + * + * @property {Object[]} messages + * The messages to publish. + * + * This object should have the same structure as [PubsubMessage]{@link PubsubMessage} + * + * @class + * @see [google.pubsub.v1.PublishRequest definition in proto format]{@link https://github.com/googleapis/googleapis/blob/master/google/pubsub/v1/pubsub.proto} + */ +var PublishRequest = { + // This is for documentation. Actual contents will be loaded by gRPC. +}; + +/** + * Response for the `Publish` method. + * + * @property {string[]} messageIds + * 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. + * + * @class + * @see [google.pubsub.v1.PublishResponse definition in proto format]{@link https://github.com/googleapis/googleapis/blob/master/google/pubsub/v1/pubsub.proto} + */ +var PublishResponse = { + // This is for documentation. Actual contents will be loaded by gRPC. +}; + +/** + * Request for the `ListTopics` method. + * + * @property {string} project + * The name of the cloud project that topics belong to. + * Format is `projects/{project}`. + * + * @property {number} pageSize + * Maximum number of topics to return. + * + * @property {string} pageToken + * 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. + * + * @class + * @see [google.pubsub.v1.ListTopicsRequest definition in proto format]{@link https://github.com/googleapis/googleapis/blob/master/google/pubsub/v1/pubsub.proto} + */ +var ListTopicsRequest = { + // This is for documentation. Actual contents will be loaded by gRPC. +}; + +/** + * Response for the `ListTopics` method. + * + * @property {Object[]} topics + * The resulting topics. + * + * This object should have the same structure as [Topic]{@link Topic} + * + * @property {string} nextPageToken + * If not empty, indicates that there may be more topics that match the + * request; this value should be passed in a new `ListTopicsRequest`. + * + * @class + * @see [google.pubsub.v1.ListTopicsResponse definition in proto format]{@link https://github.com/googleapis/googleapis/blob/master/google/pubsub/v1/pubsub.proto} + */ +var ListTopicsResponse = { + // This is for documentation. Actual contents will be loaded by gRPC. +}; + +/** + * Request for the `ListTopicSubscriptions` method. + * + * @property {string} topic + * The name of the topic that subscriptions are attached to. + * Format is `projects/{project}/topics/{topic}`. + * + * @property {number} pageSize + * Maximum number of subscription names to return. + * + * @property {string} pageToken + * 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. + * + * @class + * @see [google.pubsub.v1.ListTopicSubscriptionsRequest definition in proto format]{@link https://github.com/googleapis/googleapis/blob/master/google/pubsub/v1/pubsub.proto} + */ +var ListTopicSubscriptionsRequest = { + // This is for documentation. Actual contents will be loaded by gRPC. +}; + +/** + * Response for the `ListTopicSubscriptions` method. + * + * @property {string[]} subscriptions + * The names of the subscriptions that match the request. + * + * @property {string} nextPageToken + * 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. + * + * @class + * @see [google.pubsub.v1.ListTopicSubscriptionsResponse definition in proto format]{@link https://github.com/googleapis/googleapis/blob/master/google/pubsub/v1/pubsub.proto} + */ +var ListTopicSubscriptionsResponse = { + // This is for documentation. Actual contents will be loaded by gRPC. +}; + +/** + * Request for the `DeleteTopic` method. + * + * @property {string} topic + * Name of the topic to delete. + * Format is `projects/{project}/topics/{topic}`. + * + * @class + * @see [google.pubsub.v1.DeleteTopicRequest definition in proto format]{@link https://github.com/googleapis/googleapis/blob/master/google/pubsub/v1/pubsub.proto} + */ +var DeleteTopicRequest = { + // This is for documentation. Actual contents will be loaded by gRPC. +}; + +/** + * A subscription resource. + * + * @property {string} name + * 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"`. + * + * @property {string} topic + * 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. + * + * @property {Object} pushConfig + * 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. + * + * This object should have the same structure as [PushConfig]{@link PushConfig} + * + * @property {number} ackDeadlineSeconds + * This value is the maximum time after a subscriber receives a message + * before the subscriber should acknowledge the message. After message + * delivery but before the ack deadline expires and before the message is + * acknowledged, it is an outstanding message and will not be delivered + * again during that time (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 + * 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. + * + * @property {boolean} retainAckedMessages + * 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. + * + * @property {Object} messageRetentionDuration + * 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. + * + * This object should have the same structure as [google.protobuf.Duration]{@link external:"google.protobuf.Duration"} + * + * @class + * @see [google.pubsub.v1.Subscription definition in proto format]{@link https://github.com/googleapis/googleapis/blob/master/google/pubsub/v1/pubsub.proto} + */ +var Subscription = { + // This is for documentation. Actual contents will be loaded by gRPC. +}; + +/** + * Configuration for a push delivery endpoint. + * + * @property {string} pushEndpoint + * A URL locating the endpoint to which messages should be pushed. + * For example, a Webhook endpoint might use "https://example.com/push". + * + * @property {Object.} attributes + * 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. + * + * @class + * @see [google.pubsub.v1.PushConfig definition in proto format]{@link https://github.com/googleapis/googleapis/blob/master/google/pubsub/v1/pubsub.proto} + */ +var PushConfig = { + // This is for documentation. Actual contents will be loaded by gRPC. +}; + +/** + * A message and its corresponding acknowledgment ID. + * + * @property {string} ackId + * This ID can be used to acknowledge the received message. + * + * @property {Object} message + * The message. + * + * This object should have the same structure as [PubsubMessage]{@link PubsubMessage} + * + * @class + * @see [google.pubsub.v1.ReceivedMessage definition in proto format]{@link https://github.com/googleapis/googleapis/blob/master/google/pubsub/v1/pubsub.proto} + */ +var ReceivedMessage = { + // This is for documentation. Actual contents will be loaded by gRPC. +}; + +/** + * Request for the GetSubscription method. + * + * @property {string} subscription + * The name of the subscription to get. + * Format is `projects/{project}/subscriptions/{sub}`. + * + * @class + * @see [google.pubsub.v1.GetSubscriptionRequest definition in proto format]{@link https://github.com/googleapis/googleapis/blob/master/google/pubsub/v1/pubsub.proto} + */ +var GetSubscriptionRequest = { + // This is for documentation. Actual contents will be loaded by gRPC. +}; + +/** + * Request for the UpdateSubscription method. + * + * @property {Object} subscription + * The updated subscription object. + * + * This object should have the same structure as [Subscription]{@link Subscription} + * + * @property {Object} updateMask + * Indicates which fields in the provided subscription to update. + * Must be specified and non-empty. + * + * This object should have the same structure as [google.protobuf.FieldMask]{@link external:"google.protobuf.FieldMask"} + * + * @class + * @see [google.pubsub.v1.UpdateSubscriptionRequest definition in proto format]{@link https://github.com/googleapis/googleapis/blob/master/google/pubsub/v1/pubsub.proto} + */ +var UpdateSubscriptionRequest = { + // This is for documentation. Actual contents will be loaded by gRPC. +}; + +/** + * Request for the `ListSubscriptions` method. + * + * @property {string} project + * The name of the cloud project that subscriptions belong to. + * Format is `projects/{project}`. + * + * @property {number} pageSize + * Maximum number of subscriptions to return. + * + * @property {string} pageToken + * 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. + * + * @class + * @see [google.pubsub.v1.ListSubscriptionsRequest definition in proto format]{@link https://github.com/googleapis/googleapis/blob/master/google/pubsub/v1/pubsub.proto} + */ +var ListSubscriptionsRequest = { + // This is for documentation. Actual contents will be loaded by gRPC. +}; + +/** + * Response for the `ListSubscriptions` method. + * + * @property {Object[]} subscriptions + * The subscriptions that match the request. + * + * This object should have the same structure as [Subscription]{@link Subscription} + * + * @property {string} nextPageToken + * 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. + * + * @class + * @see [google.pubsub.v1.ListSubscriptionsResponse definition in proto format]{@link https://github.com/googleapis/googleapis/blob/master/google/pubsub/v1/pubsub.proto} + */ +var ListSubscriptionsResponse = { + // This is for documentation. Actual contents will be loaded by gRPC. +}; + +/** + * Request for the DeleteSubscription method. + * + * @property {string} subscription + * The subscription to delete. + * Format is `projects/{project}/subscriptions/{sub}`. + * + * @class + * @see [google.pubsub.v1.DeleteSubscriptionRequest definition in proto format]{@link https://github.com/googleapis/googleapis/blob/master/google/pubsub/v1/pubsub.proto} + */ +var DeleteSubscriptionRequest = { + // This is for documentation. Actual contents will be loaded by gRPC. +}; + +/** + * Request for the ModifyPushConfig method. + * + * @property {string} subscription + * The name of the subscription. + * Format is `projects/{project}/subscriptions/{sub}`. + * + * @property {Object} pushConfig + * 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` is not called. + * + * This object should have the same structure as [PushConfig]{@link PushConfig} + * + * @class + * @see [google.pubsub.v1.ModifyPushConfigRequest definition in proto format]{@link https://github.com/googleapis/googleapis/blob/master/google/pubsub/v1/pubsub.proto} + */ +var ModifyPushConfigRequest = { + // This is for documentation. Actual contents will be loaded by gRPC. +}; + +/** + * Request for the `Pull` method. + * + * @property {string} subscription + * The subscription from which messages should be pulled. + * Format is `projects/{project}/subscriptions/{sub}`. + * + * @property {boolean} returnImmediately + * 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. The + * client may cancel the request if it does not wish to wait any longer for + * the response. + * + * @property {number} maxMessages + * The maximum number of messages returned for this request. The Pub/Sub + * system may return fewer than the number specified. + * + * @class + * @see [google.pubsub.v1.PullRequest definition in proto format]{@link https://github.com/googleapis/googleapis/blob/master/google/pubsub/v1/pubsub.proto} + */ +var PullRequest = { + // This is for documentation. Actual contents will be loaded by gRPC. +}; + +/** + * Response for the `Pull` method. + * + * @property {Object[]} receivedMessages + * 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 + * available in the backlog. + * + * This object should have the same structure as [ReceivedMessage]{@link ReceivedMessage} + * + * @class + * @see [google.pubsub.v1.PullResponse definition in proto format]{@link https://github.com/googleapis/googleapis/blob/master/google/pubsub/v1/pubsub.proto} + */ +var PullResponse = { + // This is for documentation. Actual contents will be loaded by gRPC. +}; + +/** + * Request for the ModifyAckDeadline method. + * + * @property {string} subscription + * The name of the subscription. + * Format is `projects/{project}/subscriptions/{sub}`. + * + * @property {string[]} ackIds + * List of acknowledgment IDs. + * + * @property {number} ackDeadlineSeconds + * 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 may immediately make the message available for + * another pull request. + * The minimum deadline you can specify is 0 seconds. + * The maximum deadline you can specify is 600 seconds (10 minutes). + * + * @class + * @see [google.pubsub.v1.ModifyAckDeadlineRequest definition in proto format]{@link https://github.com/googleapis/googleapis/blob/master/google/pubsub/v1/pubsub.proto} + */ +var ModifyAckDeadlineRequest = { + // This is for documentation. Actual contents will be loaded by gRPC. +}; + +/** + * Request for the Acknowledge method. + * + * @property {string} subscription + * The subscription whose message is being acknowledged. + * Format is `projects/{project}/subscriptions/{sub}`. + * + * @property {string[]} ackIds + * The acknowledgment ID for the messages being acknowledged that was returned + * by the Pub/Sub system in the `Pull` response. Must not be empty. + * + * @class + * @see [google.pubsub.v1.AcknowledgeRequest definition in proto format]{@link https://github.com/googleapis/googleapis/blob/master/google/pubsub/v1/pubsub.proto} + */ +var AcknowledgeRequest = { + // This is for documentation. Actual contents will be loaded by gRPC. +}; + +/** + * 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. + * + * @property {string} subscription + * 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}`. + * + * @property {string[]} ackIds + * 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`. + * + * @property {number[]} modifyDeadlineSeconds + * 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`. + * + * @property {string[]} modifyDeadlineAckIds + * 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. + * + * @property {number} streamAckDeadlineSeconds + * 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). + * + * @class + * @see [google.pubsub.v1.StreamingPullRequest definition in proto format]{@link https://github.com/googleapis/googleapis/blob/master/google/pubsub/v1/pubsub.proto} + */ +var StreamingPullRequest = { + // This is for documentation. Actual contents will be loaded by gRPC. +}; + +/** + * Response for the `StreamingPull` method. This response is used to stream + * messages from the server to the client. + * + * @property {Object[]} receivedMessages + * Received Pub/Sub messages. This will not be empty. + * + * This object should have the same structure as [ReceivedMessage]{@link ReceivedMessage} + * + * @class + * @see [google.pubsub.v1.StreamingPullResponse definition in proto format]{@link https://github.com/googleapis/googleapis/blob/master/google/pubsub/v1/pubsub.proto} + */ +var StreamingPullResponse = { + // This is for documentation. Actual contents will be loaded by gRPC. +}; + +/** + * Request for the `CreateSnapshot` method. + * + * @property {string} name + * 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. + * Format is `projects/{project}/snapshots/{snap}`. + * + * @property {string} subscription + * 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}`. + * + * @class + * @see [google.pubsub.v1.CreateSnapshotRequest definition in proto format]{@link https://github.com/googleapis/googleapis/blob/master/google/pubsub/v1/pubsub.proto} + */ +var CreateSnapshotRequest = { + // This is for documentation. Actual contents will be loaded by gRPC. +}; + +/** + * A snapshot resource. + * + * @property {string} name + * The name of the snapshot. + * + * @property {string} topic + * The name of the topic from which this snapshot is retaining messages. + * + * @property {Object} expireTime + * 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. + * + * This object should have the same structure as [google.protobuf.Timestamp]{@link external:"google.protobuf.Timestamp"} + * + * @class + * @see [google.pubsub.v1.Snapshot definition in proto format]{@link https://github.com/googleapis/googleapis/blob/master/google/pubsub/v1/pubsub.proto} + */ +var Snapshot = { + // This is for documentation. Actual contents will be loaded by gRPC. +}; + +/** + * Request for the `ListSnapshots` method. + * + * @property {string} project + * The name of the cloud project that snapshots belong to. + * Format is `projects/{project}`. + * + * @property {number} pageSize + * Maximum number of snapshots to return. + * + * @property {string} pageToken + * 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. + * + * @class + * @see [google.pubsub.v1.ListSnapshotsRequest definition in proto format]{@link https://github.com/googleapis/googleapis/blob/master/google/pubsub/v1/pubsub.proto} + */ +var ListSnapshotsRequest = { + // This is for documentation. Actual contents will be loaded by gRPC. +}; + +/** + * Response for the `ListSnapshots` method. + * + * @property {Object[]} snapshots + * The resulting snapshots. + * + * This object should have the same structure as [Snapshot]{@link Snapshot} + * + * @property {string} nextPageToken + * If not empty, indicates that there may be more snapshot that match the + * request; this value should be passed in a new `ListSnapshotsRequest`. + * + * @class + * @see [google.pubsub.v1.ListSnapshotsResponse definition in proto format]{@link https://github.com/googleapis/googleapis/blob/master/google/pubsub/v1/pubsub.proto} + */ +var ListSnapshotsResponse = { + // This is for documentation. Actual contents will be loaded by gRPC. +}; + +/** + * Request for the `DeleteSnapshot` method. + * + * @property {string} snapshot + * The name of the snapshot to delete. + * Format is `projects/{project}/snapshots/{snap}`. + * + * @class + * @see [google.pubsub.v1.DeleteSnapshotRequest definition in proto format]{@link https://github.com/googleapis/googleapis/blob/master/google/pubsub/v1/pubsub.proto} + */ +var DeleteSnapshotRequest = { + // This is for documentation. Actual contents will be loaded by gRPC. +}; + +/** + * Request for the `Seek` method. + * + * @property {string} subscription + * The subscription to affect. + * + * @property {Object} time + * 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. + * + * This object should have the same structure as [google.protobuf.Timestamp]{@link external:"google.protobuf.Timestamp"} + * + * @property {string} snapshot + * 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}`. + * + * @class + * @see [google.pubsub.v1.SeekRequest definition in proto format]{@link https://github.com/googleapis/googleapis/blob/master/google/pubsub/v1/pubsub.proto} + */ +var SeekRequest = { + // This is for documentation. Actual contents will be loaded by gRPC. +}; + +/** + * @class + * @see [google.pubsub.v1.SeekResponse definition in proto format]{@link https://github.com/googleapis/googleapis/blob/master/google/pubsub/v1/pubsub.proto} + */ +var SeekResponse = { + // This is for documentation. Actual contents will be loaded by gRPC. +}; \ No newline at end of file diff --git a/packages/spanner/src/admin/database/v1/doc/doc_google_protobuf_any.js b/packages/spanner/src/admin/database/v1/doc/doc_google_protobuf_any.js new file mode 100644 index 00000000000..0697ec15814 --- /dev/null +++ b/packages/spanner/src/admin/database/v1/doc/doc_google_protobuf_any.js @@ -0,0 +1,121 @@ +/* + * Copyright 2017, Google Inc. All rights reserved. + * + * 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. + */ + +/* + * Note: this file is purely for documentation. Any contents are not expected + * to be loaded as the JS file. + */ + +/** + * `Any` contains an arbitrary serialized protocol buffer message along with a + * URL that describes the type of the serialized message. + * + * Protobuf library provides support to pack/unpack Any values in the form + * of utility functions or additional generated methods of the Any type. + * + * Example 1: Pack and unpack a message in C++. + * + * Foo foo = ...; + * Any any; + * any.PackFrom(foo); + * ... + * if (any.UnpackTo(&foo)) { + * ... + * } + * + * Example 2: Pack and unpack a message in Java. + * + * Foo foo = ...; + * Any any = Any.pack(foo); + * ... + * if (any.is(Foo.class)) { + * foo = any.unpack(Foo.class); + * } + * + * Example 3: Pack and unpack a message in Python. + * + * foo = Foo(...) + * any = Any() + * any.Pack(foo) + * ... + * if any.Is(Foo.DESCRIPTOR): + * any.Unpack(foo) + * ... + * + * The pack methods provided by protobuf library will by default use + * 'type.googleapis.com/full.type.name' as the type URL and the unpack + * methods only use the fully qualified type name after the last '/' + * in the type URL, for example "foo.bar.com/x/y.z" will yield type + * name "y.z". + * + * + * # JSON + * + * The JSON representation of an `Any` value uses the regular + * representation of the deserialized, embedded message, with an + * additional field `@type` which contains the type URL. Example: + * + * package google.profile; + * message Person { + * string first_name = 1; + * string last_name = 2; + * } + * + * { + * "@type": "type.googleapis.com/google.profile.Person", + * "firstName": , + * "lastName": + * } + * + * If the embedded message type is well-known and has a custom JSON + * representation, that representation will be embedded adding a field + * `value` which holds the custom JSON in addition to the `@type` + * field. Example (for message {@link google.protobuf.Duration}): + * + * { + * "@type": "type.googleapis.com/google.protobuf.Duration", + * "value": "1.212s" + * } + * + * @external "google.protobuf.Any" + * @property {string} typeUrl + * A URL/resource name whose content describes the type of the + * serialized protocol buffer message. + * + * For URLs which use the scheme `http`, `https`, or no scheme, the + * following restrictions and interpretations apply: + * + * * If no scheme is provided, `https` is assumed. + * * The last segment of the URL's path must represent the fully + * qualified name of the type (as in `path/google.protobuf.Duration`). + * The name should be in a canonical form (e.g., leading "." is + * not accepted). + * * An HTTP GET on the URL must yield a {@link google.protobuf.Type} + * value in binary format, or produce an error. + * * Applications are allowed to cache lookup results based on the + * URL, or have them precompiled into a binary to avoid any + * lookup. Therefore, binary compatibility needs to be preserved + * on changes to types. (Use versioned type names to manage + * breaking changes.) + * + * Schemes other than `http`, `https` (or the empty scheme) might be + * used with implementation specific semantics. + * + * @property {string} value + * Must be a valid serialized protocol buffer of the above specified type. + * + * @see [google.protobuf.Any definition in proto format]{@link https://github.com/google/protobuf/blob/master/src/google/protobuf/any.proto} + */ \ No newline at end of file diff --git a/packages/spanner/src/admin/database/v1/doc/doc_google_rpc_status.js b/packages/spanner/src/admin/database/v1/doc/doc_google_rpc_status.js new file mode 100644 index 00000000000..c85f1befe90 --- /dev/null +++ b/packages/spanner/src/admin/database/v1/doc/doc_google_rpc_status.js @@ -0,0 +1,92 @@ +/* + * Copyright 2017, Google Inc. All rights reserved. + * + * 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. + */ + +/* + * Note: this file is purely for documentation. Any contents are not expected + * to be loaded as the JS file. + */ + +/** + * The `Status` type defines a logical error model that is suitable for different + * programming environments, including REST APIs and RPC APIs. It is used by + * [gRPC](https://github.com/grpc). The error model is designed to be: + * + * - Simple to use and understand for most users + * - Flexible enough to meet unexpected needs + * + * # Overview + * + * The `Status` message contains three pieces of data: error code, error message, + * and error details. The error code should be an enum value of + * {@link google.rpc.Code}, but it may accept additional error codes if needed. The + * error message should be a developer-facing English message that helps + * developers *understand* and *resolve* the error. If a localized user-facing + * error message is needed, put the localized message in the error details or + * localize it in the client. The optional error details may contain arbitrary + * information about the error. There is a predefined set of error detail types + * in the package `google.rpc` which can be used for common error conditions. + * + * # Language mapping + * + * The `Status` message is the logical representation of the error model, but it + * is not necessarily the actual wire format. When the `Status` message is + * exposed in different client libraries and different wire protocols, it can be + * mapped differently. For example, it will likely be mapped to some exceptions + * in Java, but more likely mapped to some error codes in C. + * + * # Other uses + * + * The error model and the `Status` message can be used in a variety of + * environments, either with or without APIs, to provide a + * consistent developer experience across different environments. + * + * Example uses of this error model include: + * + * - Partial errors. If a service needs to return partial errors to the client, + * it may embed the `Status` in the normal response to indicate the partial + * errors. + * + * - Workflow errors. A typical workflow has multiple steps. Each step may + * have a `Status` message for error reporting purpose. + * + * - Batch operations. If a client uses batch request and batch response, the + * `Status` message should be used directly inside batch response, one for + * each error sub-response. + * + * - Asynchronous operations. If an API call embeds asynchronous operation + * results in its response, the status of those operations should be + * represented directly using the `Status` message. + * + * - Logging. If some API errors are stored in logs, the message `Status` could + * be used directly after any stripping needed for security/privacy reasons. + * + * @external "google.rpc.Status" + * @property {number} code + * The status code, which should be an enum value of {@link google.rpc.Code}. + * + * @property {string} message + * A developer-facing error message, which should be in English. Any + * user-facing error message should be localized and sent in the + * {@link google.rpc.Status.details} field, or localized by the client. + * + * @property {Object[]} details + * A list of messages that carry the error details. There will be a + * common set of message types for APIs to use. + * + * This object should have the same structure as [google.protobuf.Any]{@link external:"google.protobuf.Any"} + * + * @see [google.rpc.Status definition in proto format]{@link https://github.com/googleapis/googleapis/blob/master/google/rpc/status.proto} + */ \ No newline at end of file diff --git a/packages/spanner/src/admin/database/v1/doc/doc_policy.js b/packages/spanner/src/admin/database/v1/doc/doc_policy.js new file mode 100644 index 00000000000..d42c7352569 --- /dev/null +++ b/packages/spanner/src/admin/database/v1/doc/doc_policy.js @@ -0,0 +1,185 @@ +/* + * Copyright 2017, Google Inc. All rights reserved. + * + * 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. + */ + +/* + * Note: this file is purely for documentation. Any contents are not expected + * to be loaded as the JS file. + */ + +/** + * Defines an Identity and Access Management (IAM) policy. It is used to + * specify access control policies for Cloud Platform resources. + * + * + * A `Policy` consists of a list of `bindings`. A `Binding` binds a list of + * `members` to a `role`, where the members can be user accounts, Google groups, + * Google domains, and service accounts. A `role` is a named list of permissions + * defined by IAM. + * + * **Example** + * + * { + * "bindings": [ + * { + * "role": "roles/owner", + * "members": [ + * "user:mike@example.com", + * "group:admins@example.com", + * "domain:google.com", + * "serviceAccount:my-other-app@appspot.gserviceaccount.com", + * ] + * }, + * { + * "role": "roles/viewer", + * "members": ["user:sean@example.com"] + * } + * ] + * } + * + * For a description of IAM and its features, see the + * [IAM developer's guide](https://cloud.google.com/iam). + * + * @property {number} version + * Version of the `Policy`. The default version is 0. + * + * @property {Object[]} bindings + * Associates a list of `members` to a `role`. + * Multiple `bindings` must not be specified for the same `role`. + * `bindings` with no members will result in an error. + * + * This object should have the same structure as [Binding]{@link Binding} + * + * @property {string} etag + * `etag` is used for optimistic concurrency control as a way to help + * prevent simultaneous updates of a policy from overwriting each other. + * It is strongly suggested that systems make use of the `etag` in the + * read-modify-write cycle to perform policy updates in order to avoid race + * conditions: An `etag` is returned in the response to `getIamPolicy`, and + * systems are expected to put that etag in the request to `setIamPolicy` to + * ensure that their change will be applied to the same version of the policy. + * + * If no `etag` is provided in the call to `setIamPolicy`, then the existing + * policy is overwritten blindly. + * + * @class + * @see [google.iam.v1.Policy definition in proto format]{@link https://github.com/googleapis/googleapis/blob/master/google/iam/v1/policy.proto} + */ +var Policy = { + // This is for documentation. Actual contents will be loaded by gRPC. +}; + +/** + * Associates `members` with a `role`. + * + * @property {string} role + * Role that is assigned to `members`. + * For example, `roles/viewer`, `roles/editor`, or `roles/owner`. + * Required + * + * @property {string[]} members + * Specifies the identities requesting access for a Cloud Platform resource. + * `members` can have the following values: + * + * * `allUsers`: A special identifier that represents anyone who is + * on the internet; with or without a Google account. + * + * * `allAuthenticatedUsers`: A special identifier that represents anyone + * who is authenticated with a Google account or a service account. + * + * * `user:{emailid}`: An email address that represents a specific Google + * account. For example, `alice@gmail.com` or `joe@example.com`. + * + * + * * `serviceAccount:{emailid}`: An email address that represents a service + * account. For example, `my-other-app@appspot.gserviceaccount.com`. + * + * * `group:{emailid}`: An email address that represents a Google group. + * For example, `admins@example.com`. + * + * * `domain:{domain}`: A Google Apps domain name that represents all the + * users of that domain. For example, `google.com` or `example.com`. + * + * @class + * @see [google.iam.v1.Binding definition in proto format]{@link https://github.com/googleapis/googleapis/blob/master/google/iam/v1/policy.proto} + */ +var Binding = { + // This is for documentation. Actual contents will be loaded by gRPC. +}; + +/** + * The difference delta between two policies. + * + * @property {Object[]} bindingDeltas + * The delta for Bindings between two policies. + * + * This object should have the same structure as [BindingDelta]{@link BindingDelta} + * + * @class + * @see [google.iam.v1.PolicyDelta definition in proto format]{@link https://github.com/googleapis/googleapis/blob/master/google/iam/v1/policy.proto} + */ +var PolicyDelta = { + // This is for documentation. Actual contents will be loaded by gRPC. +}; + +/** + * One delta entry for Binding. Each individual change (only one member in each + * entry) to a binding will be a separate entry. + * + * @property {number} action + * The action that was performed on a Binding. + * Required + * + * The number should be among the values of [Action]{@link Action} + * + * @property {string} role + * Role that is assigned to `members`. + * For example, `roles/viewer`, `roles/editor`, or `roles/owner`. + * Required + * + * @property {string} member + * A single identity requesting access for a Cloud Platform resource. + * Follows the same format of Binding.members. + * Required + * + * @class + * @see [google.iam.v1.BindingDelta definition in proto format]{@link https://github.com/googleapis/googleapis/blob/master/google/iam/v1/policy.proto} + */ +var BindingDelta = { + // This is for documentation. Actual contents will be loaded by gRPC. + + /** + * The type of action performed on a Binding in a policy. + * + * @enum {number} + */ + Action: { + + /** + * Unspecified. + */ + ACTION_UNSPECIFIED: 0, + + /** + * Addition of a Binding. + */ + ADD: 1, + + /** + * Removal of a Binding. + */ + REMOVE: 2 + } +}; \ No newline at end of file diff --git a/packages/spanner/src/admin/database/v1/doc/doc_spanner_database_admin.js b/packages/spanner/src/admin/database/v1/doc/doc_spanner_database_admin.js new file mode 100644 index 00000000000..13ad17bd3e1 --- /dev/null +++ b/packages/spanner/src/admin/database/v1/doc/doc_spanner_database_admin.js @@ -0,0 +1,279 @@ +/* + * Copyright 2017, Google Inc. All rights reserved. + * + * 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. + */ + +/* + * Note: this file is purely for documentation. Any contents are not expected + * to be loaded as the JS file. + */ + +/** + * A Cloud Spanner database. + * + * @property {string} name + * Required. The name of the database. Values are of the form + * `projects//instances//databases/`, + * where `` is as specified in the `CREATE DATABASE` + * statement. This name can be passed to other API methods to + * identify the database. + * + * @property {number} state + * Output only. The current database state. + * + * The number should be among the values of [State]{@link State} + * + * @class + * @see [google.spanner.admin.database.v1.Database definition in proto format]{@link https://github.com/googleapis/googleapis/blob/master/google/spanner/admin/database/v1/spanner_database_admin.proto} + */ +var Database = { + // This is for documentation. Actual contents will be loaded by gRPC. + + /** + * Indicates the current state of the database. + * + * @enum {number} + */ + State: { + + /** + * Not specified. + */ + STATE_UNSPECIFIED: 0, + + /** + * The database is still being created. Operations on the database may fail + * with `FAILED_PRECONDITION` in this state. + */ + CREATING: 1, + + /** + * The database is fully created and ready for use. + */ + READY: 2 + } +}; + +/** + * The request for {@link ListDatabases}. + * + * @property {string} parent + * Required. The instance whose databases should be listed. + * Values are of the form `projects//instances/`. + * + * @property {number} pageSize + * Number of databases to be returned in the response. If 0 or less, + * defaults to the server's maximum allowed page size. + * + * @property {string} pageToken + * If non-empty, `page_token` should contain a + * {@link next_page_token} from a + * previous {@link ListDatabasesResponse}. + * + * @class + * @see [google.spanner.admin.database.v1.ListDatabasesRequest definition in proto format]{@link https://github.com/googleapis/googleapis/blob/master/google/spanner/admin/database/v1/spanner_database_admin.proto} + */ +var ListDatabasesRequest = { + // This is for documentation. Actual contents will be loaded by gRPC. +}; + +/** + * The response for {@link ListDatabases}. + * + * @property {Object[]} databases + * Databases that matched the request. + * + * This object should have the same structure as [Database]{@link Database} + * + * @property {string} nextPageToken + * `next_page_token` can be sent in a subsequent + * {@link ListDatabases} call to fetch more + * of the matching databases. + * + * @class + * @see [google.spanner.admin.database.v1.ListDatabasesResponse definition in proto format]{@link https://github.com/googleapis/googleapis/blob/master/google/spanner/admin/database/v1/spanner_database_admin.proto} + */ +var ListDatabasesResponse = { + // This is for documentation. Actual contents will be loaded by gRPC. +}; + +/** + * The request for {@link CreateDatabase}. + * + * @property {string} parent + * Required. The name of the instance that will serve the new database. + * Values are of the form `projects//instances/`. + * + * @property {string} createStatement + * Required. A `CREATE DATABASE` statement, which specifies the ID of the + * new database. The database ID must conform to the regular expression + * `[a-z][a-z0-9_\-]*[a-z0-9]` and be between 2 and 30 characters in length. + * + * @property {string[]} extraStatements + * An optional list of DDL statements to run inside the newly created + * database. Statements can create tables, indexes, etc. These + * statements execute atomically with the creation of the database: + * if there is an error in any statement, the database is not created. + * + * @class + * @see [google.spanner.admin.database.v1.CreateDatabaseRequest definition in proto format]{@link https://github.com/googleapis/googleapis/blob/master/google/spanner/admin/database/v1/spanner_database_admin.proto} + */ +var CreateDatabaseRequest = { + // This is for documentation. Actual contents will be loaded by gRPC. +}; + +/** + * Metadata type for the operation returned by + * {@link CreateDatabase}. + * + * @property {string} database + * The database being created. + * + * @class + * @see [google.spanner.admin.database.v1.CreateDatabaseMetadata definition in proto format]{@link https://github.com/googleapis/googleapis/blob/master/google/spanner/admin/database/v1/spanner_database_admin.proto} + */ +var CreateDatabaseMetadata = { + // This is for documentation. Actual contents will be loaded by gRPC. +}; + +/** + * The request for {@link GetDatabase}. + * + * @property {string} name + * Required. The name of the requested database. Values are of the form + * `projects//instances//databases/`. + * + * @class + * @see [google.spanner.admin.database.v1.GetDatabaseRequest definition in proto format]{@link https://github.com/googleapis/googleapis/blob/master/google/spanner/admin/database/v1/spanner_database_admin.proto} + */ +var GetDatabaseRequest = { + // This is for documentation. Actual contents will be loaded by gRPC. +}; + +/** + * Enqueues the given DDL statements to be applied, in order but not + * necessarily all at once, to the database schema at some point (or + * points) in the future. The server checks that the statements + * are executable (syntactically valid, name tables that exist, etc.) + * before enqueueing them, but they may still fail upon + * later execution (e.g., if a statement from another batch of + * statements is applied first and it conflicts in some way, or if + * there is some data-related problem like a `NULL` value in a column to + * which `NOT NULL` would be added). If a statement fails, all + * subsequent statements in the batch are automatically cancelled. + * + * Each batch of statements is assigned a name which can be used with + * the {@link Operations} API to monitor + * progress. See the + * {@link operation_id} field for more + * details. + * + * @property {string} database + * Required. The database to update. + * + * @property {string[]} statements + * DDL statements to be applied to the database. + * + * @property {string} operationId + * If empty, the new update request is assigned an + * automatically-generated operation ID. Otherwise, `operation_id` + * is used to construct the name of the resulting + * {@link Operation}. + * + * Specifying an explicit operation ID simplifies determining + * whether the statements were executed in the event that the + * {@link UpdateDatabaseDdl} call is replayed, + * or the return value is otherwise lost: the {@link database} and + * `operation_id` fields can be combined to form the + * {@link name} of the resulting + * {@link longrunning.Operation}: `/operations/`. + * + * `operation_id` should be unique within the database, and must be + * a valid identifier: `[a-z][a-z0-9_]*`. Note that + * automatically-generated operation IDs always begin with an + * underscore. If the named operation already exists, + * {@link UpdateDatabaseDdl} returns + * `ALREADY_EXISTS`. + * + * @class + * @see [google.spanner.admin.database.v1.UpdateDatabaseDdlRequest definition in proto format]{@link https://github.com/googleapis/googleapis/blob/master/google/spanner/admin/database/v1/spanner_database_admin.proto} + */ +var UpdateDatabaseDdlRequest = { + // This is for documentation. Actual contents will be loaded by gRPC. +}; + +/** + * Metadata type for the operation returned by + * {@link UpdateDatabaseDdl}. + * + * @property {string} database + * The database being modified. + * + * @property {string[]} statements + * For an update this list contains all the statements. For an + * individual statement, this list contains only that statement. + * + * @property {Object[]} commitTimestamps + * Reports the commit timestamps of all statements that have + * succeeded so far, where `commit_timestamps[i]` is the commit + * timestamp for the statement `statements[i]`. + * + * This object should have the same structure as [google.protobuf.Timestamp]{@link external:"google.protobuf.Timestamp"} + * + * @class + * @see [google.spanner.admin.database.v1.UpdateDatabaseDdlMetadata definition in proto format]{@link https://github.com/googleapis/googleapis/blob/master/google/spanner/admin/database/v1/spanner_database_admin.proto} + */ +var UpdateDatabaseDdlMetadata = { + // This is for documentation. Actual contents will be loaded by gRPC. +}; + +/** + * The request for {@link DropDatabase}. + * + * @property {string} database + * Required. The database to be dropped. + * + * @class + * @see [google.spanner.admin.database.v1.DropDatabaseRequest definition in proto format]{@link https://github.com/googleapis/googleapis/blob/master/google/spanner/admin/database/v1/spanner_database_admin.proto} + */ +var DropDatabaseRequest = { + // This is for documentation. Actual contents will be loaded by gRPC. +}; + +/** + * The request for {@link GetDatabaseDdl}. + * + * @property {string} database + * Required. The database whose schema we wish to get. + * + * @class + * @see [google.spanner.admin.database.v1.GetDatabaseDdlRequest definition in proto format]{@link https://github.com/googleapis/googleapis/blob/master/google/spanner/admin/database/v1/spanner_database_admin.proto} + */ +var GetDatabaseDdlRequest = { + // This is for documentation. Actual contents will be loaded by gRPC. +}; + +/** + * The response for {@link GetDatabaseDdl}. + * + * @property {string[]} statements + * A list of formatted DDL statements defining the schema of the database + * specified in the request. + * + * @class + * @see [google.spanner.admin.database.v1.GetDatabaseDdlResponse definition in proto format]{@link https://github.com/googleapis/googleapis/blob/master/google/spanner/admin/database/v1/spanner_database_admin.proto} + */ +var GetDatabaseDdlResponse = { + // This is for documentation. Actual contents will be loaded by gRPC. +}; \ No newline at end of file diff --git a/packages/spanner/src/admin/instance/v1/doc/doc_google_protobuf_any.js b/packages/spanner/src/admin/instance/v1/doc/doc_google_protobuf_any.js new file mode 100644 index 00000000000..0697ec15814 --- /dev/null +++ b/packages/spanner/src/admin/instance/v1/doc/doc_google_protobuf_any.js @@ -0,0 +1,121 @@ +/* + * Copyright 2017, Google Inc. All rights reserved. + * + * 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. + */ + +/* + * Note: this file is purely for documentation. Any contents are not expected + * to be loaded as the JS file. + */ + +/** + * `Any` contains an arbitrary serialized protocol buffer message along with a + * URL that describes the type of the serialized message. + * + * Protobuf library provides support to pack/unpack Any values in the form + * of utility functions or additional generated methods of the Any type. + * + * Example 1: Pack and unpack a message in C++. + * + * Foo foo = ...; + * Any any; + * any.PackFrom(foo); + * ... + * if (any.UnpackTo(&foo)) { + * ... + * } + * + * Example 2: Pack and unpack a message in Java. + * + * Foo foo = ...; + * Any any = Any.pack(foo); + * ... + * if (any.is(Foo.class)) { + * foo = any.unpack(Foo.class); + * } + * + * Example 3: Pack and unpack a message in Python. + * + * foo = Foo(...) + * any = Any() + * any.Pack(foo) + * ... + * if any.Is(Foo.DESCRIPTOR): + * any.Unpack(foo) + * ... + * + * The pack methods provided by protobuf library will by default use + * 'type.googleapis.com/full.type.name' as the type URL and the unpack + * methods only use the fully qualified type name after the last '/' + * in the type URL, for example "foo.bar.com/x/y.z" will yield type + * name "y.z". + * + * + * # JSON + * + * The JSON representation of an `Any` value uses the regular + * representation of the deserialized, embedded message, with an + * additional field `@type` which contains the type URL. Example: + * + * package google.profile; + * message Person { + * string first_name = 1; + * string last_name = 2; + * } + * + * { + * "@type": "type.googleapis.com/google.profile.Person", + * "firstName": , + * "lastName": + * } + * + * If the embedded message type is well-known and has a custom JSON + * representation, that representation will be embedded adding a field + * `value` which holds the custom JSON in addition to the `@type` + * field. Example (for message {@link google.protobuf.Duration}): + * + * { + * "@type": "type.googleapis.com/google.protobuf.Duration", + * "value": "1.212s" + * } + * + * @external "google.protobuf.Any" + * @property {string} typeUrl + * A URL/resource name whose content describes the type of the + * serialized protocol buffer message. + * + * For URLs which use the scheme `http`, `https`, or no scheme, the + * following restrictions and interpretations apply: + * + * * If no scheme is provided, `https` is assumed. + * * The last segment of the URL's path must represent the fully + * qualified name of the type (as in `path/google.protobuf.Duration`). + * The name should be in a canonical form (e.g., leading "." is + * not accepted). + * * An HTTP GET on the URL must yield a {@link google.protobuf.Type} + * value in binary format, or produce an error. + * * Applications are allowed to cache lookup results based on the + * URL, or have them precompiled into a binary to avoid any + * lookup. Therefore, binary compatibility needs to be preserved + * on changes to types. (Use versioned type names to manage + * breaking changes.) + * + * Schemes other than `http`, `https` (or the empty scheme) might be + * used with implementation specific semantics. + * + * @property {string} value + * Must be a valid serialized protocol buffer of the above specified type. + * + * @see [google.protobuf.Any definition in proto format]{@link https://github.com/google/protobuf/blob/master/src/google/protobuf/any.proto} + */ \ No newline at end of file diff --git a/packages/spanner/src/admin/instance/v1/doc/doc_google_protobuf_field_mask.js b/packages/spanner/src/admin/instance/v1/doc/doc_google_protobuf_field_mask.js new file mode 100644 index 00000000000..db0cea463fe --- /dev/null +++ b/packages/spanner/src/admin/instance/v1/doc/doc_google_protobuf_field_mask.js @@ -0,0 +1,230 @@ +/* + * Copyright 2017, Google Inc. All rights reserved. + * + * 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. + */ + +/* + * Note: this file is purely for documentation. Any contents are not expected + * to be loaded as the JS file. + */ + +/** + * `FieldMask` represents a set of symbolic field paths, for example: + * + * paths: "f.a" + * paths: "f.b.d" + * + * Here `f` represents a field in some root message, `a` and `b` + * fields in the message found in `f`, and `d` a field found in the + * message in `f.b`. + * + * Field masks are used to specify a subset of fields that should be + * returned by a get operation or modified by an update operation. + * Field masks also have a custom JSON encoding (see below). + * + * # Field Masks in Projections + * + * When used in the context of a projection, a response message or + * sub-message is filtered by the API to only contain those fields as + * specified in the mask. For example, if the mask in the previous + * example is applied to a response message as follows: + * + * f { + * a : 22 + * b { + * d : 1 + * x : 2 + * } + * y : 13 + * } + * z: 8 + * + * The result will not contain specific values for fields x,y and z + * (their value will be set to the default, and omitted in proto text + * output): + * + * + * f { + * a : 22 + * b { + * d : 1 + * } + * } + * + * A repeated field is not allowed except at the last position of a + * paths string. + * + * If a FieldMask object is not present in a get operation, the + * operation applies to all fields (as if a FieldMask of all fields + * had been specified). + * + * Note that a field mask does not necessarily apply to the + * top-level response message. In case of a REST get operation, the + * field mask applies directly to the response, but in case of a REST + * list operation, the mask instead applies to each individual message + * in the returned resource list. In case of a REST custom method, + * other definitions may be used. Where the mask applies will be + * clearly documented together with its declaration in the API. In + * any case, the effect on the returned resource/resources is required + * behavior for APIs. + * + * # Field Masks in Update Operations + * + * A field mask in update operations specifies which fields of the + * targeted resource are going to be updated. The API is required + * to only change the values of the fields as specified in the mask + * and leave the others untouched. If a resource is passed in to + * describe the updated values, the API ignores the values of all + * fields not covered by the mask. + * + * If a repeated field is specified for an update operation, the existing + * repeated values in the target resource will be overwritten by the new values. + * Note that a repeated field is only allowed in the last position of a `paths` + * string. + * + * If a sub-message is specified in the last position of the field mask for an + * update operation, then the existing sub-message in the target resource is + * overwritten. Given the target message: + * + * f { + * b { + * d : 1 + * x : 2 + * } + * c : 1 + * } + * + * And an update message: + * + * f { + * b { + * d : 10 + * } + * } + * + * then if the field mask is: + * + * paths: "f.b" + * + * then the result will be: + * + * f { + * b { + * d : 10 + * } + * c : 1 + * } + * + * However, if the update mask was: + * + * paths: "f.b.d" + * + * then the result would be: + * + * f { + * b { + * d : 10 + * x : 2 + * } + * c : 1 + * } + * + * In order to reset a field's value to the default, the field must + * be in the mask and set to the default value in the provided resource. + * Hence, in order to reset all fields of a resource, provide a default + * instance of the resource and set all fields in the mask, or do + * not provide a mask as described below. + * + * If a field mask is not present on update, the operation applies to + * all fields (as if a field mask of all fields has been specified). + * Note that in the presence of schema evolution, this may mean that + * fields the client does not know and has therefore not filled into + * the request will be reset to their default. If this is unwanted + * behavior, a specific service may require a client to always specify + * a field mask, producing an error if not. + * + * As with get operations, the location of the resource which + * describes the updated values in the request message depends on the + * operation kind. In any case, the effect of the field mask is + * required to be honored by the API. + * + * ## Considerations for HTTP REST + * + * The HTTP kind of an update operation which uses a field mask must + * be set to PATCH instead of PUT in order to satisfy HTTP semantics + * (PUT must only be used for full updates). + * + * # JSON Encoding of Field Masks + * + * In JSON, a field mask is encoded as a single string where paths are + * separated by a comma. Fields name in each path are converted + * to/from lower-camel naming conventions. + * + * As an example, consider the following message declarations: + * + * message Profile { + * User user = 1; + * Photo photo = 2; + * } + * message User { + * string display_name = 1; + * string address = 2; + * } + * + * In proto a field mask for `Profile` may look as such: + * + * mask { + * paths: "user.display_name" + * paths: "photo" + * } + * + * In JSON, the same mask is represented as below: + * + * { + * mask: "user.displayName,photo" + * } + * + * # Field Masks and Oneof Fields + * + * Field masks treat fields in oneofs just as regular fields. Consider the + * following message: + * + * message SampleMessage { + * oneof test_oneof { + * string name = 4; + * SubMessage sub_message = 9; + * } + * } + * + * The field mask can be: + * + * mask { + * paths: "name" + * } + * + * Or: + * + * mask { + * paths: "sub_message" + * } + * + * Note that oneof type names ("test_oneof" in this case) cannot be used in + * paths. + * + * @external "google.protobuf.FieldMask" + * @property {string[]} paths + * The set of field mask paths. + * + * @see [google.protobuf.FieldMask definition in proto format]{@link https://github.com/google/protobuf/blob/master/src/google/protobuf/field_mask.proto} + */ \ No newline at end of file diff --git a/packages/spanner/src/admin/instance/v1/doc/doc_google_rpc_status.js b/packages/spanner/src/admin/instance/v1/doc/doc_google_rpc_status.js new file mode 100644 index 00000000000..c85f1befe90 --- /dev/null +++ b/packages/spanner/src/admin/instance/v1/doc/doc_google_rpc_status.js @@ -0,0 +1,92 @@ +/* + * Copyright 2017, Google Inc. All rights reserved. + * + * 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. + */ + +/* + * Note: this file is purely for documentation. Any contents are not expected + * to be loaded as the JS file. + */ + +/** + * The `Status` type defines a logical error model that is suitable for different + * programming environments, including REST APIs and RPC APIs. It is used by + * [gRPC](https://github.com/grpc). The error model is designed to be: + * + * - Simple to use and understand for most users + * - Flexible enough to meet unexpected needs + * + * # Overview + * + * The `Status` message contains three pieces of data: error code, error message, + * and error details. The error code should be an enum value of + * {@link google.rpc.Code}, but it may accept additional error codes if needed. The + * error message should be a developer-facing English message that helps + * developers *understand* and *resolve* the error. If a localized user-facing + * error message is needed, put the localized message in the error details or + * localize it in the client. The optional error details may contain arbitrary + * information about the error. There is a predefined set of error detail types + * in the package `google.rpc` which can be used for common error conditions. + * + * # Language mapping + * + * The `Status` message is the logical representation of the error model, but it + * is not necessarily the actual wire format. When the `Status` message is + * exposed in different client libraries and different wire protocols, it can be + * mapped differently. For example, it will likely be mapped to some exceptions + * in Java, but more likely mapped to some error codes in C. + * + * # Other uses + * + * The error model and the `Status` message can be used in a variety of + * environments, either with or without APIs, to provide a + * consistent developer experience across different environments. + * + * Example uses of this error model include: + * + * - Partial errors. If a service needs to return partial errors to the client, + * it may embed the `Status` in the normal response to indicate the partial + * errors. + * + * - Workflow errors. A typical workflow has multiple steps. Each step may + * have a `Status` message for error reporting purpose. + * + * - Batch operations. If a client uses batch request and batch response, the + * `Status` message should be used directly inside batch response, one for + * each error sub-response. + * + * - Asynchronous operations. If an API call embeds asynchronous operation + * results in its response, the status of those operations should be + * represented directly using the `Status` message. + * + * - Logging. If some API errors are stored in logs, the message `Status` could + * be used directly after any stripping needed for security/privacy reasons. + * + * @external "google.rpc.Status" + * @property {number} code + * The status code, which should be an enum value of {@link google.rpc.Code}. + * + * @property {string} message + * A developer-facing error message, which should be in English. Any + * user-facing error message should be localized and sent in the + * {@link google.rpc.Status.details} field, or localized by the client. + * + * @property {Object[]} details + * A list of messages that carry the error details. There will be a + * common set of message types for APIs to use. + * + * This object should have the same structure as [google.protobuf.Any]{@link external:"google.protobuf.Any"} + * + * @see [google.rpc.Status definition in proto format]{@link https://github.com/googleapis/googleapis/blob/master/google/rpc/status.proto} + */ \ No newline at end of file diff --git a/packages/spanner/src/admin/instance/v1/doc/doc_policy.js b/packages/spanner/src/admin/instance/v1/doc/doc_policy.js new file mode 100644 index 00000000000..d42c7352569 --- /dev/null +++ b/packages/spanner/src/admin/instance/v1/doc/doc_policy.js @@ -0,0 +1,185 @@ +/* + * Copyright 2017, Google Inc. All rights reserved. + * + * 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. + */ + +/* + * Note: this file is purely for documentation. Any contents are not expected + * to be loaded as the JS file. + */ + +/** + * Defines an Identity and Access Management (IAM) policy. It is used to + * specify access control policies for Cloud Platform resources. + * + * + * A `Policy` consists of a list of `bindings`. A `Binding` binds a list of + * `members` to a `role`, where the members can be user accounts, Google groups, + * Google domains, and service accounts. A `role` is a named list of permissions + * defined by IAM. + * + * **Example** + * + * { + * "bindings": [ + * { + * "role": "roles/owner", + * "members": [ + * "user:mike@example.com", + * "group:admins@example.com", + * "domain:google.com", + * "serviceAccount:my-other-app@appspot.gserviceaccount.com", + * ] + * }, + * { + * "role": "roles/viewer", + * "members": ["user:sean@example.com"] + * } + * ] + * } + * + * For a description of IAM and its features, see the + * [IAM developer's guide](https://cloud.google.com/iam). + * + * @property {number} version + * Version of the `Policy`. The default version is 0. + * + * @property {Object[]} bindings + * Associates a list of `members` to a `role`. + * Multiple `bindings` must not be specified for the same `role`. + * `bindings` with no members will result in an error. + * + * This object should have the same structure as [Binding]{@link Binding} + * + * @property {string} etag + * `etag` is used for optimistic concurrency control as a way to help + * prevent simultaneous updates of a policy from overwriting each other. + * It is strongly suggested that systems make use of the `etag` in the + * read-modify-write cycle to perform policy updates in order to avoid race + * conditions: An `etag` is returned in the response to `getIamPolicy`, and + * systems are expected to put that etag in the request to `setIamPolicy` to + * ensure that their change will be applied to the same version of the policy. + * + * If no `etag` is provided in the call to `setIamPolicy`, then the existing + * policy is overwritten blindly. + * + * @class + * @see [google.iam.v1.Policy definition in proto format]{@link https://github.com/googleapis/googleapis/blob/master/google/iam/v1/policy.proto} + */ +var Policy = { + // This is for documentation. Actual contents will be loaded by gRPC. +}; + +/** + * Associates `members` with a `role`. + * + * @property {string} role + * Role that is assigned to `members`. + * For example, `roles/viewer`, `roles/editor`, or `roles/owner`. + * Required + * + * @property {string[]} members + * Specifies the identities requesting access for a Cloud Platform resource. + * `members` can have the following values: + * + * * `allUsers`: A special identifier that represents anyone who is + * on the internet; with or without a Google account. + * + * * `allAuthenticatedUsers`: A special identifier that represents anyone + * who is authenticated with a Google account or a service account. + * + * * `user:{emailid}`: An email address that represents a specific Google + * account. For example, `alice@gmail.com` or `joe@example.com`. + * + * + * * `serviceAccount:{emailid}`: An email address that represents a service + * account. For example, `my-other-app@appspot.gserviceaccount.com`. + * + * * `group:{emailid}`: An email address that represents a Google group. + * For example, `admins@example.com`. + * + * * `domain:{domain}`: A Google Apps domain name that represents all the + * users of that domain. For example, `google.com` or `example.com`. + * + * @class + * @see [google.iam.v1.Binding definition in proto format]{@link https://github.com/googleapis/googleapis/blob/master/google/iam/v1/policy.proto} + */ +var Binding = { + // This is for documentation. Actual contents will be loaded by gRPC. +}; + +/** + * The difference delta between two policies. + * + * @property {Object[]} bindingDeltas + * The delta for Bindings between two policies. + * + * This object should have the same structure as [BindingDelta]{@link BindingDelta} + * + * @class + * @see [google.iam.v1.PolicyDelta definition in proto format]{@link https://github.com/googleapis/googleapis/blob/master/google/iam/v1/policy.proto} + */ +var PolicyDelta = { + // This is for documentation. Actual contents will be loaded by gRPC. +}; + +/** + * One delta entry for Binding. Each individual change (only one member in each + * entry) to a binding will be a separate entry. + * + * @property {number} action + * The action that was performed on a Binding. + * Required + * + * The number should be among the values of [Action]{@link Action} + * + * @property {string} role + * Role that is assigned to `members`. + * For example, `roles/viewer`, `roles/editor`, or `roles/owner`. + * Required + * + * @property {string} member + * A single identity requesting access for a Cloud Platform resource. + * Follows the same format of Binding.members. + * Required + * + * @class + * @see [google.iam.v1.BindingDelta definition in proto format]{@link https://github.com/googleapis/googleapis/blob/master/google/iam/v1/policy.proto} + */ +var BindingDelta = { + // This is for documentation. Actual contents will be loaded by gRPC. + + /** + * The type of action performed on a Binding in a policy. + * + * @enum {number} + */ + Action: { + + /** + * Unspecified. + */ + ACTION_UNSPECIFIED: 0, + + /** + * Addition of a Binding. + */ + ADD: 1, + + /** + * Removal of a Binding. + */ + REMOVE: 2 + } +}; \ No newline at end of file diff --git a/packages/spanner/src/admin/instance/v1/doc/doc_spanner_instance_admin.js b/packages/spanner/src/admin/instance/v1/doc/doc_spanner_instance_admin.js new file mode 100644 index 00000000000..821ee0e278b --- /dev/null +++ b/packages/spanner/src/admin/instance/v1/doc/doc_spanner_instance_admin.js @@ -0,0 +1,395 @@ +/* + * Copyright 2017, Google Inc. All rights reserved. + * + * 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. + */ + +/* + * Note: this file is purely for documentation. Any contents are not expected + * to be loaded as the JS file. + */ + +/** + * A possible configuration for a Cloud Spanner instance. Configurations + * define the geographic placement of nodes and their replication. + * + * @property {string} name + * A unique identifier for the instance configuration. Values + * are of the form + * `projects//instanceConfigs/[a-z][-a-z0-9]*` + * + * @property {string} displayName + * The name of this instance configuration as it appears in UIs. + * + * @class + * @see [google.spanner.admin.instance.v1.InstanceConfig definition in proto format]{@link https://github.com/googleapis/googleapis/blob/master/google/spanner/admin/instance/v1/spanner_instance_admin.proto} + */ +var InstanceConfig = { + // This is for documentation. Actual contents will be loaded by gRPC. +}; + +/** + * An isolated set of Cloud Spanner resources on which databases can be hosted. + * + * @property {string} name + * Required. A unique identifier for the instance, which cannot be changed + * after the instance is created. Values are of the form + * `projects//instances/[a-z][-a-z0-9]*[a-z0-9]`. The final + * segment of the name must be between 6 and 30 characters in length. + * + * @property {string} config + * Required. The name of the instance's configuration. Values are of the form + * `projects//instanceConfigs/`. See + * also {@link InstanceConfig} and + * {@link ListInstanceConfigs}. + * + * @property {string} displayName + * Required. The descriptive name for this instance as it appears in UIs. + * Must be unique per project and between 4 and 30 characters in length. + * + * @property {number} nodeCount + * Required. The number of nodes allocated to this instance. + * + * @property {number} state + * Output only. The current instance state. For + * {@link CreateInstance}, the state must be + * either omitted or set to `CREATING`. For + * {@link UpdateInstance}, the state must be + * either omitted or set to `READY`. + * + * The number should be among the values of [State]{@link State} + * + * @property {Object.} labels + * Cloud Labels are a flexible and lightweight mechanism for organizing cloud + * resources into groups that reflect a customer's organizational needs and + * deployment strategies. Cloud Labels can be used to filter collections of + * resources. They can be used to control how resource metrics are aggregated. + * And they can be used as arguments to policy management rules (e.g. route, + * firewall, load balancing, etc.). + * + * * Label keys must be between 1 and 63 characters long and must conform to + * the following regular expression: `[a-z](https://cloud.google.com[-a-z0-9]*[a-z0-9])?`. + * * Label values must be between 0 and 63 characters long and must conform + * to the regular expression `([a-z](https://cloud.google.com[-a-z0-9]*[a-z0-9])?)?`. + * * No more than 64 labels can be associated with a given resource. + * + * See https://goo.gl/xmQnxf for more information on and examples of labels. + * + * If you plan to use labels in your own code, please note that additional + * characters may be allowed in the future. And so you are advised to use an + * internal label representation, such as JSON, which doesn't rely upon + * specific characters being disallowed. For example, representing labels + * as the string: name + "_" + value would prove problematic if we were to + * allow "_" in a future release. + * + * @class + * @see [google.spanner.admin.instance.v1.Instance definition in proto format]{@link https://github.com/googleapis/googleapis/blob/master/google/spanner/admin/instance/v1/spanner_instance_admin.proto} + */ +var Instance = { + // This is for documentation. Actual contents will be loaded by gRPC. + + /** + * Indicates the current state of the instance. + * + * @enum {number} + */ + State: { + + /** + * Not specified. + */ + STATE_UNSPECIFIED: 0, + + /** + * The instance is still being created. Resources may not be + * available yet, and operations such as database creation may not + * work. + */ + CREATING: 1, + + /** + * The instance is fully created and ready to do work such as + * creating databases. + */ + READY: 2 + } +}; + +/** + * The request for {@link ListInstanceConfigs}. + * + * @property {string} parent + * Required. The name of the project for which a list of supported instance + * configurations is requested. Values are of the form + * `projects/`. + * + * @property {number} pageSize + * Number of instance configurations to be returned in the response. If 0 or + * less, defaults to the server's maximum allowed page size. + * + * @property {string} pageToken + * If non-empty, `page_token` should contain a + * {@link next_page_token} + * from a previous {@link ListInstanceConfigsResponse}. + * + * @class + * @see [google.spanner.admin.instance.v1.ListInstanceConfigsRequest definition in proto format]{@link https://github.com/googleapis/googleapis/blob/master/google/spanner/admin/instance/v1/spanner_instance_admin.proto} + */ +var ListInstanceConfigsRequest = { + // This is for documentation. Actual contents will be loaded by gRPC. +}; + +/** + * The response for {@link ListInstanceConfigs}. + * + * @property {Object[]} instanceConfigs + * The list of requested instance configurations. + * + * This object should have the same structure as [InstanceConfig]{@link InstanceConfig} + * + * @property {string} nextPageToken + * `next_page_token` can be sent in a subsequent + * {@link ListInstanceConfigs} call to + * fetch more of the matching instance configurations. + * + * @class + * @see [google.spanner.admin.instance.v1.ListInstanceConfigsResponse definition in proto format]{@link https://github.com/googleapis/googleapis/blob/master/google/spanner/admin/instance/v1/spanner_instance_admin.proto} + */ +var ListInstanceConfigsResponse = { + // This is for documentation. Actual contents will be loaded by gRPC. +}; + +/** + * The request for + * {@link GetInstanceConfigRequest}. + * + * @property {string} name + * Required. The name of the requested instance configuration. Values are of + * the form `projects//instanceConfigs/`. + * + * @class + * @see [google.spanner.admin.instance.v1.GetInstanceConfigRequest definition in proto format]{@link https://github.com/googleapis/googleapis/blob/master/google/spanner/admin/instance/v1/spanner_instance_admin.proto} + */ +var GetInstanceConfigRequest = { + // This is for documentation. Actual contents will be loaded by gRPC. +}; + +/** + * The request for {@link GetInstance}. + * + * @property {string} name + * Required. The name of the requested instance. Values are of the form + * `projects//instances/`. + * + * @class + * @see [google.spanner.admin.instance.v1.GetInstanceRequest definition in proto format]{@link https://github.com/googleapis/googleapis/blob/master/google/spanner/admin/instance/v1/spanner_instance_admin.proto} + */ +var GetInstanceRequest = { + // This is for documentation. Actual contents will be loaded by gRPC. +}; + +/** + * The request for {@link CreateInstance}. + * + * @property {string} parent + * Required. The name of the project in which to create the instance. Values + * are of the form `projects/`. + * + * @property {string} instanceId + * Required. The ID of the instance to create. Valid identifiers are of the + * form `[a-z][-a-z0-9]*[a-z0-9]` and must be between 6 and 30 characters in + * length. + * + * @property {Object} instance + * Required. The instance to create. The name may be omitted, but if + * specified must be `/instances/`. + * + * This object should have the same structure as [Instance]{@link Instance} + * + * @class + * @see [google.spanner.admin.instance.v1.CreateInstanceRequest definition in proto format]{@link https://github.com/googleapis/googleapis/blob/master/google/spanner/admin/instance/v1/spanner_instance_admin.proto} + */ +var CreateInstanceRequest = { + // This is for documentation. Actual contents will be loaded by gRPC. +}; + +/** + * The request for {@link ListInstances}. + * + * @property {string} parent + * Required. The name of the project for which a list of instances is + * requested. Values are of the form `projects/`. + * + * @property {number} pageSize + * Number of instances to be returned in the response. If 0 or less, defaults + * to the server's maximum allowed page size. + * + * @property {string} pageToken + * If non-empty, `page_token` should contain a + * {@link next_page_token} from a + * previous {@link ListInstancesResponse}. + * + * @property {string} filter + * An expression for filtering the results of the request. Filter rules are + * case insensitive. The fields eligible for filtering are: + * + * * name + * * display_name + * * labels.key where key is the name of a label + * + * Some examples of using filters are: + * + * * name:* --> The instance has a name. + * * name:Howl --> The instance's name contains the string "howl". + * * name:HOWL --> Equivalent to above. + * * NAME:howl --> Equivalent to above. + * * labels.env:* --> The instance has the label "env". + * * labels.env:dev --> The instance has the label "env" and the value of + * the label contains the string "dev". + * * name:howl labels.env:dev --> The instance's name contains "howl" and + * it has the label "env" with its value + * containing "dev". + * + * @class + * @see [google.spanner.admin.instance.v1.ListInstancesRequest definition in proto format]{@link https://github.com/googleapis/googleapis/blob/master/google/spanner/admin/instance/v1/spanner_instance_admin.proto} + */ +var ListInstancesRequest = { + // This is for documentation. Actual contents will be loaded by gRPC. +}; + +/** + * The response for {@link ListInstances}. + * + * @property {Object[]} instances + * The list of requested instances. + * + * This object should have the same structure as [Instance]{@link Instance} + * + * @property {string} nextPageToken + * `next_page_token` can be sent in a subsequent + * {@link ListInstances} call to fetch more + * of the matching instances. + * + * @class + * @see [google.spanner.admin.instance.v1.ListInstancesResponse definition in proto format]{@link https://github.com/googleapis/googleapis/blob/master/google/spanner/admin/instance/v1/spanner_instance_admin.proto} + */ +var ListInstancesResponse = { + // This is for documentation. Actual contents will be loaded by gRPC. +}; + +/** + * The request for {@link UpdateInstance}. + * + * @property {Object} instance + * Required. The instance to update, which must always include the instance + * name. Otherwise, only fields mentioned in [][google.spanner.admin.instance.v1.UpdateInstanceRequest.field_mask] need be included. + * + * This object should have the same structure as [Instance]{@link Instance} + * + * @property {Object} fieldMask + * Required. A mask specifying which fields in [][google.spanner.admin.instance.v1.UpdateInstanceRequest.instance] should be updated. + * The field mask must always be specified; this prevents any future fields in + * [][google.spanner.admin.instance.v1.Instance] from being erased accidentally by clients that do not know + * about them. + * + * This object should have the same structure as [google.protobuf.FieldMask]{@link external:"google.protobuf.FieldMask"} + * + * @class + * @see [google.spanner.admin.instance.v1.UpdateInstanceRequest definition in proto format]{@link https://github.com/googleapis/googleapis/blob/master/google/spanner/admin/instance/v1/spanner_instance_admin.proto} + */ +var UpdateInstanceRequest = { + // This is for documentation. Actual contents will be loaded by gRPC. +}; + +/** + * The request for {@link DeleteInstance}. + * + * @property {string} name + * Required. The name of the instance to be deleted. Values are of the form + * `projects//instances/` + * + * @class + * @see [google.spanner.admin.instance.v1.DeleteInstanceRequest definition in proto format]{@link https://github.com/googleapis/googleapis/blob/master/google/spanner/admin/instance/v1/spanner_instance_admin.proto} + */ +var DeleteInstanceRequest = { + // This is for documentation. Actual contents will be loaded by gRPC. +}; + +/** + * Metadata type for the operation returned by + * {@link CreateInstance}. + * + * @property {Object} instance + * The instance being created. + * + * This object should have the same structure as [Instance]{@link Instance} + * + * @property {Object} startTime + * The time at which the + * {@link CreateInstance} request was + * received. + * + * This object should have the same structure as [google.protobuf.Timestamp]{@link external:"google.protobuf.Timestamp"} + * + * @property {Object} cancelTime + * The time at which this operation was cancelled. If set, this operation is + * in the process of undoing itself (which is guaranteed to succeed) and + * cannot be cancelled again. + * + * This object should have the same structure as [google.protobuf.Timestamp]{@link external:"google.protobuf.Timestamp"} + * + * @property {Object} endTime + * The time at which this operation failed or was completed successfully. + * + * This object should have the same structure as [google.protobuf.Timestamp]{@link external:"google.protobuf.Timestamp"} + * + * @class + * @see [google.spanner.admin.instance.v1.CreateInstanceMetadata definition in proto format]{@link https://github.com/googleapis/googleapis/blob/master/google/spanner/admin/instance/v1/spanner_instance_admin.proto} + */ +var CreateInstanceMetadata = { + // This is for documentation. Actual contents will be loaded by gRPC. +}; + +/** + * Metadata type for the operation returned by + * {@link UpdateInstance}. + * + * @property {Object} instance + * The desired end state of the update. + * + * This object should have the same structure as [Instance]{@link Instance} + * + * @property {Object} startTime + * The time at which {@link UpdateInstance} + * request was received. + * + * This object should have the same structure as [google.protobuf.Timestamp]{@link external:"google.protobuf.Timestamp"} + * + * @property {Object} cancelTime + * The time at which this operation was cancelled. If set, this operation is + * in the process of undoing itself (which is guaranteed to succeed) and + * cannot be cancelled again. + * + * This object should have the same structure as [google.protobuf.Timestamp]{@link external:"google.protobuf.Timestamp"} + * + * @property {Object} endTime + * The time at which this operation failed or was completed successfully. + * + * This object should have the same structure as [google.protobuf.Timestamp]{@link external:"google.protobuf.Timestamp"} + * + * @class + * @see [google.spanner.admin.instance.v1.UpdateInstanceMetadata definition in proto format]{@link https://github.com/googleapis/googleapis/blob/master/google/spanner/admin/instance/v1/spanner_instance_admin.proto} + */ +var UpdateInstanceMetadata = { + // This is for documentation. Actual contents will be loaded by gRPC. +}; \ No newline at end of file diff --git a/packages/spanner/src/v1/doc/doc_google_protobuf_duration.js b/packages/spanner/src/v1/doc/doc_google_protobuf_duration.js new file mode 100644 index 00000000000..b81fd71f130 --- /dev/null +++ b/packages/spanner/src/v1/doc/doc_google_protobuf_duration.js @@ -0,0 +1,84 @@ +/* + * Copyright 2017, Google Inc. All rights reserved. + * + * 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. + */ + +/* + * Note: this file is purely for documentation. Any contents are not expected + * to be loaded as the JS file. + */ + +/** + * A Duration represents a signed, fixed-length span of time represented + * as a count of seconds and fractions of seconds at nanosecond + * resolution. It is independent of any calendar and concepts like "day" + * or "month". It is related to Timestamp in that the difference between + * two Timestamp values is a Duration and it can be added or subtracted + * from a Timestamp. Range is approximately +-10,000 years. + * + * Example 1: Compute Duration from two Timestamps in pseudo code. + * + * Timestamp start = ...; + * Timestamp end = ...; + * Duration duration = ...; + * + * duration.seconds = end.seconds - start.seconds; + * duration.nanos = end.nanos - start.nanos; + * + * if (duration.seconds < 0 && duration.nanos > 0) { + * duration.seconds += 1; + * duration.nanos -= 1000000000; + * } else if (durations.seconds > 0 && duration.nanos < 0) { + * duration.seconds -= 1; + * duration.nanos += 1000000000; + * } + * + * Example 2: Compute Timestamp from Timestamp + Duration in pseudo code. + * + * Timestamp start = ...; + * Duration duration = ...; + * Timestamp end = ...; + * + * end.seconds = start.seconds + duration.seconds; + * end.nanos = start.nanos + duration.nanos; + * + * if (end.nanos < 0) { + * end.seconds -= 1; + * end.nanos += 1000000000; + * } else if (end.nanos >= 1000000000) { + * end.seconds += 1; + * end.nanos -= 1000000000; + * } + * + * Example 3: Compute Duration from datetime.timedelta in Python. + * + * td = datetime.timedelta(days=3, minutes=10) + * duration = Duration() + * duration.FromTimedelta(td) + * + * @external "google.protobuf.Duration" + * @property {number} seconds + * Signed seconds of the span of time. Must be from -315,576,000,000 + * to +315,576,000,000 inclusive. + * + * @property {number} nanos + * Signed fractions of a second at nanosecond resolution of the span + * of time. Durations less than one second are represented with a 0 + * `seconds` field and a positive or negative `nanos` field. For durations + * of one second or more, a non-zero value for the `nanos` field must be + * of the same sign as the `seconds` field. Must be from -999,999,999 + * to +999,999,999 inclusive. + * + * @see [google.protobuf.Duration definition in proto format]{@link https://github.com/google/protobuf/blob/master/src/google/protobuf/duration.proto} + */ \ No newline at end of file diff --git a/packages/spanner/src/v1/doc/doc_google_protobuf_struct.js b/packages/spanner/src/v1/doc/doc_google_protobuf_struct.js new file mode 100644 index 00000000000..11b6f09af75 --- /dev/null +++ b/packages/spanner/src/v1/doc/doc_google_protobuf_struct.js @@ -0,0 +1,88 @@ +/* + * Copyright 2017, Google Inc. All rights reserved. + * + * 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. + */ + +/* + * Note: this file is purely for documentation. Any contents are not expected + * to be loaded as the JS file. + */ + +/** + * `Struct` represents a structured data value, consisting of fields + * which map to dynamically typed values. In some languages, `Struct` + * might be supported by a native representation. For example, in + * scripting languages like JS a struct is represented as an + * object. The details of that representation are described together + * with the proto support for the language. + * + * The JSON representation for `Struct` is JSON object. + * + * @external "google.protobuf.Struct" + * @property {Object.} fields + * Unordered map of dynamically typed values. + * + * @see [google.protobuf.Struct definition in proto format]{@link https://github.com/google/protobuf/blob/master/src/google/protobuf/struct.proto} + */ + +/** + * `Value` represents a dynamically typed value which can be either + * null, a number, a string, a boolean, a recursive struct value, or a + * list of values. A producer of value is expected to set one of that + * variants, absence of any variant indicates an error. + * + * The JSON representation for `Value` is JSON value. + * + * @external "google.protobuf.Value" + * @property {number} nullValue + * Represents a null value. + * + * The number should be among the values of [google.protobuf.NullValue]{@link external:"google.protobuf.NullValue"} + * + * @property {number} numberValue + * Represents a double value. + * + * @property {string} stringValue + * Represents a string value. + * + * @property {boolean} boolValue + * Represents a boolean value. + * + * @property {Object} structValue + * Represents a structured value. + * + * This object should have the same structure as [google.protobuf.Struct]{@link external:"google.protobuf.Struct"} + * + * @property {Object} listValue + * Represents a repeated `Value`. + * + * This object should have the same structure as [google.protobuf.ListValue]{@link external:"google.protobuf.ListValue"} + * + * @see [google.protobuf.Value definition in proto format]{@link https://github.com/google/protobuf/blob/master/src/google/protobuf/struct.proto} + */ + +/** + * `ListValue` is a wrapper around a repeated field of values. + * + * The JSON representation for `ListValue` is JSON array. + * + * @external "google.protobuf.ListValue" + * @property {Object[]} values + * Repeated field of dynamically typed values. + * + * This object should have the same structure as [google.protobuf.Value]{@link external:"google.protobuf.Value"} + * + * @see [google.protobuf.ListValue definition in proto format]{@link https://github.com/google/protobuf/blob/master/src/google/protobuf/struct.proto} + */ + diff --git a/packages/spanner/src/v1/doc/doc_google_protobuf_timestamp.js b/packages/spanner/src/v1/doc/doc_google_protobuf_timestamp.js new file mode 100644 index 00000000000..ed8fc627b92 --- /dev/null +++ b/packages/spanner/src/v1/doc/doc_google_protobuf_timestamp.js @@ -0,0 +1,88 @@ +/* + * Copyright 2017, Google Inc. All rights reserved. + * + * 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. + */ + +/* + * Note: this file is purely for documentation. Any contents are not expected + * to be loaded as the JS file. + */ + +/** + * A Timestamp represents a point in time independent of any time zone + * or calendar, represented as seconds and fractions of seconds at + * nanosecond resolution in UTC Epoch time. It is encoded using the + * Proleptic Gregorian Calendar which extends the Gregorian calendar + * backwards to year one. It is encoded assuming all minutes are 60 + * seconds long, i.e. leap seconds are "smeared" so that no leap second + * table is needed for interpretation. Range is from + * 0001-01-01T00:00:00Z to 9999-12-31T23:59:59.999999999Z. + * By restricting to that range, we ensure that we can convert to + * and from RFC 3339 date strings. + * See [https://www.ietf.org/rfc/rfc3339.txt](https://www.ietf.org/rfc/rfc3339.txt). + * + * Example 1: Compute Timestamp from POSIX `time()`. + * + * Timestamp timestamp; + * timestamp.set_seconds(time(NULL)); + * timestamp.set_nanos(0); + * + * Example 2: Compute Timestamp from POSIX `gettimeofday()`. + * + * struct timeval tv; + * gettimeofday(&tv, NULL); + * + * Timestamp timestamp; + * timestamp.set_seconds(tv.tv_sec); + * timestamp.set_nanos(tv.tv_usec * 1000); + * + * Example 3: Compute Timestamp from Win32 `GetSystemTimeAsFileTime()`. + * + * FILETIME ft; + * GetSystemTimeAsFileTime(&ft); + * UINT64 ticks = (((UINT64)ft.dwHighDateTime) << 32) | ft.dwLowDateTime; + * + * // A Windows tick is 100 nanoseconds. Windows epoch 1601-01-01T00:00:00Z + * // is 11644473600 seconds before Unix epoch 1970-01-01T00:00:00Z. + * Timestamp timestamp; + * timestamp.set_seconds((INT64) ((ticks / 10000000) - 11644473600LL)); + * timestamp.set_nanos((INT32) ((ticks % 10000000) * 100)); + * + * Example 4: Compute Timestamp from Java `System.currentTimeMillis()`. + * + * long millis = System.currentTimeMillis(); + * + * Timestamp timestamp = Timestamp.newBuilder().setSeconds(millis / 1000) + * .setNanos((int) ((millis % 1000) * 1000000)).build(); + * + * + * Example 5: Compute Timestamp from current time in Python. + * + * timestamp = Timestamp() + * timestamp.GetCurrentTime() + * + * @external "google.protobuf.Timestamp" + * @property {number} seconds + * Represents seconds of UTC time since Unix epoch + * 1970-01-01T00:00:00Z. Must be from 0001-01-01T00:00:00Z to + * 9999-12-31T23:59:59Z inclusive. + * + * @property {number} nanos + * Non-negative fractions of a second at nanosecond resolution. Negative + * second values with fractions must still have non-negative nanos values + * that count forward in time. Must be from 0 to 999,999,999 + * inclusive. + * + * @see [google.protobuf.Timestamp definition in proto format]{@link https://github.com/google/protobuf/blob/master/src/google/protobuf/timestamp.proto} + */ \ No newline at end of file diff --git a/packages/spanner/src/v1/doc/doc_keys.js b/packages/spanner/src/v1/doc/doc_keys.js new file mode 100644 index 00000000000..8b25422bf3b --- /dev/null +++ b/packages/spanner/src/v1/doc/doc_keys.js @@ -0,0 +1,175 @@ +/* + * Copyright 2017, Google Inc. All rights reserved. + * + * 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. + */ + +/* + * Note: this file is purely for documentation. Any contents are not expected + * to be loaded as the JS file. + */ + +/** + * KeyRange represents a range of rows in a table or index. + * + * A range has a start key and an end key. These keys can be open or + * closed, indicating if the range includes rows with that key. + * + * Keys are represented by lists, where the ith value in the list + * corresponds to the ith component of the table or index primary key. + * Individual values are encoded as described {@link here}. + * + * For example, consider the following table definition: + * + * CREATE TABLE UserEvents ( + * UserName STRING(MAX), + * EventDate STRING(10) + * ) PRIMARY KEY(UserName, EventDate); + * + * The following keys name rows in this table: + * + * ["Bob", "2014-09-23"] + * ["Alfred", "2015-06-12"] + * + * Since the `UserEvents` table's `PRIMARY KEY` clause names two + * columns, each `UserEvents` key has two elements; the first is the + * `UserName`, and the second is the `EventDate`. + * + * Key ranges with multiple components are interpreted + * lexicographically by component using the table or index key's declared + * sort order. For example, the following range returns all events for + * user `"Bob"` that occurred in the year 2015: + * + * "start_closed": ["Bob", "2015-01-01"] + * "end_closed": ["Bob", "2015-12-31"] + * + * Start and end keys can omit trailing key components. This affects the + * inclusion and exclusion of rows that exactly match the provided key + * components: if the key is closed, then rows that exactly match the + * provided components are included; if the key is open, then rows + * that exactly match are not included. + * + * For example, the following range includes all events for `"Bob"` that + * occurred during and after the year 2000: + * + * "start_closed": ["Bob", "2000-01-01"] + * "end_closed": ["Bob"] + * + * The next example retrieves all events for `"Bob"`: + * + * "start_closed": ["Bob"] + * "end_closed": ["Bob"] + * + * To retrieve events before the year 2000: + * + * "start_closed": ["Bob"] + * "end_open": ["Bob", "2000-01-01"] + * + * The following range includes all rows in the table: + * + * "start_closed": [] + * "end_closed": [] + * + * This range returns all users whose `UserName` begins with any + * character from A to C: + * + * "start_closed": ["A"] + * "end_open": ["D"] + * + * This range returns all users whose `UserName` begins with B: + * + * "start_closed": ["B"] + * "end_open": ["C"] + * + * Key ranges honor column sort order. For example, suppose a table is + * defined as follows: + * + * CREATE TABLE DescendingSortedTable { + * Key INT64, + * ... + * ) PRIMARY KEY(Key DESC); + * + * The following range retrieves all rows with key values between 1 + * and 100 inclusive: + * + * "start_closed": ["100"] + * "end_closed": ["1"] + * + * Note that 100 is passed as the start, and 1 is passed as the end, + * because `Key` is a descending column in the schema. + * + * @property {Object} startClosed + * If the start is closed, then the range includes all rows whose + * first `len(start_closed)` key columns exactly match `start_closed`. + * + * This object should have the same structure as [google.protobuf.ListValue]{@link external:"google.protobuf.ListValue"} + * + * @property {Object} startOpen + * If the start is open, then the range excludes rows whose first + * `len(start_open)` key columns exactly match `start_open`. + * + * This object should have the same structure as [google.protobuf.ListValue]{@link external:"google.protobuf.ListValue"} + * + * @property {Object} endClosed + * If the end is closed, then the range includes all rows whose + * first `len(end_closed)` key columns exactly match `end_closed`. + * + * This object should have the same structure as [google.protobuf.ListValue]{@link external:"google.protobuf.ListValue"} + * + * @property {Object} endOpen + * If the end is open, then the range excludes rows whose first + * `len(end_open)` key columns exactly match `end_open`. + * + * This object should have the same structure as [google.protobuf.ListValue]{@link external:"google.protobuf.ListValue"} + * + * @class + * @see [google.spanner.v1.KeyRange definition in proto format]{@link https://github.com/googleapis/googleapis/blob/master/google/spanner/v1/keys.proto} + */ +var KeyRange = { + // This is for documentation. Actual contents will be loaded by gRPC. +}; + +/** + * `KeySet` defines a collection of Cloud Spanner keys and/or key ranges. All + * the keys are expected to be in the same table or index. The keys need + * not be sorted in any particular way. + * + * If the same key is specified multiple times in the set (for example + * if two ranges, two keys, or a key and a range overlap), Cloud Spanner + * behaves as if the key were only specified once. + * + * @property {Object[]} keys + * A list of specific keys. Entries in `keys` should have exactly as + * many elements as there are columns in the primary or index key + * with which this `KeySet` is used. Individual key values are + * encoded as described {@link here}. + * + * This object should have the same structure as [google.protobuf.ListValue]{@link external:"google.protobuf.ListValue"} + * + * @property {Object[]} ranges + * A list of key ranges. See {@link KeyRange} for more information about + * key range specifications. + * + * This object should have the same structure as [KeyRange]{@link KeyRange} + * + * @property {boolean} all + * For convenience `all` can be set to `true` to indicate that this + * `KeySet` matches all keys in the table or index. Note that any keys + * specified in `keys` or `ranges` are only yielded once. + * + * @class + * @see [google.spanner.v1.KeySet definition in proto format]{@link https://github.com/googleapis/googleapis/blob/master/google/spanner/v1/keys.proto} + */ +var KeySet = { + // This is for documentation. Actual contents will be loaded by gRPC. +}; \ No newline at end of file diff --git a/packages/spanner/src/v1/doc/doc_mutation.js b/packages/spanner/src/v1/doc/doc_mutation.js new file mode 100644 index 00000000000..bd3796cdb8c --- /dev/null +++ b/packages/spanner/src/v1/doc/doc_mutation.js @@ -0,0 +1,116 @@ +/* + * Copyright 2017, Google Inc. All rights reserved. + * + * 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. + */ + +/* + * Note: this file is purely for documentation. Any contents are not expected + * to be loaded as the JS file. + */ + +/** + * A modification to one or more Cloud Spanner rows. Mutations can be + * applied to a Cloud Spanner database by sending them in a + * {@link Commit} call. + * + * @property {Object} insert + * Insert new rows in a table. If any of the rows already exist, + * the write or transaction fails with error `ALREADY_EXISTS`. + * + * This object should have the same structure as [Write]{@link Write} + * + * @property {Object} update + * Update existing rows in a table. If any of the rows does not + * already exist, the transaction fails with error `NOT_FOUND`. + * + * This object should have the same structure as [Write]{@link Write} + * + * @property {Object} insertOrUpdate + * Like {@link insert}, except that if the row already exists, then + * its column values are overwritten with the ones provided. Any + * column values not explicitly written are preserved. + * + * This object should have the same structure as [Write]{@link Write} + * + * @property {Object} replace + * Like {@link insert}, except that if the row already exists, it is + * deleted, and the column values provided are inserted + * instead. Unlike {@link insert_or_update}, this means any values not + * explicitly written become `NULL`. + * + * This object should have the same structure as [Write]{@link Write} + * + * @property {Object} delete + * Delete rows from a table. Succeeds whether or not the named + * rows were present. + * + * This object should have the same structure as [Delete]{@link Delete} + * + * @class + * @see [google.spanner.v1.Mutation definition in proto format]{@link https://github.com/googleapis/googleapis/blob/master/google/spanner/v1/mutation.proto} + */ +var Mutation = { + // This is for documentation. Actual contents will be loaded by gRPC. + + /** + * Arguments to {@link insert}, {@link update}, {@link insert_or_update}, and + * {@link replace} operations. + * + * @property {string} table + * Required. The table whose rows will be written. + * + * @property {string[]} columns + * The names of the columns in {@link table} to be written. + * + * The list of columns must contain enough columns to allow + * Cloud Spanner to derive values for all primary key columns in the + * row(s) to be modified. + * + * @property {Object[]} values + * The values to be written. `values` can contain more than one + * list of values. If it does, then multiple rows are written, one + * for each entry in `values`. Each list in `values` must have + * exactly as many entries as there are entries in {@link columns} + * above. Sending multiple lists is equivalent to sending multiple + * `Mutation`s, each containing one `values` entry and repeating + * {@link table} and {@link columns}. Individual values in each list are + * encoded as described {@link here}. + * + * This object should have the same structure as [google.protobuf.ListValue]{@link external:"google.protobuf.ListValue"} + * + * @class + * @see [google.spanner.v1.Mutation.Write definition in proto format]{@link https://github.com/googleapis/googleapis/blob/master/google/spanner/v1/mutation.proto} + */ + Write: { + // This is for documentation. Actual contents will be loaded by gRPC. + }, + + /** + * Arguments to {@link delete} operations. + * + * @property {string} table + * Required. The table whose rows will be deleted. + * + * @property {Object} keySet + * Required. The primary keys of the rows within {@link table} to delete. + * + * This object should have the same structure as [KeySet]{@link KeySet} + * + * @class + * @see [google.spanner.v1.Mutation.Delete definition in proto format]{@link https://github.com/googleapis/googleapis/blob/master/google/spanner/v1/mutation.proto} + */ + Delete: { + // This is for documentation. Actual contents will be loaded by gRPC. + } +}; \ No newline at end of file diff --git a/packages/spanner/src/v1/doc/doc_query_plan.js b/packages/spanner/src/v1/doc/doc_query_plan.js new file mode 100644 index 00000000000..39998720d4e --- /dev/null +++ b/packages/spanner/src/v1/doc/doc_query_plan.js @@ -0,0 +1,172 @@ +/* + * Copyright 2017, Google Inc. All rights reserved. + * + * 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. + */ + +/* + * Note: this file is purely for documentation. Any contents are not expected + * to be loaded as the JS file. + */ + +/** + * Node information for nodes appearing in a {@link QueryPlan.plan_nodes}. + * + * @property {number} index + * The `PlanNode`'s index in {@link node list}. + * + * @property {number} kind + * Used to determine the type of node. May be needed for visualizing + * different kinds of nodes differently. For example, If the node is a + * {@link SCALAR} node, it will have a condensed representation + * which can be used to directly embed a description of the node in its + * parent. + * + * The number should be among the values of [Kind]{@link Kind} + * + * @property {string} displayName + * The display name for the node. + * + * @property {Object[]} childLinks + * List of child node `index`es and their relationship to this parent. + * + * This object should have the same structure as [ChildLink]{@link ChildLink} + * + * @property {Object} shortRepresentation + * Condensed representation for {@link SCALAR} nodes. + * + * This object should have the same structure as [ShortRepresentation]{@link ShortRepresentation} + * + * @property {Object} metadata + * Attributes relevant to the node contained in a group of key-value pairs. + * For example, a Parameter Reference node could have the following + * information in its metadata: + * + * { + * "parameter_reference": "param1", + * "parameter_type": "array" + * } + * + * This object should have the same structure as [google.protobuf.Struct]{@link external:"google.protobuf.Struct"} + * + * @property {Object} executionStats + * The execution statistics associated with the node, contained in a group of + * key-value pairs. Only present if the plan was returned as a result of a + * profile query. For example, number of executions, number of rows/time per + * execution etc. + * + * This object should have the same structure as [google.protobuf.Struct]{@link external:"google.protobuf.Struct"} + * + * @class + * @see [google.spanner.v1.PlanNode definition in proto format]{@link https://github.com/googleapis/googleapis/blob/master/google/spanner/v1/query_plan.proto} + */ +var PlanNode = { + // This is for documentation. Actual contents will be loaded by gRPC. + + /** + * Metadata associated with a parent-child relationship appearing in a + * {@link PlanNode}. + * + * @property {number} childIndex + * The node to which the link points. + * + * @property {string} type + * The type of the link. For example, in Hash Joins this could be used to + * distinguish between the build child and the probe child, or in the case + * of the child being an output variable, to represent the tag associated + * with the output variable. + * + * @property {string} variable + * Only present if the child node is {@link SCALAR} and corresponds + * to an output variable of the parent node. The field carries the name of + * the output variable. + * For example, a `TableScan` operator that reads rows from a table will + * have child links to the `SCALAR` nodes representing the output variables + * created for each column that is read by the operator. The corresponding + * `variable` fields will be set to the variable names assigned to the + * columns. + * + * @class + * @see [google.spanner.v1.PlanNode.ChildLink definition in proto format]{@link https://github.com/googleapis/googleapis/blob/master/google/spanner/v1/query_plan.proto} + */ + ChildLink: { + // This is for documentation. Actual contents will be loaded by gRPC. + }, + + /** + * Condensed representation of a node and its subtree. Only present for + * `SCALAR` {@link PlanNode(s)}. + * + * @property {string} description + * A string representation of the expression subtree rooted at this node. + * + * @property {Object.} subqueries + * A mapping of (subquery variable name) -> (subquery node id) for cases + * where the `description` string of this node references a `SCALAR` + * subquery contained in the expression subtree rooted at this node. The + * referenced `SCALAR` subquery may not necessarily be a direct child of + * this node. + * + * @class + * @see [google.spanner.v1.PlanNode.ShortRepresentation definition in proto format]{@link https://github.com/googleapis/googleapis/blob/master/google/spanner/v1/query_plan.proto} + */ + ShortRepresentation: { + // This is for documentation. Actual contents will be loaded by gRPC. + }, + + /** + * The kind of {@link PlanNode}. Distinguishes between the two different kinds of + * nodes that can appear in a query plan. + * + * @enum {number} + */ + Kind: { + + /** + * Not specified. + */ + KIND_UNSPECIFIED: 0, + + /** + * Denotes a Relational operator node in the expression tree. Relational + * operators represent iterative processing of rows during query execution. + * For example, a `TableScan` operation that reads rows from a table. + */ + RELATIONAL: 1, + + /** + * Denotes a Scalar node in the expression tree. Scalar nodes represent + * non-iterable entities in the query plan. For example, constants or + * arithmetic operators appearing inside predicate expressions or references + * to column names. + */ + SCALAR: 2 + } +}; + +/** + * Contains an ordered list of nodes appearing in the query plan. + * + * @property {Object[]} planNodes + * The nodes in the query plan. Plan nodes are returned in pre-order starting + * with the plan root. Each {@link PlanNode}'s `id` corresponds to its index in + * `plan_nodes`. + * + * This object should have the same structure as [PlanNode]{@link PlanNode} + * + * @class + * @see [google.spanner.v1.QueryPlan definition in proto format]{@link https://github.com/googleapis/googleapis/blob/master/google/spanner/v1/query_plan.proto} + */ +var QueryPlan = { + // This is for documentation. Actual contents will be loaded by gRPC. +}; \ No newline at end of file diff --git a/packages/spanner/src/v1/doc/doc_result_set.js b/packages/spanner/src/v1/doc/doc_result_set.js new file mode 100644 index 00000000000..6ed1ec2070f --- /dev/null +++ b/packages/spanner/src/v1/doc/doc_result_set.js @@ -0,0 +1,224 @@ +/* + * Copyright 2017, Google Inc. All rights reserved. + * + * 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. + */ + +/* + * Note: this file is purely for documentation. Any contents are not expected + * to be loaded as the JS file. + */ + +/** + * Results from {@link Read} or + * {@link ExecuteSql}. + * + * @property {Object} metadata + * Metadata about the result set, such as row type information. + * + * This object should have the same structure as [ResultSetMetadata]{@link ResultSetMetadata} + * + * @property {Object[]} rows + * Each element in `rows` is a row whose format is defined by + * {@link metadata.row_type}. The ith element + * in each row matches the ith field in + * {@link metadata.row_type}. Elements are + * encoded based on type as described + * {@link here}. + * + * This object should have the same structure as [google.protobuf.ListValue]{@link external:"google.protobuf.ListValue"} + * + * @property {Object} stats + * Query plan and execution statistics for the query that produced this + * result set. These can be requested by setting + * {@link ExecuteSqlRequest.query_mode}. + * + * This object should have the same structure as [ResultSetStats]{@link ResultSetStats} + * + * @class + * @see [google.spanner.v1.ResultSet definition in proto format]{@link https://github.com/googleapis/googleapis/blob/master/google/spanner/v1/result_set.proto} + */ +var ResultSet = { + // This is for documentation. Actual contents will be loaded by gRPC. +}; + +/** + * Partial results from a streaming read or SQL query. Streaming reads and + * SQL queries better tolerate large result sets, large rows, and large + * values, but are a little trickier to consume. + * + * @property {Object} metadata + * Metadata about the result set, such as row type information. + * Only present in the first response. + * + * This object should have the same structure as [ResultSetMetadata]{@link ResultSetMetadata} + * + * @property {Object[]} values + * A streamed result set consists of a stream of values, which might + * be split into many `PartialResultSet` messages to accommodate + * large rows and/or large values. Every N complete values defines a + * row, where N is equal to the number of entries in + * {@link metadata.row_type.fields}. + * + * Most values are encoded based on type as described + * {@link here}. + * + * It is possible that the last value in values is "chunked", + * meaning that the rest of the value is sent in subsequent + * `PartialResultSet`(s). This is denoted by the {@link chunked_value} + * field. Two or more chunked values can be merged to form a + * complete value as follows: + * + * * `bool/number/null`: cannot be chunked + * * `string`: concatenate the strings + * * `list`: concatenate the lists. If the last element in a list is a + * `string`, `list`, or `object`, merge it with the first element in + * the next list by applying these rules recursively. + * * `object`: concatenate the (field name, field value) pairs. If a + * field name is duplicated, then apply these rules recursively + * to merge the field values. + * + * Some examples of merging: + * + * # Strings are concatenated. + * "foo", "bar" => "foobar" + * + * # Lists of non-strings are concatenated. + * [2, 3], [4] => [2, 3, 4] + * + * # Lists are concatenated, but the last and first elements are merged + * # because they are strings. + * ["a", "b"], ["c", "d"] => ["a", "bc", "d"] + * + * # Lists are concatenated, but the last and first elements are merged + * # because they are lists. Recursively, the last and first elements + * # of the inner lists are merged because they are strings. + * ["a", ["b", "c"]], [["d"], "e"] => ["a", ["b", "cd"], "e"] + * + * # Non-overlapping object fields are combined. + * {"a": "1"}, {"b": "2"} => {"a": "1", "b": 2"} + * + * # Overlapping object fields are merged. + * {"a": "1"}, {"a": "2"} => {"a": "12"} + * + * # Examples of merging objects containing lists of strings. + * {"a": ["1"]}, {"a": ["2"]} => {"a": ["12"]} + * + * For a more complete example, suppose a streaming SQL query is + * yielding a result set whose rows contain a single string + * field. The following `PartialResultSet`s might be yielded: + * + * { + * "metadata": { ... } + * "values": ["Hello", "W"] + * "chunked_value": true + * "resume_token": "Af65..." + * } + * { + * "values": ["orl"] + * "chunked_value": true + * "resume_token": "Bqp2..." + * } + * { + * "values": ["d"] + * "resume_token": "Zx1B..." + * } + * + * This sequence of `PartialResultSet`s encodes two rows, one + * containing the field value `"Hello"`, and a second containing the + * field value `"World" = "W" + "orl" + "d"`. + * + * This object should have the same structure as [google.protobuf.Value]{@link external:"google.protobuf.Value"} + * + * @property {boolean} chunkedValue + * If true, then the final value in {@link values} is chunked, and must + * be combined with more values from subsequent `PartialResultSet`s + * to obtain a complete field value. + * + * @property {string} resumeToken + * Streaming calls might be interrupted for a variety of reasons, such + * as TCP connection loss. If this occurs, the stream of results can + * be resumed by re-sending the original request and including + * `resume_token`. Note that executing any other transaction in the + * same session invalidates the token. + * + * @property {Object} stats + * Query plan and execution statistics for the query that produced this + * streaming result set. These can be requested by setting + * {@link ExecuteSqlRequest.query_mode} and are sent + * only once with the last response in the stream. + * + * This object should have the same structure as [ResultSetStats]{@link ResultSetStats} + * + * @class + * @see [google.spanner.v1.PartialResultSet definition in proto format]{@link https://github.com/googleapis/googleapis/blob/master/google/spanner/v1/result_set.proto} + */ +var PartialResultSet = { + // This is for documentation. Actual contents will be loaded by gRPC. +}; + +/** + * Metadata about a {@link ResultSet} or {@link PartialResultSet}. + * + * @property {Object} rowType + * Indicates the field names and types for the rows in the result + * set. For example, a SQL query like `"SELECT UserId, UserName FROM + * Users"` could return a `row_type` value like: + * + * "fields": [ + * { "name": "UserId", "type": { "code": "INT64" } }, + * { "name": "UserName", "type": { "code": "STRING" } }, + * ] + * + * This object should have the same structure as [StructType]{@link StructType} + * + * @property {Object} transaction + * If the read or SQL query began a transaction as a side-effect, the + * information about the new transaction is yielded here. + * + * This object should have the same structure as [Transaction]{@link Transaction} + * + * @class + * @see [google.spanner.v1.ResultSetMetadata definition in proto format]{@link https://github.com/googleapis/googleapis/blob/master/google/spanner/v1/result_set.proto} + */ +var ResultSetMetadata = { + // This is for documentation. Actual contents will be loaded by gRPC. +}; + +/** + * Additional statistics about a {@link ResultSet} or {@link PartialResultSet}. + * + * @property {Object} queryPlan + * {@link QueryPlan} for the query associated with this result. + * + * This object should have the same structure as [QueryPlan]{@link QueryPlan} + * + * @property {Object} queryStats + * Aggregated statistics from the execution of the query. Only present when + * the query is profiled. For example, a query could return the statistics as + * follows: + * + * { + * "rows_returned": "3", + * "elapsed_time": "1.22 secs", + * "cpu_time": "1.19 secs" + * } + * + * This object should have the same structure as [google.protobuf.Struct]{@link external:"google.protobuf.Struct"} + * + * @class + * @see [google.spanner.v1.ResultSetStats definition in proto format]{@link https://github.com/googleapis/googleapis/blob/master/google/spanner/v1/result_set.proto} + */ +var ResultSetStats = { + // This is for documentation. Actual contents will be loaded by gRPC. +}; \ No newline at end of file diff --git a/packages/spanner/src/v1/doc/doc_spanner.js b/packages/spanner/src/v1/doc/doc_spanner.js new file mode 100644 index 00000000000..1b4e4846e6b --- /dev/null +++ b/packages/spanner/src/v1/doc/doc_spanner.js @@ -0,0 +1,306 @@ +/* + * Copyright 2017, Google Inc. All rights reserved. + * + * 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. + */ + +/* + * Note: this file is purely for documentation. Any contents are not expected + * to be loaded as the JS file. + */ + +/** + * The request for {@link CreateSession}. + * + * @property {string} database + * Required. The database in which the new session is created. + * + * @class + * @see [google.spanner.v1.CreateSessionRequest definition in proto format]{@link https://github.com/googleapis/googleapis/blob/master/google/spanner/v1/spanner.proto} + */ +var CreateSessionRequest = { + // This is for documentation. Actual contents will be loaded by gRPC. +}; + +/** + * A session in the Cloud Spanner API. + * + * @property {string} name + * Required. The name of the session. + * + * @class + * @see [google.spanner.v1.Session definition in proto format]{@link https://github.com/googleapis/googleapis/blob/master/google/spanner/v1/spanner.proto} + */ +var Session = { + // This is for documentation. Actual contents will be loaded by gRPC. +}; + +/** + * The request for {@link GetSession}. + * + * @property {string} name + * Required. The name of the session to retrieve. + * + * @class + * @see [google.spanner.v1.GetSessionRequest definition in proto format]{@link https://github.com/googleapis/googleapis/blob/master/google/spanner/v1/spanner.proto} + */ +var GetSessionRequest = { + // This is for documentation. Actual contents will be loaded by gRPC. +}; + +/** + * The request for {@link DeleteSession}. + * + * @property {string} name + * Required. The name of the session to delete. + * + * @class + * @see [google.spanner.v1.DeleteSessionRequest definition in proto format]{@link https://github.com/googleapis/googleapis/blob/master/google/spanner/v1/spanner.proto} + */ +var DeleteSessionRequest = { + // This is for documentation. Actual contents will be loaded by gRPC. +}; + +/** + * The request for {@link ExecuteSql} and + * {@link ExecuteStreamingSql}. + * + * @property {string} session + * Required. The session in which the SQL query should be performed. + * + * @property {Object} transaction + * The transaction to use. If none is provided, the default is a + * temporary read-only transaction with strong concurrency. + * + * This object should have the same structure as [TransactionSelector]{@link TransactionSelector} + * + * @property {string} sql + * Required. The SQL query string. + * + * @property {Object} params + * The SQL query string can contain parameter placeholders. A parameter + * placeholder consists of `'@'` followed by the parameter + * name. Parameter names consist of any combination of letters, + * numbers, and underscores. + * + * Parameters can appear anywhere that a literal value is expected. The same + * parameter name can be used more than once, for example: + * `"WHERE id > @msg_id AND id < @msg_id + 100"` + * + * It is an error to execute an SQL query with unbound parameters. + * + * Parameter values are specified using `params`, which is a JSON + * object whose keys are parameter names, and whose values are the + * corresponding parameter values. + * + * This object should have the same structure as [google.protobuf.Struct]{@link external:"google.protobuf.Struct"} + * + * @property {Object.} paramTypes + * It is not always possible for Cloud Spanner to infer the right SQL type + * from a JSON value. For example, values of type `BYTES` and values + * of type `STRING` both appear in {@link params} as JSON strings. + * + * In these cases, `param_types` can be used to specify the exact + * SQL type for some or all of the SQL query parameters. See the + * definition of {@link Type} for more information + * about SQL types. + * + * @property {string} resumeToken + * If this request is resuming a previously interrupted SQL query + * execution, `resume_token` should be copied from the last + * {@link PartialResultSet} yielded before the interruption. Doing this + * enables the new SQL query execution to resume where the last one left + * off. The rest of the request parameters must exactly match the + * request that yielded this token. + * + * @property {number} queryMode + * Used to control the amount of debugging information returned in + * {@link ResultSetStats}. + * + * The number should be among the values of [QueryMode]{@link QueryMode} + * + * @class + * @see [google.spanner.v1.ExecuteSqlRequest definition in proto format]{@link https://github.com/googleapis/googleapis/blob/master/google/spanner/v1/spanner.proto} + */ +var ExecuteSqlRequest = { + // This is for documentation. Actual contents will be loaded by gRPC. + + /** + * Mode in which the query must be processed. + * + * @enum {number} + */ + QueryMode: { + + /** + * The default mode where only the query result, without any information + * about the query plan is returned. + */ + NORMAL: 0, + + /** + * This mode returns only the query plan, without any result rows or + * execution statistics information. + */ + PLAN: 1, + + /** + * This mode returns both the query plan and the execution statistics along + * with the result rows. + */ + PROFILE: 2 + } +}; + +/** + * The request for {@link Read} and + * {@link StreamingRead}. + * + * @property {string} session + * Required. The session in which the read should be performed. + * + * @property {Object} transaction + * The transaction to use. If none is provided, the default is a + * temporary read-only transaction with strong concurrency. + * + * This object should have the same structure as [TransactionSelector]{@link TransactionSelector} + * + * @property {string} table + * Required. The name of the table in the database to be read. + * + * @property {string} index + * If non-empty, the name of an index on {@link table}. This index is + * used instead of the table primary key when interpreting {@link key_set} + * and sorting result rows. See {@link key_set} for further information. + * + * @property {string[]} columns + * The columns of {@link table} to be returned for each row matching + * this request. + * + * @property {Object} keySet + * Required. `key_set` identifies the rows to be yielded. `key_set` names the + * primary keys of the rows in {@link table} to be yielded, unless {@link index} + * is present. If {@link index} is present, then {@link key_set} instead names + * index keys in {@link index}. + * + * Rows are yielded in table primary key order (if {@link index} is empty) + * or index key order (if {@link index} is non-empty). + * + * It is not an error for the `key_set` to name rows that do not + * exist in the database. Read yields nothing for nonexistent rows. + * + * This object should have the same structure as [KeySet]{@link KeySet} + * + * @property {number} limit + * If greater than zero, only the first `limit` rows are yielded. If `limit` + * is zero, the default is no limit. + * + * @property {string} resumeToken + * If this request is resuming a previously interrupted read, + * `resume_token` should be copied from the last + * {@link PartialResultSet} yielded before the interruption. Doing this + * enables the new read to resume where the last read left off. The + * rest of the request parameters must exactly match the request + * that yielded this token. + * + * @class + * @see [google.spanner.v1.ReadRequest definition in proto format]{@link https://github.com/googleapis/googleapis/blob/master/google/spanner/v1/spanner.proto} + */ +var ReadRequest = { + // This is for documentation. Actual contents will be loaded by gRPC. +}; + +/** + * The request for {@link BeginTransaction}. + * + * @property {string} session + * Required. The session in which the transaction runs. + * + * @property {Object} options + * Required. Options for the new transaction. + * + * This object should have the same structure as [TransactionOptions]{@link TransactionOptions} + * + * @class + * @see [google.spanner.v1.BeginTransactionRequest definition in proto format]{@link https://github.com/googleapis/googleapis/blob/master/google/spanner/v1/spanner.proto} + */ +var BeginTransactionRequest = { + // This is for documentation. Actual contents will be loaded by gRPC. +}; + +/** + * The request for {@link Commit}. + * + * @property {string} session + * Required. The session in which the transaction to be committed is running. + * + * @property {string} transactionId + * Commit a previously-started transaction. + * + * @property {Object} singleUseTransaction + * Execute mutations in a temporary transaction. Note that unlike + * commit of a previously-started transaction, commit with a + * temporary transaction is non-idempotent. That is, if the + * `CommitRequest` is sent to Cloud Spanner more than once (for + * instance, due to retries in the application, or in the + * transport library), it is possible that the mutations are + * executed more than once. If this is undesirable, use + * {@link BeginTransaction} and + * {@link Commit} instead. + * + * This object should have the same structure as [TransactionOptions]{@link TransactionOptions} + * + * @property {Object[]} mutations + * The mutations to be executed when this transaction commits. All + * mutations are applied atomically, in the order they appear in + * this list. + * + * This object should have the same structure as [Mutation]{@link Mutation} + * + * @class + * @see [google.spanner.v1.CommitRequest definition in proto format]{@link https://github.com/googleapis/googleapis/blob/master/google/spanner/v1/spanner.proto} + */ +var CommitRequest = { + // This is for documentation. Actual contents will be loaded by gRPC. +}; + +/** + * The response for {@link Commit}. + * + * @property {Object} commitTimestamp + * The Cloud Spanner timestamp at which the transaction committed. + * + * This object should have the same structure as [google.protobuf.Timestamp]{@link external:"google.protobuf.Timestamp"} + * + * @class + * @see [google.spanner.v1.CommitResponse definition in proto format]{@link https://github.com/googleapis/googleapis/blob/master/google/spanner/v1/spanner.proto} + */ +var CommitResponse = { + // This is for documentation. Actual contents will be loaded by gRPC. +}; + +/** + * The request for {@link Rollback}. + * + * @property {string} session + * Required. The session in which the transaction to roll back is running. + * + * @property {string} transactionId + * Required. The transaction to roll back. + * + * @class + * @see [google.spanner.v1.RollbackRequest definition in proto format]{@link https://github.com/googleapis/googleapis/blob/master/google/spanner/v1/spanner.proto} + */ +var RollbackRequest = { + // This is for documentation. Actual contents will be loaded by gRPC. +}; \ No newline at end of file diff --git a/packages/spanner/src/v1/doc/doc_transaction.js b/packages/spanner/src/v1/doc/doc_transaction.js new file mode 100644 index 00000000000..4990823a3e1 --- /dev/null +++ b/packages/spanner/src/v1/doc/doc_transaction.js @@ -0,0 +1,404 @@ +/* + * Copyright 2017, Google Inc. All rights reserved. + * + * 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. + */ + +/* + * Note: this file is purely for documentation. Any contents are not expected + * to be loaded as the JS file. + */ + +/** + * # Transactions + * + * Each session can have at most one active transaction at a time. After the + * active transaction is completed, the session can immediately be + * re-used for the next transaction. It is not necessary to create a + * new session for each transaction. + * + * # Transaction Modes + * + * Cloud Spanner supports two transaction modes: + * + * 1. Locking read-write. This type of transaction is the only way + * to write data into Cloud Spanner. These transactions rely on + * pessimistic locking and, if necessary, two-phase commit. + * Locking read-write transactions may abort, requiring the + * application to retry. + * + * 2. Snapshot read-only. This transaction type provides guaranteed + * consistency across several reads, but does not allow + * writes. Snapshot read-only transactions can be configured to + * read at timestamps in the past. Snapshot read-only + * transactions do not need to be committed. + * + * For transactions that only read, snapshot read-only transactions + * provide simpler semantics and are almost always faster. In + * particular, read-only transactions do not take locks, so they do + * not conflict with read-write transactions. As a consequence of not + * taking locks, they also do not abort, so retry loops are not needed. + * + * Transactions may only read/write data in a single database. They + * may, however, read/write data in different tables within that + * database. + * + * ## Locking Read-Write Transactions + * + * Locking transactions may be used to atomically read-modify-write + * data anywhere in a database. This type of transaction is externally + * consistent. + * + * Clients should attempt to minimize the amount of time a transaction + * is active. Faster transactions commit with higher probability + * and cause less contention. Cloud Spanner attempts to keep read locks + * active as long as the transaction continues to do reads, and the + * transaction has not been terminated by + * {@link Commit} or + * {@link Rollback}. Long periods of + * inactivity at the client may cause Cloud Spanner to release a + * transaction's locks and abort it. + * + * Reads performed within a transaction acquire locks on the data + * being read. Writes can only be done at commit time, after all reads + * have been completed. + * Conceptually, a read-write transaction consists of zero or more + * reads or SQL queries followed by + * {@link Commit}. At any time before + * {@link Commit}, the client can send a + * {@link Rollback} request to abort the + * transaction. + * + * ### Semantics + * + * Cloud Spanner can commit the transaction if all read locks it acquired + * are still valid at commit time, and it is able to acquire write + * locks for all writes. Cloud Spanner can abort the transaction for any + * reason. If a commit attempt returns `ABORTED`, Cloud Spanner guarantees + * that the transaction has not modified any user data in Cloud Spanner. + * + * Unless the transaction commits, Cloud Spanner makes no guarantees about + * how long the transaction's locks were held for. It is an error to + * use Cloud Spanner locks for any sort of mutual exclusion other than + * between Cloud Spanner transactions themselves. + * + * ### Retrying Aborted Transactions + * + * When a transaction aborts, the application can choose to retry the + * whole transaction again. To maximize the chances of successfully + * committing the retry, the client should execute the retry in the + * same session as the original attempt. The original session's lock + * priority increases with each consecutive abort, meaning that each + * attempt has a slightly better chance of success than the previous. + * + * Under some circumstances (e.g., many transactions attempting to + * modify the same row(s)), a transaction can abort many times in a + * short period before successfully committing. Thus, it is not a good + * idea to cap the number of retries a transaction can attempt; + * instead, it is better to limit the total amount of wall time spent + * retrying. + * + * ### Idle Transactions + * + * A transaction is considered idle if it has no outstanding reads or + * SQL queries and has not started a read or SQL query within the last 10 + * seconds. Idle transactions can be aborted by Cloud Spanner so that they + * don't hold on to locks indefinitely. In that case, the commit will + * fail with error `ABORTED`. + * + * If this behavior is undesirable, periodically executing a simple + * SQL query in the transaction (e.g., `SELECT 1`) prevents the + * transaction from becoming idle. + * + * ## Snapshot Read-Only Transactions + * + * Snapshot read-only transactions provides a simpler method than + * locking read-write transactions for doing several consistent + * reads. However, this type of transaction does not support writes. + * + * Snapshot transactions do not take locks. Instead, they work by + * choosing a Cloud Spanner timestamp, then executing all reads at that + * timestamp. Since they do not acquire locks, they do not block + * concurrent read-write transactions. + * + * Unlike locking read-write transactions, snapshot read-only + * transactions never abort. They can fail if the chosen read + * timestamp is garbage collected; however, the default garbage + * collection policy is generous enough that most applications do not + * need to worry about this in practice. + * + * Snapshot read-only transactions do not need to call + * {@link Commit} or + * {@link Rollback} (and in fact are not + * permitted to do so). + * + * To execute a snapshot transaction, the client specifies a timestamp + * bound, which tells Cloud Spanner how to choose a read timestamp. + * + * The types of timestamp bound are: + * + * - Strong (the default). + * - Bounded staleness. + * - Exact staleness. + * + * If the Cloud Spanner database to be read is geographically distributed, + * stale read-only transactions can execute more quickly than strong + * or read-write transaction, because they are able to execute far + * from the leader replica. + * + * Each type of timestamp bound is discussed in detail below. + * + * ### Strong + * + * Strong reads are guaranteed to see the effects of all transactions + * that have committed before the start of the read. Furthermore, all + * rows yielded by a single read are consistent with each other -- if + * any part of the read observes a transaction, all parts of the read + * see the transaction. + * + * Strong reads are not repeatable: two consecutive strong read-only + * transactions might return inconsistent results if there are + * concurrent writes. If consistency across reads is required, the + * reads should be executed within a transaction or at an exact read + * timestamp. + * + * See {@link TransactionOptions.ReadOnly.strong}. + * + * ### Exact Staleness + * + * These timestamp bounds execute reads at a user-specified + * timestamp. Reads at a timestamp are guaranteed to see a consistent + * prefix of the global transaction history: they observe + * modifications done by all transactions with a commit timestamp <= + * the read timestamp, and observe none of the modifications done by + * transactions with a larger commit timestamp. They will block until + * all conflicting transactions that may be assigned commit timestamps + * <= the read timestamp have finished. + * + * The timestamp can either be expressed as an absolute Cloud Spanner commit + * timestamp or a staleness relative to the current time. + * + * These modes do not require a "negotiation phase" to pick a + * timestamp. As a result, they execute slightly faster than the + * equivalent boundedly stale concurrency modes. On the other hand, + * boundedly stale reads usually return fresher results. + * + * See {@link TransactionOptions.ReadOnly.read_timestamp} and + * {@link TransactionOptions.ReadOnly.exact_staleness}. + * + * ### Bounded Staleness + * + * Bounded staleness modes allow Cloud Spanner to pick the read timestamp, + * subject to a user-provided staleness bound. Cloud Spanner chooses the + * newest timestamp within the staleness bound that allows execution + * of the reads at the closest available replica without blocking. + * + * All rows yielded are consistent with each other -- if any part of + * the read observes a transaction, all parts of the read see the + * transaction. Boundedly stale reads are not repeatable: two stale + * reads, even if they use the same staleness bound, can execute at + * different timestamps and thus return inconsistent results. + * + * Boundedly stale reads execute in two phases: the first phase + * negotiates a timestamp among all replicas needed to serve the + * read. In the second phase, reads are executed at the negotiated + * timestamp. + * + * As a result of the two phase execution, bounded staleness reads are + * usually a little slower than comparable exact staleness + * reads. However, they are typically able to return fresher + * results, and are more likely to execute at the closest replica. + * + * Because the timestamp negotiation requires up-front knowledge of + * which rows will be read, it can only be used with single-use + * read-only transactions. + * + * See {@link TransactionOptions.ReadOnly.max_staleness} and + * {@link TransactionOptions.ReadOnly.min_read_timestamp}. + * + * ### Old Read Timestamps and Garbage Collection + * + * Cloud Spanner continuously garbage collects deleted and overwritten data + * in the background to reclaim storage space. This process is known + * as "version GC". By default, version GC reclaims versions after they + * are one hour old. Because of this, Cloud Spanner cannot perform reads + * at read timestamps more than one hour in the past. This + * restriction also applies to in-progress reads and/or SQL queries whose + * timestamp become too old while executing. Reads and SQL queries with + * too-old read timestamps fail with the error `FAILED_PRECONDITION`. + * + * @property {Object} readWrite + * Transaction may write. + * + * Authorization to begin a read-write transaction requires + * `spanner.databases.beginOrRollbackReadWriteTransaction` permission + * on the `session` resource. + * + * This object should have the same structure as [ReadWrite]{@link ReadWrite} + * + * @property {Object} readOnly + * Transaction will not write. + * + * Authorization to begin a read-only transaction requires + * `spanner.databases.beginReadOnlyTransaction` permission + * on the `session` resource. + * + * This object should have the same structure as [ReadOnly]{@link ReadOnly} + * + * @class + * @see [google.spanner.v1.TransactionOptions definition in proto format]{@link https://github.com/googleapis/googleapis/blob/master/google/spanner/v1/transaction.proto} + */ +var TransactionOptions = { + // This is for documentation. Actual contents will be loaded by gRPC. + + /** + * Options for read-write transactions. + * @class + * @see [google.spanner.v1.TransactionOptions.ReadWrite definition in proto format]{@link https://github.com/googleapis/googleapis/blob/master/google/spanner/v1/transaction.proto} + */ + ReadWrite: { + // This is for documentation. Actual contents will be loaded by gRPC. + }, + + /** + * Options for read-only transactions. + * + * @property {boolean} strong + * Read at a timestamp where all previously committed transactions + * are visible. + * + * @property {Object} minReadTimestamp + * Executes all reads at a timestamp >= `min_read_timestamp`. + * + * This is useful for requesting fresher data than some previous + * read, or data that is fresh enough to observe the effects of some + * previously committed transaction whose timestamp is known. + * + * Note that this option can only be used in single-use transactions. + * + * This object should have the same structure as [google.protobuf.Timestamp]{@link external:"google.protobuf.Timestamp"} + * + * @property {Object} maxStaleness + * Read data at a timestamp >= `NOW - max_staleness` + * seconds. Guarantees that all writes that have committed more + * than the specified number of seconds ago are visible. Because + * Cloud Spanner chooses the exact timestamp, this mode works even if + * the client's local clock is substantially skewed from Cloud Spanner + * commit timestamps. + * + * Useful for reading the freshest data available at a nearby + * replica, while bounding the possible staleness if the local + * replica has fallen behind. + * + * Note that this option can only be used in single-use + * transactions. + * + * This object should have the same structure as [google.protobuf.Duration]{@link external:"google.protobuf.Duration"} + * + * @property {Object} readTimestamp + * Executes all reads at the given timestamp. Unlike other modes, + * reads at a specific timestamp are repeatable; the same read at + * the same timestamp always returns the same data. If the + * timestamp is in the future, the read will block until the + * specified timestamp, modulo the read's deadline. + * + * Useful for large scale consistent reads such as mapreduces, or + * for coordinating many reads against a consistent snapshot of the + * data. + * + * This object should have the same structure as [google.protobuf.Timestamp]{@link external:"google.protobuf.Timestamp"} + * + * @property {Object} exactStaleness + * Executes all reads at a timestamp that is `exact_staleness` + * old. The timestamp is chosen soon after the read is started. + * + * Guarantees that all writes that have committed more than the + * specified number of seconds ago are visible. Because Cloud Spanner + * chooses the exact timestamp, this mode works even if the client's + * local clock is substantially skewed from Cloud Spanner commit + * timestamps. + * + * Useful for reading at nearby replicas without the distributed + * timestamp negotiation overhead of `max_staleness`. + * + * This object should have the same structure as [google.protobuf.Duration]{@link external:"google.protobuf.Duration"} + * + * @property {boolean} returnReadTimestamp + * If true, the Cloud Spanner-selected read timestamp is included in + * the {@link Transaction} message that describes the transaction. + * + * @class + * @see [google.spanner.v1.TransactionOptions.ReadOnly definition in proto format]{@link https://github.com/googleapis/googleapis/blob/master/google/spanner/v1/transaction.proto} + */ + ReadOnly: { + // This is for documentation. Actual contents will be loaded by gRPC. + } +}; + +/** + * A transaction. + * + * @property {string} id + * `id` may be used to identify the transaction in subsequent + * {@link Read}, + * {@link ExecuteSql}, + * {@link Commit}, or + * {@link Rollback} calls. + * + * Single-use read-only transactions do not have IDs, because + * single-use transactions do not support multiple requests. + * + * @property {Object} readTimestamp + * For snapshot read-only transactions, the read timestamp chosen + * for the transaction. Not returned by default: see + * {@link TransactionOptions.ReadOnly.return_read_timestamp}. + * + * This object should have the same structure as [google.protobuf.Timestamp]{@link external:"google.protobuf.Timestamp"} + * + * @class + * @see [google.spanner.v1.Transaction definition in proto format]{@link https://github.com/googleapis/googleapis/blob/master/google/spanner/v1/transaction.proto} + */ +var Transaction = { + // This is for documentation. Actual contents will be loaded by gRPC. +}; + +/** + * This message is used to select the transaction in which a + * {@link Read} or + * {@link ExecuteSql} call runs. + * + * See {@link TransactionOptions} for more information about transactions. + * + * @property {Object} singleUse + * Execute the read or SQL query in a temporary transaction. + * This is the most efficient way to execute a transaction that + * consists of a single SQL query. + * + * This object should have the same structure as [TransactionOptions]{@link TransactionOptions} + * + * @property {string} id + * Execute the read or SQL query in a previously-started transaction. + * + * @property {Object} begin + * Begin a new transaction and execute this read or SQL query in + * it. The transaction ID of the new transaction is returned in + * {@link ResultSetMetadata.transaction}, which is a {@link Transaction}. + * + * This object should have the same structure as [TransactionOptions]{@link TransactionOptions} + * + * @class + * @see [google.spanner.v1.TransactionSelector definition in proto format]{@link https://github.com/googleapis/googleapis/blob/master/google/spanner/v1/transaction.proto} + */ +var TransactionSelector = { + // This is for documentation. Actual contents will be loaded by gRPC. +}; \ No newline at end of file