Understanding the secrets.edgelq.com service APIv1, in proto package ntt.secrets.v1.

Service secrets.edgelq.com in version v1, proto package ntt.secrets.v1

Here is the list of resources supported in Secrets service APIv1:

CryptoKey Resource

CryptoKey Resource

Name patterns:

  • projects/{project}/regions/{region}/cryptoKeys/{crypto_key}

Parent resources:

This section covers the methods and messages to interact with CryptoKey resource.

CryptoKey Methods

Here is the list of CryptoKey resource methods:

GetCryptoKey Method

GetCryptoKey

rpc GetCryptoKey(GetCryptoKeyRequest) returns (CryptoKey)

with the following messages:

Required Permissions:

  • services/secrets.edgelq.com/permissions/cryptoKeys.get

The equivalent REST API is:

GET /v1/{name=projects/*/regions/*/cryptoKeys/*}

BatchGetCryptoKeys Method

BatchGetCryptoKeys

rpc BatchGetCryptoKeys(BatchGetCryptoKeysRequest) returns (BatchGetCryptoKeysResponse)

with the following messages:

Required Permissions:

  • services/secrets.edgelq.com/permissions/cryptoKeys.batchGet

The equivalent REST API is:

GET /v1/cryptoKeys:batchGet

ListCryptoKeys Method

ListCryptoKeys

rpc ListCryptoKeys(ListCryptoKeysRequest) returns (ListCryptoKeysResponse)

with the following messages:

Required Permissions:

  • services/secrets.edgelq.com/permissions/cryptoKeys.list

The equivalent REST API is:

GET /v1/{parent=projects/*/regions/*}/cryptoKeys

WatchCryptoKey Method

WatchCryptoKey

rpc WatchCryptoKey(WatchCryptoKeyRequest) returns (WatchCryptoKeyResponse)

with the following messages:

Required Permissions:

  • services/secrets.edgelq.com/permissions/cryptoKeys.watch

The equivalent REST API is:

POST /v1/{name=projects/*/regions/*/cryptoKeys/*}:watch

WatchCryptoKeys Method

WatchCryptoKeys

rpc WatchCryptoKeys(WatchCryptoKeysRequest) returns (WatchCryptoKeysResponse)

with the following messages:

Required Permissions:

  • services/secrets.edgelq.com/permissions/cryptoKeys.watch

The equivalent REST API is:

POST /v1/{parent=projects/*/regions/*}/cryptoKeys:watch

DeleteCryptoKey Method

DeleteCryptoKey

rpc DeleteCryptoKey(DeleteCryptoKeyRequest) returns (Empty)

with the following messages:

Required Permissions:

  • services/secrets.edgelq.com/permissions/cryptoKeys.delete

The equivalent REST API is:

DELETE /v1/{name=projects/*/regions/*/cryptoKeys/*}

CryptoKey Messages

Here is the list of CryptoKey resource messages:

CryptoKey Message

Name Type Description
name string (name of CryptoKey) Name of CryptoKey When creating a new instance, this field is optional and if not provided, it will be generated automatically. Last ID segment must conform to the following regex: [a-z][a-z0-9\-]{0,28}[a-z0-9]
metadata Meta Metadata is an object with information like create, update and delete time (for async deleted resources), has user labels/annotations, sharding information, multi-region syncing information and may have non-schema owners (useful for taking ownership of resources belonging to lower level services by higher ones).
key string

GetCryptoKeyRequest Message

A request message of the GetCryptoKey method.

Name Type Description
name string (name of CryptoKey) Name of ntt.secrets.v1.CryptoKey
field_mask .google.protobuf.FieldMask A list of extra fields to be obtained for each response item on top of fields defined by request field view
view View View defines list of standard response fields present in response items. Additional fields can be amended by request field field_mask

BatchGetCryptoKeysRequest Message

A request message of the BatchGetCryptoKeys method.

Name Type Description
names repeated string (name of CryptoKey) Names of CryptoKeys
field_mask .google.protobuf.FieldMask A list of extra fields to be obtained for each response item on top of fields defined by request field view
view View View defines list of standard response fields present in response items. Additional fields can be amended by request field field_mask

BatchGetCryptoKeysResponse Message

A response message of the BatchGetCryptoKeys method.

Name Type Description
crypto_keys repeated CryptoKey found CryptoKeys
missing repeated string (name of CryptoKey) list of not found CryptoKeys

ListCryptoKeysRequest Message

A request message of the ListCryptoKeys method.

Name Type Description
parent string (parent name of CryptoKey) Parent name of ntt.secrets.v1.CryptoKey
page_size int32 Requested page size. Server may return fewer CryptoKeys than requested. If unspecified, server will pick an appropriate default.
page_token string (cursor of CryptoKey) A token identifying a page of results the server should return. Typically, this is the value of ListCryptoKeysResponse.next_page_token.
order_by string (orderBy of CryptoKey) Order By - https://cloud.google.com/apis/design/design_patterns#list_pagination list of field path with order directive, either ‘asc’ or ‘desc’. If direction is not provided, ‘asc’ is assumed. e.g. “state.nested_field asc, state.something.else desc, theme”
filter string (filter of CryptoKey) Filter - filter results by field criteria. Simplified SQL-like syntax with following operators: <=, >=, =, !=, <, >, LIKE, CONTAINS (aliases CONTAIN, HAS, HAVE), IN, IS [NOT] NULL
field_mask .google.protobuf.FieldMask A list of extra fields to be obtained for each response item on top of fields defined by request field view
view View View defines list of standard response fields present in response items. Additional fields can be amended by request field field_mask
include_paging_info bool Indicates if list response should contain total count and offset (fields current_offset and total_results_count).

ListCryptoKeysResponse Message

A response message of the ListCryptoKeys method.

Name Type Description
crypto_keys repeated CryptoKey The list of CryptoKeys
prev_page_token string (cursor of CryptoKey) A token to retrieve previous page of results. Pass this value in the ListCryptoKeysRequest.page_token.
next_page_token string (cursor of CryptoKey) A token to retrieve next page of results. Pass this value in the ListCryptoKeysRequest.page_token.
current_offset int32 Current offset from the first page or 0 if no page tokens were given, paging info was not requested or there was an error while trying to get it). Page index can be computed from offset and limit provided in a request.
total_results_count int32 Number of total CryptoKeys across all pages or 0, if there are no items, paging info was not requested or there was an error while trying to get it.

WatchCryptoKeyRequest Message

A request message of the WatchCryptoKey method.

Name Type Description
name string (name of CryptoKey) Name of ntt.secrets.v1.CryptoKey
field_mask .google.protobuf.FieldMask A list of extra fields to be obtained for each response item on top of fields defined by request field view
view View View defines list of standard response fields present in response items. Additional fields can be amended by request field field_mask

WatchCryptoKeyResponse Message

A response message of the WatchCryptoKey method.

Name Type Description
change CryptoKeyChange

WatchCryptoKeysRequest Message

A request message of the WatchCryptoKeys method.

Name Type Description
type WatchType Type of a watch. Identifies how server stream data to a client, which fields in a request are allowed and which fields in response are relevant.
parent string (parent name of CryptoKey) Parent name of ntt.secrets.v1.CryptoKey
page_size int32 Requested page size. Server may return fewer CryptoKeys than requested. If unspecified, server will pick an appropriate default. Can be populated only for stateful watch type.
page_token string (cursor of CryptoKey) A token identifying a page of results the server should return. Can be populated only for stateful watch type.
order_by string (orderBy of CryptoKey) Order By - https://cloud.google.com/apis/design/design_patterns#list_pagination Can be populated only for stateful watch type.
resume_token string A token identifying watch resume point from previous session. Can be populated only for stateless watch type.
starting_time .google.protobuf.Timestamp Point in the time from which we want to start getting updates. This field can be populated only for stateless watch type and if resume token is not known yet. If specified, initial snapshot will NOT be provided. It is assumed client can obtain it using separate means. Watch responses will contain resume tokens which should be used to resume broken connection.
filter string (filter of CryptoKey) Filter - filter results by field criteria. Simplified SQL-like syntax with following operators: <=, >=, =, !=, <, >, LIKE, CONTAINS (aliases CONTAIN, HAS, HAVE), IN, IS [NOT] NULL
field_mask .google.protobuf.FieldMask A list of extra fields to be obtained for each response item on top of fields defined by request field view Changes to CryptoKey that don’t affect any of masked fields won’t be sent back.
view View View defines list of standard response fields present in response items. Additional fields can be amended by request field field_mask Changes to CryptoKey that don’t affect any of masked fields won’t be sent back.
max_chunk_size int32 Maximum amount of changes in each response message. Query result response is divided on the server side into chunks with size of a specified amount to limit memory footprint of each message. Responses will hold information whether more elements will continue for the actual change. If unspecified, server will pick an appropriate default.

WatchCryptoKeysResponse Message

A response message of the WatchCryptoKeys method.

Name Type Description
crypto_key_changes repeated CryptoKeyChange Changes of CryptoKeys
is_current bool If request specified max_chunk_size (or this limit was enforced if stateless watch has been chosen), then responses with “full changeset” will be divided into chunks. Client should keep receiving messages and, once is_current has value true, combine this recent message with all previous ones where is_current is false. If this is the first is_current in a whole watch stream, then it means that client should have, at this moment, contain snapshot of the current situation (or more accurately, snapshot of situation at the moment of request). All CryptoKeys will be of type Added/Current (depending on watch_type specified in the request). Further responses will be incremental - however messages may still be chunked and is_current logic still applies. is_current is always true for stateful watch if max_chunk_size was left to 0.
page_token_change WatchCryptoKeysResponse.PageTokenChange When present, PageTokens used for page navigation should be updated. Present only if is_current is true (last chunk).
resume_token string Token that can be used if current connection drops and client needs to reconnect. Populated only for stateless watch type. Present only if is_current is true (last chunk).
snapshot_size int64 Server may occasionally send information how many resources should client have in its state so far (response message without any changes, but with snapshot_size field specified). If client has different value than the one sent by the server, then it should be treated by a client as an error and should reconnect. If value is smaller then 0, then client should ignore this field as unpopulated. This field should be checked only for stateless watch. In stateful those kind of errors are handled by the server side. Will be never sent together with is_current, is_soft_reset and is_hard_reset flags.
is_soft_reset bool In case of internal issue server may send response message with this flag. It indicates that client should drop all changes from recent responses where is_current is false only! If last message had is_current set to true, client should do nothing and process normally. Resume token received before is still valid. This field should be checked only for stateless watch. In stateful those kind of errors are handled by the server side. Will never be sent along with is_current, is_hard_reset or snapshot_size.
is_hard_reset bool In case of internal issue server may send response message with this flag. After receiving, client should clear whole state (drop all changes received so far) as server will send new snapshot (CryptoKeys will contains changes of type Current only). Any resume tokens should be discarded as well. This field should be checked only for stateless watch. In stateful those kind of errors are handled by the server side. Will never be sent along with is_current, is_soft_reset or snapshot_size.

WatchCryptoKeysResponse.PageTokenChange Message

Name Type Description
prev_page_token string (cursor of CryptoKey) New token to retrieve previous page of results.
next_page_token string (cursor of CryptoKey) New token to retrieve next page of results.

DeleteCryptoKeyRequest Message

A request message of the DeleteCryptoKey method.

Name Type Description
name string (name of CryptoKey) Name of ntt.secrets.v1.CryptoKey

Project Resource

Project Resource

Name patterns:

  • projects/{project}

This section covers the methods and messages to interact with Project resource.

Project Methods

Here is the list of Project resource methods:

GetProject Method

GetProject

rpc GetProject(GetProjectRequest) returns (Project)

with the following messages:

Required Permissions:

  • services/secrets.edgelq.com/permissions/projects.get

The equivalent REST API is:

GET /v1/{name=projects/*}

BatchGetProjects Method

BatchGetProjects

rpc BatchGetProjects(BatchGetProjectsRequest) returns (BatchGetProjectsResponse)

with the following messages:

Required Permissions:

  • services/secrets.edgelq.com/permissions/projects.batchGet

The equivalent REST API is:

GET /v1/projects:batchGet

ListProjects Method

ListProjects

rpc ListProjects(ListProjectsRequest) returns (ListProjectsResponse)

with the following messages:

Required Permissions:

  • services/secrets.edgelq.com/permissions/projects.list

The equivalent REST API is:

GET /v1/projects

WatchProject Method

WatchProject

rpc WatchProject(WatchProjectRequest) returns (WatchProjectResponse)

with the following messages:

Required Permissions:

  • services/secrets.edgelq.com/permissions/projects.watch

The equivalent REST API is:

POST /v1/{name=projects/*}:watch

WatchProjects Method

WatchProjects

rpc WatchProjects(WatchProjectsRequest) returns (WatchProjectsResponse)

with the following messages:

Required Permissions:

  • services/secrets.edgelq.com/permissions/projects.watch

The equivalent REST API is:

POST /v1/projects:watch

CreateProject Method

CreateProject

rpc CreateProject(CreateProjectRequest) returns (Project)

with the following messages:

Required Permissions:

  • services/secrets.edgelq.com/permissions/projects.create

The equivalent REST API is:

POST /v1/projects (BODY: project)

UpdateProject Method

UpdateProject

rpc UpdateProject(UpdateProjectRequest) returns (Project)

with the following messages:

Required Permissions:

  • services/secrets.edgelq.com/permissions/projects.update

The equivalent REST API is:

PUT /v1/{project.name=projects/*} (BODY: project)

DeleteProject Method

DeleteProject

rpc DeleteProject(DeleteProjectRequest) returns (Empty)

with the following messages:

Required Permissions:

  • services/secrets.edgelq.com/permissions/projects.delete

The equivalent REST API is:

DELETE /v1/{name=projects/*}

Project Messages

Here is the list of Project resource messages:

Project Message

Name Type Description
name string (name of Project) Name of Project When creating a new instance, this field is optional and if not provided, it will be generated automatically. Last ID segment must conform to the following regex: [a-z][a-z0-9\-]{0,28}[a-z0-9]
metadata Meta Metadata is an object with information like create, update and delete time (for async deleted resources), has user labels/annotations, sharding information, multi-region syncing information and may have non-schema owners (useful for taking ownership of resources belonging to lower level services by higher ones).
multi_region_policy MultiRegionPolicy Multi region policy defines in which region all kid resources (and their kids) will by default belong and cross-region syncing policies.

GetProjectRequest Message

A request message of the GetProject method.

Name Type Description
name string (name of Project) Name of ntt.secrets.v1.Project
field_mask .google.protobuf.FieldMask A list of extra fields to be obtained for each response item on top of fields defined by request field view
view View View defines list of standard response fields present in response items. Additional fields can be amended by request field field_mask

BatchGetProjectsRequest Message

A request message of the BatchGetProjects method.

Name Type Description
names repeated string (name of Project) Names of Projects
field_mask .google.protobuf.FieldMask A list of extra fields to be obtained for each response item on top of fields defined by request field view
view View View defines list of standard response fields present in response items. Additional fields can be amended by request field field_mask

BatchGetProjectsResponse Message

A response message of the BatchGetProjects method.

Name Type Description
projects repeated Project found Projects
missing repeated string (name of Project) list of not found Projects

ListProjectsRequest Message

A request message of the ListProjects method.

Name Type Description
page_size int32 Requested page size. Server may return fewer Projects than requested. If unspecified, server will pick an appropriate default.
page_token string (cursor of Project) A token identifying a page of results the server should return. Typically, this is the value of ListProjectsResponse.next_page_token.
order_by string (orderBy of Project) Order By - https://cloud.google.com/apis/design/design_patterns#list_pagination list of field path with order directive, either ‘asc’ or ‘desc’. If direction is not provided, ‘asc’ is assumed. e.g. “state.nested_field asc, state.something.else desc, theme”
filter string (filter of Project) Filter - filter results by field criteria. Simplified SQL-like syntax with following operators: <=, >=, =, !=, <, >, LIKE, CONTAINS (aliases CONTAIN, HAS, HAVE), IN, IS [NOT] NULL
field_mask .google.protobuf.FieldMask A list of extra fields to be obtained for each response item on top of fields defined by request field view
view View View defines list of standard response fields present in response items. Additional fields can be amended by request field field_mask
include_paging_info bool Indicates if list response should contain total count and offset (fields current_offset and total_results_count).

ListProjectsResponse Message

A response message of the ListProjects method.

Name Type Description
projects repeated Project The list of Projects
prev_page_token string (cursor of Project) A token to retrieve previous page of results. Pass this value in the ListProjectsRequest.page_token.
next_page_token string (cursor of Project) A token to retrieve next page of results. Pass this value in the ListProjectsRequest.page_token.
current_offset int32 Current offset from the first page or 0 if no page tokens were given, paging info was not requested or there was an error while trying to get it). Page index can be computed from offset and limit provided in a request.
total_results_count int32 Number of total Projects across all pages or 0, if there are no items, paging info was not requested or there was an error while trying to get it.

WatchProjectRequest Message

A request message of the WatchProject method.

Name Type Description
name string (name of Project) Name of ntt.secrets.v1.Project
field_mask .google.protobuf.FieldMask A list of extra fields to be obtained for each response item on top of fields defined by request field view
view View View defines list of standard response fields present in response items. Additional fields can be amended by request field field_mask

WatchProjectResponse Message

A response message of the WatchProject method.

Name Type Description
change ProjectChange

WatchProjectsRequest Message

A request message of the WatchProjects method.

Name Type Description
type WatchType Type of a watch. Identifies how server stream data to a client, which fields in a request are allowed and which fields in response are relevant.
page_size int32 Requested page size. Server may return fewer Projects than requested. If unspecified, server will pick an appropriate default. Can be populated only for stateful watch type.
page_token string (cursor of Project) A token identifying a page of results the server should return. Can be populated only for stateful watch type.
order_by string (orderBy of Project) Order By - https://cloud.google.com/apis/design/design_patterns#list_pagination Can be populated only for stateful watch type.
resume_token string A token identifying watch resume point from previous session. Can be populated only for stateless watch type.
starting_time .google.protobuf.Timestamp Point in the time from which we want to start getting updates. This field can be populated only for stateless watch type and if resume token is not known yet. If specified, initial snapshot will NOT be provided. It is assumed client can obtain it using separate means. Watch responses will contain resume tokens which should be used to resume broken connection.
filter string (filter of Project) Filter - filter results by field criteria. Simplified SQL-like syntax with following operators: <=, >=, =, !=, <, >, LIKE, CONTAINS (aliases CONTAIN, HAS, HAVE), IN, IS [NOT] NULL
field_mask .google.protobuf.FieldMask A list of extra fields to be obtained for each response item on top of fields defined by request field view Changes to Project that don’t affect any of masked fields won’t be sent back.
view View View defines list of standard response fields present in response items. Additional fields can be amended by request field field_mask Changes to Project that don’t affect any of masked fields won’t be sent back.
max_chunk_size int32 Maximum amount of changes in each response message. Query result response is divided on the server side into chunks with size of a specified amount to limit memory footprint of each message. Responses will hold information whether more elements will continue for the actual change. If unspecified, server will pick an appropriate default.

WatchProjectsResponse Message

A response message of the WatchProjects method.

Name Type Description
project_changes repeated ProjectChange Changes of Projects
is_current bool If request specified max_chunk_size (or this limit was enforced if stateless watch has been chosen), then responses with “full changeset” will be divided into chunks. Client should keep receiving messages and, once is_current has value true, combine this recent message with all previous ones where is_current is false. If this is the first is_current in a whole watch stream, then it means that client should have, at this moment, contain snapshot of the current situation (or more accurately, snapshot of situation at the moment of request). All Projects will be of type Added/Current (depending on watch_type specified in the request). Further responses will be incremental - however messages may still be chunked and is_current logic still applies. is_current is always true for stateful watch if max_chunk_size was left to 0.
page_token_change WatchProjectsResponse.PageTokenChange When present, PageTokens used for page navigation should be updated. Present only if is_current is true (last chunk).
resume_token string Token that can be used if current connection drops and client needs to reconnect. Populated only for stateless watch type. Present only if is_current is true (last chunk).
snapshot_size int64 Server may occasionally send information how many resources should client have in its state so far (response message without any changes, but with snapshot_size field specified). If client has different value than the one sent by the server, then it should be treated by a client as an error and should reconnect. If value is smaller then 0, then client should ignore this field as unpopulated. This field should be checked only for stateless watch. In stateful those kind of errors are handled by the server side. Will be never sent together with is_current, is_soft_reset and is_hard_reset flags.
is_soft_reset bool In case of internal issue server may send response message with this flag. It indicates that client should drop all changes from recent responses where is_current is false only! If last message had is_current set to true, client should do nothing and process normally. Resume token received before is still valid. This field should be checked only for stateless watch. In stateful those kind of errors are handled by the server side. Will never be sent along with is_current, is_hard_reset or snapshot_size.
is_hard_reset bool In case of internal issue server may send response message with this flag. After receiving, client should clear whole state (drop all changes received so far) as server will send new snapshot (Projects will contains changes of type Current only). Any resume tokens should be discarded as well. This field should be checked only for stateless watch. In stateful those kind of errors are handled by the server side. Will never be sent along with is_current, is_soft_reset or snapshot_size.

WatchProjectsResponse.PageTokenChange Message

Name Type Description
prev_page_token string (cursor of Project) New token to retrieve previous page of results.
next_page_token string (cursor of Project) New token to retrieve next page of results.

CreateProjectRequest Message

A request message of the CreateProject method.

Name Type Description
project Project Project resource body
response_mask CreateProjectRequest.ResponseMask Optional masking applied to response object to reduce message response size.

CreateProjectRequest.ResponseMask Message

ResponseMask allows client to reduce response message size.

Name Type Description
skip_entire_response_body bool If this flag has value true, then response will contain just empty resource without any fields populated.
body_mask .google.protobuf.FieldMask If this field is populated, then resource in response will contain only specific fields.

UpdateProjectRequest Message

A request message of the UpdateProject method.

Name Type Description
project Project Project resource body
update_mask .google.protobuf.FieldMask FieldMask applied to request - change will be applied only for fields in the mask
cas UpdateProjectRequest.CAS Conditional update applied to request if update should be executed only for specific resource state. If this field is populated, then server will fetch existing resource, compare with the one stored in the cas field (after applying field mask) and proceed with update only and only if they match. Otherwise RPC error Aborted will be returned.
allow_missing bool If set to true, and the resource is not found, a new resource will be created. In this situation, ‘field_mask’ is ignored. https://google.aip.dev/134#create-or-update
response_mask UpdateProjectRequest.ResponseMask reduce message response size.

UpdateProjectRequest.CAS Message

CAS - Compare and Swap. This object is used if user wants to make update conditional based upon previous resource version.

Name Type Description
conditional_state Project Conditional desired state of a resource before update.
field_mask .google.protobuf.FieldMask Field paths from conditional state of resource server should check and compare.

UpdateProjectRequest.ResponseMask Message

ResponseMask allows client to reduce response message size.

Name Type Description
skip_entire_response_body bool If this flag has value true, then response will contain just empty resource without any fields populated. Field body_mask is ignored if set.
updated_fields_only bool Include all fields that were actually updated during processing. Note this may be larger than update mask if some fields were computed additionally. Name is added as well.
body_mask .google.protobuf.FieldMask If this field is populated, then resource in response will contain only specific fields. If skip_entire_response_body is true, this field is ignored.

DeleteProjectRequest Message

A request message of the DeleteProject method.

Name Type Description
name string (name of Project) Name of ntt.secrets.v1.Project

Secret Resource

Secret Resource

Name patterns:

  • projects/{project}/regions/{region}/secrets/{secret}

Parent resources:

This section covers the methods and messages to interact with Secret resource.

Secret Methods

Here is the list of Secret resource methods:

GetSecret Method

GetSecret

rpc GetSecret(GetSecretRequest) returns (Secret)

with the following messages:

Required Permissions:

  • services/secrets.edgelq.com/permissions/secrets.get

The equivalent REST API is:

GET /v1/{name=projects/*/regions/*/secrets/*}

BatchGetSecrets Method

BatchGetSecrets

rpc BatchGetSecrets(BatchGetSecretsRequest) returns (BatchGetSecretsResponse)

with the following messages:

Required Permissions:

  • services/secrets.edgelq.com/permissions/secrets.batchGet

The equivalent REST API is:

GET /v1/secrets:batchGet

ListSecrets Method

ListSecrets

rpc ListSecrets(ListSecretsRequest) returns (ListSecretsResponse)

with the following messages:

Required Permissions:

  • services/secrets.edgelq.com/permissions/secrets.list

The equivalent REST API is:

GET /v1/{parent=projects/*/regions/*}/secrets

WatchSecret Method

WatchSecret

rpc WatchSecret(WatchSecretRequest) returns (WatchSecretResponse)

with the following messages:

Required Permissions:

  • services/secrets.edgelq.com/permissions/secrets.watch

The equivalent REST API is:

POST /v1/{name=projects/*/regions/*/secrets/*}:watch

WatchSecrets Method

WatchSecrets

rpc WatchSecrets(WatchSecretsRequest) returns (WatchSecretsResponse)

with the following messages:

Required Permissions:

  • services/secrets.edgelq.com/permissions/secrets.watch

The equivalent REST API is:

POST /v1/{parent=projects/*/regions/*}/secrets:watch

CreateSecret Method

CreateSecret

rpc CreateSecret(CreateSecretRequest) returns (Secret)

with the following messages:

Required Permissions:

  • services/secrets.edgelq.com/permissions/secrets.create

The equivalent REST API is:

POST /v1/{parent=projects/*/regions/*}/secrets (BODY: secret)

UpdateSecret Method

UpdateSecret

rpc UpdateSecret(UpdateSecretRequest) returns (Secret)

with the following messages:

Required Permissions:

  • services/secrets.edgelq.com/permissions/secrets.update

The equivalent REST API is:

PUT /v1/{secret.name=projects/*/regions/*/secrets/*} (BODY: secret)

DeleteSecret Method

DeleteSecret

rpc DeleteSecret(DeleteSecretRequest) returns (Empty)

with the following messages:

Required Permissions:

  • services/secrets.edgelq.com/permissions/secrets.delete

The equivalent REST API is:

DELETE /v1/{name=projects/*/regions/*/secrets/*}

Secret Messages

Here is the list of Secret resource messages:

Secret Message

Name Type Description
name string (name of Secret) Name of Secret When creating a new instance, this field is optional and if not provided, it will be generated automatically. Last ID segment must conform to the following regex: [a-z][a-z0-9\-]{0,28}[a-z0-9]
metadata Meta Metadata is an object with information like create, update and delete time (for async deleted resources), has user labels/annotations, sharding information, multi-region syncing information and may have non-schema owners (useful for taking ownership of resources belonging to lower level services by higher ones).
display_name string Display name of Secret
description string Optional. A detailed description of the Secret.
enc_data bytes masked by read_checks. Database only.
data map<string, string> Data to store as secret. Must be base64 encoded.

GetSecretRequest Message

A request message of the GetSecret method.

Name Type Description
name string (name of Secret) Name of ntt.secrets.v1.Secret
field_mask .google.protobuf.FieldMask A list of extra fields to be obtained for each response item on top of fields defined by request field view
view View View defines list of standard response fields present in response items. Additional fields can be amended by request field field_mask

BatchGetSecretsRequest Message

A request message of the BatchGetSecrets method.

Name Type Description
names repeated string (name of Secret) Names of Secrets
field_mask .google.protobuf.FieldMask A list of extra fields to be obtained for each response item on top of fields defined by request field view
view View View defines list of standard response fields present in response items. Additional fields can be amended by request field field_mask

BatchGetSecretsResponse Message

A response message of the BatchGetSecrets method.

Name Type Description
secrets repeated Secret found Secrets
missing repeated string (name of Secret) list of not found Secrets

ListSecretsRequest Message

A request message of the ListSecrets method.

Name Type Description
parent string (parent name of Secret) Parent name of ntt.secrets.v1.Secret
page_size int32 Requested page size. Server may return fewer Secrets than requested. If unspecified, server will pick an appropriate default.
page_token string (cursor of Secret) A token identifying a page of results the server should return. Typically, this is the value of ListSecretsResponse.next_page_token.
order_by string (orderBy of Secret) Order By - https://cloud.google.com/apis/design/design_patterns#list_pagination list of field path with order directive, either ‘asc’ or ‘desc’. If direction is not provided, ‘asc’ is assumed. e.g. “state.nested_field asc, state.something.else desc, theme”
filter string (filter of Secret) Filter - filter results by field criteria. Simplified SQL-like syntax with following operators: <=, >=, =, !=, <, >, LIKE, CONTAINS (aliases CONTAIN, HAS, HAVE), IN, IS [NOT] NULL
field_mask .google.protobuf.FieldMask A list of extra fields to be obtained for each response item on top of fields defined by request field view
view View View defines list of standard response fields present in response items. Additional fields can be amended by request field field_mask
include_paging_info bool Indicates if list response should contain total count and offset (fields current_offset and total_results_count).

ListSecretsResponse Message

A response message of the ListSecrets method.

Name Type Description
secrets repeated Secret The list of Secrets
prev_page_token string (cursor of Secret) A token to retrieve previous page of results. Pass this value in the ListSecretsRequest.page_token.
next_page_token string (cursor of Secret) A token to retrieve next page of results. Pass this value in the ListSecretsRequest.page_token.
current_offset int32 Current offset from the first page or 0 if no page tokens were given, paging info was not requested or there was an error while trying to get it). Page index can be computed from offset and limit provided in a request.
total_results_count int32 Number of total Secrets across all pages or 0, if there are no items, paging info was not requested or there was an error while trying to get it.

WatchSecretRequest Message

A request message of the WatchSecret method.

Name Type Description
name string (name of Secret) Name of ntt.secrets.v1.Secret
field_mask .google.protobuf.FieldMask A list of extra fields to be obtained for each response item on top of fields defined by request field view
view View View defines list of standard response fields present in response items. Additional fields can be amended by request field field_mask

WatchSecretResponse Message

A response message of the WatchSecret method.

Name Type Description
change SecretChange

WatchSecretsRequest Message

A request message of the WatchSecrets method.

Name Type Description
type WatchType Type of a watch. Identifies how server stream data to a client, which fields in a request are allowed and which fields in response are relevant.
parent string (parent name of Secret) Parent name of ntt.secrets.v1.Secret
page_size int32 Requested page size. Server may return fewer Secrets than requested. If unspecified, server will pick an appropriate default. Can be populated only for stateful watch type.
page_token string (cursor of Secret) A token identifying a page of results the server should return. Can be populated only for stateful watch type.
order_by string (orderBy of Secret) Order By - https://cloud.google.com/apis/design/design_patterns#list_pagination Can be populated only for stateful watch type.
resume_token string A token identifying watch resume point from previous session. Can be populated only for stateless watch type.
starting_time .google.protobuf.Timestamp Point in the time from which we want to start getting updates. This field can be populated only for stateless watch type and if resume token is not known yet. If specified, initial snapshot will NOT be provided. It is assumed client can obtain it using separate means. Watch responses will contain resume tokens which should be used to resume broken connection.
filter string (filter of Secret) Filter - filter results by field criteria. Simplified SQL-like syntax with following operators: <=, >=, =, !=, <, >, LIKE, CONTAINS (aliases CONTAIN, HAS, HAVE), IN, IS [NOT] NULL
field_mask .google.protobuf.FieldMask A list of extra fields to be obtained for each response item on top of fields defined by request field view Changes to Secret that don’t affect any of masked fields won’t be sent back.
view View View defines list of standard response fields present in response items. Additional fields can be amended by request field field_mask Changes to Secret that don’t affect any of masked fields won’t be sent back.
max_chunk_size int32 Maximum amount of changes in each response message. Query result response is divided on the server side into chunks with size of a specified amount to limit memory footprint of each message. Responses will hold information whether more elements will continue for the actual change. If unspecified, server will pick an appropriate default.

WatchSecretsResponse Message

A response message of the WatchSecrets method.

Name Type Description
secret_changes repeated SecretChange Changes of Secrets
is_current bool If request specified max_chunk_size (or this limit was enforced if stateless watch has been chosen), then responses with “full changeset” will be divided into chunks. Client should keep receiving messages and, once is_current has value true, combine this recent message with all previous ones where is_current is false. If this is the first is_current in a whole watch stream, then it means that client should have, at this moment, contain snapshot of the current situation (or more accurately, snapshot of situation at the moment of request). All Secrets will be of type Added/Current (depending on watch_type specified in the request). Further responses will be incremental - however messages may still be chunked and is_current logic still applies. is_current is always true for stateful watch if max_chunk_size was left to 0.
page_token_change WatchSecretsResponse.PageTokenChange When present, PageTokens used for page navigation should be updated. Present only if is_current is true (last chunk).
resume_token string Token that can be used if current connection drops and client needs to reconnect. Populated only for stateless watch type. Present only if is_current is true (last chunk).
snapshot_size int64 Server may occasionally send information how many resources should client have in its state so far (response message without any changes, but with snapshot_size field specified). If client has different value than the one sent by the server, then it should be treated by a client as an error and should reconnect. If value is smaller then 0, then client should ignore this field as unpopulated. This field should be checked only for stateless watch. In stateful those kind of errors are handled by the server side. Will be never sent together with is_current, is_soft_reset and is_hard_reset flags.
is_soft_reset bool In case of internal issue server may send response message with this flag. It indicates that client should drop all changes from recent responses where is_current is false only! If last message had is_current set to true, client should do nothing and process normally. Resume token received before is still valid. This field should be checked only for stateless watch. In stateful those kind of errors are handled by the server side. Will never be sent along with is_current, is_hard_reset or snapshot_size.
is_hard_reset bool In case of internal issue server may send response message with this flag. After receiving, client should clear whole state (drop all changes received so far) as server will send new snapshot (Secrets will contains changes of type Current only). Any resume tokens should be discarded as well. This field should be checked only for stateless watch. In stateful those kind of errors are handled by the server side. Will never be sent along with is_current, is_soft_reset or snapshot_size.

WatchSecretsResponse.PageTokenChange Message

Name Type Description
prev_page_token string (cursor of Secret) New token to retrieve previous page of results.
next_page_token string (cursor of Secret) New token to retrieve next page of results.

CreateSecretRequest Message

A request message of the CreateSecret method.

Name Type Description
parent string (parent name of Secret) Parent name of ntt.secrets.v1.Secret
secret Secret Secret resource body
response_mask CreateSecretRequest.ResponseMask Optional masking applied to response object to reduce message response size.

CreateSecretRequest.ResponseMask Message

ResponseMask allows client to reduce response message size.

Name Type Description
skip_entire_response_body bool If this flag has value true, then response will contain just empty resource without any fields populated.
body_mask .google.protobuf.FieldMask If this field is populated, then resource in response will contain only specific fields.

UpdateSecretRequest Message

A request message of the UpdateSecret method.

Name Type Description
secret Secret Secret resource body
update_mask .google.protobuf.FieldMask FieldMask applied to request - change will be applied only for fields in the mask
cas UpdateSecretRequest.CAS Conditional update applied to request if update should be executed only for specific resource state. If this field is populated, then server will fetch existing resource, compare with the one stored in the cas field (after applying field mask) and proceed with update only and only if they match. Otherwise RPC error Aborted will be returned.
allow_missing bool If set to true, and the resource is not found, a new resource will be created. In this situation, ‘field_mask’ is ignored. https://google.aip.dev/134#create-or-update
response_mask UpdateSecretRequest.ResponseMask reduce message response size.

UpdateSecretRequest.CAS Message

CAS - Compare and Swap. This object is used if user wants to make update conditional based upon previous resource version.

Name Type Description
conditional_state Secret Conditional desired state of a resource before update.
field_mask .google.protobuf.FieldMask Field paths from conditional state of resource server should check and compare.

UpdateSecretRequest.ResponseMask Message

ResponseMask allows client to reduce response message size.

Name Type Description
skip_entire_response_body bool If this flag has value true, then response will contain just empty resource without any fields populated. Field body_mask is ignored if set.
updated_fields_only bool Include all fields that were actually updated during processing. Note this may be larger than update mask if some fields were computed additionally. Name is added as well.
body_mask .google.protobuf.FieldMask If this field is populated, then resource in response will contain only specific fields. If skip_entire_response_body is true, this field is ignored.

DeleteSecretRequest Message

A request message of the DeleteSecret method.

Name Type Description
name string (name of Secret) Name of ntt.secrets.v1.Secret

Secrets Service Shared Methods and Messages

Secrets Service Shared Messages

Here is the list of Secrets service shared messages:

CryptoKeyChange Message

CryptoKeyChange is used by Watch notifications Responses to describe change of single CryptoKey One of Added, Modified, Removed

Name Type Description
added CryptoKeyChange.Added Added is returned when watched document is added, either created or enters Query view
modified CryptoKeyChange.Modified Modified is returned when watched document is modified
current CryptoKeyChange.Current Current is returned in stateless watch when document enters query view or is modified within.
removed CryptoKeyChange.Removed Removed is returned when CryptoKey is deleted or leaves Query view

CryptoKeyChange.Added Message

CryptoKey has been added to query view

Name Type Description
crypto_key CryptoKey
view_index int32 Integer describing index of added CryptoKey in resulting query view.

CryptoKeyChange.Current Message

CryptoKey has been added or modified in a query view. Version used for stateless watching

Name Type Description
crypto_key CryptoKey

CryptoKeyChange.Modified Message

CryptoKey changed some of it’s fields - contains either full document or masked change

Name Type Description
name string (name of CryptoKey) Name of modified CryptoKey
crypto_key CryptoKey New version of CryptoKey or masked difference, depending on mask_changes instrumentation of issued [WatchCryptoKeyRequest] or [WatchCryptoKeysRequest]
field_mask .google.protobuf.FieldMask Used when mask_changes is set, contains field paths of modified properties.
previous_view_index int32 Previous view index specifies previous position of modified CryptoKey. When modification doesn’t affect sorted order, value will remain identical to [view_index].
view_index int32 Integer specifying CryptoKey new index in resulting query view.

CryptoKeyChange.Removed Message

Removed is returned when CryptoKey is deleted or leaves Query view

Name Type Description
name string (name of CryptoKey)
view_index int32 Integer specifying removed CryptoKey index. Not populated in stateless watch type.

ProjectChange Message

ProjectChange is used by Watch notifications Responses to describe change of single Project One of Added, Modified, Removed

Name Type Description
added ProjectChange.Added Added is returned when watched document is added, either created or enters Query view
modified ProjectChange.Modified Modified is returned when watched document is modified
current ProjectChange.Current Current is returned in stateless watch when document enters query view or is modified within.
removed ProjectChange.Removed Removed is returned when Project is deleted or leaves Query view

ProjectChange.Added Message

Project has been added to query view

Name Type Description
project Project
view_index int32 Integer describing index of added Project in resulting query view.

ProjectChange.Current Message

Project has been added or modified in a query view. Version used for stateless watching

Name Type Description
project Project

ProjectChange.Modified Message

Project changed some of it’s fields - contains either full document or masked change

Name Type Description
name string (name of Project) Name of modified Project
project Project New version of Project or masked difference, depending on mask_changes instrumentation of issued [WatchProjectRequest] or [WatchProjectsRequest]
field_mask .google.protobuf.FieldMask Used when mask_changes is set, contains field paths of modified properties.
previous_view_index int32 Previous view index specifies previous position of modified Project. When modification doesn’t affect sorted order, value will remain identical to [view_index].
view_index int32 Integer specifying Project new index in resulting query view.

ProjectChange.Removed Message

Removed is returned when Project is deleted or leaves Query view

Name Type Description
name string (name of Project)
view_index int32 Integer specifying removed Project index. Not populated in stateless watch type.

SecretChange Message

SecretChange is used by Watch notifications Responses to describe change of single Secret One of Added, Modified, Removed

Name Type Description
added SecretChange.Added Added is returned when watched document is added, either created or enters Query view
modified SecretChange.Modified Modified is returned when watched document is modified
current SecretChange.Current Current is returned in stateless watch when document enters query view or is modified within.
removed SecretChange.Removed Removed is returned when Secret is deleted or leaves Query view

SecretChange.Added Message

Secret has been added to query view

Name Type Description
secret Secret
view_index int32 Integer describing index of added Secret in resulting query view.

SecretChange.Current Message

Secret has been added or modified in a query view. Version used for stateless watching

Name Type Description
secret Secret

SecretChange.Modified Message

Secret changed some of it’s fields - contains either full document or masked change

Name Type Description
name string (name of Secret) Name of modified Secret
secret Secret New version of Secret or masked difference, depending on mask_changes instrumentation of issued [WatchSecretRequest] or [WatchSecretsRequest]
field_mask .google.protobuf.FieldMask Used when mask_changes is set, contains field paths of modified properties.
previous_view_index int32 Previous view index specifies previous position of modified Secret. When modification doesn’t affect sorted order, value will remain identical to [view_index].
view_index int32 Integer specifying Secret new index in resulting query view.

SecretChange.Removed Message

Removed is returned when Secret is deleted or leaves Query view

Name Type Description
name string (name of Secret)
view_index int32 Integer specifying removed Secret index. Not populated in stateless watch type.