Package google.cloud.servicedirectory.v1

Index

LookupService

Service Directory API for looking up service data at runtime.

ResolveService

rpc ResolveService(ResolveServiceRequest) returns (ResolveServiceResponse)

Returns a service and its associated endpoints. Resolving a service is not considered an active developer method.

Authorization Scopes

Requires the following OAuth scope:

  • https://www.googleapis.com/auth/cloud-platform

For more information, see the Authentication Overview.

RegistrationService

Service Directory API for registering services. It defines the following resource model:

  • The API has a collection of Namespace resources, named projects/*/locations/*/namespaces/*.

  • Each Namespace has a collection of Service resources, named projects/*/locations/*/namespaces/*/services/*.

  • Each Service has a collection of Endpoint resources, named projects/*/locations/*/namespaces/*/services/*/endpoints/*.

CreateEndpoint

rpc CreateEndpoint(CreateEndpointRequest) returns (Endpoint)

Creates an endpoint, and returns the new endpoint.

Authorization Scopes

Requires the following OAuth scope:

  • https://www.googleapis.com/auth/cloud-platform

For more information, see the Authentication Overview.
CreateNamespace

rpc CreateNamespace(CreateNamespaceRequest) returns (Namespace)

Creates a namespace, and returns the new namespace.

Authorization Scopes

Requires the following OAuth scope:

  • https://www.googleapis.com/auth/cloud-platform

For more information, see the Authentication Overview.
CreateService

rpc CreateService(CreateServiceRequest) returns (Service)

Creates a service, and returns the new service.

Authorization Scopes

Requires the following OAuth scope:

  • https://www.googleapis.com/auth/cloud-platform

For more information, see the Authentication Overview.
DeleteEndpoint

rpc DeleteEndpoint(DeleteEndpointRequest) returns (Empty)

Deletes an endpoint.

Authorization Scopes

Requires the following OAuth scope:

  • https://www.googleapis.com/auth/cloud-platform

For more information, see the Authentication Overview.
DeleteNamespace

rpc DeleteNamespace(DeleteNamespaceRequest) returns (Empty)

Deletes a namespace. This also deletes all services and endpoints in the namespace.

Authorization Scopes

Requires the following OAuth scope:

  • https://www.googleapis.com/auth/cloud-platform

For more information, see the Authentication Overview.
DeleteService

rpc DeleteService(DeleteServiceRequest) returns (Empty)

Deletes a service. This also deletes all endpoints associated with the service.

Authorization Scopes

Requires the following OAuth scope:

  • https://www.googleapis.com/auth/cloud-platform

For more information, see the Authentication Overview.
GetEndpoint

rpc GetEndpoint(GetEndpointRequest) returns (Endpoint)

Gets an endpoint.

Authorization Scopes

Requires the following OAuth scope:

  • https://www.googleapis.com/auth/cloud-platform

For more information, see the Authentication Overview.
GetIamPolicy

rpc GetIamPolicy(GetIamPolicyRequest) returns (Policy)

Gets the IAM Policy for a resource (namespace or service only).

Authorization Scopes

Requires the following OAuth scope:

  • https://www.googleapis.com/auth/cloud-platform

For more information, see the Authentication Overview.
GetNamespace

rpc GetNamespace(GetNamespaceRequest) returns (Namespace)

Gets a namespace.

Authorization Scopes

Requires the following OAuth scope:

  • https://www.googleapis.com/auth/cloud-platform

For more information, see the Authentication Overview.
GetService

rpc GetService(GetServiceRequest) returns (Service)

Gets a service.

Authorization Scopes

Requires the following OAuth scope:

  • https://www.googleapis.com/auth/cloud-platform

For more information, see the Authentication Overview.
ListEndpoints

rpc ListEndpoints(ListEndpointsRequest) returns (ListEndpointsResponse)

Lists all endpoints.

Authorization Scopes

Requires the following OAuth scope:

  • https://www.googleapis.com/auth/cloud-platform

For more information, see the Authentication Overview.
ListNamespaces

rpc ListNamespaces(ListNamespacesRequest) returns (ListNamespacesResponse)

Lists all namespaces.

Authorization Scopes

Requires the following OAuth scope:

  • https://www.googleapis.com/auth/cloud-platform

For more information, see the Authentication Overview.
ListServices

rpc ListServices(ListServicesRequest) returns (ListServicesResponse)

Lists all services belonging to a namespace.

Authorization Scopes

Requires the following OAuth scope:

  • https://www.googleapis.com/auth/cloud-platform

For more information, see the Authentication Overview.
SetIamPolicy

rpc SetIamPolicy(SetIamPolicyRequest) returns (Policy)

Sets the IAM Policy for a resource (namespace or service only).

Authorization Scopes

Requires the following OAuth scope:

  • https://www.googleapis.com/auth/cloud-platform

For more information, see the Authentication Overview.
TestIamPermissions

rpc TestIamPermissions(TestIamPermissionsRequest) returns (TestIamPermissionsResponse)

Tests IAM permissions for a resource (namespace or service only).

Authorization Scopes

Requires the following OAuth scope:

  • https://www.googleapis.com/auth/cloud-platform

For more information, see the Authentication Overview.
UpdateEndpoint

rpc UpdateEndpoint(UpdateEndpointRequest) returns (Endpoint)

Updates an endpoint.

Authorization Scopes

Requires the following OAuth scope:

  • https://www.googleapis.com/auth/cloud-platform

For more information, see the Authentication Overview.
UpdateNamespace

rpc UpdateNamespace(UpdateNamespaceRequest) returns (Namespace)

Updates a namespace.

Authorization Scopes

Requires the following OAuth scope:

  • https://www.googleapis.com/auth/cloud-platform

For more information, see the Authentication Overview.
UpdateService

rpc UpdateService(UpdateServiceRequest) returns (Service)

Updates a service.

Authorization Scopes

Requires the following OAuth scope:

  • https://www.googleapis.com/auth/cloud-platform

For more information, see the Authentication Overview.

CreateEndpointRequest

The request message for RegistrationService.CreateEndpoint.

Fields
parent

string

Required. The resource name of the service that this endpoint provides.

Authorization requires the following IAM permission on the specified resource parent:

  • servicedirectory.endpoints.create
endpoint_id

string

Required. The Resource ID must be 1-63 characters long, and comply with RFC1035. Specifically, the name must be 1-63 characters long and match the regular expression [a-z](?:[-a-z0-9]{0,61}[a-z0-9])? which means the first character must be a lowercase letter, and all following characters must be a dash, lowercase letter, or digit, except the last character, which cannot be a dash.
endpoint

Endpoint

Required. A endpoint with initial fields set.

CreateNamespaceRequest

The request message for RegistrationService.CreateNamespace.

Fields
parent

string

Required. The resource name of the project and location the namespace will be created in.

Authorization requires the following IAM permission on the specified resource parent:

  • servicedirectory.namespaces.create
namespace_id

string

Required. The Resource ID must be 1-63 characters long, and comply with RFC1035. Specifically, the name must be 1-63 characters long and match the regular expression [a-z](?:[-a-z0-9]{0,61}[a-z0-9])? which means the first character must be a lowercase letter, and all following characters must be a dash, lowercase letter, or digit, except the last character, which cannot be a dash.
namespace

Namespace

Required. A namespace with initial fields set.

CreateServiceRequest

The request message for RegistrationService.CreateService.

Fields
parent

string

Required. The resource name of the namespace this service will belong to.

Authorization requires the following IAM permission on the specified resource parent:

  • servicedirectory.services.create
service_id

string

Required. The Resource ID must be 1-63 characters long, and comply with RFC1035. Specifically, the name must be 1-63 characters long and match the regular expression [a-z](?:[-a-z0-9]{0,61}[a-z0-9])? which means the first character must be a lowercase letter, and all following characters must be a dash, lowercase letter, or digit, except the last character, which cannot be a dash.
service

Service

Required. A service with initial fields set.

DeleteEndpointRequest

The request message for RegistrationService.DeleteEndpoint.

Fields
name

string

Required. The name of the endpoint to delete.

Authorization requires the following IAM permission on the specified resource name:

  • servicedirectory.endpoints.delete

DeleteNamespaceRequest

The request message for RegistrationService.DeleteNamespace.

Fields
name

string

Required. The name of the namespace to delete.

Authorization requires the following IAM permission on the specified resource name:

  • servicedirectory.namespaces.delete

DeleteServiceRequest

The request message for RegistrationService.DeleteService.

Fields
name

string

Required. The name of the service to delete.

Authorization requires the following IAM permission on the specified resource name:

  • servicedirectory.services.delete

Endpoint

An individual endpoint that provides a service. The service must already exist to create an endpoint.

Fields
name

string

Immutable. The resource name for the endpoint in the format projects/*/locations/*/namespaces/*/services/*/endpoints/*.
address

string

Optional. An IPv4 or IPv6 address. Service Directory rejects bad addresses like:

  • 8.8.8
  • 8.8.8.8:53
  • test:bad:address
  • [::1]
  • [::1]:8080

Limited to 45 characters.
port

int32

Optional. Service Directory rejects values outside of [0, 65535].
annotations

map<string, string>

Optional. Annotations for the endpoint. This data can be consumed by service clients.

Restrictions:

  • The entire annotations dictionary may contain up to 512 characters, spread accoss all key-value pairs. Annotations that go beyond this limit are rejected
  • Valid annotation keys have two segments: an optional prefix and name, separated by a slash (/). The name segment is required and must be 63 characters or less, beginning and ending with an alphanumeric character ([a-z0-9A-Z]) with dashes (-), underscores (_), dots (.), and alphanumerics between. The prefix is optional. If specified, the prefix must be a DNS subdomain: a series of DNS labels separated by dots (.), not longer than 253 characters in total, followed by a slash (/) Annotations that fails to meet these requirements are rejected.

Note: This field is equivalent to the metadata field in the v1beta1 API. They have the same syntax and read/write to the same location in Service Directory.
network

string

Immutable. The Google Compute Engine network (VPC) of the endpoint in the format projects/<project number>/locations/global/networks/*.

The project must be specified by project number (project id is rejected). Incorrectly formatted networks are rejected, we also check to make sure that you have the servicedirectory.networks.attach permission on the project specified.
uid

string

Output only. The globally unique identifier of the endpoint in the UUID4 format.

GetEndpointRequest

The request message for RegistrationService.GetEndpoint. This should not be used to lookup endpoints at runtime. Instead, use the resolve method.

Fields
name

string

Required. The name of the endpoint to get.

Authorization requires the following IAM permission on the specified resource name:

  • servicedirectory.endpoints.get

GetNamespaceRequest

The request message for RegistrationService.GetNamespace.

Fields
name

string

Required. The name of the namespace to retrieve.

Authorization requires the following IAM permission on the specified resource name:

  • servicedirectory.namespaces.get

GetServiceRequest

The request message for RegistrationService.GetService. This should not be used for looking up a service. Instead, use the resolve method as it contains all endpoints and associated annotations.

Fields
name

string

Required. The name of the service to get.

Authorization requires the following IAM permission on the specified resource name:

  • servicedirectory.services.get

ListEndpointsRequest

The request message for RegistrationService.ListEndpoints.

Fields
parent

string

Required. The resource name of the service whose endpoints you'd like to list.

Authorization requires the following IAM permission on the specified resource parent:

  • servicedirectory.endpoints.list
page_size

int32

Optional. The maximum number of items to return.
page_token

string

Optional. The next_page_token value returned from a previous List request, if any.
filter

string

Optional. The filter to list results by.

General filter string syntax: <field> <operator> <value> (<logical connector>)

  • <field> can be name, address, port, or annotations.<key> for map field
  • <operator> can be <, >, <=, >=, !=, =, :. Of which : means HAS, and is roughly the same as =
  • <value> must be the same data type as field
  • <logical connector> can be AND, OR, NOT

Examples of valid filters:

  • annotations.owner returns endpoints that have a annotation with the key owner, this is the same as annotations:owner
  • annotations.protocol=gRPC returns endpoints that have key/value protocol=gRPC
  • address=192.108.1.105 returns endpoints that have this address
  • port>8080 returns endpoints that have port number larger than 8080 * name>projects/my-project/locations/us-east1/namespaces/my-namespace/services/my-service/endpoints/endpoint-c returns endpoints that have name that is alphabetically later than the string, so "endpoint-e" is returned but "endpoint-a" is not
  • annotations.owner!=sd AND annotations.foo=bar returns endpoints that have owner in annotation key but value is not sd AND have key/value foo=bar
  • doesnotexist.foo=bar returns an empty list. Note that endpoint doesn't have a field called "doesnotexist". Since the filter does not match any endpoints, it returns no results

For more information about filtering, see API Filtering.
order_by

string

Optional. The order to list results by.

General order_by string syntax: <field> (<asc|desc>) (,)

  • <field> allows values: name, address, port
  • <asc|desc> ascending or descending order by <field>. If this is left blank, asc is used

Note that an empty order_by string results in default order, which is order by name in ascending order.

ListEndpointsResponse

The response message for RegistrationService.ListEndpoints.

Fields
endpoints[]

Endpoint

The list of endpoints.
next_page_token

string

Token to retrieve the next page of results, or empty if there are no more results in the list.

ListNamespacesRequest

The request message for RegistrationService.ListNamespaces.

Fields
parent

string

Required. The resource name of the project and location whose namespaces you'd like to list.

Authorization requires the following IAM permission on the specified resource parent:

  • servicedirectory.namespaces.list
page_size

int32

Optional. The maximum number of items to return.
page_token

string

Optional. The next_page_token value returned from a previous List request, if any.
filter

string

Optional. The filter to list results by.

General filter string syntax: <field> <operator> <value> (<logical connector>)

  • <field> can be name or labels.<key> for map field
  • <operator> can be <, >, <=, >=, !=, =, :. Of which : means HAS, and is roughly the same as =
  • <value> must be the same data type as field
  • <logical connector> can be AND, OR, NOT

Examples of valid filters:

  • labels.owner returns namespaces that have a label with the key owner, this is the same as labels:owner
  • labels.owner=sd returns namespaces that have key/value owner=sd
  • name>projects/my-project/locations/us-east1/namespaces/namespace-c returns namespaces that have name that is alphabetically later than the string, so "namespace-e" is returned but "namespace-a" is not
  • labels.owner!=sd AND labels.foo=bar returns namespaces that have owner in label key but value is not sd AND have key/value foo=bar
  • doesnotexist.foo=bar returns an empty list. Note that namespace doesn't have a field called "doesnotexist". Since the filter does not match any namespaces, it returns no results

For more information about filtering, see API Filtering.
order_by

string

Optional. The order to list results by.

General order_by string syntax: <field> (<asc|desc>) (,)

  • <field> allows value: name
  • <asc|desc> ascending or descending order by <field>. If this is left blank, asc is used

Note that an empty order_by string results in default order, which is order by name in ascending order.

ListNamespacesResponse

The response message for RegistrationService.ListNamespaces.

Fields
namespaces[]

Namespace

The list of namespaces.
next_page_token

string

Token to retrieve the next page of results, or empty if there are no more results in the list.

ListServicesRequest

The request message for RegistrationService.ListServices.

Fields
parent

string

Required. The resource name of the namespace whose services you'd like to list.

Authorization requires the following IAM permission on the specified resource parent:

  • servicedirectory.services.list
page_size

int32

Optional. The maximum number of items to return.
page_token

string

Optional. The next_page_token value returned from a previous List request, if any.
filter

string

Optional. The filter to list results by.

General filter string syntax: <field> <operator> <value> (<logical connector>)

  • <field> can be name or annotations.<key> for map field
  • <operator> can be <, >, <=, >=, !=, =, :. Of which : means HAS, and is roughly the same as =
  • <value> must be the same data type as field
  • <logical connector> can be AND, OR, NOT

Examples of valid filters:

  • annotations.owner returns services that have a annotation with the key owner, this is the same as annotations:owner
  • annotations.protocol=gRPC returns services that have key/value protocol=gRPC * name>projects/my-project/locations/us-east1/namespaces/my-namespace/services/service-c returns services that have name that is alphabetically later than the string, so "service-e" is returned but "service-a" is not
  • annotations.owner!=sd AND annotations.foo=bar returns services that have owner in annotation key but value is not sd AND have key/value foo=bar
  • doesnotexist.foo=bar returns an empty list. Note that service doesn't have a field called "doesnotexist". Since the filter does not match any services, it returns no results

For more information about filtering, see API Filtering.
order_by

string

Optional. The order to list results by.

General order_by string syntax: <field> (<asc|desc>) (,)

  • <field> allows value: name
  • <asc|desc> ascending or descending order by <field>. If this is left blank, asc is used

Note that an empty order_by string results in default order, which is order by name in ascending order.

ListServicesResponse

The response message for RegistrationService.ListServices.

Fields
services[]

Service

The list of services.
next_page_token

string

Token to retrieve the next page of results, or empty if there are no more results in the list.

Namespace

A container for services. Namespaces allow administrators to group services together and define permissions for a collection of services.

Fields
name

string

Immutable. The resource name for the namespace in the format projects/*/locations/*/namespaces/*.
labels

map<string, string>

Optional. Resource labels associated with this namespace. No more than 64 user labels can be associated with a given resource. Label keys and values can be no longer than 63 characters.
uid

string

Output only. The globally unique identifier of the namespace in the UUID4 format.

ResolveServiceRequest

The request message for LookupService.ResolveService. Looks up a service by its name, returns the service and its endpoints.

Fields
name

string

Required. The name of the service to resolve.

Authorization requires the following IAM permission on the specified resource name:

  • servicedirectory.services.resolve
max_endpoints

int32

Optional. The maximum number of endpoints to return. Defaults to 25. Maximum is 100. If a value less than one is specified, the Default is used. If a value greater than the Maximum is specified, the Maximum is used.
endpoint_filter

string

Optional. The filter applied to the endpoints of the resolved service.

General filter string syntax: <field> <operator> <value> (<logical connector>)

  • <field> can be name, address, port, or annotations.<key> for map field
  • <operator> can be <, >, <=, >=, !=, =, :. Of which : means HAS, and is roughly the same as =
  • <value> must be the same data type as field
  • <logical connector> can be AND, OR, NOT

Examples of valid filters:

  • annotations.owner returns endpoints that have a annotation with the key owner, this is the same as annotations:owner
  • annotations.protocol=gRPC returns endpoints that have key/value protocol=gRPC
  • address=192.108.1.105 returns endpoints that have this address
  • port>8080 returns endpoints that have port number larger than 8080 * name>projects/my-project/locations/us-east1/namespaces/my-namespace/services/my-service/endpoints/endpoint-c returns endpoints that have name that is alphabetically later than the string, so "endpoint-e" is returned but "endpoint-a" is not * name=projects/my-project/locations/us-central1/namespaces/my-namespace/services/my-service/endpoints/ep-1 returns the endpoint that has an endpoint_id equal to ep-1
  • annotations.owner!=sd AND annotations.foo=bar returns endpoints that have owner in annotation key but value is not sd AND have key/value foo=bar
  • doesnotexist.foo=bar returns an empty list. Note that endpoint doesn't have a field called "doesnotexist". Since the filter does not match any endpoint, it returns no results

For more information about filtering, see API Filtering.

ResolveServiceResponse

The response message for LookupService.ResolveService.

Fields
service

Service

Service

An individual service. A service contains a name and optional metadata. A service must exist before endpoints can be added to it.

Fields
name

string

Immutable. The resource name for the service in the format projects/*/locations/*/namespaces/*/services/*.
annotations

map<string, string>

Optional. Annotations for the service. This data can be consumed by service clients.

Restrictions:

  • The entire annotations dictionary may contain up to 2000 characters, spread accoss all key-value pairs. Annotations that go beyond this limit are rejected
  • Valid annotation keys have two segments: an optional prefix and name, separated by a slash (/). The name segment is required and must be 63 characters or less, beginning and ending with an alphanumeric character ([a-z0-9A-Z]) with dashes (-), underscores (_), dots (.), and alphanumerics between. The prefix is optional. If specified, the prefix must be a DNS subdomain: a series of DNS labels separated by dots (.), not longer than 253 characters in total, followed by a slash (/). Annotations that fails to meet these requirements are rejected

Note: This field is equivalent to the metadata field in the v1beta1 API. They have the same syntax and read/write to the same location in Service Directory.
endpoints[]

Endpoint

Output only. Endpoints associated with this service. Returned on LookupService.ResolveService. Control plane clients should use RegistrationService.ListEndpoints.
uid

string

Output only. The globally unique identifier of the service in the UUID4 format.

UpdateEndpointRequest

The request message for RegistrationService.UpdateEndpoint.

Fields
endpoint

Endpoint

Required. The updated endpoint.

Authorization requires the following IAM permission on the specified resource endpoint:

  • servicedirectory.endpoints.update
update_mask

FieldMask

Required. List of fields to be updated in this request.

UpdateNamespaceRequest

The request message for RegistrationService.UpdateNamespace.

Fields
namespace

Namespace

Required. The updated namespace.

Authorization requires the following IAM permission on the specified resource namespace:

  • servicedirectory.namespaces.update
update_mask

FieldMask

Required. List of fields to be updated in this request.

UpdateServiceRequest

The request message for RegistrationService.UpdateService.

Fields
service

Service

Required. The updated service.

Authorization requires the following IAM permission on the specified resource service:

  • servicedirectory.services.update
update_mask

FieldMask

Required. List of fields to be updated in this request.