def __init__(self, collection_config): entity_name = collection_config.entity_name name_template = path_template.PathTemplate(collection_config.name_pattern) id_segments = [seg.literal for seg in name_template.segments if seg.kind == path_template._BINDING] self.format_name_upper = casing_utils.get_resource_type_class_name( entity_name) self.format_name_lower = casing_utils.get_resource_type_var_name( entity_name) self.type_name_upper = casing_utils.get_resource_type_from_class_name( self.format_name_upper) self.parameter_list = [ { 'parameter': casing_utils.lower_underscore_to_lower_camel(lit), 'parameter_name': lit, 'not_first': True, 'not_last': True, } for lit in id_segments] self.parameter_list[0]['not_first'] = False self.parameter_list[-1]['not_last'] = False self.format_fields = [ { 'upper': casing_utils.lower_camel_to_upper_camel(f['parameter']), 'lower': f['parameter'], } for f in self.parameter_list] self.format_string = collection_config.name_pattern
def __init__(self, collection_config, java_package, oneof): entity_name = collection_config.java_entity_name name_template = path_template.PathTemplate( collection_config.name_pattern) id_segments = [ seg.literal for seg in name_template.segments if seg.kind == path_template._BINDING ] self.format_name_upper = casing_utils.get_resource_type_class_name( entity_name) self.format_name_lower = casing_utils.get_resource_type_var_name( entity_name) self.type_name_upper = casing_utils.get_resource_type_from_class_name( self.format_name_upper) if oneof: self.parent_interface = casing_utils.get_parent_resource_name_class_name( oneof.oneof_name) self.extension_keyword = 'extends' else: self.parent_interface = 'ResourceName' self.extension_keyword = 'implements' self.parameter_list = [{ 'parameter': casing_utils.lower_underscore_to_lower_camel(lit), 'parameter_name': lit, 'not_first': True, 'not_last': True, } for lit in id_segments] self.parameter_list[0]['not_first'] = False self.parameter_list[-1]['not_last'] = False self.format_fields = [{ 'upper': casing_utils.lower_camel_to_upper_camel(f['parameter']), 'lower': f['parameter'], } for f in self.parameter_list] self.format_string = collection_config.name_pattern self.package_name = java_package
class FirestoreAdminClient(object): """ The Cloud Firestore Admin API. This API provides several administrative services for Cloud Firestore. # Concepts Project, Database, Namespace, Collection, and Document are used as defined in the Google Cloud Firestore API. Operation: An Operation represents work being performed in the background. # Services ## Index The index service manages Cloud Firestore indexes. Index creation is performed asynchronously. An Operation resource is created for each such asynchronous operation. The state of the operation (including any errors encountered) may be queried via the Operation resource. ## Metadata Provides metadata and statistical information about data in Cloud Firestore. The data provided as part of this API may be stale. ## Operation The Operations collection provides a record of actions performed for the specified Project (including any Operations in progress). Operations are not created directly but through calls on other collections or resources. An Operation that is not yet done may be cancelled. The request to cancel is asynchronous and the Operation may continue to run for some time after the request to cancel is made. An Operation that is done may be deleted so that it is no longer listed as part of the Operation collection. Operations are created by service ``FirestoreAdmin``, but are accessed via service ``google.longrunning.Operations``. """ SERVICE_ADDRESS = 'firestore.googleapis.com' """The default address of the service.""" DEFAULT_SERVICE_PORT = 443 """The default port of the service.""" _PAGE_DESCRIPTORS = { 'list_indexes': _PageDesc('page_token', 'next_page_token', 'indexes') } # The scopes needed to make gRPC calls to all of the methods defined in # this service _ALL_SCOPES = ( 'https://www.googleapis.com/auth/cloud-platform', 'https://www.googleapis.com/auth/datastore', ) _DATABASE_PATH_TEMPLATE = path_template.PathTemplate( 'projects/{project}/databases/{database}') _INDEX_PATH_TEMPLATE = path_template.PathTemplate( 'projects/{project}/databases/{database}/indexes/{index}') @classmethod def database_path(cls, project, database): """Returns a fully-qualified database resource name string.""" return cls._DATABASE_PATH_TEMPLATE.render({ 'project': project, 'database': database, }) @classmethod def index_path(cls, project, database, index): """Returns a fully-qualified index resource name string.""" return cls._INDEX_PATH_TEMPLATE.render({ 'project': project, 'database': database, 'index': index, }) @classmethod def match_project_from_database_name(cls, database_name): """Parses the project from a database resource. Args: database_name (str): A fully-qualified path representing a database resource. Returns: A string representing the project. """ return cls._DATABASE_PATH_TEMPLATE.match(database_name).get('project') @classmethod def match_database_from_database_name(cls, database_name): """Parses the database from a database resource. Args: database_name (str): A fully-qualified path representing a database resource. Returns: A string representing the database. """ return cls._DATABASE_PATH_TEMPLATE.match(database_name).get('database') @classmethod def match_project_from_index_name(cls, index_name): """Parses the project from a index resource. Args: index_name (str): A fully-qualified path representing a index resource. Returns: A string representing the project. """ return cls._INDEX_PATH_TEMPLATE.match(index_name).get('project') @classmethod def match_database_from_index_name(cls, index_name): """Parses the database from a index resource. Args: index_name (str): A fully-qualified path representing a index resource. Returns: A string representing the database. """ return cls._INDEX_PATH_TEMPLATE.match(index_name).get('database') @classmethod def match_index_from_index_name(cls, index_name): """Parses the index from a index resource. Args: index_name (str): A fully-qualified path representing a index resource. Returns: A string representing the index. """ return cls._INDEX_PATH_TEMPLATE.match(index_name).get('index') def __init__(self, channel=None, credentials=None, ssl_credentials=None, scopes=None, client_config=None, lib_name=None, lib_version='', metrics_headers=()): """Constructor. Args: channel (~grpc.Channel): A ``Channel`` instance through which to make calls. credentials (~google.auth.credentials.Credentials): The authorization credentials to attach to requests. These credentials identify this application to the service. ssl_credentials (~grpc.ChannelCredentials): A ``ChannelCredentials`` instance for use with an SSL-enabled channel. scopes (Sequence[str]): A list of OAuth2 scopes to attach to requests. client_config (dict): A dictionary for call options for each method. See :func:`google.gax.construct_settings` for the structure of this data. Falls back to the default config if not specified or the specified config is missing data points. lib_name (str): The API library software used for calling the service. (Unless you are writing an API client itself, leave this as default.) lib_version (str): The API library software version used for calling the service. (Unless you are writing an API client itself, leave this as default.) metrics_headers (dict): A dictionary of values for tracking client library metrics. Ultimately serializes to a string (e.g. 'foo/1.2.3 bar/3.14.1'). This argument should be considered private. """ # Unless the calling application specifically requested # OAuth scopes, request everything. if scopes is None: scopes = self._ALL_SCOPES # Initialize an empty client config, if none is set. if client_config is None: client_config = {} # Initialize metrics_headers as an ordered dictionary # (cuts down on cardinality of the resulting string slightly). metrics_headers = collections.OrderedDict(metrics_headers) metrics_headers['gl-python'] = platform.python_version() # The library may or may not be set, depending on what is # calling this client. Newer client libraries set the library name # and version. if lib_name: metrics_headers[lib_name] = lib_version # Finally, track the GAPIC package version. metrics_headers['gapic'] = pkg_resources.get_distribution( 'google-cloud-firestore', ).version # Load the configuration defaults. defaults = api_callable.construct_settings( 'google.firestore.admin.v1beta1.FirestoreAdmin', firestore_admin_client_config.config, client_config, config.STATUS_CODE_NAMES, metrics_headers=metrics_headers, page_descriptors=self._PAGE_DESCRIPTORS, ) self.firestore_admin_stub = config.create_stub( firestore_admin_pb2.FirestoreAdminStub, channel=channel, service_path=self.SERVICE_ADDRESS, service_port=self.DEFAULT_SERVICE_PORT, credentials=credentials, scopes=scopes, ssl_credentials=ssl_credentials) self._create_index = api_callable.create_api_call( self.firestore_admin_stub.CreateIndex, settings=defaults['create_index']) self._list_indexes = api_callable.create_api_call( self.firestore_admin_stub.ListIndexes, settings=defaults['list_indexes']) self._get_index = api_callable.create_api_call( self.firestore_admin_stub.GetIndex, settings=defaults['get_index']) self._delete_index = api_callable.create_api_call( self.firestore_admin_stub.DeleteIndex, settings=defaults['delete_index']) # Service calls def create_index(self, parent, index, options=None): """ Creates the specified index. A newly created index's initial state is ``CREATING``. On completion of the returned ``google.longrunning.Operation``, the state will be ``READY``. If the index already exists, the call will return an ``ALREADY_EXISTS`` status. During creation, the process could result in an error, in which case the index will move to the ``ERROR`` state. The process can be recovered by fixing the data that caused the error, removing the index with ``delete``, then re-creating the index with ``create``. Indexes with a single field cannot be created. Example: >>> from google.cloud import firestore_v1beta1 >>> >>> client = firestore_v1beta1.FirestoreAdminClient() >>> >>> parent = client.database_path('[PROJECT]', '[DATABASE]') >>> index = {} >>> >>> response = client.create_index(parent, index) Args: parent (str): The name of the database this index will apply to. For example: ``projects/{project_id}/databases/{database_id}`` index (Union[dict, ~google.cloud.firestore_v1beta1.types.Index]): The index to create. The name and state should not be specified. Certain single field indexes cannot be created or deleted. If a dict is provided, it must be of the same form as the protobuf message :class:`~google.cloud.firestore_v1beta1.types.Index` options (~google.gax.CallOptions): Overrides the default settings for this call, e.g, timeout, retries etc. Returns: A :class:`~google.cloud.firestore_v1beta1.types.Operation` instance. Raises: :exc:`google.gax.errors.GaxError` if the RPC is aborted. :exc:`ValueError` if the parameters are invalid. """ request = firestore_admin_pb2.CreateIndexRequest( parent=parent, index=index) return self._create_index(request, options) def list_indexes(self, parent, filter_=None, page_size=None, options=None): """ Lists the indexes that match the specified filters. Example: >>> from google.cloud import firestore_v1beta1 >>> from google.gax import CallOptions, INITIAL_PAGE >>> >>> client = firestore_v1beta1.FirestoreAdminClient() >>> >>> parent = client.database_path('[PROJECT]', '[DATABASE]') >>> >>> >>> # Iterate over all results >>> for element in client.list_indexes(parent): ... # process element ... pass >>> >>> # Or iterate over results one page at a time >>> for page in client.list_indexes(parent, options=CallOptions(page_token=INITIAL_PAGE)): ... for element in page: ... # process element ... pass Args: parent (str): The database name. For example: ``projects/{project_id}/databases/{database_id}`` filter_ (str) page_size (int): The maximum number of resources contained in the underlying API response. If page streaming is performed per- resource, this parameter does not affect the return value. If page streaming is performed per-page, this determines the maximum number of resources in a page. options (~google.gax.CallOptions): Overrides the default settings for this call, e.g, timeout, retries etc. Returns: A :class:`~google.gax.PageIterator` instance. By default, this is an iterable of :class:`~google.cloud.firestore_v1beta1.types.Index` instances. This object can also be configured to iterate over the pages of the response through the `options` parameter. Raises: :exc:`google.gax.errors.GaxError` if the RPC is aborted. :exc:`ValueError` if the parameters are invalid. """ request = firestore_admin_pb2.ListIndexesRequest( parent=parent, filter=filter_, page_size=page_size) return self._list_indexes(request, options) def get_index(self, name, options=None): """ Gets an index. Example: >>> from google.cloud import firestore_v1beta1 >>> >>> client = firestore_v1beta1.FirestoreAdminClient() >>> >>> name = client.index_path('[PROJECT]', '[DATABASE]', '[INDEX]') >>> >>> response = client.get_index(name) Args: name (str): The name of the index. For example: ``projects/{project_id}/databases/{database_id}/indexes/{index_id}`` options (~google.gax.CallOptions): Overrides the default settings for this call, e.g, timeout, retries etc. Returns: A :class:`~google.cloud.firestore_v1beta1.types.Index` instance. Raises: :exc:`google.gax.errors.GaxError` if the RPC is aborted. :exc:`ValueError` if the parameters are invalid. """ request = firestore_admin_pb2.GetIndexRequest(name=name) return self._get_index(request, options) def delete_index(self, name, options=None): """ Deletes an index. Example: >>> from google.cloud import firestore_v1beta1 >>> >>> client = firestore_v1beta1.FirestoreAdminClient() >>> >>> name = client.index_path('[PROJECT]', '[DATABASE]', '[INDEX]') >>> >>> client.delete_index(name) Args: name (str): The index name. For example: ``projects/{project_id}/databases/{database_id}/indexes/{index_id}`` options (~google.gax.CallOptions): Overrides the default settings for this call, e.g, timeout, retries etc. Raises: :exc:`google.gax.errors.GaxError` if the RPC is aborted. :exc:`ValueError` if the parameters are invalid. """ request = firestore_admin_pb2.DeleteIndexRequest(name=name) self._delete_index(request, options)
class GroupServiceClient(object): """ The Group API lets you inspect and manage your `groups <https://cloud.google.comgoogle.monitoring.v3.Group>`_. A group is a named filter that is used to identify a collection of monitored resources. Groups are typically used to mirror the physical and/or logical topology of the environment. Because group membership is computed dynamically, monitored resources that are started in the future are automatically placed in matching groups. By using a group to name monitored resources in, for example, an alert policy, the target of that alert policy is updated automatically as monitored resources are added and removed from the infrastructure. """ SERVICE_ADDRESS = 'monitoring.googleapis.com' """The default address of the service.""" DEFAULT_SERVICE_PORT = 443 """The default port of the service.""" _PAGE_DESCRIPTORS = { 'list_groups': _PageDesc('page_token', 'next_page_token', 'group'), 'list_group_members': _PageDesc('page_token', 'next_page_token', 'members') } # The scopes needed to make gRPC calls to all of the methods defined in # this service _ALL_SCOPES = ( 'https://www.googleapis.com/auth/cloud-platform', 'https://www.googleapis.com/auth/monitoring', 'https://www.googleapis.com/auth/monitoring.read', 'https://www.googleapis.com/auth/monitoring.write', ) _PROJECT_PATH_TEMPLATE = path_template.PathTemplate('projects/{project}') _GROUP_PATH_TEMPLATE = path_template.PathTemplate( 'projects/{project}/groups/{group}') @classmethod def project_path(cls, project): """Returns a fully-qualified project resource name string.""" return cls._PROJECT_PATH_TEMPLATE.render({ 'project': project, }) @classmethod def group_path(cls, project, group): """Returns a fully-qualified group resource name string.""" return cls._GROUP_PATH_TEMPLATE.render({ 'project': project, 'group': group, }) @classmethod def match_project_from_project_name(cls, project_name): """Parses the project from a project resource. Args: project_name (string): A fully-qualified path representing a project resource. Returns: A string representing the project. """ return cls._PROJECT_PATH_TEMPLATE.match(project_name).get('project') @classmethod def match_project_from_group_name(cls, group_name): """Parses the project from a group resource. Args: group_name (string): A fully-qualified path representing a group resource. Returns: A string representing the project. """ return cls._GROUP_PATH_TEMPLATE.match(group_name).get('project') @classmethod def match_group_from_group_name(cls, group_name): """Parses the group from a group resource. Args: group_name (string): A fully-qualified path representing a group resource. Returns: A string representing the group. """ return cls._GROUP_PATH_TEMPLATE.match(group_name).get('group') def __init__(self, service_path=SERVICE_ADDRESS, port=DEFAULT_SERVICE_PORT, channel=None, credentials=None, ssl_credentials=None, scopes=None, client_config=None, app_name=None, app_version='', lib_name=None, lib_version='', metrics_headers=()): """Constructor. Args: service_path (string): The domain name of the API remote host. port (int): The port on which to connect to the remote host. channel (:class:`grpc.Channel`): A ``Channel`` instance through which to make calls. credentials (object): The authorization credentials to attach to requests. These credentials identify this application to the service. ssl_credentials (:class:`grpc.ChannelCredentials`): A ``ChannelCredentials`` instance for use with an SSL-enabled channel. scopes (list[string]): A list of OAuth2 scopes to attach to requests. client_config (dict): A dictionary for call options for each method. See :func:`google.gax.construct_settings` for the structure of this data. Falls back to the default config if not specified or the specified config is missing data points. app_name (string): The name of the application calling the service. Recommended for analytics purposes. app_version (string): The version of the application calling the service. Recommended for analytics purposes. lib_name (string): The API library software used for calling the service. (Unless you are writing an API client itself, leave this as default.) lib_version (string): The API library software version used for calling the service. (Unless you are writing an API client itself, leave this as default.) metrics_headers (dict): A dictionary of values for tracking client library metrics. Ultimately serializes to a string (e.g. 'foo/1.2.3 bar/3.14.1'). This argument should be considered private. Returns: A GroupServiceClient object. """ # Unless the calling application specifically requested # OAuth scopes, request everything. if scopes is None: scopes = self._ALL_SCOPES # Initialize an empty client config, if none is set. if client_config is None: client_config = {} # Initialize metrics_headers as an ordered dictionary # (cuts down on cardinality of the resulting string slightly). metrics_headers = collections.OrderedDict(metrics_headers) metrics_headers['gl-python'] = platform.python_version() # The library may or may not be set, depending on what is # calling this client. Newer client libraries set the library name # and version. if lib_name: metrics_headers[lib_name] = lib_version # Finally, track the GAPIC package version. metrics_headers['gapic'] = pkg_resources.get_distribution( 'gapic-google-cloud-monitoring-v3', ).version # Load the configuration defaults. default_client_config = json.loads( pkg_resources.resource_string( __name__, 'group_service_client_config.json').decode()) defaults = api_callable.construct_settings( 'google.monitoring.v3.GroupService', default_client_config, client_config, config.STATUS_CODE_NAMES, metrics_headers=metrics_headers, page_descriptors=self._PAGE_DESCRIPTORS, ) self.group_service_stub = config.create_stub( group_service_pb2.GroupServiceStub, channel=channel, service_path=service_path, service_port=port, credentials=credentials, scopes=scopes, ssl_credentials=ssl_credentials) self._list_groups = api_callable.create_api_call( self.group_service_stub.ListGroups, settings=defaults['list_groups']) self._get_group = api_callable.create_api_call( self.group_service_stub.GetGroup, settings=defaults['get_group']) self._create_group = api_callable.create_api_call( self.group_service_stub.CreateGroup, settings=defaults['create_group']) self._update_group = api_callable.create_api_call( self.group_service_stub.UpdateGroup, settings=defaults['update_group']) self._delete_group = api_callable.create_api_call( self.group_service_stub.DeleteGroup, settings=defaults['delete_group']) self._list_group_members = api_callable.create_api_call( self.group_service_stub.ListGroupMembers, settings=defaults['list_group_members']) # Service calls def list_groups(self, name, children_of_group=None, ancestors_of_group=None, descendants_of_group=None, page_size=0, options=None): """ Lists the existing groups. Example: >>> from google.cloud.gapic.monitoring.v3 import group_service_client >>> from google.gax import CallOptions, INITIAL_PAGE >>> api = group_service_client.GroupServiceClient() >>> name = api.project_path('[PROJECT]') >>> >>> # Iterate over all results >>> for element in api.list_groups(name): >>> # process element >>> pass >>> >>> # Or iterate over results one page at a time >>> for page in api.list_groups(name, options=CallOptions(page_token=INITIAL_PAGE)): >>> for element in page: >>> # process element >>> pass Args: name (string): The project whose groups are to be listed. The format is ``\"projects/{project_id_or_number}\"``. children_of_group (string): A group name: ``\"projects/{project_id_or_number}/groups/{group_id}\"``. Returns groups whose ``parentName`` field contains the group name. If no groups have this parent, the results are empty. ancestors_of_group (string): A group name: ``\"projects/{project_id_or_number}/groups/{group_id}\"``. Returns groups that are ancestors of the specified group. The groups are returned in order, starting with the immediate parent and ending with the most distant ancestor. If the specified group has no immediate parent, the results are empty. descendants_of_group (string): A group name: ``\"projects/{project_id_or_number}/groups/{group_id}\"``. Returns the descendants of the specified group. This is a superset of the results returned by the ``childrenOfGroup`` filter, and includes children-of-children, and so forth. page_size (int): The maximum number of resources contained in the underlying API response. If page streaming is performed per- resource, this parameter does not affect the return value. If page streaming is performed per-page, this determines the maximum number of resources in a page. options (:class:`google.gax.CallOptions`): Overrides the default settings for this call, e.g, timeout, retries etc. Returns: A :class:`google.gax.PageIterator` instance. By default, this is an iterable of :class:`google.cloud.proto.monitoring.v3.group_pb2.Group` instances. This object can also be configured to iterate over the pages of the response through the `CallOptions` parameter. Raises: :exc:`google.gax.errors.GaxError` if the RPC is aborted. :exc:`ValueError` if the parameters are invalid. """ # Sanity check: We have some fields which are mutually exclusive; # raise ValueError if more than one is sent. oneof.check_oneof( children_of_group=children_of_group, ancestors_of_group=ancestors_of_group, descendants_of_group=descendants_of_group, ) # Create the request object. request = group_service_pb2.ListGroupsRequest( name=name, children_of_group=children_of_group, ancestors_of_group=ancestors_of_group, descendants_of_group=descendants_of_group, page_size=page_size) return self._list_groups(request, options) def get_group(self, name, options=None): """ Gets a single group. Example: >>> from google.cloud.gapic.monitoring.v3 import group_service_client >>> api = group_service_client.GroupServiceClient() >>> name = api.group_path('[PROJECT]', '[GROUP]') >>> response = api.get_group(name) Args: name (string): The group to retrieve. The format is ``\"projects/{project_id_or_number}/groups/{group_id}\"``. options (:class:`google.gax.CallOptions`): Overrides the default settings for this call, e.g, timeout, retries etc. Returns: A :class:`google.cloud.proto.monitoring.v3.group_pb2.Group` instance. Raises: :exc:`google.gax.errors.GaxError` if the RPC is aborted. :exc:`ValueError` if the parameters are invalid. """ # Create the request object. request = group_service_pb2.GetGroupRequest(name=name) return self._get_group(request, options) def create_group(self, name, group, validate_only=False, options=None): """ Creates a new group. Example: >>> from google.cloud.gapic.monitoring.v3 import group_service_client >>> from google.cloud.proto.monitoring.v3 import group_pb2 >>> api = group_service_client.GroupServiceClient() >>> name = api.project_path('[PROJECT]') >>> group = group_pb2.Group() >>> response = api.create_group(name, group) Args: name (string): The project in which to create the group. The format is ``\"projects/{project_id_or_number}\"``. group (:class:`google.cloud.proto.monitoring.v3.group_pb2.Group`): A group definition. It is an error to define the ``name`` field because the system assigns the name. validate_only (bool): If true, validate this request but do not create the group. options (:class:`google.gax.CallOptions`): Overrides the default settings for this call, e.g, timeout, retries etc. Returns: A :class:`google.cloud.proto.monitoring.v3.group_pb2.Group` instance. Raises: :exc:`google.gax.errors.GaxError` if the RPC is aborted. :exc:`ValueError` if the parameters are invalid. """ # Create the request object. request = group_service_pb2.CreateGroupRequest( name=name, group=group, validate_only=validate_only) return self._create_group(request, options) def update_group(self, group, validate_only=False, options=None): """ Updates an existing group. You can change any group attributes except ``name``. Example: >>> from google.cloud.gapic.monitoring.v3 import group_service_client >>> from google.cloud.proto.monitoring.v3 import group_pb2 >>> api = group_service_client.GroupServiceClient() >>> group = group_pb2.Group() >>> response = api.update_group(group) Args: group (:class:`google.cloud.proto.monitoring.v3.group_pb2.Group`): The new definition of the group. All fields of the existing group, excepting ``name``, are replaced with the corresponding fields of this group. validate_only (bool): If true, validate this request but do not update the existing group. options (:class:`google.gax.CallOptions`): Overrides the default settings for this call, e.g, timeout, retries etc. Returns: A :class:`google.cloud.proto.monitoring.v3.group_pb2.Group` instance. Raises: :exc:`google.gax.errors.GaxError` if the RPC is aborted. :exc:`ValueError` if the parameters are invalid. """ # Create the request object. request = group_service_pb2.UpdateGroupRequest( group=group, validate_only=validate_only) return self._update_group(request, options) def delete_group(self, name, options=None): """ Deletes an existing group. Example: >>> from google.cloud.gapic.monitoring.v3 import group_service_client >>> api = group_service_client.GroupServiceClient() >>> name = api.group_path('[PROJECT]', '[GROUP]') >>> api.delete_group(name) Args: name (string): The group to delete. The format is ``\"projects/{project_id_or_number}/groups/{group_id}\"``. options (:class:`google.gax.CallOptions`): Overrides the default settings for this call, e.g, timeout, retries etc. Raises: :exc:`google.gax.errors.GaxError` if the RPC is aborted. :exc:`ValueError` if the parameters are invalid. """ # Create the request object. request = group_service_pb2.DeleteGroupRequest(name=name) self._delete_group(request, options) def list_group_members(self, name, page_size=0, filter_='', interval=None, options=None): """ Lists the monitored resources that are members of a group. Example: >>> from google.cloud.gapic.monitoring.v3 import group_service_client >>> from google.gax import CallOptions, INITIAL_PAGE >>> api = group_service_client.GroupServiceClient() >>> name = api.group_path('[PROJECT]', '[GROUP]') >>> >>> # Iterate over all results >>> for element in api.list_group_members(name): >>> # process element >>> pass >>> >>> # Or iterate over results one page at a time >>> for page in api.list_group_members(name, options=CallOptions(page_token=INITIAL_PAGE)): >>> for element in page: >>> # process element >>> pass Args: name (string): The group whose members are listed. The format is ``\"projects/{project_id_or_number}/groups/{group_id}\"``. page_size (int): The maximum number of resources contained in the underlying API response. If page streaming is performed per- resource, this parameter does not affect the return value. If page streaming is performed per-page, this determines the maximum number of resources in a page. filter_ (string): An optional `list filter <https://cloud.google.com/monitoring/api/learn_more#filtering>`_ describing the members to be returned. The filter may reference the type, labels, and metadata of monitored resources that comprise the group. For example, to return only resources representing Compute Engine VM instances, use this filter: :: resource.type = \"gce_instance\" interval (:class:`google.cloud.proto.monitoring.v3.common_pb2.TimeInterval`): An optional time interval for which results should be returned. Only members that were part of the group during the specified interval are included in the response. If no interval is provided then the group membership over the last minute is returned. options (:class:`google.gax.CallOptions`): Overrides the default settings for this call, e.g, timeout, retries etc. Returns: A :class:`google.gax.PageIterator` instance. By default, this is an iterable of :class:`google.api.monitored_resource_pb2.MonitoredResource` instances. This object can also be configured to iterate over the pages of the response through the `CallOptions` parameter. Raises: :exc:`google.gax.errors.GaxError` if the RPC is aborted. :exc:`ValueError` if the parameters are invalid. """ if interval is None: interval = common_pb2.TimeInterval() # Create the request object. request = group_service_pb2.ListGroupMembersRequest( name=name, page_size=page_size, filter=filter_, interval=interval) return self._list_group_members(request, options)
class LoggingServiceV2Client(object): """Service for ingesting and querying logs.""" SERVICE_ADDRESS = 'logging.googleapis.com' """The default address of the service.""" DEFAULT_SERVICE_PORT = 443 """The default port of the service.""" _PAGE_DESCRIPTORS = { 'list_log_entries': _PageDesc('page_token', 'next_page_token', 'entries'), 'list_monitored_resource_descriptors': _PageDesc('page_token', 'next_page_token', 'resource_descriptors'), 'list_logs': _PageDesc('page_token', 'next_page_token', 'log_names') } # The scopes needed to make gRPC calls to all of the methods defined in # this service _ALL_SCOPES = ('https://www.googleapis.com/auth/cloud-platform', 'https://www.googleapis.com/auth/cloud-platform.read-only', 'https://www.googleapis.com/auth/logging.admin', 'https://www.googleapis.com/auth/logging.read', 'https://www.googleapis.com/auth/logging.write', ) _PROJECT_PATH_TEMPLATE = path_template.PathTemplate('projects/{project}') _LOG_PATH_TEMPLATE = path_template.PathTemplate( 'projects/{project}/logs/{log}') @classmethod def project_path(cls, project): """Returns a fully-qualified project resource name string.""" return cls._PROJECT_PATH_TEMPLATE.render({ 'project': project, }) @classmethod def log_path(cls, project, log): """Returns a fully-qualified log resource name string.""" return cls._LOG_PATH_TEMPLATE.render({ 'project': project, 'log': log, }) @classmethod def match_project_from_project_name(cls, project_name): """Parses the project from a project resource. Args: project_name (string): A fully-qualified path representing a project resource. Returns: A string representing the project. """ return cls._PROJECT_PATH_TEMPLATE.match(project_name).get('project') @classmethod def match_project_from_log_name(cls, log_name): """Parses the project from a log resource. Args: log_name (string): A fully-qualified path representing a log resource. Returns: A string representing the project. """ return cls._LOG_PATH_TEMPLATE.match(log_name).get('project') @classmethod def match_log_from_log_name(cls, log_name): """Parses the log from a log resource. Args: log_name (string): A fully-qualified path representing a log resource. Returns: A string representing the log. """ return cls._LOG_PATH_TEMPLATE.match(log_name).get('log') def __init__(self, service_path=SERVICE_ADDRESS, port=DEFAULT_SERVICE_PORT, channel=None, credentials=None, ssl_credentials=None, scopes=None, client_config=None, app_name=None, app_version='', lib_name=None, lib_version='', metrics_headers=()): """Constructor. Args: service_path (string): The domain name of the API remote host. port (int): The port on which to connect to the remote host. channel (:class:`grpc.Channel`): A ``Channel`` instance through which to make calls. credentials (object): The authorization credentials to attach to requests. These credentials identify this application to the service. ssl_credentials (:class:`grpc.ChannelCredentials`): A ``ChannelCredentials`` instance for use with an SSL-enabled channel. scopes (list[string]): A list of OAuth2 scopes to attach to requests. client_config (dict): A dictionary for call options for each method. See :func:`google.gax.construct_settings` for the structure of this data. Falls back to the default config if not specified or the specified config is missing data points. app_name (string): The name of the application calling the service. Recommended for analytics purposes. app_version (string): The version of the application calling the service. Recommended for analytics purposes. lib_name (string): The API library software used for calling the service. (Unless you are writing an API client itself, leave this as default.) lib_version (string): The API library software version used for calling the service. (Unless you are writing an API client itself, leave this as default.) metrics_headers (dict): A dictionary of values for tracking client library metrics. Ultimately serializes to a string (e.g. 'foo/1.2.3 bar/3.14.1'). This argument should be considered private. Returns: A LoggingServiceV2Client object. """ # Unless the calling application specifically requested # OAuth scopes, request everything. if scopes is None: scopes = self._ALL_SCOPES # Initialize an empty client config, if none is set. if client_config is None: client_config = {} # Initialize metrics_headers as an ordered dictionary # (cuts down on cardinality of the resulting string slightly). metrics_headers = collections.OrderedDict(metrics_headers) metrics_headers['gl-python'] = platform.python_version() # The library may or may not be set, depending on what is # calling this client. Newer client libraries set the library name # and version. if lib_name: metrics_headers[lib_name] = lib_version # Finally, track the GAPIC package version. metrics_headers['gapic'] = pkg_resources.get_distribution( 'gapic-google-cloud-logging-v2', ).version # Load the configuration defaults. default_client_config = json.loads( pkg_resources.resource_string( __name__, 'logging_service_v2_client_config.json').decode()) defaults = api_callable.construct_settings( 'google.logging.v2.LoggingServiceV2', default_client_config, client_config, config.STATUS_CODE_NAMES, metrics_headers=metrics_headers, page_descriptors=self._PAGE_DESCRIPTORS, ) self.logging_service_v2_stub = config.create_stub( logging_pb2.LoggingServiceV2Stub, channel=channel, service_path=service_path, service_port=port, credentials=credentials, scopes=scopes, ssl_credentials=ssl_credentials) self._delete_log = api_callable.create_api_call( self.logging_service_v2_stub.DeleteLog, settings=defaults['delete_log']) self._write_log_entries = api_callable.create_api_call( self.logging_service_v2_stub.WriteLogEntries, settings=defaults['write_log_entries']) self._list_log_entries = api_callable.create_api_call( self.logging_service_v2_stub.ListLogEntries, settings=defaults['list_log_entries']) self._list_monitored_resource_descriptors = api_callable.create_api_call( self.logging_service_v2_stub.ListMonitoredResourceDescriptors, settings=defaults['list_monitored_resource_descriptors']) self._list_logs = api_callable.create_api_call( self.logging_service_v2_stub.ListLogs, settings=defaults['list_logs']) # Service calls def delete_log(self, log_name, options=None): """ Deletes all the log entries in a log. The log reappears if it receives new entries. Log entries written shortly before the delete operation might not be deleted. Example: >>> from google.cloud.gapic.logging.v2 import logging_service_v2_client >>> client = logging_service_v2_client.LoggingServiceV2Client() >>> log_name = client.log_path('[PROJECT]', '[LOG]') >>> client.delete_log(log_name) Args: log_name (string): 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 ``LogEntry``. options (:class:`google.gax.CallOptions`): Overrides the default settings for this call, e.g, timeout, retries etc. Raises: :exc:`google.gax.errors.GaxError` if the RPC is aborted. :exc:`ValueError` if the parameters are invalid. """ # Create the request object. request = logging_pb2.DeleteLogRequest(log_name=log_name) self._delete_log(request, options) def write_log_entries(self, entries, log_name=None, resource=None, labels=None, partial_success=None, options=None): """ Writes log entries to Stackdriver Logging. Example: >>> from google.cloud.gapic.logging.v2 import logging_service_v2_client >>> client = logging_service_v2_client.LoggingServiceV2Client() >>> entries = [] >>> response = client.write_log_entries(entries) Args: entries (list[:class:`google.cloud.proto.logging.v2.log_entry_pb2.LogEntry`]): 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. log_name (string): 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 ``LogEntry``. resource (:class:`google.api.monitored_resource_pb2.MonitoredResource`): 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 ``LogEntry``. labels (dict[string -> string]): 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 ``LogEntry``. partial_success (bool): 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. options (:class:`google.gax.CallOptions`): Overrides the default settings for this call, e.g, timeout, retries etc. Returns: A :class:`google.cloud.proto.logging.v2.logging_pb2.WriteLogEntriesResponse` instance. Raises: :exc:`google.gax.errors.GaxError` if the RPC is aborted. :exc:`ValueError` if the parameters are invalid. """ # Create the request object. request = logging_pb2.WriteLogEntriesRequest( entries=entries, log_name=log_name, resource=resource, labels=labels, partial_success=partial_success) return self._write_log_entries(request, options) def list_log_entries(self, resource_names, project_ids=None, filter_=None, order_by=None, page_size=None, options=None): """ Lists log entries. Use this method to retrieve log entries from Stackdriver Logging. For ways to export log entries, see `Exporting Logs <https://cloud.google.com/logging/docs/export>`_. Example: >>> from google.cloud.gapic.logging.v2 import logging_service_v2_client >>> from google.gax import CallOptions, INITIAL_PAGE >>> client = logging_service_v2_client.LoggingServiceV2Client() >>> resource_names = [] >>> >>> # Iterate over all results >>> for element in client.list_log_entries(resource_names): >>> # process element >>> pass >>> >>> # Or iterate over results one page at a time >>> for page in client.list_log_entries(resource_names, options=CallOptions(page_token=INITIAL_PAGE)): >>> for element in page: >>> # process element >>> pass Args: resource_names (list[string]): 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. project_ids (list[string]): 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``. filter_ (string): Optional. A filter that chooses which log entries to return. See [Advanced Logs Filters](/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. order_by (string): 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. page_size (int): The maximum number of resources contained in the underlying API response. If page streaming is performed per- resource, this parameter does not affect the return value. If page streaming is performed per-page, this determines the maximum number of resources in a page. options (:class:`google.gax.CallOptions`): Overrides the default settings for this call, e.g, timeout, retries etc. Returns: A :class:`google.gax.PageIterator` instance. By default, this is an iterable of :class:`google.cloud.proto.logging.v2.log_entry_pb2.LogEntry` instances. This object can also be configured to iterate over the pages of the response through the `CallOptions` parameter. Raises: :exc:`google.gax.errors.GaxError` if the RPC is aborted. :exc:`ValueError` if the parameters are invalid. """ # Create the request object. request = logging_pb2.ListLogEntriesRequest( resource_names=resource_names, project_ids=project_ids, filter=filter_, order_by=order_by, page_size=page_size) return self._list_log_entries(request, options) def list_monitored_resource_descriptors(self, page_size=None, options=None): """ Lists the descriptors for monitored resource types used by Stackdriver Logging. Example: >>> from google.cloud.gapic.logging.v2 import logging_service_v2_client >>> from google.gax import CallOptions, INITIAL_PAGE >>> client = logging_service_v2_client.LoggingServiceV2Client() >>> >>> # Iterate over all results >>> for element in client.list_monitored_resource_descriptors(): >>> # process element >>> pass >>> >>> # Or iterate over results one page at a time >>> for page in client.list_monitored_resource_descriptors(options=CallOptions(page_token=INITIAL_PAGE)): >>> for element in page: >>> # process element >>> pass Args: page_size (int): The maximum number of resources contained in the underlying API response. If page streaming is performed per- resource, this parameter does not affect the return value. If page streaming is performed per-page, this determines the maximum number of resources in a page. options (:class:`google.gax.CallOptions`): Overrides the default settings for this call, e.g, timeout, retries etc. Returns: A :class:`google.gax.PageIterator` instance. By default, this is an iterable of :class:`google.api.monitored_resource_pb2.MonitoredResourceDescriptor` instances. This object can also be configured to iterate over the pages of the response through the `CallOptions` parameter. Raises: :exc:`google.gax.errors.GaxError` if the RPC is aborted. :exc:`ValueError` if the parameters are invalid. """ # Create the request object. request = logging_pb2.ListMonitoredResourceDescriptorsRequest( page_size=page_size) return self._list_monitored_resource_descriptors(request, options) def list_logs(self, parent, page_size=None, options=None): """ Lists the logs in projects, organizations, folders, or billing accounts. Only logs that have entries are listed. Example: >>> from google.cloud.gapic.logging.v2 import logging_service_v2_client >>> from google.gax import CallOptions, INITIAL_PAGE >>> client = logging_service_v2_client.LoggingServiceV2Client() >>> parent = client.project_path('[PROJECT]') >>> >>> # Iterate over all results >>> for element in client.list_logs(parent): >>> # process element >>> pass >>> >>> # Or iterate over results one page at a time >>> for page in client.list_logs(parent, options=CallOptions(page_token=INITIAL_PAGE)): >>> for element in page: >>> # process element >>> pass Args: parent (string): Required. The resource name that owns the logs: :: \"projects/[PROJECT_ID]\" \"organizations/[ORGANIZATION_ID]\" \"billingAccounts/[BILLING_ACCOUNT_ID]\" \"folders/[FOLDER_ID]\" page_size (int): The maximum number of resources contained in the underlying API response. If page streaming is performed per- resource, this parameter does not affect the return value. If page streaming is performed per-page, this determines the maximum number of resources in a page. options (:class:`google.gax.CallOptions`): Overrides the default settings for this call, e.g, timeout, retries etc. Returns: A :class:`google.gax.PageIterator` instance. By default, this is an iterable of string instances. This object can also be configured to iterate over the pages of the response through the `CallOptions` parameter. Raises: :exc:`google.gax.errors.GaxError` if the RPC is aborted. :exc:`ValueError` if the parameters are invalid. """ # Create the request object. request = logging_pb2.ListLogsRequest( parent=parent, page_size=page_size) return self._list_logs(request, options)
class FirestoreClient(object): """ The Cloud Firestore service. This service exposes several types of comparable timestamps: * ``create_time`` - The time at which a document was created. Changes only :: when a document is deleted, then re-created. Increases in a strict monotonic fashion. * ``update_time`` - The time at which a document was last updated. Changes :: every time a document is modified. Does not change when a write results in no modifications. Increases in a strict monotonic fashion. * ``read_time`` - The time at which a particular state was observed. Used :: to denote a consistent snapshot of the database or the time at which a Document was observed to not exist. * ``commit_time`` - The time at which the writes in a transaction were :: committed. Any read with an equal or greater `read_time` is guaranteed to see the effects of the transaction. """ SERVICE_ADDRESS = 'firestore.googleapis.com' """The default address of the service.""" DEFAULT_SERVICE_PORT = 443 """The default port of the service.""" _PAGE_DESCRIPTORS = { 'list_documents': _PageDesc('page_token', 'next_page_token', 'documents'), 'list_collection_ids': _PageDesc('page_token', 'next_page_token', 'collection_ids') } # The scopes needed to make gRPC calls to all of the methods defined in # this service _ALL_SCOPES = ( 'https://www.googleapis.com/auth/cloud-platform', 'https://www.googleapis.com/auth/datastore', ) _DATABASE_ROOT_PATH_TEMPLATE = path_template.PathTemplate( 'projects/{project}/databases/{database}') _DOCUMENT_ROOT_PATH_TEMPLATE = path_template.PathTemplate( 'projects/{project}/databases/{database}/documents') _DOCUMENT_PATH_PATH_TEMPLATE = path_template.PathTemplate( 'projects/{project}/databases/{database}/documents/{document_path=**}') _ANY_PATH_PATH_TEMPLATE = path_template.PathTemplate( 'projects/{project}/databases/{database}/documents/{document}/{any_path=**}' ) @classmethod def database_root_path(cls, project, database): """Returns a fully-qualified database_root resource name string.""" return cls._DATABASE_ROOT_PATH_TEMPLATE.render({ 'project': project, 'database': database, }) @classmethod def document_root_path(cls, project, database): """Returns a fully-qualified document_root resource name string.""" return cls._DOCUMENT_ROOT_PATH_TEMPLATE.render({ 'project': project, 'database': database, }) @classmethod def document_path_path(cls, project, database, document_path): """Returns a fully-qualified document_path resource name string.""" return cls._DOCUMENT_PATH_PATH_TEMPLATE.render({ 'project': project, 'database': database, 'document_path': document_path, }) @classmethod def any_path_path(cls, project, database, document, any_path): """Returns a fully-qualified any_path resource name string.""" return cls._ANY_PATH_PATH_TEMPLATE.render({ 'project': project, 'database': database, 'document': document, 'any_path': any_path, }) @classmethod def match_project_from_database_root_name(cls, database_root_name): """Parses the project from a database_root resource. Args: database_root_name (str): A fully-qualified path representing a database_root resource. Returns: A string representing the project. """ return cls._DATABASE_ROOT_PATH_TEMPLATE.match(database_root_name).get( 'project') @classmethod def match_database_from_database_root_name(cls, database_root_name): """Parses the database from a database_root resource. Args: database_root_name (str): A fully-qualified path representing a database_root resource. Returns: A string representing the database. """ return cls._DATABASE_ROOT_PATH_TEMPLATE.match(database_root_name).get( 'database') @classmethod def match_project_from_document_root_name(cls, document_root_name): """Parses the project from a document_root resource. Args: document_root_name (str): A fully-qualified path representing a document_root resource. Returns: A string representing the project. """ return cls._DOCUMENT_ROOT_PATH_TEMPLATE.match(document_root_name).get( 'project') @classmethod def match_database_from_document_root_name(cls, document_root_name): """Parses the database from a document_root resource. Args: document_root_name (str): A fully-qualified path representing a document_root resource. Returns: A string representing the database. """ return cls._DOCUMENT_ROOT_PATH_TEMPLATE.match(document_root_name).get( 'database') @classmethod def match_project_from_document_path_name(cls, document_path_name): """Parses the project from a document_path resource. Args: document_path_name (str): A fully-qualified path representing a document_path resource. Returns: A string representing the project. """ return cls._DOCUMENT_PATH_PATH_TEMPLATE.match(document_path_name).get( 'project') @classmethod def match_database_from_document_path_name(cls, document_path_name): """Parses the database from a document_path resource. Args: document_path_name (str): A fully-qualified path representing a document_path resource. Returns: A string representing the database. """ return cls._DOCUMENT_PATH_PATH_TEMPLATE.match(document_path_name).get( 'database') @classmethod def match_document_path_from_document_path_name(cls, document_path_name): """Parses the document_path from a document_path resource. Args: document_path_name (str): A fully-qualified path representing a document_path resource. Returns: A string representing the document_path. """ return cls._DOCUMENT_PATH_PATH_TEMPLATE.match(document_path_name).get( 'document_path') @classmethod def match_project_from_any_path_name(cls, any_path_name): """Parses the project from a any_path resource. Args: any_path_name (str): A fully-qualified path representing a any_path resource. Returns: A string representing the project. """ return cls._ANY_PATH_PATH_TEMPLATE.match(any_path_name).get('project') @classmethod def match_database_from_any_path_name(cls, any_path_name): """Parses the database from a any_path resource. Args: any_path_name (str): A fully-qualified path representing a any_path resource. Returns: A string representing the database. """ return cls._ANY_PATH_PATH_TEMPLATE.match(any_path_name).get('database') @classmethod def match_document_from_any_path_name(cls, any_path_name): """Parses the document from a any_path resource. Args: any_path_name (str): A fully-qualified path representing a any_path resource. Returns: A string representing the document. """ return cls._ANY_PATH_PATH_TEMPLATE.match(any_path_name).get('document') @classmethod def match_any_path_from_any_path_name(cls, any_path_name): """Parses the any_path from a any_path resource. Args: any_path_name (str): A fully-qualified path representing a any_path resource. Returns: A string representing the any_path. """ return cls._ANY_PATH_PATH_TEMPLATE.match(any_path_name).get('any_path') def __init__(self, channel=None, credentials=None, ssl_credentials=None, scopes=None, client_config=None, lib_name=None, lib_version='', metrics_headers=()): """Constructor. Args: channel (~grpc.Channel): A ``Channel`` instance through which to make calls. credentials (~google.auth.credentials.Credentials): The authorization credentials to attach to requests. These credentials identify this application to the service. ssl_credentials (~grpc.ChannelCredentials): A ``ChannelCredentials`` instance for use with an SSL-enabled channel. scopes (Sequence[str]): A list of OAuth2 scopes to attach to requests. client_config (dict): A dictionary for call options for each method. See :func:`google.gax.construct_settings` for the structure of this data. Falls back to the default config if not specified or the specified config is missing data points. lib_name (str): The API library software used for calling the service. (Unless you are writing an API client itself, leave this as default.) lib_version (str): The API library software version used for calling the service. (Unless you are writing an API client itself, leave this as default.) metrics_headers (dict): A dictionary of values for tracking client library metrics. Ultimately serializes to a string (e.g. 'foo/1.2.3 bar/3.14.1'). This argument should be considered private. """ # Unless the calling application specifically requested # OAuth scopes, request everything. if scopes is None: scopes = self._ALL_SCOPES # Initialize an empty client config, if none is set. if client_config is None: client_config = {} # Initialize metrics_headers as an ordered dictionary # (cuts down on cardinality of the resulting string slightly). metrics_headers = collections.OrderedDict(metrics_headers) metrics_headers['gl-python'] = platform.python_version() # The library may or may not be set, depending on what is # calling this client. Newer client libraries set the library name # and version. if lib_name: metrics_headers[lib_name] = lib_version # Finally, track the GAPIC package version. metrics_headers['gapic'] = pkg_resources.get_distribution( 'google-cloud-firestore', ).version # Load the configuration defaults. defaults = api_callable.construct_settings( 'google.firestore.v1beta1.Firestore', firestore_client_config.config, client_config, config.STATUS_CODE_NAMES, metrics_headers=metrics_headers, page_descriptors=self._PAGE_DESCRIPTORS, ) self.firestore_stub = config.create_stub( firestore_pb2.FirestoreStub, channel=channel, service_path=self.SERVICE_ADDRESS, service_port=self.DEFAULT_SERVICE_PORT, credentials=credentials, scopes=scopes, ssl_credentials=ssl_credentials) self._get_document = api_callable.create_api_call( self.firestore_stub.GetDocument, settings=defaults['get_document']) self._list_documents = api_callable.create_api_call( self.firestore_stub.ListDocuments, settings=defaults['list_documents']) self._create_document = api_callable.create_api_call( self.firestore_stub.CreateDocument, settings=defaults['create_document']) self._update_document = api_callable.create_api_call( self.firestore_stub.UpdateDocument, settings=defaults['update_document']) self._delete_document = api_callable.create_api_call( self.firestore_stub.DeleteDocument, settings=defaults['delete_document']) self._batch_get_documents = api_callable.create_api_call( self.firestore_stub.BatchGetDocuments, settings=defaults['batch_get_documents']) self._begin_transaction = api_callable.create_api_call( self.firestore_stub.BeginTransaction, settings=defaults['begin_transaction']) self._commit = api_callable.create_api_call( self.firestore_stub.Commit, settings=defaults['commit']) self._rollback = api_callable.create_api_call( self.firestore_stub.Rollback, settings=defaults['rollback']) self._run_query = api_callable.create_api_call( self.firestore_stub.RunQuery, settings=defaults['run_query']) self._write = api_callable.create_api_call(self.firestore_stub.Write, settings=defaults['write']) self._listen = api_callable.create_api_call( self.firestore_stub.Listen, settings=defaults['listen']) self._list_collection_ids = api_callable.create_api_call( self.firestore_stub.ListCollectionIds, settings=defaults['list_collection_ids']) # Service calls def get_document(self, name, mask=None, transaction=None, read_time=None, options=None): """ Gets a single document. Example: >>> from google.cloud import firestore_v1beta1 >>> >>> client = firestore_v1beta1.FirestoreClient() >>> >>> name = client.any_path_path('[PROJECT]', '[DATABASE]', '[DOCUMENT]', '[ANY_PATH]') >>> >>> response = client.get_document(name) Args: name (str): The resource name of the Document to get. In the format: ``projects/{project_id}/databases/{database_id}/documents/{document_path}``. mask (Union[dict, ~google.cloud.firestore_v1beta1.types.DocumentMask]): The fields to return. If not set, returns all fields. If the document has a field that is not present in this mask, that field will not be returned in the response. If a dict is provided, it must be of the same form as the protobuf message :class:`~google.cloud.firestore_v1beta1.types.DocumentMask` transaction (bytes): Reads the document in a transaction. read_time (Union[dict, ~google.cloud.firestore_v1beta1.types.Timestamp]): Reads the version of the document at the given time. This may not be older than 60 seconds. If a dict is provided, it must be of the same form as the protobuf message :class:`~google.cloud.firestore_v1beta1.types.Timestamp` options (~google.gax.CallOptions): Overrides the default settings for this call, e.g, timeout, retries etc. Returns: A :class:`~google.cloud.firestore_v1beta1.types.Document` instance. Raises: :exc:`google.gax.errors.GaxError` if the RPC is aborted. :exc:`ValueError` if the parameters are invalid. """ # Sanity check: We have some fields which are mutually exclusive; # raise ValueError if more than one is sent. oneof.check_oneof( transaction=transaction, read_time=read_time, ) request = firestore_pb2.GetDocumentRequest(name=name, mask=mask, transaction=transaction, read_time=read_time) return self._get_document(request, options) def list_documents(self, parent, collection_id, page_size=None, order_by=None, mask=None, transaction=None, read_time=None, show_missing=None, options=None): """ Lists documents. Example: >>> from google.cloud import firestore_v1beta1 >>> from google.gax import CallOptions, INITIAL_PAGE >>> >>> client = firestore_v1beta1.FirestoreClient() >>> >>> parent = client.any_path_path('[PROJECT]', '[DATABASE]', '[DOCUMENT]', '[ANY_PATH]') >>> collection_id = '' >>> >>> >>> # Iterate over all results >>> for element in client.list_documents(parent, collection_id): ... # process element ... pass >>> >>> # Or iterate over results one page at a time >>> for page in client.list_documents(parent, collection_id, options=CallOptions(page_token=INITIAL_PAGE)): ... for element in page: ... # process element ... pass Args: parent (str): The parent resource name. In the format: ``projects/{project_id}/databases/{database_id}/documents`` or ``projects/{project_id}/databases/{database_id}/documents/{document_path}``. For example: ``projects/my-project/databases/my-database/documents`` or ``projects/my-project/databases/my-database/documents/chatrooms/my-chatroom`` collection_id (str): The collection ID, relative to ``parent``, to list. For example: ``chatrooms`` or ``messages``. page_size (int): The maximum number of resources contained in the underlying API response. If page streaming is performed per- resource, this parameter does not affect the return value. If page streaming is performed per-page, this determines the maximum number of resources in a page. order_by (str): The order to sort results by. For example: ``priority desc, name``. mask (Union[dict, ~google.cloud.firestore_v1beta1.types.DocumentMask]): The fields to return. If not set, returns all fields. If a document has a field that is not present in this mask, that field will not be returned in the response. If a dict is provided, it must be of the same form as the protobuf message :class:`~google.cloud.firestore_v1beta1.types.DocumentMask` transaction (bytes): Reads documents in a transaction. read_time (Union[dict, ~google.cloud.firestore_v1beta1.types.Timestamp]): Reads documents as they were at the given time. This may not be older than 60 seconds. If a dict is provided, it must be of the same form as the protobuf message :class:`~google.cloud.firestore_v1beta1.types.Timestamp` show_missing (bool): If the list should show missing documents. A missing document is a document that does not exist but has sub-documents. These documents will be returned with a key but will not have fields, ``Document.create_time``, or ``Document.update_time`` set. Requests with ``show_missing`` may not specify ``where`` or ``order_by``. options (~google.gax.CallOptions): Overrides the default settings for this call, e.g, timeout, retries etc. Returns: A :class:`~google.gax.PageIterator` instance. By default, this is an iterable of :class:`~google.cloud.firestore_v1beta1.types.Document` instances. This object can also be configured to iterate over the pages of the response through the `options` parameter. Raises: :exc:`google.gax.errors.GaxError` if the RPC is aborted. :exc:`ValueError` if the parameters are invalid. """ # Sanity check: We have some fields which are mutually exclusive; # raise ValueError if more than one is sent. oneof.check_oneof( transaction=transaction, read_time=read_time, ) request = firestore_pb2.ListDocumentsRequest( parent=parent, collection_id=collection_id, page_size=page_size, order_by=order_by, mask=mask, transaction=transaction, read_time=read_time, show_missing=show_missing) return self._list_documents(request, options) def create_document(self, parent, collection_id, document_id, document, mask=None, options=None): """ Creates a new document. Example: >>> from google.cloud import firestore_v1beta1 >>> >>> client = firestore_v1beta1.FirestoreClient() >>> >>> parent = client.any_path_path('[PROJECT]', '[DATABASE]', '[DOCUMENT]', '[ANY_PATH]') >>> collection_id = '' >>> document_id = '' >>> document = {} >>> >>> response = client.create_document(parent, collection_id, document_id, document) Args: parent (str): The parent resource. For example: ``projects/{project_id}/databases/{database_id}/documents`` or ``projects/{project_id}/databases/{database_id}/documents/chatrooms/{chatroom_id}`` collection_id (str): The collection ID, relative to ``parent``, to list. For example: ``chatrooms``. document_id (str): The client-assigned document ID to use for this document. Optional. If not specified, an ID will be assigned by the service. document (Union[dict, ~google.cloud.firestore_v1beta1.types.Document]): The document to create. ``name`` must not be set. If a dict is provided, it must be of the same form as the protobuf message :class:`~google.cloud.firestore_v1beta1.types.Document` mask (Union[dict, ~google.cloud.firestore_v1beta1.types.DocumentMask]): The fields to return. If not set, returns all fields. If the document has a field that is not present in this mask, that field will not be returned in the response. If a dict is provided, it must be of the same form as the protobuf message :class:`~google.cloud.firestore_v1beta1.types.DocumentMask` options (~google.gax.CallOptions): Overrides the default settings for this call, e.g, timeout, retries etc. Returns: A :class:`~google.cloud.firestore_v1beta1.types.Document` instance. Raises: :exc:`google.gax.errors.GaxError` if the RPC is aborted. :exc:`ValueError` if the parameters are invalid. """ request = firestore_pb2.CreateDocumentRequest( parent=parent, collection_id=collection_id, document_id=document_id, document=document, mask=mask) return self._create_document(request, options) def update_document(self, document, update_mask, mask=None, current_document=None, options=None): """ Updates or inserts a document. Example: >>> from google.cloud import firestore_v1beta1 >>> >>> client = firestore_v1beta1.FirestoreClient() >>> >>> document = {} >>> update_mask = {} >>> >>> response = client.update_document(document, update_mask) Args: document (Union[dict, ~google.cloud.firestore_v1beta1.types.Document]): The updated document. Creates the document if it does not already exist. If a dict is provided, it must be of the same form as the protobuf message :class:`~google.cloud.firestore_v1beta1.types.Document` update_mask (Union[dict, ~google.cloud.firestore_v1beta1.types.DocumentMask]): The fields to update. None of the field paths in the mask may contain a reserved name. If the document exists on the server and has fields not referenced in the mask, they are left unchanged. Fields referenced in the mask, but not present in the input document, are deleted from the document on the server. If a dict is provided, it must be of the same form as the protobuf message :class:`~google.cloud.firestore_v1beta1.types.DocumentMask` mask (Union[dict, ~google.cloud.firestore_v1beta1.types.DocumentMask]): The fields to return. If not set, returns all fields. If the document has a field that is not present in this mask, that field will not be returned in the response. If a dict is provided, it must be of the same form as the protobuf message :class:`~google.cloud.firestore_v1beta1.types.DocumentMask` current_document (Union[dict, ~google.cloud.firestore_v1beta1.types.Precondition]): An optional precondition on the document. The request will fail if this is set and not met by the target document. If a dict is provided, it must be of the same form as the protobuf message :class:`~google.cloud.firestore_v1beta1.types.Precondition` options (~google.gax.CallOptions): Overrides the default settings for this call, e.g, timeout, retries etc. Returns: A :class:`~google.cloud.firestore_v1beta1.types.Document` instance. Raises: :exc:`google.gax.errors.GaxError` if the RPC is aborted. :exc:`ValueError` if the parameters are invalid. """ request = firestore_pb2.UpdateDocumentRequest( document=document, update_mask=update_mask, mask=mask, current_document=current_document) return self._update_document(request, options) def delete_document(self, name, current_document=None, options=None): """ Deletes a document. Example: >>> from google.cloud import firestore_v1beta1 >>> >>> client = firestore_v1beta1.FirestoreClient() >>> >>> name = client.any_path_path('[PROJECT]', '[DATABASE]', '[DOCUMENT]', '[ANY_PATH]') >>> >>> client.delete_document(name) Args: name (str): The resource name of the Document to delete. In the format: ``projects/{project_id}/databases/{database_id}/documents/{document_path}``. current_document (Union[dict, ~google.cloud.firestore_v1beta1.types.Precondition]): An optional precondition on the document. The request will fail if this is set and not met by the target document. If a dict is provided, it must be of the same form as the protobuf message :class:`~google.cloud.firestore_v1beta1.types.Precondition` options (~google.gax.CallOptions): Overrides the default settings for this call, e.g, timeout, retries etc. Raises: :exc:`google.gax.errors.GaxError` if the RPC is aborted. :exc:`ValueError` if the parameters are invalid. """ request = firestore_pb2.DeleteDocumentRequest( name=name, current_document=current_document) self._delete_document(request, options) def batch_get_documents(self, database, documents, mask=None, transaction=None, new_transaction=None, read_time=None, options=None): """ Gets multiple documents. Documents returned by this method are not guaranteed to be returned in the same order that they were requested. Example: >>> from google.cloud import firestore_v1beta1 >>> >>> client = firestore_v1beta1.FirestoreClient() >>> >>> database = client.database_root_path('[PROJECT]', '[DATABASE]') >>> documents = [] >>> >>> for element in client.batch_get_documents(database, documents): ... # process element ... pass Args: database (str): The database name. In the format: ``projects/{project_id}/databases/{database_id}``. documents (list[str]): The names of the documents to retrieve. In the format: ``projects/{project_id}/databases/{database_id}/documents/{document_path}``. The request will fail if any of the document is not a child resource of the given ``database``. Duplicate names will be elided. mask (Union[dict, ~google.cloud.firestore_v1beta1.types.DocumentMask]): The fields to return. If not set, returns all fields. If a document has a field that is not present in this mask, that field will not be returned in the response. If a dict is provided, it must be of the same form as the protobuf message :class:`~google.cloud.firestore_v1beta1.types.DocumentMask` transaction (bytes): Reads documents in a transaction. new_transaction (Union[dict, ~google.cloud.firestore_v1beta1.types.TransactionOptions]): Starts a new transaction and reads the documents. Defaults to a read-only transaction. The new transaction ID will be returned as the first response in the stream. If a dict is provided, it must be of the same form as the protobuf message :class:`~google.cloud.firestore_v1beta1.types.TransactionOptions` read_time (Union[dict, ~google.cloud.firestore_v1beta1.types.Timestamp]): Reads documents as they were at the given time. This may not be older than 60 seconds. If a dict is provided, it must be of the same form as the protobuf message :class:`~google.cloud.firestore_v1beta1.types.Timestamp` options (~google.gax.CallOptions): Overrides the default settings for this call, e.g, timeout, retries etc. Returns: Iterable[~google.cloud.firestore_v1beta1.types.BatchGetDocumentsResponse]. Raises: :exc:`google.gax.errors.GaxError` if the RPC is aborted. :exc:`ValueError` if the parameters are invalid. """ # Sanity check: We have some fields which are mutually exclusive; # raise ValueError if more than one is sent. oneof.check_oneof( transaction=transaction, new_transaction=new_transaction, read_time=read_time, ) request = firestore_pb2.BatchGetDocumentsRequest( database=database, documents=documents, mask=mask, transaction=transaction, new_transaction=new_transaction, read_time=read_time) return self._batch_get_documents(request, options) def begin_transaction(self, database, options_=None, options=None): """ Starts a new transaction. Example: >>> from google.cloud import firestore_v1beta1 >>> >>> client = firestore_v1beta1.FirestoreClient() >>> >>> database = client.database_root_path('[PROJECT]', '[DATABASE]') >>> >>> response = client.begin_transaction(database) Args: database (str): The database name. In the format: ``projects/{project_id}/databases/{database_id}``. options_ (Union[dict, ~google.cloud.firestore_v1beta1.types.TransactionOptions]): The options for the transaction. Defaults to a read-write transaction. If a dict is provided, it must be of the same form as the protobuf message :class:`~google.cloud.firestore_v1beta1.types.TransactionOptions` options (~google.gax.CallOptions): Overrides the default settings for this call, e.g, timeout, retries etc. Returns: A :class:`~google.cloud.firestore_v1beta1.types.BeginTransactionResponse` instance. Raises: :exc:`google.gax.errors.GaxError` if the RPC is aborted. :exc:`ValueError` if the parameters are invalid. """ request = firestore_pb2.BeginTransactionRequest(database=database, options=options_) return self._begin_transaction(request, options) def commit(self, database, writes, transaction=None, options=None): """ Commits a transaction, while optionally updating documents. Example: >>> from google.cloud import firestore_v1beta1 >>> >>> client = firestore_v1beta1.FirestoreClient() >>> >>> database = client.database_root_path('[PROJECT]', '[DATABASE]') >>> writes = [] >>> >>> response = client.commit(database, writes) Args: database (str): The database name. In the format: ``projects/{project_id}/databases/{database_id}``. writes (list[Union[dict, ~google.cloud.firestore_v1beta1.types.Write]]): The writes to apply. Always executed atomically and in order. If a dict is provided, it must be of the same form as the protobuf message :class:`~google.cloud.firestore_v1beta1.types.Write` transaction (bytes): If set, applies all writes in this transaction, and commits it. options (~google.gax.CallOptions): Overrides the default settings for this call, e.g, timeout, retries etc. Returns: A :class:`~google.cloud.firestore_v1beta1.types.CommitResponse` instance. Raises: :exc:`google.gax.errors.GaxError` if the RPC is aborted. :exc:`ValueError` if the parameters are invalid. """ request = firestore_pb2.CommitRequest(database=database, writes=writes, transaction=transaction) return self._commit(request, options) def rollback(self, database, transaction, options=None): """ Rolls back a transaction. Example: >>> from google.cloud import firestore_v1beta1 >>> >>> client = firestore_v1beta1.FirestoreClient() >>> >>> database = client.database_root_path('[PROJECT]', '[DATABASE]') >>> transaction = b'' >>> >>> client.rollback(database, transaction) Args: database (str): The database name. In the format: ``projects/{project_id}/databases/{database_id}``. transaction (bytes): The transaction to roll back. options (~google.gax.CallOptions): Overrides the default settings for this call, e.g, timeout, retries etc. Raises: :exc:`google.gax.errors.GaxError` if the RPC is aborted. :exc:`ValueError` if the parameters are invalid. """ request = firestore_pb2.RollbackRequest(database=database, transaction=transaction) self._rollback(request, options) def run_query(self, parent, structured_query=None, transaction=None, new_transaction=None, read_time=None, options=None): """ Runs a query. Example: >>> from google.cloud import firestore_v1beta1 >>> >>> client = firestore_v1beta1.FirestoreClient() >>> >>> parent = client.any_path_path('[PROJECT]', '[DATABASE]', '[DOCUMENT]', '[ANY_PATH]') >>> >>> for element in client.run_query(parent): ... # process element ... pass Args: parent (str): The parent resource name. In the format: ``projects/{project_id}/databases/{database_id}/documents`` or ``projects/{project_id}/databases/{database_id}/documents/{document_path}``. For example: ``projects/my-project/databases/my-database/documents`` or ``projects/my-project/databases/my-database/documents/chatrooms/my-chatroom`` structured_query (Union[dict, ~google.cloud.firestore_v1beta1.types.StructuredQuery]): A structured query. If a dict is provided, it must be of the same form as the protobuf message :class:`~google.cloud.firestore_v1beta1.types.StructuredQuery` transaction (bytes): Reads documents in a transaction. new_transaction (Union[dict, ~google.cloud.firestore_v1beta1.types.TransactionOptions]): Starts a new transaction and reads the documents. Defaults to a read-only transaction. The new transaction ID will be returned as the first response in the stream. If a dict is provided, it must be of the same form as the protobuf message :class:`~google.cloud.firestore_v1beta1.types.TransactionOptions` read_time (Union[dict, ~google.cloud.firestore_v1beta1.types.Timestamp]): Reads documents as they were at the given time. This may not be older than 60 seconds. If a dict is provided, it must be of the same form as the protobuf message :class:`~google.cloud.firestore_v1beta1.types.Timestamp` options (~google.gax.CallOptions): Overrides the default settings for this call, e.g, timeout, retries etc. Returns: Iterable[~google.cloud.firestore_v1beta1.types.RunQueryResponse]. Raises: :exc:`google.gax.errors.GaxError` if the RPC is aborted. :exc:`ValueError` if the parameters are invalid. """ # Sanity check: We have some fields which are mutually exclusive; # raise ValueError if more than one is sent. oneof.check_oneof(structured_query=structured_query, ) # Sanity check: We have some fields which are mutually exclusive; # raise ValueError if more than one is sent. oneof.check_oneof( transaction=transaction, new_transaction=new_transaction, read_time=read_time, ) request = firestore_pb2.RunQueryRequest( parent=parent, structured_query=structured_query, transaction=transaction, new_transaction=new_transaction, read_time=read_time) return self._run_query(request, options) def write(self, requests, options=None): """ Streams batches of document updates and deletes, in order. EXPERIMENTAL: This method interface might change in the future. Example: >>> from google.cloud import firestore_v1beta1 >>> >>> client = firestore_v1beta1.FirestoreClient() >>> >>> database = client.database_root_path('[PROJECT]', '[DATABASE]') >>> request = {'database': database} >>> >>> requests = [request] >>> for element in client.write(requests): ... # process element ... pass Args: requests (iterator[dict|google.cloud.firestore_v1beta1.proto.firestore_pb2.WriteRequest]): The input objects. If a dict is provided, it must be of the same form as the protobuf message :class:`~google.cloud.firestore_v1beta1.types.WriteRequest` options (~google.gax.CallOptions): Overrides the default settings for this call, e.g, timeout, retries etc. Returns: Iterable[~google.cloud.firestore_v1beta1.types.WriteResponse]. Raises: :exc:`google.gax.errors.GaxError` if the RPC is aborted. :exc:`ValueError` if the parameters are invalid. """ return self._write(requests, options) def listen(self, requests, options=None): """ Listens to changes. EXPERIMENTAL: This method interface might change in the future. Example: >>> from google.cloud import firestore_v1beta1 >>> >>> client = firestore_v1beta1.FirestoreClient() >>> >>> database = client.database_root_path('[PROJECT]', '[DATABASE]') >>> request = {'database': database} >>> >>> requests = [request] >>> for element in client.listen(requests): ... # process element ... pass Args: requests (iterator[dict|google.cloud.firestore_v1beta1.proto.firestore_pb2.ListenRequest]): The input objects. If a dict is provided, it must be of the same form as the protobuf message :class:`~google.cloud.firestore_v1beta1.types.ListenRequest` options (~google.gax.CallOptions): Overrides the default settings for this call, e.g, timeout, retries etc. Returns: Iterable[~google.cloud.firestore_v1beta1.types.ListenResponse]. Raises: :exc:`google.gax.errors.GaxError` if the RPC is aborted. :exc:`ValueError` if the parameters are invalid. """ return self._listen(requests, options) def list_collection_ids(self, parent, page_size=None, options=None): """ Lists all the collection IDs underneath a document. Example: >>> from google.cloud import firestore_v1beta1 >>> from google.gax import CallOptions, INITIAL_PAGE >>> >>> client = firestore_v1beta1.FirestoreClient() >>> >>> parent = client.any_path_path('[PROJECT]', '[DATABASE]', '[DOCUMENT]', '[ANY_PATH]') >>> >>> >>> # Iterate over all results >>> for element in client.list_collection_ids(parent): ... # process element ... pass >>> >>> # Or iterate over results one page at a time >>> for page in client.list_collection_ids(parent, options=CallOptions(page_token=INITIAL_PAGE)): ... for element in page: ... # process element ... pass Args: parent (str): The parent document. In the format: ``projects/{project_id}/databases/{database_id}/documents/{document_path}``. For example: ``projects/my-project/databases/my-database/documents/chatrooms/my-chatroom`` page_size (int): The maximum number of resources contained in the underlying API response. If page streaming is performed per- resource, this parameter does not affect the return value. If page streaming is performed per-page, this determines the maximum number of resources in a page. options (~google.gax.CallOptions): Overrides the default settings for this call, e.g, timeout, retries etc. Returns: A :class:`~google.gax.PageIterator` instance. By default, this is an iterable of :class:`str` instances. This object can also be configured to iterate over the pages of the response through the `options` parameter. Raises: :exc:`google.gax.errors.GaxError` if the RPC is aborted. :exc:`ValueError` if the parameters are invalid. """ request = firestore_pb2.ListCollectionIdsRequest(parent=parent, page_size=page_size) return self._list_collection_ids(request, options)
class PublisherApi(object): """ The service that an application uses to manipulate topics, and to send messages to a topic. """ SERVICE_ADDRESS = 'pubsub.googleapis.com' """The default address of the service.""" DEFAULT_SERVICE_PORT = 443 """The default port of the service.""" _CODE_GEN_NAME_VERSION = 'gapic/0.1.0' _GAX_VERSION = pkg_resources.get_distribution('google-gax').version _PAGE_DESCRIPTORS = { 'list_topics': _PageDesc('page_token', 'next_page_token', 'topics'), 'list_topic_subscriptions': _PageDesc('page_token', 'next_page_token', 'subscriptions') } _BUNDLE_DESCRIPTORS = { 'publish': _BundleDesc( 'messages', ['topic'], subresponse_field='message_ids', ) } # The scopes needed to make gRPC calls to all of the methods defined in # this service _ALL_SCOPES = ( 'https://www.googleapis.com/auth/cloud-platform', 'https://www.googleapis.com/auth/pubsub', ) _PROJECT_PATH_TEMPLATE = path_template.PathTemplate('projects/{project}') _TOPIC_PATH_TEMPLATE = path_template.PathTemplate( 'projects/{project}/topics/{topic}') @classmethod def project_path(cls, project): """Returns a fully-qualified project resource name string.""" return cls._PROJECT_PATH_TEMPLATE.render({ 'project': project, }) @classmethod def topic_path(cls, project, topic): """Returns a fully-qualified topic resource name string.""" return cls._TOPIC_PATH_TEMPLATE.render({ 'project': project, 'topic': topic, }) @classmethod def match_project_from_project_name(cls, project_name): """Parses the project from a project resource. Args: project_name (string): A fully-qualified path representing a project resource. Returns: A string representing the project. """ return cls._PROJECT_PATH_TEMPLATE.match(project_name).get('project') @classmethod def match_project_from_topic_name(cls, topic_name): """Parses the project from a topic resource. Args: topic_name (string): A fully-qualified path representing a topic resource. Returns: A string representing the project. """ return cls._TOPIC_PATH_TEMPLATE.match(topic_name).get('project') @classmethod def match_topic_from_topic_name(cls, topic_name): """Parses the topic from a topic resource. Args: topic_name (string): A fully-qualified path representing a topic resource. Returns: A string representing the topic. """ return cls._TOPIC_PATH_TEMPLATE.match(topic_name).get('topic') def __init__(self, service_path=SERVICE_ADDRESS, port=DEFAULT_SERVICE_PORT, channel=None, metadata_transformer=None, ssl_creds=None, scopes=None, client_config=None, app_name='gax', app_version=_GAX_VERSION): """Constructor. Args: service_path (string): The domain name of the API remote host. port (int): The port on which to connect to the remote host. channel (:class:`grpc.Channel`): A ``Channel`` instance through which to make calls. ssl_creds (:class:`grpc.ChannelCredentials`): A ``ChannelCredentials`` instance for use with an SSL-enabled channel. client_config (dict): A dictionary for call options for each method. See :func:`google.gax.construct_settings` for the structure of this data. Falls back to the default config if not specified or the specified config is missing data points. metadata_transformer (Callable[[], list]): A function that creates the metadata for requests. app_name (string): The codename of the calling service. app_version (string): The version of the calling service. Returns: A PublisherApi object. """ if scopes is None: scopes = self._ALL_SCOPES if client_config is None: client_config = {} goog_api_client = '{}/{} {} gax/{} python/{}'.format( app_name, app_version, self._CODE_GEN_NAME_VERSION, self._GAX_VERSION, platform.python_version()) metadata = [('x-goog-api-client', goog_api_client)] default_client_config = json.loads( pkg_resources.resource_string( __name__, 'publisher_client_config.json').decode()) defaults = api_callable.construct_settings( 'google.pubsub.v1.Publisher', default_client_config, client_config, config.STATUS_CODE_NAMES, kwargs={'metadata': metadata}, bundle_descriptors=self._BUNDLE_DESCRIPTORS, page_descriptors=self._PAGE_DESCRIPTORS) self.stub = config.create_stub( pubsub_pb2.PublisherStub, service_path, port, ssl_creds=ssl_creds, channel=channel, metadata_transformer=metadata_transformer, scopes=scopes) self._create_topic = api_callable.create_api_call( self.stub.CreateTopic, settings=defaults['create_topic']) self._publish = api_callable.create_api_call( self.stub.Publish, settings=defaults['publish']) self._get_topic = api_callable.create_api_call( self.stub.GetTopic, settings=defaults['get_topic']) self._list_topics = api_callable.create_api_call( self.stub.ListTopics, settings=defaults['list_topics']) self._list_topic_subscriptions = api_callable.create_api_call( self.stub.ListTopicSubscriptions, settings=defaults['list_topic_subscriptions']) self._delete_topic = api_callable.create_api_call( self.stub.DeleteTopic, settings=defaults['delete_topic']) # Service calls def create_topic(self, name, options=None): """ Creates the given topic with the given name. Example: >>> from google.cloud.gapic.pubsub.v1.publisher_api import PublisherApi >>> api = PublisherApi() >>> name = api.topic_path('[PROJECT]', '[TOPIC]') >>> response = api.create_topic(name) Args: name (string): 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\"``. options (:class:`google.gax.CallOptions`): Overrides the default settings for this call, e.g, timeout, retries etc. Returns: A :class:`google.pubsub.v1.pubsub_pb2.Topic` instance. Raises: :exc:`google.gax.errors.GaxError` if the RPC is aborted. """ request = pubsub_pb2.Topic(name=name) return self._create_topic(request, options) def publish(self, topic, messages, options=None): """ Adds one or more messages to the topic. Returns ``NOT_FOUND`` if the topic does not exist. The message payload must not be empty; it must contain either a non-empty data field, or at least one attribute. Example: >>> from google.cloud.gapic.pubsub.v1.publisher_api import PublisherApi >>> from google.pubsub.v1 import pubsub_pb2 >>> api = PublisherApi() >>> topic = api.topic_path('[PROJECT]', '[TOPIC]') >>> data = '' >>> messages_element = pubsub_pb2.PubsubMessage(data) >>> messages = [messages_element] >>> response = api.publish(topic, messages) Args: topic (string): The messages in the request will be published on this topic. messages (list[:class:`google.pubsub.v1.pubsub_pb2.PubsubMessage`]): The messages to publish. options (:class:`google.gax.CallOptions`): Overrides the default settings for this call, e.g, timeout, retries etc. Returns: A :class:`google.pubsub.v1.pubsub_pb2.PublishResponse` instance. Raises: :exc:`google.gax.errors.GaxError` if the RPC is aborted. """ request = pubsub_pb2.PublishRequest(topic=topic, messages=messages) return self._publish(request, options) def get_topic(self, topic, options=None): """ Gets the configuration of a topic. Example: >>> from google.cloud.gapic.pubsub.v1.publisher_api import PublisherApi >>> api = PublisherApi() >>> topic = api.topic_path('[PROJECT]', '[TOPIC]') >>> response = api.get_topic(topic) Args: topic (string): The name of the topic to get. options (:class:`google.gax.CallOptions`): Overrides the default settings for this call, e.g, timeout, retries etc. Returns: A :class:`google.pubsub.v1.pubsub_pb2.Topic` instance. Raises: :exc:`google.gax.errors.GaxError` if the RPC is aborted. """ request = pubsub_pb2.GetTopicRequest(topic=topic) return self._get_topic(request, options) def list_topics(self, project, page_size=0, options=None): """ Lists matching topics. Example: >>> from google.cloud.gapic.pubsub.v1.publisher_api import PublisherApi >>> from google.gax import CallOptions, INITIAL_PAGE >>> api = PublisherApi() >>> project = api.project_path('[PROJECT]') >>> >>> # Iterate over all results >>> for element in api.list_topics(project): >>> # process element >>> pass >>> >>> # Or iterate over results one page at a time >>> for page in api.list_topics(project, options=CallOptions(page_token=INITIAL_PAGE)): >>> for element in page: >>> # process element >>> pass Args: project (string): The name of the cloud project that topics belong to. page_size (int): The maximum number of resources contained in the underlying API response. If page streaming is performed per- resource, this parameter does not affect the return value. If page streaming is performed per-page, this determines the maximum number of resources in a page. options (:class:`google.gax.CallOptions`): Overrides the default settings for this call, e.g, timeout, retries etc. Returns: A :class:`google.gax.PageIterator` instance. By default, this is an iterable of :class:`google.pubsub.v1.pubsub_pb2.Topic` instances. This object can also be configured to iterate over the pages of the response through the `CallOptions` parameter. Raises: :exc:`google.gax.errors.GaxError` if the RPC is aborted. """ request = pubsub_pb2.ListTopicsRequest(project=project, page_size=page_size) return self._list_topics(request, options) def list_topic_subscriptions(self, topic, page_size=0, options=None): """ Lists the name of the subscriptions for this topic. Example: >>> from google.cloud.gapic.pubsub.v1.publisher_api import PublisherApi >>> from google.gax import CallOptions, INITIAL_PAGE >>> api = PublisherApi() >>> topic = api.topic_path('[PROJECT]', '[TOPIC]') >>> >>> # Iterate over all results >>> for element in api.list_topic_subscriptions(topic): >>> # process element >>> pass >>> >>> # Or iterate over results one page at a time >>> for page in api.list_topic_subscriptions(topic, options=CallOptions(page_token=INITIAL_PAGE)): >>> for element in page: >>> # process element >>> pass Args: topic (string): The name of the topic that subscriptions are attached to. page_size (int): The maximum number of resources contained in the underlying API response. If page streaming is performed per- resource, this parameter does not affect the return value. If page streaming is performed per-page, this determines the maximum number of resources in a page. options (:class:`google.gax.CallOptions`): Overrides the default settings for this call, e.g, timeout, retries etc. Returns: A :class:`google.gax.PageIterator` instance. By default, this is an iterable of string instances. This object can also be configured to iterate over the pages of the response through the `CallOptions` parameter. Raises: :exc:`google.gax.errors.GaxError` if the RPC is aborted. """ request = pubsub_pb2.ListTopicSubscriptionsRequest(topic=topic, page_size=page_size) return self._list_topic_subscriptions(request, options) def delete_topic(self, topic, options=None): """ Deletes the topic with the given name. Returns ``NOT_FOUND`` if the topic does not exist. After a topic is deleted, a new topic may be created with the same name; this is an entirely new topic with none of the old configuration or subscriptions. Existing subscriptions to this topic are not deleted, but their ``topic`` field is set to ``_deleted-topic_``. Example: >>> from google.cloud.gapic.pubsub.v1.publisher_api import PublisherApi >>> api = PublisherApi() >>> topic = api.topic_path('[PROJECT]', '[TOPIC]') >>> api.delete_topic(topic) Args: topic (string): Name of the topic to delete. options (:class:`google.gax.CallOptions`): Overrides the default settings for this call, e.g, timeout, retries etc. Raises: :exc:`google.gax.errors.GaxError` if the RPC is aborted. """ request = pubsub_pb2.DeleteTopicRequest(topic=topic) self._delete_topic(request, options)
class SubscriberApi(object): """ The service that an application uses to manipulate subscriptions and to consume messages from a subscription via the ``Pull`` method. """ SERVICE_ADDRESS = 'pubsub.googleapis.com' """The default address of the service.""" DEFAULT_SERVICE_PORT = 443 """The default port of the service.""" _CODE_GEN_NAME_VERSION = 'gapic/0.1.0' _GAX_VERSION = pkg_resources.get_distribution('google-gax').version _PAGE_DESCRIPTORS = { 'list_subscriptions': _PageDesc('page_token', 'next_page_token', 'subscriptions') } # The scopes needed to make gRPC calls to all of the methods defined in # this service _ALL_SCOPES = ( 'https://www.googleapis.com/auth/cloud-platform', 'https://www.googleapis.com/auth/pubsub', ) _PROJECT_PATH_TEMPLATE = path_template.PathTemplate('projects/{project}') _SUBSCRIPTION_PATH_TEMPLATE = path_template.PathTemplate( 'projects/{project}/subscriptions/{subscription}') _TOPIC_PATH_TEMPLATE = path_template.PathTemplate( 'projects/{project}/topics/{topic}') @classmethod def project_path(cls, project): """Returns a fully-qualified project resource name string.""" return cls._PROJECT_PATH_TEMPLATE.render({ 'project': project, }) @classmethod def subscription_path(cls, project, subscription): """Returns a fully-qualified subscription resource name string.""" return cls._SUBSCRIPTION_PATH_TEMPLATE.render({ 'project': project, 'subscription': subscription, }) @classmethod def topic_path(cls, project, topic): """Returns a fully-qualified topic resource name string.""" return cls._TOPIC_PATH_TEMPLATE.render({ 'project': project, 'topic': topic, }) @classmethod def match_project_from_project_name(cls, project_name): """Parses the project from a project resource. Args: project_name (string): A fully-qualified path representing a project resource. Returns: A string representing the project. """ return cls._PROJECT_PATH_TEMPLATE.match(project_name).get('project') @classmethod def match_project_from_subscription_name(cls, subscription_name): """Parses the project from a subscription resource. Args: subscription_name (string): A fully-qualified path representing a subscription resource. Returns: A string representing the project. """ return cls._SUBSCRIPTION_PATH_TEMPLATE.match(subscription_name).get( 'project') @classmethod def match_subscription_from_subscription_name(cls, subscription_name): """Parses the subscription from a subscription resource. Args: subscription_name (string): A fully-qualified path representing a subscription resource. Returns: A string representing the subscription. """ return cls._SUBSCRIPTION_PATH_TEMPLATE.match(subscription_name).get( 'subscription') @classmethod def match_project_from_topic_name(cls, topic_name): """Parses the project from a topic resource. Args: topic_name (string): A fully-qualified path representing a topic resource. Returns: A string representing the project. """ return cls._TOPIC_PATH_TEMPLATE.match(topic_name).get('project') @classmethod def match_topic_from_topic_name(cls, topic_name): """Parses the topic from a topic resource. Args: topic_name (string): A fully-qualified path representing a topic resource. Returns: A string representing the topic. """ return cls._TOPIC_PATH_TEMPLATE.match(topic_name).get('topic') def __init__(self, service_path=SERVICE_ADDRESS, port=DEFAULT_SERVICE_PORT, channel=None, metadata_transformer=None, ssl_creds=None, scopes=None, client_config=None, app_name='gax', app_version=_GAX_VERSION): """Constructor. Args: service_path (string): The domain name of the API remote host. port (int): The port on which to connect to the remote host. channel (:class:`grpc.Channel`): A ``Channel`` instance through which to make calls. ssl_creds (:class:`grpc.ChannelCredentials`): A ``ChannelCredentials`` instance for use with an SSL-enabled channel. client_config (dict): A dictionary for call options for each method. See :func:`google.gax.construct_settings` for the structure of this data. Falls back to the default config if not specified or the specified config is missing data points. metadata_transformer (Callable[[], list]): A function that creates the metadata for requests. app_name (string): The codename of the calling service. app_version (string): The version of the calling service. Returns: A SubscriberApi object. """ if scopes is None: scopes = self._ALL_SCOPES if client_config is None: client_config = {} goog_api_client = '{}/{} {} gax/{} python/{}'.format( app_name, app_version, self._CODE_GEN_NAME_VERSION, self._GAX_VERSION, platform.python_version()) metadata = [('x-goog-api-client', goog_api_client)] default_client_config = json.loads( pkg_resources.resource_string( __name__, 'subscriber_client_config.json').decode()) defaults = api_callable.construct_settings( 'google.pubsub.v1.Subscriber', default_client_config, client_config, config.STATUS_CODE_NAMES, kwargs={'metadata': metadata}, page_descriptors=self._PAGE_DESCRIPTORS) self.iam_policy_stub = config.create_stub( iam_policy_pb2.IAMPolicyStub, service_path, port, ssl_creds=ssl_creds, channel=channel, metadata_transformer=metadata_transformer, scopes=scopes) self.subscriber_stub = config.create_stub( pubsub_pb2.SubscriberStub, service_path, port, ssl_creds=ssl_creds, channel=channel, metadata_transformer=metadata_transformer, scopes=scopes) self._create_subscription = api_callable.create_api_call( self.subscriber_stub.CreateSubscription, settings=defaults['create_subscription']) self._get_subscription = api_callable.create_api_call( self.subscriber_stub.GetSubscription, settings=defaults['get_subscription']) self._list_subscriptions = api_callable.create_api_call( self.subscriber_stub.ListSubscriptions, settings=defaults['list_subscriptions']) self._delete_subscription = api_callable.create_api_call( self.subscriber_stub.DeleteSubscription, settings=defaults['delete_subscription']) self._modify_ack_deadline = api_callable.create_api_call( self.subscriber_stub.ModifyAckDeadline, settings=defaults['modify_ack_deadline']) self._acknowledge = api_callable.create_api_call( self.subscriber_stub.Acknowledge, settings=defaults['acknowledge']) self._pull = api_callable.create_api_call(self.subscriber_stub.Pull, settings=defaults['pull']) self._modify_push_config = api_callable.create_api_call( self.subscriber_stub.ModifyPushConfig, settings=defaults['modify_push_config']) self._set_iam_policy = api_callable.create_api_call( self.iam_policy_stub.SetIamPolicy, settings=defaults['set_iam_policy']) self._get_iam_policy = api_callable.create_api_call( self.iam_policy_stub.GetIamPolicy, settings=defaults['get_iam_policy']) self._test_iam_permissions = api_callable.create_api_call( self.iam_policy_stub.TestIamPermissions, settings=defaults['test_iam_permissions']) # Service calls def create_subscription(self, name, topic, push_config=None, ack_deadline_seconds=0, options=None): """ Creates a subscription to a given topic. If the subscription already exists, returns ``ALREADY_EXISTS``. If the corresponding topic doesn't exist, returns ``NOT_FOUND``. If the name is not provided in the request, the server will assign a random name for this subscription on the same project as the topic. Note that for REST API requests, you must specify a name. Example: >>> from google.cloud.gapic.pubsub.v1 import subscriber_api >>> api = subscriber_api.SubscriberApi() >>> name = api.subscription_path('[PROJECT]', '[SUBSCRIPTION]') >>> topic = api.topic_path('[PROJECT]', '[TOPIC]') >>> response = api.create_subscription(name, topic) Args: name (string): 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\"``. topic (string): The name of the topic from which this subscription is receiving messages. The value of this field will be ``_deleted-topic_`` if the topic has been deleted. push_config (:class:`google.pubsub.v1.pubsub_pb2.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. ack_deadline_seconds (int): 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 maximum custom deadline you can specify is 600 seconds (10 minutes). 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. If this parameter is 0, a default value of 10 seconds is used. options (:class:`google.gax.CallOptions`): Overrides the default settings for this call, e.g, timeout, retries etc. Returns: A :class:`google.pubsub.v1.pubsub_pb2.Subscription` instance. Raises: :exc:`google.gax.errors.GaxError` if the RPC is aborted. :exc:`ValueError` if the parameters are invalid. """ if push_config is None: push_config = pubsub_pb2.PushConfig() request = pubsub_pb2.Subscription( name=name, topic=topic, push_config=push_config, ack_deadline_seconds=ack_deadline_seconds) return self._create_subscription(request, options) def get_subscription(self, subscription, options=None): """ Gets the configuration details of a subscription. Example: >>> from google.cloud.gapic.pubsub.v1 import subscriber_api >>> api = subscriber_api.SubscriberApi() >>> subscription = api.subscription_path('[PROJECT]', '[SUBSCRIPTION]') >>> response = api.get_subscription(subscription) Args: subscription (string): The name of the subscription to get. options (:class:`google.gax.CallOptions`): Overrides the default settings for this call, e.g, timeout, retries etc. Returns: A :class:`google.pubsub.v1.pubsub_pb2.Subscription` instance. Raises: :exc:`google.gax.errors.GaxError` if the RPC is aborted. :exc:`ValueError` if the parameters are invalid. """ request = pubsub_pb2.GetSubscriptionRequest(subscription=subscription) return self._get_subscription(request, options) def list_subscriptions(self, project, page_size=0, options=None): """ Lists matching subscriptions. Example: >>> from google.cloud.gapic.pubsub.v1 import subscriber_api >>> from google.gax import CallOptions, INITIAL_PAGE >>> api = subscriber_api.SubscriberApi() >>> project = api.project_path('[PROJECT]') >>> >>> # Iterate over all results >>> for element in api.list_subscriptions(project): >>> # process element >>> pass >>> >>> # Or iterate over results one page at a time >>> for page in api.list_subscriptions(project, options=CallOptions(page_token=INITIAL_PAGE)): >>> for element in page: >>> # process element >>> pass Args: project (string): The name of the cloud project that subscriptions belong to. page_size (int): The maximum number of resources contained in the underlying API response. If page streaming is performed per- resource, this parameter does not affect the return value. If page streaming is performed per-page, this determines the maximum number of resources in a page. options (:class:`google.gax.CallOptions`): Overrides the default settings for this call, e.g, timeout, retries etc. Returns: A :class:`google.gax.PageIterator` instance. By default, this is an iterable of :class:`google.pubsub.v1.pubsub_pb2.Subscription` instances. This object can also be configured to iterate over the pages of the response through the `CallOptions` parameter. Raises: :exc:`google.gax.errors.GaxError` if the RPC is aborted. :exc:`ValueError` if the parameters are invalid. """ request = pubsub_pb2.ListSubscriptionsRequest(project=project, page_size=page_size) return self._list_subscriptions(request, options) def delete_subscription(self, subscription, options=None): """ Deletes an existing subscription. All pending messages in the subscription are immediately dropped. Calls to ``Pull`` after deletion will return ``NOT_FOUND``. After a subscription is deleted, a new one may be created with the same name, but the new one has no association with the old subscription, or its topic unless the same topic is specified. Example: >>> from google.cloud.gapic.pubsub.v1 import subscriber_api >>> api = subscriber_api.SubscriberApi() >>> subscription = api.subscription_path('[PROJECT]', '[SUBSCRIPTION]') >>> api.delete_subscription(subscription) Args: subscription (string): The subscription to delete. options (:class:`google.gax.CallOptions`): Overrides the default settings for this call, e.g, timeout, retries etc. Raises: :exc:`google.gax.errors.GaxError` if the RPC is aborted. :exc:`ValueError` if the parameters are invalid. """ request = pubsub_pb2.DeleteSubscriptionRequest( subscription=subscription) self._delete_subscription(request, options) def modify_ack_deadline(self, subscription, ack_ids, ack_deadline_seconds, options=None): """ Modifies the ack deadline for a specific message. This method is useful to indicate that more time is needed to process a message by the subscriber, or to make the message available for redelivery if the processing was interrupted. Note that this does not modify the subscription-level ``ackDeadlineSeconds`` used for subsequent messages. Example: >>> from google.cloud.gapic.pubsub.v1 import subscriber_api >>> api = subscriber_api.SubscriberApi() >>> subscription = api.subscription_path('[PROJECT]', '[SUBSCRIPTION]') >>> ack_ids = [] >>> ack_deadline_seconds = 0 >>> api.modify_ack_deadline(subscription, ack_ids, ack_deadline_seconds) Args: subscription (string): The name of the subscription. ack_ids (list[string]): List of acknowledgment IDs. ack_deadline_seconds (int): The new ack deadline with respect to the time this request was sent to the Pub/Sub system. Must be >= 0. For example, if the value is 10, the new ack deadline will expire 10 seconds after the ``ModifyAckDeadline`` call was made. Specifying zero may immediately make the message available for another pull request. options (:class:`google.gax.CallOptions`): Overrides the default settings for this call, e.g, timeout, retries etc. Raises: :exc:`google.gax.errors.GaxError` if the RPC is aborted. :exc:`ValueError` if the parameters are invalid. """ request = pubsub_pb2.ModifyAckDeadlineRequest( subscription=subscription, ack_ids=ack_ids, ack_deadline_seconds=ack_deadline_seconds) self._modify_ack_deadline(request, options) def acknowledge(self, subscription, ack_ids, options=None): """ Acknowledges the messages associated with the ``ack_ids`` in the ``AcknowledgeRequest``. The Pub/Sub system can remove the relevant messages from the subscription. Acknowledging a message whose ack deadline has expired may succeed, but such a message may be redelivered later. Acknowledging a message more than once will not result in an error. Example: >>> from google.cloud.gapic.pubsub.v1 import subscriber_api >>> api = subscriber_api.SubscriberApi() >>> subscription = api.subscription_path('[PROJECT]', '[SUBSCRIPTION]') >>> ack_ids = [] >>> api.acknowledge(subscription, ack_ids) Args: subscription (string): The subscription whose message is being acknowledged. ack_ids (list[string]): The acknowledgment ID for the messages being acknowledged that was returned by the Pub/Sub system in the ``Pull`` response. Must not be empty. options (:class:`google.gax.CallOptions`): Overrides the default settings for this call, e.g, timeout, retries etc. Raises: :exc:`google.gax.errors.GaxError` if the RPC is aborted. :exc:`ValueError` if the parameters are invalid. """ request = pubsub_pb2.AcknowledgeRequest(subscription=subscription, ack_ids=ack_ids) self._acknowledge(request, options) def pull(self, subscription, max_messages, return_immediately=False, options=None): """ Pulls messages from the server. Returns an empty list if there are no messages available in the backlog. The server may return ``UNAVAILABLE`` if there are too many concurrent pull requests pending for the given subscription. Example: >>> from google.cloud.gapic.pubsub.v1 import subscriber_api >>> api = subscriber_api.SubscriberApi() >>> subscription = api.subscription_path('[PROJECT]', '[SUBSCRIPTION]') >>> max_messages = 0 >>> response = api.pull(subscription, max_messages) Args: subscription (string): The subscription from which messages should be pulled. return_immediately (bool): If this is specified as true the system will respond immediately even if it is not able to return a message in the ``Pull`` response. Otherwise the system is allowed to wait until at least one message is available rather than returning no messages. The client may cancel the request if it does not wish to wait any longer for the response. max_messages (int): The maximum number of messages returned for this request. The Pub/Sub system may return fewer than the number specified. options (:class:`google.gax.CallOptions`): Overrides the default settings for this call, e.g, timeout, retries etc. Returns: A :class:`google.pubsub.v1.pubsub_pb2.PullResponse` instance. Raises: :exc:`google.gax.errors.GaxError` if the RPC is aborted. :exc:`ValueError` if the parameters are invalid. """ request = pubsub_pb2.PullRequest(subscription=subscription, max_messages=max_messages, return_immediately=return_immediately) return self._pull(request, options) def modify_push_config(self, subscription, push_config, options=None): """ Modifies the ``PushConfig`` for a specified subscription. This may be used to change a push subscription to a pull one (signified by an empty ``PushConfig``) or vice versa, or change the endpoint URL and other attributes of a push subscription. Messages will accumulate for delivery continuously through the call regardless of changes to the ``PushConfig``. Example: >>> from google.cloud.gapic.pubsub.v1 import subscriber_api >>> from google.pubsub.v1 import pubsub_pb2 >>> api = subscriber_api.SubscriberApi() >>> subscription = api.subscription_path('[PROJECT]', '[SUBSCRIPTION]') >>> push_config = pubsub_pb2.PushConfig() >>> api.modify_push_config(subscription, push_config) Args: subscription (string): The name of the subscription. push_config (:class:`google.pubsub.v1.pubsub_pb2.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. options (:class:`google.gax.CallOptions`): Overrides the default settings for this call, e.g, timeout, retries etc. Raises: :exc:`google.gax.errors.GaxError` if the RPC is aborted. :exc:`ValueError` if the parameters are invalid. """ request = pubsub_pb2.ModifyPushConfigRequest(subscription=subscription, push_config=push_config) self._modify_push_config(request, options) def set_iam_policy(self, resource, policy, options=None): """ Sets the access control policy on the specified resource. Replaces any existing policy. Example: >>> from google.cloud.gapic.pubsub.v1 import subscriber_api >>> from google.iam.v1 import policy_pb2 >>> api = subscriber_api.SubscriberApi() >>> resource = api.subscription_path('[PROJECT]', '[SUBSCRIPTION]') >>> policy = policy_pb2.Policy() >>> response = api.set_iam_policy(resource, policy) Args: resource (string): REQUIRED: The resource for which policy is being specified. Resource is usually specified as a path, such as, projects/{project}/zones/{zone}/disks/{disk}. policy (:class:`google.iam.v1.policy_pb2.Policy`): REQUIRED: The complete policy to be applied to the 'resource'. The size of the policy is limited to a few 10s of KB. An empty policy is in general a valid policy but certain services (like Projects) might reject them. options (:class:`google.gax.CallOptions`): Overrides the default settings for this call, e.g, timeout, retries etc. Returns: A :class:`google.iam.v1.policy_pb2.Policy` instance. Raises: :exc:`google.gax.errors.GaxError` if the RPC is aborted. :exc:`ValueError` if the parameters are invalid. """ request = iam_policy_pb2.SetIamPolicyRequest(resource=resource, policy=policy) return self._set_iam_policy(request, options) def get_iam_policy(self, resource, options=None): """ Gets the access control policy for a resource. Is empty if the policy or the resource does not exist. Example: >>> from google.cloud.gapic.pubsub.v1 import subscriber_api >>> api = subscriber_api.SubscriberApi() >>> resource = api.subscription_path('[PROJECT]', '[SUBSCRIPTION]') >>> response = api.get_iam_policy(resource) Args: resource (string): REQUIRED: The resource for which policy is being requested. Resource is usually specified as a path, such as, projects/{project}. options (:class:`google.gax.CallOptions`): Overrides the default settings for this call, e.g, timeout, retries etc. Returns: A :class:`google.iam.v1.policy_pb2.Policy` instance. Raises: :exc:`google.gax.errors.GaxError` if the RPC is aborted. :exc:`ValueError` if the parameters are invalid. """ request = iam_policy_pb2.GetIamPolicyRequest(resource=resource) return self._get_iam_policy(request, options) def test_iam_permissions(self, resource, permissions, options=None): """ Returns permissions that a caller has on the specified resource. Example: >>> from google.cloud.gapic.pubsub.v1 import subscriber_api >>> api = subscriber_api.SubscriberApi() >>> resource = api.subscription_path('[PROJECT]', '[SUBSCRIPTION]') >>> permissions = [] >>> response = api.test_iam_permissions(resource, permissions) Args: resource (string): REQUIRED: The resource for which policy detail is being requested. Resource is usually specified as a path, such as, projects/{project}. permissions (list[string]): The set of permissions to check for the 'resource'. Permissions with wildcards (such as '*' or 'storage.*') are not allowed. options (:class:`google.gax.CallOptions`): Overrides the default settings for this call, e.g, timeout, retries etc. Returns: A :class:`google.iam.v1.iam_policy_pb2.TestIamPermissionsResponse` instance. Raises: :exc:`google.gax.errors.GaxError` if the RPC is aborted. :exc:`ValueError` if the parameters are invalid. """ request = iam_policy_pb2.TestIamPermissionsRequest( resource=resource, permissions=permissions) return self._test_iam_permissions(request, options)
class ReportErrorsServiceApi(object): """An API for reporting error events.""" SERVICE_ADDRESS = 'clouderrorreporting.googleapis.com' """The default address of the service.""" DEFAULT_SERVICE_PORT = 443 """The default port of the service.""" _CODE_GEN_NAME_VERSION = 'gapic/0.1.0' _GAX_VERSION = pkg_resources.get_distribution('google-gax').version # The scopes needed to make gRPC calls to all of the methods defined in # this service _ALL_SCOPES = ('https://www.googleapis.com/auth/cloud-platform', ) _PROJECT_PATH_TEMPLATE = path_template.PathTemplate('projects/{project}') @classmethod def project_path(cls, project): """Returns a fully-qualified project resource name string.""" return cls._PROJECT_PATH_TEMPLATE.render({ 'project': project, }) @classmethod def match_project_from_project_name(cls, project_name): """Parses the project from a project resource. Args: project_name (string): A fully-qualified path representing a project resource. Returns: A string representing the project. """ return cls._PROJECT_PATH_TEMPLATE.match(project_name).get('project') def __init__(self, service_path=SERVICE_ADDRESS, port=DEFAULT_SERVICE_PORT, channel=None, metadata_transformer=None, ssl_creds=None, scopes=None, client_config=None, app_name='gax', app_version=_GAX_VERSION): """Constructor. Args: service_path (string): The domain name of the API remote host. port (int): The port on which to connect to the remote host. channel (:class:`grpc.Channel`): A ``Channel`` instance through which to make calls. ssl_creds (:class:`grpc.ChannelCredentials`): A ``ChannelCredentials`` instance for use with an SSL-enabled channel. client_config (dict): A dictionary for call options for each method. See :func:`google.gax.construct_settings` for the structure of this data. Falls back to the default config if not specified or the specified config is missing data points. metadata_transformer (Callable[[], list]): A function that creates the metadata for requests. app_name (string): The codename of the calling service. app_version (string): The version of the calling service. Returns: A ReportErrorsServiceApi object. """ if scopes is None: scopes = self._ALL_SCOPES if client_config is None: client_config = {} goog_api_client = '{}/{} {} gax/{} python/{}'.format( app_name, app_version, self._CODE_GEN_NAME_VERSION, self._GAX_VERSION, platform.python_version()) metadata = [('x-goog-api-client', goog_api_client)] default_client_config = json.loads( pkg_resources.resource_string( __name__, 'report_errors_service_client_config.json').decode()) defaults = api_callable.construct_settings( 'google.devtools.clouderrorreporting.v1beta1.ReportErrorsService', default_client_config, client_config, config.STATUS_CODE_NAMES, kwargs={'metadata': metadata}) self.report_errors_service_stub = config.create_stub( report_errors_service_pb2.ReportErrorsServiceStub, service_path, port, ssl_creds=ssl_creds, channel=channel, metadata_transformer=metadata_transformer, scopes=scopes) self._report_error_event = api_callable.create_api_call( self.report_errors_service_stub.ReportErrorEvent, settings=defaults['report_error_event']) # Service calls def report_error_event(self, project_name, event, options=None): """ Report an individual error event. This endpoint accepts <strong>either</strong> an OAuth token, <strong>or</strong> an <a href=\"https://support.google.com/cloud/answer/6158862\">API key</a> for authentication. To use an API key, append it to the URL as the value of a ``key`` parameter. For example: <pre>POST https://clouderrorreporting.googleapis.com/v1beta1/projects/example-project/events:report?key=123ABC456</pre> Example: >>> from google.cloud.gapic.errorreporting.v1beta1 import report_errors_service_api >>> from google.devtools.clouderrorreporting.v1beta1 import report_errors_service_pb2 >>> api = report_errors_service_api.ReportErrorsServiceApi() >>> project_name = api.project_path('[PROJECT]') >>> event = report_errors_service_pb2.ReportedErrorEvent() >>> response = api.report_error_event(project_name, event) Args: project_name (string): [Required] The resource name of the Google Cloud Platform project. Written as ``projects/`` plus the `Google Cloud Platform project ID <https://support.google.com/cloud/answer/6158840>`_. Example: ``projects/my-project-123``. event (:class:`google.devtools.clouderrorreporting.v1beta1.report_errors_service_pb2.ReportedErrorEvent`): [Required] The error event to be reported. options (:class:`google.gax.CallOptions`): Overrides the default settings for this call, e.g, timeout, retries etc. Raises: :exc:`google.gax.errors.GaxError` if the RPC is aborted. :exc:`ValueError` if the parameters are invalid. """ request = report_errors_service_pb2.ReportErrorEventRequest( project_name=project_name, event=event) self._report_error_event(request, options)
class InstanceAdminClient(object): """ Cloud Spanner Instance Admin API The Cloud Spanner Instance Admin API can be used to create, delete, modify and list instances. Instances are dedicated Cloud Spanner serving and storage resources to be used by Cloud Spanner databases. Each instance has a \"configuration\", which dictates where the serving resources for the Cloud Spanner instance are located (e.g., US-central, Europe). Configurations are created by Google based on resource availability. Cloud Spanner billing is based on the instances that exist and their sizes. After an instance exists, there are no additional per-database or per-operation charges for use of the instance (though there may be additional network bandwidth charges). Instances offer isolation: problems with databases in one instance will not affect other instances. However, within an instance databases can affect each other. For example, if one database in an instance receives a lot of requests and consumes most of the instance resources, fewer resources are available for other databases in that instance, and their performance may suffer. """ SERVICE_ADDRESS = 'spanner.googleapis.com' """The default address of the service.""" DEFAULT_SERVICE_PORT = 443 """The default port of the service.""" _PAGE_DESCRIPTORS = { 'list_instance_configs': _PageDesc('page_token', 'next_page_token', 'instance_configs'), 'list_instances': _PageDesc('page_token', 'next_page_token', 'instances') } # The scopes needed to make gRPC calls to all of the methods defined in # this service _ALL_SCOPES = ( 'https://www.googleapis.com/auth/cloud-platform', 'https://www.googleapis.com/auth/spanner.admin', ) _PROJECT_PATH_TEMPLATE = path_template.PathTemplate('projects/{project}') _INSTANCE_CONFIG_PATH_TEMPLATE = path_template.PathTemplate( 'projects/{project}/instanceConfigs/{instance_config}') _INSTANCE_PATH_TEMPLATE = path_template.PathTemplate( 'projects/{project}/instances/{instance}') @classmethod def project_path(cls, project): """Returns a fully-qualified project resource name string.""" return cls._PROJECT_PATH_TEMPLATE.render({ 'project': project, }) @classmethod def instance_config_path(cls, project, instance_config): """Returns a fully-qualified instance_config resource name string.""" return cls._INSTANCE_CONFIG_PATH_TEMPLATE.render({ 'project': project, 'instance_config': instance_config, }) @classmethod def instance_path(cls, project, instance): """Returns a fully-qualified instance resource name string.""" return cls._INSTANCE_PATH_TEMPLATE.render({ 'project': project, 'instance': instance, }) @classmethod def match_project_from_project_name(cls, project_name): """Parses the project from a project resource. Args: project_name (str): A fully-qualified path representing a project resource. Returns: A string representing the project. """ return cls._PROJECT_PATH_TEMPLATE.match(project_name).get('project') @classmethod def match_project_from_instance_config_name(cls, instance_config_name): """Parses the project from a instance_config resource. Args: instance_config_name (str): A fully-qualified path representing a instance_config resource. Returns: A string representing the project. """ return cls._INSTANCE_CONFIG_PATH_TEMPLATE.match( instance_config_name).get('project') @classmethod def match_instance_config_from_instance_config_name( cls, instance_config_name): """Parses the instance_config from a instance_config resource. Args: instance_config_name (str): A fully-qualified path representing a instance_config resource. Returns: A string representing the instance_config. """ return cls._INSTANCE_CONFIG_PATH_TEMPLATE.match( instance_config_name).get('instance_config') @classmethod def match_project_from_instance_name(cls, instance_name): """Parses the project from a instance resource. Args: instance_name (str): A fully-qualified path representing a instance resource. Returns: A string representing the project. """ return cls._INSTANCE_PATH_TEMPLATE.match(instance_name).get('project') @classmethod def match_instance_from_instance_name(cls, instance_name): """Parses the instance from a instance resource. Args: instance_name (str): A fully-qualified path representing a instance resource. Returns: A string representing the instance. """ return cls._INSTANCE_PATH_TEMPLATE.match(instance_name).get('instance') def __init__(self, channel=None, credentials=None, ssl_credentials=None, scopes=None, client_config=None, lib_name=None, lib_version='', metrics_headers=()): """Constructor. Args: channel (~grpc.Channel): A ``Channel`` instance through which to make calls. credentials (~google.auth.credentials.Credentials): The authorization credentials to attach to requests. These credentials identify this application to the service. ssl_credentials (~grpc.ChannelCredentials): A ``ChannelCredentials`` instance for use with an SSL-enabled channel. scopes (Sequence[str]): A list of OAuth2 scopes to attach to requests. client_config (dict): A dictionary for call options for each method. See :func:`google.gax.construct_settings` for the structure of this data. Falls back to the default config if not specified or the specified config is missing data points. lib_name (str): The API library software used for calling the service. (Unless you are writing an API client itself, leave this as default.) lib_version (str): The API library software version used for calling the service. (Unless you are writing an API client itself, leave this as default.) metrics_headers (dict): A dictionary of values for tracking client library metrics. Ultimately serializes to a string (e.g. 'foo/1.2.3 bar/3.14.1'). This argument should be considered private. """ # Unless the calling application specifically requested # OAuth scopes, request everything. if scopes is None: scopes = self._ALL_SCOPES # Initialize an empty client config, if none is set. if client_config is None: client_config = {} # Initialize metrics_headers as an ordered dictionary # (cuts down on cardinality of the resulting string slightly). metrics_headers = collections.OrderedDict(metrics_headers) metrics_headers['gl-python'] = platform.python_version() # The library may or may not be set, depending on what is # calling this client. Newer client libraries set the library name # and version. if lib_name: metrics_headers[lib_name] = lib_version # Finally, track the GAPIC package version. metrics_headers['gapic'] = pkg_resources.get_distribution( 'google-cloud-spanner', ).version # Load the configuration defaults. defaults = api_callable.construct_settings( 'google.spanner.admin.instance.v1.InstanceAdmin', instance_admin_client_config.config, client_config, config.STATUS_CODE_NAMES, metrics_headers=metrics_headers, page_descriptors=self._PAGE_DESCRIPTORS, ) self.instance_admin_stub = config.create_stub( spanner_instance_admin_pb2.InstanceAdminStub, channel=channel, service_path=self.SERVICE_ADDRESS, service_port=self.DEFAULT_SERVICE_PORT, credentials=credentials, scopes=scopes, ssl_credentials=ssl_credentials) self.operations_client = operations_client.OperationsClient( service_path=self.SERVICE_ADDRESS, channel=channel, credentials=credentials, ssl_credentials=ssl_credentials, scopes=scopes, client_config=client_config, metrics_headers=metrics_headers, ) self._list_instance_configs = api_callable.create_api_call( self.instance_admin_stub.ListInstanceConfigs, settings=defaults['list_instance_configs']) self._get_instance_config = api_callable.create_api_call( self.instance_admin_stub.GetInstanceConfig, settings=defaults['get_instance_config']) self._list_instances = api_callable.create_api_call( self.instance_admin_stub.ListInstances, settings=defaults['list_instances']) self._get_instance = api_callable.create_api_call( self.instance_admin_stub.GetInstance, settings=defaults['get_instance']) self._create_instance = api_callable.create_api_call( self.instance_admin_stub.CreateInstance, settings=defaults['create_instance']) self._update_instance = api_callable.create_api_call( self.instance_admin_stub.UpdateInstance, settings=defaults['update_instance']) self._delete_instance = api_callable.create_api_call( self.instance_admin_stub.DeleteInstance, settings=defaults['delete_instance']) self._set_iam_policy = api_callable.create_api_call( self.instance_admin_stub.SetIamPolicy, settings=defaults['set_iam_policy']) self._get_iam_policy = api_callable.create_api_call( self.instance_admin_stub.GetIamPolicy, settings=defaults['get_iam_policy']) self._test_iam_permissions = api_callable.create_api_call( self.instance_admin_stub.TestIamPermissions, settings=defaults['test_iam_permissions']) # Service calls def list_instance_configs(self, parent, page_size=None, options=None): """ Lists the supported instance configurations for a given project. Example: >>> from google.cloud import spanner_admin_instance_v1 >>> from google.gax import CallOptions, INITIAL_PAGE >>> >>> client = spanner_admin_instance_v1.InstanceAdminClient() >>> >>> parent = client.project_path('[PROJECT]') >>> >>> >>> # Iterate over all results >>> for element in client.list_instance_configs(parent): ... # process element ... pass >>> >>> # Or iterate over results one page at a time >>> for page in client.list_instance_configs(parent, options=CallOptions(page_token=INITIAL_PAGE)): ... for element in page: ... # process element ... pass Args: parent (str): Required. The name of the project for which a list of supported instance configurations is requested. Values are of the form ``projects/<project>``. page_size (int): The maximum number of resources contained in the underlying API response. If page streaming is performed per- resource, this parameter does not affect the return value. If page streaming is performed per-page, this determines the maximum number of resources in a page. options (~google.gax.CallOptions): Overrides the default settings for this call, e.g, timeout, retries etc. Returns: A :class:`~google.gax.PageIterator` instance. By default, this is an iterable of :class:`~google.cloud.spanner_admin_instance_v1.types.InstanceConfig` instances. This object can also be configured to iterate over the pages of the response through the `options` parameter. Raises: :exc:`google.gax.errors.GaxError` if the RPC is aborted. :exc:`ValueError` if the parameters are invalid. """ request = spanner_instance_admin_pb2.ListInstanceConfigsRequest( parent=parent, page_size=page_size) return self._list_instance_configs(request, options) def get_instance_config(self, name, options=None): """ Gets information about a particular instance configuration. Example: >>> from google.cloud import spanner_admin_instance_v1 >>> >>> client = spanner_admin_instance_v1.InstanceAdminClient() >>> >>> name = client.instance_config_path('[PROJECT]', '[INSTANCE_CONFIG]') >>> >>> response = client.get_instance_config(name) Args: name (str): Required. The name of the requested instance configuration. Values are of the form ``projects/<project>/instanceConfigs/<config>``. options (~google.gax.CallOptions): Overrides the default settings for this call, e.g, timeout, retries etc. Returns: A :class:`~google.cloud.spanner_admin_instance_v1.types.InstanceConfig` instance. Raises: :exc:`google.gax.errors.GaxError` if the RPC is aborted. :exc:`ValueError` if the parameters are invalid. """ request = spanner_instance_admin_pb2.GetInstanceConfigRequest( name=name) return self._get_instance_config(request, options) def list_instances(self, parent, page_size=None, filter_=None, options=None): """ Lists all instances in the given project. Example: >>> from google.cloud import spanner_admin_instance_v1 >>> from google.gax import CallOptions, INITIAL_PAGE >>> >>> client = spanner_admin_instance_v1.InstanceAdminClient() >>> >>> parent = client.project_path('[PROJECT]') >>> >>> >>> # Iterate over all results >>> for element in client.list_instances(parent): ... # process element ... pass >>> >>> # Or iterate over results one page at a time >>> for page in client.list_instances(parent, options=CallOptions(page_token=INITIAL_PAGE)): ... for element in page: ... # process element ... pass Args: parent (str): Required. The name of the project for which a list of instances is requested. Values are of the form ``projects/<project>``. page_size (int): The maximum number of resources contained in the underlying API response. If page streaming is performed per- resource, this parameter does not affect the return value. If page streaming is performed per-page, this determines the maximum number of resources in a page. filter_ (str): 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\". options (~google.gax.CallOptions): Overrides the default settings for this call, e.g, timeout, retries etc. Returns: A :class:`~google.gax.PageIterator` instance. By default, this is an iterable of :class:`~google.cloud.spanner_admin_instance_v1.types.Instance` instances. This object can also be configured to iterate over the pages of the response through the `options` parameter. Raises: :exc:`google.gax.errors.GaxError` if the RPC is aborted. :exc:`ValueError` if the parameters are invalid. """ request = spanner_instance_admin_pb2.ListInstancesRequest( parent=parent, page_size=page_size, filter=filter_) return self._list_instances(request, options) def get_instance(self, name, options=None): """ Gets information about a particular instance. Example: >>> from google.cloud import spanner_admin_instance_v1 >>> >>> client = spanner_admin_instance_v1.InstanceAdminClient() >>> >>> name = client.instance_path('[PROJECT]', '[INSTANCE]') >>> >>> response = client.get_instance(name) Args: name (str): Required. The name of the requested instance. Values are of the form ``projects/<project>/instances/<instance>``. options (~google.gax.CallOptions): Overrides the default settings for this call, e.g, timeout, retries etc. Returns: A :class:`~google.cloud.spanner_admin_instance_v1.types.Instance` instance. Raises: :exc:`google.gax.errors.GaxError` if the RPC is aborted. :exc:`ValueError` if the parameters are invalid. """ request = spanner_instance_admin_pb2.GetInstanceRequest(name=name) return self._get_instance(request, options) def create_instance(self, parent, instance_id, instance, options=None): """ Creates an instance and begins preparing it to begin serving. The returned ``long-running operation`` can be used to track the progress of preparing the new instance. The instance name is assigned by the caller. If the named instance already exists, ``CreateInstance`` returns ``ALREADY_EXISTS``. Immediately upon completion of this request: * The instance is readable via the API, with all requested attributes but no allocated resources. Its state is `CREATING`. Until completion of the returned operation: * Cancelling the operation renders the instance immediately unreadable via the API. * The instance can be deleted. * All other attempts to modify the instance are rejected. Upon completion of the returned operation: * Billing for all successfully-allocated resources begins (some types may have lower than the requested levels). * Databases can be created in the instance. * The instance's allocated resource levels are readable via the API. * The instance's state becomes ``READY``. The returned ``long-running operation`` will have a name of the format ``<instance_name>/operations/<operation_id>`` and can be used to track creation of the instance. The ``metadata`` field type is ``CreateInstanceMetadata``. The ``response`` field type is ``Instance``, if successful. Example: >>> from google.cloud import spanner_admin_instance_v1 >>> >>> client = spanner_admin_instance_v1.InstanceAdminClient() >>> >>> parent = client.project_path('[PROJECT]') >>> instance_id = '' >>> instance = {} >>> >>> response = client.create_instance(parent, instance_id, instance) >>> >>> def callback(operation_future): ... # Handle result. ... result = operation_future.result() >>> >>> response.add_done_callback(callback) >>> >>> # Handle metadata. >>> metadata = response.metadata() Args: parent (str): Required. The name of the project in which to create the instance. Values are of the form ``projects/<project>``. instance_id (str): 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. instance (Union[dict, ~google.cloud.spanner_admin_instance_v1.types.Instance]): Required. The instance to create. The name may be omitted, but if specified must be ``<parent>/instances/<instance_id>``. If a dict is provided, it must be of the same form as the protobuf message :class:`~google.cloud.spanner_admin_instance_v1.types.Instance` options (~google.gax.CallOptions): Overrides the default settings for this call, e.g, timeout, retries etc. Returns: A :class:`~google.cloud.spanner_admin_instance_v1.types._OperationFuture` instance. Raises: :exc:`google.gax.errors.GaxError` if the RPC is aborted. :exc:`ValueError` if the parameters are invalid. """ request = spanner_instance_admin_pb2.CreateInstanceRequest( parent=parent, instance_id=instance_id, instance=instance) return google.gax._OperationFuture( self._create_instance(request, options), self.operations_client, spanner_instance_admin_pb2.Instance, spanner_instance_admin_pb2.CreateInstanceMetadata, options) def update_instance(self, instance, field_mask, options=None): """ Updates an instance, and begins allocating or releasing resources as requested. The returned [long-running operation][google.longrunning.Operation] can be used to track the progress of updating the instance. If the named instance does not exist, returns ``NOT_FOUND``. Immediately upon completion of this request: * For resource types for which a decrease in the instance's allocation has been requested, billing is based on the newly-requested level. Until completion of the returned operation: * Cancelling the operation sets its metadata's [cancel_time][google.spanner.admin.instance.v1.UpdateInstanceMetadata.cancel_time], and begins restoring resources to their pre-request values. The operation is guaranteed to succeed at undoing all resource changes, after which point it terminates with a `CANCELLED` status. * All other attempts to modify the instance are rejected. * Reading the instance via the API continues to give the pre-request resource levels. Upon completion of the returned operation: * Billing begins for all successfully-allocated resources (some types may have lower than the requested levels). * All newly-reserved resources are available for serving the instance's tables. * The instance's new resource levels are readable via the API. The returned ``long-running operation`` will have a name of the format ``<instance_name>/operations/<operation_id>`` and can be used to track the instance modification. The ``metadata`` field type is ``UpdateInstanceMetadata``. The ``response`` field type is ``Instance``, if successful. Authorization requires ``spanner.instances.update`` permission on resource ``name``. Example: >>> from google.cloud import spanner_admin_instance_v1 >>> >>> client = spanner_admin_instance_v1.InstanceAdminClient() >>> >>> instance = {} >>> field_mask = {} >>> >>> response = client.update_instance(instance, field_mask) >>> >>> def callback(operation_future): ... # Handle result. ... result = operation_future.result() >>> >>> response.add_done_callback(callback) >>> >>> # Handle metadata. >>> metadata = response.metadata() Args: instance (Union[dict, ~google.cloud.spanner_admin_instance_v1.types.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. If a dict is provided, it must be of the same form as the protobuf message :class:`~google.cloud.spanner_admin_instance_v1.types.Instance` field_mask (Union[dict, ~google.cloud.spanner_admin_instance_v1.types.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. If a dict is provided, it must be of the same form as the protobuf message :class:`~google.cloud.spanner_admin_instance_v1.types.FieldMask` options (~google.gax.CallOptions): Overrides the default settings for this call, e.g, timeout, retries etc. Returns: A :class:`~google.cloud.spanner_admin_instance_v1.types._OperationFuture` instance. Raises: :exc:`google.gax.errors.GaxError` if the RPC is aborted. :exc:`ValueError` if the parameters are invalid. """ request = spanner_instance_admin_pb2.UpdateInstanceRequest( instance=instance, field_mask=field_mask) return google.gax._OperationFuture( self._update_instance(request, options), self.operations_client, spanner_instance_admin_pb2.Instance, spanner_instance_admin_pb2.UpdateInstanceMetadata, options) def delete_instance(self, name, options=None): """ Deletes an instance. Immediately upon completion of the request: * Billing ceases for all of the instance's reserved resources. Soon afterward: * The instance and *all of its databases* immediately and irrevocably disappear from the API. All data in the databases is permanently deleted. Example: >>> from google.cloud import spanner_admin_instance_v1 >>> >>> client = spanner_admin_instance_v1.InstanceAdminClient() >>> >>> name = client.instance_path('[PROJECT]', '[INSTANCE]') >>> >>> client.delete_instance(name) Args: name (str): Required. The name of the instance to be deleted. Values are of the form ``projects/<project>/instances/<instance>`` options (~google.gax.CallOptions): Overrides the default settings for this call, e.g, timeout, retries etc. Raises: :exc:`google.gax.errors.GaxError` if the RPC is aborted. :exc:`ValueError` if the parameters are invalid. """ request = spanner_instance_admin_pb2.DeleteInstanceRequest(name=name) self._delete_instance(request, options) def set_iam_policy(self, resource, policy, options=None): """ Sets the access control policy on an instance resource. Replaces any existing policy. Authorization requires ``spanner.instances.setIamPolicy`` on ``resource``. Example: >>> from google.cloud import spanner_admin_instance_v1 >>> >>> client = spanner_admin_instance_v1.InstanceAdminClient() >>> >>> resource = client.instance_path('[PROJECT]', '[INSTANCE]') >>> policy = {} >>> >>> response = client.set_iam_policy(resource, policy) Args: resource (str): REQUIRED: The resource for which the policy is being specified. ``resource`` is usually specified as a path. For example, a Project resource is specified as ``projects/{project}``. policy (Union[dict, ~google.cloud.spanner_admin_instance_v1.types.Policy]): REQUIRED: The complete policy to be applied to the ``resource``. The size of the policy is limited to a few 10s of KB. An empty policy is a valid policy but certain Cloud Platform services (such as Projects) might reject them. If a dict is provided, it must be of the same form as the protobuf message :class:`~google.cloud.spanner_admin_instance_v1.types.Policy` options (~google.gax.CallOptions): Overrides the default settings for this call, e.g, timeout, retries etc. Returns: A :class:`~google.cloud.spanner_admin_instance_v1.types.Policy` instance. Raises: :exc:`google.gax.errors.GaxError` if the RPC is aborted. :exc:`ValueError` if the parameters are invalid. """ request = iam_policy_pb2.SetIamPolicyRequest(resource=resource, policy=policy) return self._set_iam_policy(request, options) def get_iam_policy(self, resource, options=None): """ Gets the access control policy for an instance resource. Returns an empty policy if an instance exists but does not have a policy set. Authorization requires ``spanner.instances.getIamPolicy`` on ``resource``. Example: >>> from google.cloud import spanner_admin_instance_v1 >>> >>> client = spanner_admin_instance_v1.InstanceAdminClient() >>> >>> resource = client.instance_path('[PROJECT]', '[INSTANCE]') >>> >>> response = client.get_iam_policy(resource) Args: resource (str): REQUIRED: The resource for which the policy is being requested. ``resource`` is usually specified as a path. For example, a Project resource is specified as ``projects/{project}``. options (~google.gax.CallOptions): Overrides the default settings for this call, e.g, timeout, retries etc. Returns: A :class:`~google.cloud.spanner_admin_instance_v1.types.Policy` instance. Raises: :exc:`google.gax.errors.GaxError` if the RPC is aborted. :exc:`ValueError` if the parameters are invalid. """ request = iam_policy_pb2.GetIamPolicyRequest(resource=resource) return self._get_iam_policy(request, options) def test_iam_permissions(self, resource, permissions, options=None): """ Returns permissions that the caller has on the specified instance resource. Attempting this RPC on a non-existent Cloud Spanner instance resource will result in a NOT_FOUND error if the user has ``spanner.instances.list`` permission on the containing Google Cloud Project. Otherwise returns an empty set of permissions. Example: >>> from google.cloud import spanner_admin_instance_v1 >>> >>> client = spanner_admin_instance_v1.InstanceAdminClient() >>> >>> resource = client.instance_path('[PROJECT]', '[INSTANCE]') >>> permissions = [] >>> >>> response = client.test_iam_permissions(resource, permissions) Args: resource (str): REQUIRED: The resource for which the policy detail is being requested. ``resource`` is usually specified as a path. For example, a Project resource is specified as ``projects/{project}``. permissions (list[str]): The set of permissions to check for the ``resource``. Permissions with wildcards (such as '*' or 'storage.*') are not allowed. For more information see `IAM Overview <https://cloud.google.com/iam/docs/overview#permissions>`_. options (~google.gax.CallOptions): Overrides the default settings for this call, e.g, timeout, retries etc. Returns: A :class:`~google.cloud.spanner_admin_instance_v1.types.TestIamPermissionsResponse` instance. Raises: :exc:`google.gax.errors.GaxError` if the RPC is aborted. :exc:`ValueError` if the parameters are invalid. """ request = iam_policy_pb2.TestIamPermissionsRequest( resource=resource, permissions=permissions) return self._test_iam_permissions(request, options)
class LoggingServiceV2Api(object): """Service for ingesting and querying logs.""" SERVICE_ADDRESS = 'logging.googleapis.com' """The default address of the service.""" DEFAULT_SERVICE_PORT = 443 """The default port of the service.""" _CODE_GEN_NAME_VERSION = 'gapic/0.1.0' _GAX_VERSION = pkg_resources.get_distribution('google-gax').version _PAGE_DESCRIPTORS = { 'list_log_entries': _PageDesc('page_token', 'next_page_token', 'entries'), 'list_monitored_resource_descriptors': _PageDesc('page_token', 'next_page_token', 'resource_descriptors') } # The scopes needed to make gRPC calls to all of the methods defined in # this service _ALL_SCOPES = ( 'https://www.googleapis.com/auth/cloud-platform', 'https://www.googleapis.com/auth/cloud-platform.read-only', 'https://www.googleapis.com/auth/logging.admin', 'https://www.googleapis.com/auth/logging.read', 'https://www.googleapis.com/auth/logging.write', ) _PARENT_PATH_TEMPLATE = path_template.PathTemplate('projects/{project}') _LOG_PATH_TEMPLATE = path_template.PathTemplate( 'projects/{project}/logs/{log}') @classmethod def parent_path(cls, project): """Returns a fully-qualified parent resource name string.""" return cls._PARENT_PATH_TEMPLATE.render({ 'project': project, }) @classmethod def log_path(cls, project, log): """Returns a fully-qualified log resource name string.""" return cls._LOG_PATH_TEMPLATE.render({ 'project': project, 'log': log, }) @classmethod def match_project_from_parent_name(cls, parent_name): """Parses the project from a parent resource. Args: parent_name (string): A fully-qualified path representing a parent resource. Returns: A string representing the project. """ return cls._PARENT_PATH_TEMPLATE.match(parent_name).get('project') @classmethod def match_project_from_log_name(cls, log_name): """Parses the project from a log resource. Args: log_name (string): A fully-qualified path representing a log resource. Returns: A string representing the project. """ return cls._LOG_PATH_TEMPLATE.match(log_name).get('project') @classmethod def match_log_from_log_name(cls, log_name): """Parses the log from a log resource. Args: log_name (string): A fully-qualified path representing a log resource. Returns: A string representing the log. """ return cls._LOG_PATH_TEMPLATE.match(log_name).get('log') def __init__(self, service_path=SERVICE_ADDRESS, port=DEFAULT_SERVICE_PORT, channel=None, metadata_transformer=None, ssl_creds=None, scopes=None, client_config=None, app_name='gax', app_version=_GAX_VERSION): """Constructor. Args: service_path (string): The domain name of the API remote host. port (int): The port on which to connect to the remote host. channel (:class:`grpc.Channel`): A ``Channel`` instance through which to make calls. ssl_creds (:class:`grpc.ChannelCredentials`): A ``ChannelCredentials`` instance for use with an SSL-enabled channel. client_config (dict): A dictionary for call options for each method. See :func:`google.gax.construct_settings` for the structure of this data. Falls back to the default config if not specified or the specified config is missing data points. metadata_transformer (Callable[[], list]): A function that creates the metadata for requests. app_name (string): The codename of the calling service. app_version (string): The version of the calling service. Returns: A LoggingServiceV2Api object. """ if scopes is None: scopes = self._ALL_SCOPES if client_config is None: client_config = {} goog_api_client = '{}/{} {} gax/{} python/{}'.format( app_name, app_version, self._CODE_GEN_NAME_VERSION, self._GAX_VERSION, platform.python_version()) metadata = [('x-goog-api-client', goog_api_client)] default_client_config = json.loads( pkg_resources.resource_string( __name__, 'logging_service_v2_client_config.json').decode()) defaults = api_callable.construct_settings( 'google.logging.v2.LoggingServiceV2', default_client_config, client_config, config.STATUS_CODE_NAMES, kwargs={'metadata': metadata}, page_descriptors=self._PAGE_DESCRIPTORS) self.logging_service_v2_stub = config.create_stub( logging_pb2.LoggingServiceV2Stub, service_path, port, ssl_creds=ssl_creds, channel=channel, metadata_transformer=metadata_transformer, scopes=scopes) self._delete_log = api_callable.create_api_call( self.logging_service_v2_stub.DeleteLog, settings=defaults['delete_log']) self._write_log_entries = api_callable.create_api_call( self.logging_service_v2_stub.WriteLogEntries, settings=defaults['write_log_entries']) self._list_log_entries = api_callable.create_api_call( self.logging_service_v2_stub.ListLogEntries, settings=defaults['list_log_entries']) self._list_monitored_resource_descriptors = api_callable.create_api_call( self.logging_service_v2_stub.ListMonitoredResourceDescriptors, settings=defaults['list_monitored_resource_descriptors']) # Service calls def delete_log(self, log_name, options=None): """ Deletes a log and all its log entries. The log will reappear if it receives new entries. Example: >>> from google.cloud.gapic.logging.v2 import logging_service_v2_api >>> api = logging_service_v2_api.LoggingServiceV2Api() >>> log_name = api.log_path('[PROJECT]', '[LOG]') >>> api.delete_log(log_name) Args: log_name (string): Required. The resource name of the log to delete. Example: ``\"projects/my-project/logs/syslog\"``. options (:class:`google.gax.CallOptions`): Overrides the default settings for this call, e.g, timeout, retries etc. Raises: :exc:`google.gax.errors.GaxError` if the RPC is aborted. :exc:`ValueError` if the parameters are invalid. """ request = logging_pb2.DeleteLogRequest(log_name=log_name) self._delete_log(request, options) def write_log_entries(self, entries, log_name='', resource=None, labels=None, partial_success=False, options=None): """ Writes log entries to Stackdriver Logging. All log entries are written by this method. Example: >>> from google.cloud.gapic.logging.v2 import logging_service_v2_api >>> from google.logging.v2 import log_entry_pb2 >>> api = logging_service_v2_api.LoggingServiceV2Api() >>> entries = [] >>> response = api.write_log_entries(entries) Args: log_name (string): Optional. A default log resource name that is assigned to all log entries in ``entries`` that do not specify a value for ``log_name``. Example: ``\"projects/my-project/logs/syslog\"``. See ``LogEntry``. resource (:class:`google.api.monitored_resource_pb2.MonitoredResource`): 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 ``LogEntry``. labels (dict[string -> :class:`google.logging.v2.logging_pb2.WriteLogEntriesRequest.LabelsEntry`]): 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 ``LogEntry``. entries (list[:class:`google.logging.v2.log_entry_pb2.LogEntry`]): Required. The log entries to write. Values supplied for the fields ``log_name``, ``resource``, and ``labels`` in this ``entries.write`` request are added to those log entries that do not provide their own values for the fields. 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. partial_success (bool): 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, the response status will be the error associated with one of the failed entries and include error details in the form of WriteLogEntriesPartialErrors. options (:class:`google.gax.CallOptions`): Overrides the default settings for this call, e.g, timeout, retries etc. Raises: :exc:`google.gax.errors.GaxError` if the RPC is aborted. :exc:`ValueError` if the parameters are invalid. """ if resource is None: resource = monitored_resource_pb2.MonitoredResource() if labels is None: labels = [] request = logging_pb2.WriteLogEntriesRequest( entries=entries, log_name=log_name, resource=resource, labels=labels, partial_success=partial_success) self._write_log_entries(request, options) def list_log_entries(self, project_ids, resource_names=None, filter_='', order_by='', page_size=0, options=None): """ Lists log entries. Use this method to retrieve log entries from Cloud Logging. For ways to export log entries, see `Exporting Logs <https://cloud.google.com/logging/docs/export>`_. Example: >>> from google.cloud.gapic.logging.v2 import logging_service_v2_api >>> from google.gax import CallOptions, INITIAL_PAGE >>> api = logging_service_v2_api.LoggingServiceV2Api() >>> project_ids = [] >>> >>> # Iterate over all results >>> for element in api.list_log_entries(project_ids): >>> # process element >>> pass >>> >>> # Or iterate over results one page at a time >>> for page in api.list_log_entries(project_ids, options=CallOptions(page_token=INITIAL_PAGE)): >>> for element in page: >>> # process element >>> pass Args: project_ids (list[string]): Deprecated. One or more project identifiers or project numbers from which to retrieve log entries. Examples: ``\"my-project-1A\"``, ``\"1234567890\"``. If present, these project identifiers are converted to resource format and added to the list of resources in ``resourceNames``. Callers should use ``resourceNames`` rather than this parameter. resource_names (list[string]): Optional. One or more cloud resources from which to retrieve log entries. Example: ``\"projects/my-project-1A\"``, ``\"projects/1234567890\"``. Projects listed in ``projectIds`` are added to this list. filter_ (string): 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. order_by (string): 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 ``LogEntry.insertId``. page_size (int): The maximum number of resources contained in the underlying API response. If page streaming is performed per- resource, this parameter does not affect the return value. If page streaming is performed per-page, this determines the maximum number of resources in a page. options (:class:`google.gax.CallOptions`): Overrides the default settings for this call, e.g, timeout, retries etc. Returns: A :class:`google.gax.PageIterator` instance. By default, this is an iterable of :class:`google.logging.v2.log_entry_pb2.LogEntry` instances. This object can also be configured to iterate over the pages of the response through the `CallOptions` parameter. Raises: :exc:`google.gax.errors.GaxError` if the RPC is aborted. :exc:`ValueError` if the parameters are invalid. """ if resource_names is None: resource_names = [] request = logging_pb2.ListLogEntriesRequest( project_ids=project_ids, resource_names=resource_names, filter=filter_, order_by=order_by, page_size=page_size) return self._list_log_entries(request, options) def list_monitored_resource_descriptors(self, page_size=0, options=None): """ Lists the monitored resource descriptors used by Stackdriver Logging. Example: >>> from google.cloud.gapic.logging.v2 import logging_service_v2_api >>> from google.gax import CallOptions, INITIAL_PAGE >>> api = logging_service_v2_api.LoggingServiceV2Api() >>> >>> # Iterate over all results >>> for element in api.list_monitored_resource_descriptors(): >>> # process element >>> pass >>> >>> # Or iterate over results one page at a time >>> for page in api.list_monitored_resource_descriptors(options=CallOptions(page_token=INITIAL_PAGE)): >>> for element in page: >>> # process element >>> pass Args: page_size (int): The maximum number of resources contained in the underlying API response. If page streaming is performed per- resource, this parameter does not affect the return value. If page streaming is performed per-page, this determines the maximum number of resources in a page. options (:class:`google.gax.CallOptions`): Overrides the default settings for this call, e.g, timeout, retries etc. Returns: A :class:`google.gax.PageIterator` instance. By default, this is an iterable of :class:`google.api.monitored_resource_pb2.MonitoredResourceDescriptor` instances. This object can also be configured to iterate over the pages of the response through the `CallOptions` parameter. Raises: :exc:`google.gax.errors.GaxError` if the RPC is aborted. :exc:`ValueError` if the parameters are invalid. """ request = logging_pb2.ListMonitoredResourceDescriptorsRequest( page_size=page_size) return self._list_monitored_resource_descriptors(request, options)
class DlpServiceClient(object): """ The DLP API is a service that allows clients to detect the presence of Personally Identifiable Information (PII) and other privacy-sensitive data in user-supplied, unstructured data streams, like text blocks or images. The service also includes methods for sensitive data redaction and scheduling of data scans on Google Cloud Platform based data sets. """ SERVICE_ADDRESS = 'dlp.googleapis.com' """The default address of the service.""" DEFAULT_SERVICE_PORT = 443 """The default port of the service.""" # The scopes needed to make gRPC calls to all of the methods defined in # this service _ALL_SCOPES = ('https://www.googleapis.com/auth/cloud-platform', ) _RESULT_PATH_TEMPLATE = path_template.PathTemplate( 'inspect/results/{result}') @classmethod def result_path(cls, result): """Returns a fully-qualified result resource name string.""" return cls._RESULT_PATH_TEMPLATE.render({ 'result': result, }) @classmethod def match_result_from_result_name(cls, result_name): """Parses the result from a result resource. Args: result_name (string): A fully-qualified path representing a result resource. Returns: A string representing the result. """ return cls._RESULT_PATH_TEMPLATE.match(result_name).get('result') def __init__(self, service_path=SERVICE_ADDRESS, port=DEFAULT_SERVICE_PORT, channel=None, credentials=None, ssl_credentials=None, scopes=None, client_config=None, app_name=None, app_version='', lib_name=None, lib_version='', metrics_headers=()): """Constructor. Args: service_path (string): The domain name of the API remote host. port (int): The port on which to connect to the remote host. channel (:class:`grpc.Channel`): A ``Channel`` instance through which to make calls. credentials (object): The authorization credentials to attach to requests. These credentials identify this application to the service. ssl_credentials (:class:`grpc.ChannelCredentials`): A ``ChannelCredentials`` instance for use with an SSL-enabled channel. scopes (list[string]): A list of OAuth2 scopes to attach to requests. client_config (dict): A dictionary for call options for each method. See :func:`google.gax.construct_settings` for the structure of this data. Falls back to the default config if not specified or the specified config is missing data points. app_name (string): The name of the application calling the service. Recommended for analytics purposes. app_version (string): The version of the application calling the service. Recommended for analytics purposes. lib_name (string): The API library software used for calling the service. (Unless you are writing an API client itself, leave this as default.) lib_version (string): The API library software version used for calling the service. (Unless you are writing an API client itself, leave this as default.) metrics_headers (dict): A dictionary of values for tracking client library metrics. Ultimately serializes to a string (e.g. 'foo/1.2.3 bar/3.14.1'). This argument should be considered private. Returns: A DlpServiceClient object. """ # Unless the calling application specifically requested # OAuth scopes, request everything. if scopes is None: scopes = self._ALL_SCOPES # Initialize an empty client config, if none is set. if client_config is None: client_config = {} # Initialize metrics_headers as an ordered dictionary # (cuts down on cardinality of the resulting string slightly). metrics_headers = collections.OrderedDict(metrics_headers) metrics_headers['gl-python'] = platform.python_version() # The library may or may not be set, depending on what is # calling this client. Newer client libraries set the library name # and version. if lib_name: metrics_headers[lib_name] = lib_version # Finally, track the GAPIC package version. metrics_headers['gapic'] = pkg_resources.get_distribution( 'gapic-google-cloud-dlp-v2beta1', ).version # Load the configuration defaults. default_client_config = json.loads( pkg_resources.resource_string( __name__, 'dlp_service_client_config.json').decode()) defaults = api_callable.construct_settings( 'google.privacy.dlp.v2beta1.DlpService', default_client_config, client_config, config.STATUS_CODE_NAMES, metrics_headers=metrics_headers, ) self.dlp_service_stub = config.create_stub( dlp_pb2.DlpServiceStub, channel=channel, service_path=service_path, service_port=port, credentials=credentials, scopes=scopes, ssl_credentials=ssl_credentials) self._inspect_content = api_callable.create_api_call( self.dlp_service_stub.InspectContent, settings=defaults['inspect_content']) self._redact_content = api_callable.create_api_call( self.dlp_service_stub.RedactContent, settings=defaults['redact_content']) self._create_inspect_operation = api_callable.create_api_call( self.dlp_service_stub.CreateInspectOperation, settings=defaults['create_inspect_operation']) self._list_inspect_findings = api_callable.create_api_call( self.dlp_service_stub.ListInspectFindings, settings=defaults['list_inspect_findings']) self._list_info_types = api_callable.create_api_call( self.dlp_service_stub.ListInfoTypes, settings=defaults['list_info_types']) self._list_root_categories = api_callable.create_api_call( self.dlp_service_stub.ListRootCategories, settings=defaults['list_root_categories']) # Service calls def inspect_content(self, inspect_config, items, options=None): """ Find potentially sensitive info in a list of strings. This method has limits on input size, processing time, and output size. Example: >>> from google.cloud.gapic.privacy.dlp.v2beta1 import dlp_service_client >>> from google.cloud.proto.privacy.dlp.v2beta1 import dlp_pb2 >>> client = dlp_service_client.DlpServiceClient() >>> inspect_config = dlp_pb2.InspectConfig() >>> items = [] >>> response = client.inspect_content(inspect_config, items) Args: inspect_config (:class:`google.cloud.proto.privacy.dlp.v2beta1.dlp_pb2.InspectConfig`): Configuration for the inspector. items (list[:class:`google.cloud.proto.privacy.dlp.v2beta1.dlp_pb2.ContentItem`]): The list of items to inspect. Items in a single request are considered \"related\" unless inspect_config.independent_inputs is true. Up to 100 are allowed per request. options (:class:`google.gax.CallOptions`): Overrides the default settings for this call, e.g, timeout, retries etc. Returns: A :class:`google.cloud.proto.privacy.dlp.v2beta1.dlp_pb2.InspectContentResponse` instance. Raises: :exc:`google.gax.errors.GaxError` if the RPC is aborted. :exc:`ValueError` if the parameters are invalid. """ # Create the request object. request = dlp_pb2.InspectContentRequest(inspect_config=inspect_config, items=items) return self._inspect_content(request, options) def redact_content(self, inspect_config, items, replace_configs, options=None): """ Redact potentially sensitive info from a list of strings. This method has limits on input size, processing time, and output size. Example: >>> from google.cloud.gapic.privacy.dlp.v2beta1 import dlp_service_client >>> from google.cloud.proto.privacy.dlp.v2beta1 import dlp_pb2 >>> client = dlp_service_client.DlpServiceClient() >>> inspect_config = dlp_pb2.InspectConfig() >>> items = [] >>> replace_configs = [] >>> response = client.redact_content(inspect_config, items, replace_configs) Args: inspect_config (:class:`google.cloud.proto.privacy.dlp.v2beta1.dlp_pb2.InspectConfig`): Configuration for the inspector. items (list[:class:`google.cloud.proto.privacy.dlp.v2beta1.dlp_pb2.ContentItem`]): The list of items to inspect. Up to 100 are allowed per request. replace_configs (list[:class:`google.cloud.proto.privacy.dlp.v2beta1.dlp_pb2.RedactContentRequest.ReplaceConfig`]): The strings to replace findings with. Must specify at least one. options (:class:`google.gax.CallOptions`): Overrides the default settings for this call, e.g, timeout, retries etc. Returns: A :class:`google.cloud.proto.privacy.dlp.v2beta1.dlp_pb2.RedactContentResponse` instance. Raises: :exc:`google.gax.errors.GaxError` if the RPC is aborted. :exc:`ValueError` if the parameters are invalid. """ # Create the request object. request = dlp_pb2.RedactContentRequest(inspect_config=inspect_config, items=items, replace_configs=replace_configs) return self._redact_content(request, options) def create_inspect_operation(self, inspect_config, storage_config, output_config, options=None): """ Schedule a job scanning content in a Google Cloud Platform data repository. Example: >>> from google.cloud.gapic.privacy.dlp.v2beta1 import dlp_service_client >>> from google.cloud.proto.privacy.dlp.v2beta1 import dlp_pb2 >>> from google.cloud.proto.privacy.dlp.v2beta1 import storage_pb2 >>> client = dlp_service_client.DlpServiceClient() >>> inspect_config = dlp_pb2.InspectConfig() >>> storage_config = storage_pb2.StorageConfig() >>> output_config = dlp_pb2.OutputStorageConfig() >>> response = client.create_inspect_operation(inspect_config, storage_config, output_config) Args: inspect_config (:class:`google.cloud.proto.privacy.dlp.v2beta1.dlp_pb2.InspectConfig`): Configuration for the inspector. storage_config (:class:`google.cloud.proto.privacy.dlp.v2beta1.storage_pb2.StorageConfig`): Specification of the data set to process. output_config (:class:`google.cloud.proto.privacy.dlp.v2beta1.dlp_pb2.OutputStorageConfig`): Optional location to store findings. The bucket must already exist and the Google APIs service account for DLP must have write permission to write to the given bucket. Results will be split over multiple csv files with each file name matching the pattern \"[operation_id] + [count].csv\". The operation_id will match the identifier for the Operation, and the [count] is a counter used for tracking the number of files written. The CSV file(s) contain the following columns regardless of storage type scanned: id, info_type, likelihood, byte size of finding, quote, time_stamp For cloud storage the next two columns are: file_path, start_offset For datastore the next two columns are: project_id, namespace_id, path, :: column_name, offset. options (:class:`google.gax.CallOptions`): Overrides the default settings for this call, e.g, timeout, retries etc. Returns: A :class:`google.longrunning.operations_pb2.Operation` instance. Raises: :exc:`google.gax.errors.GaxError` if the RPC is aborted. :exc:`ValueError` if the parameters are invalid. """ # Create the request object. request = dlp_pb2.CreateInspectOperationRequest( inspect_config=inspect_config, storage_config=storage_config, output_config=output_config) return self._create_inspect_operation(request, options) def list_inspect_findings(self, name, page_size=None, page_token=None, options=None): """ Returns list of results for given inspect operation result set id. Example: >>> from google.cloud.gapic.privacy.dlp.v2beta1 import dlp_service_client >>> client = dlp_service_client.DlpServiceClient() >>> name = client.result_path('[RESULT]') >>> response = client.list_inspect_findings(name) Args: name (string): Identifier of the results set returned as metadata of the longrunning operation created by a call to CreateInspectOperation. Should be in the format of ``inspect/results/{id}. page_size (int): Maximum number of results to return. If 0, the implementation will select a reasonable value. page_token (string): The value returned by the last ``ListInspectFindingsResponse``; indicates that this is a continuation of a prior ``ListInspectFindings`` call, and that the system should return the next page of data. options (:class:`google.gax.CallOptions`): Overrides the default settings for this call, e.g, timeout, retries etc. Returns: A :class:`google.cloud.proto.privacy.dlp.v2beta1.dlp_pb2.ListInspectFindingsResponse` instance. Raises: :exc:`google.gax.errors.GaxError` if the RPC is aborted. :exc:`ValueError` if the parameters are invalid. """ # Create the request object. request = dlp_pb2.ListInspectFindingsRequest(name=name, page_size=page_size, page_token=page_token) return self._list_inspect_findings(request, options) def list_info_types(self, category, language_code, options=None): """ Returns sensitive information types for given category. Example: >>> from google.cloud.gapic.privacy.dlp.v2beta1 import dlp_service_client >>> client = dlp_service_client.DlpServiceClient() >>> category = '' >>> language_code = '' >>> response = client.list_info_types(category, language_code) Args: category (string): Category name as returned by ListRootCategories. language_code (string): Optional BCP-47 language code for localized info type friendly names. If omitted, or if localized strings are not available, en-US strings will be returned. options (:class:`google.gax.CallOptions`): Overrides the default settings for this call, e.g, timeout, retries etc. Returns: A :class:`google.cloud.proto.privacy.dlp.v2beta1.dlp_pb2.ListInfoTypesResponse` instance. Raises: :exc:`google.gax.errors.GaxError` if the RPC is aborted. :exc:`ValueError` if the parameters are invalid. """ # Create the request object. request = dlp_pb2.ListInfoTypesRequest(category=category, language_code=language_code) return self._list_info_types(request, options) def list_root_categories(self, language_code, options=None): """ Returns the list of root categories of sensitive information. Example: >>> from google.cloud.gapic.privacy.dlp.v2beta1 import dlp_service_client >>> client = dlp_service_client.DlpServiceClient() >>> language_code = '' >>> response = client.list_root_categories(language_code) Args: language_code (string): Optional language code for localized friendly category names. If omitted or if localized strings are not available, en-US strings will be returned. options (:class:`google.gax.CallOptions`): Overrides the default settings for this call, e.g, timeout, retries etc. Returns: A :class:`google.cloud.proto.privacy.dlp.v2beta1.dlp_pb2.ListRootCategoriesResponse` instance. Raises: :exc:`google.gax.errors.GaxError` if the RPC is aborted. :exc:`ValueError` if the parameters are invalid. """ # Create the request object. request = dlp_pb2.ListRootCategoriesRequest( language_code=language_code) return self._list_root_categories(request, options)
class BigtableApi(object): """Service for reading from and writing to existing Bigtable tables.""" SERVICE_ADDRESS = 'bigtable.googleapis.com' """The default address of the service.""" DEFAULT_SERVICE_PORT = 443 """The default port of the service.""" _CODE_GEN_NAME_VERSION = 'gapic/0.1.0' _GAX_VERSION = pkg_resources.get_distribution('google-gax').version # The scopes needed to make gRPC calls to all of the methods defined in # this service _ALL_SCOPES = ( 'https://www.googleapis.com/auth/bigtable.data', 'https://www.googleapis.com/auth/bigtable.data.readonly', 'https://www.googleapis.com/auth/cloud-bigtable.data', 'https://www.googleapis.com/auth/cloud-bigtable.data.readonly', 'https://www.googleapis.com/auth/cloud-platform', 'https://www.googleapis.com/auth/cloud-platform.read-only', ) _TABLE_PATH_TEMPLATE = path_template.PathTemplate( 'projects/{project}/instances/{instance}/tables/{table}') @classmethod def table_path(cls, project, instance, table): """Returns a fully-qualified table resource name string.""" return cls._TABLE_PATH_TEMPLATE.render({ 'project': project, 'instance': instance, 'table': table, }) @classmethod def match_project_from_table_name(cls, table_name): """Parses the project from a table resource. Args: table_name (string): A fully-qualified path representing a table resource. Returns: A string representing the project. """ return cls._TABLE_PATH_TEMPLATE.match(table_name).get('project') @classmethod def match_instance_from_table_name(cls, table_name): """Parses the instance from a table resource. Args: table_name (string): A fully-qualified path representing a table resource. Returns: A string representing the instance. """ return cls._TABLE_PATH_TEMPLATE.match(table_name).get('instance') @classmethod def match_table_from_table_name(cls, table_name): """Parses the table from a table resource. Args: table_name (string): A fully-qualified path representing a table resource. Returns: A string representing the table. """ return cls._TABLE_PATH_TEMPLATE.match(table_name).get('table') def __init__(self, service_path=SERVICE_ADDRESS, port=DEFAULT_SERVICE_PORT, channel=None, metadata_transformer=None, ssl_creds=None, scopes=None, client_config=None, app_name='gax', app_version=_GAX_VERSION): """Constructor. Args: service_path (string): The domain name of the API remote host. port (int): The port on which to connect to the remote host. channel (:class:`grpc.Channel`): A ``Channel`` instance through which to make calls. ssl_creds (:class:`grpc.ChannelCredentials`): A ``ChannelCredentials`` instance for use with an SSL-enabled channel. client_config (dict): A dictionary for call options for each method. See :func:`google.gax.construct_settings` for the structure of this data. Falls back to the default config if not specified or the specified config is missing data points. metadata_transformer (Callable[[], list]): A function that creates the metadata for requests. app_name (string): The codename of the calling service. app_version (string): The version of the calling service. Returns: A BigtableApi object. """ if scopes is None: scopes = self._ALL_SCOPES if client_config is None: client_config = {} goog_api_client = '{}/{} {} gax/{} python/{}'.format( app_name, app_version, self._CODE_GEN_NAME_VERSION, self._GAX_VERSION, platform.python_version()) metadata = [('x-goog-api-client', goog_api_client)] default_client_config = json.loads( pkg_resources.resource_string( __name__, 'bigtable_client_config.json').decode()) defaults = api_callable.construct_settings( 'google.bigtable.v2.Bigtable', default_client_config, client_config, config.STATUS_CODE_NAMES, kwargs={'metadata': metadata}) self.bigtable_stub = config.create_stub( bigtable_pb2.BigtableStub, service_path, port, ssl_creds=ssl_creds, channel=channel, metadata_transformer=metadata_transformer, scopes=scopes) self._read_rows = api_callable.create_api_call( self.bigtable_stub.ReadRows, settings=defaults['read_rows']) self._sample_row_keys = api_callable.create_api_call( self.bigtable_stub.SampleRowKeys, settings=defaults['sample_row_keys']) self._mutate_row = api_callable.create_api_call( self.bigtable_stub.MutateRow, settings=defaults['mutate_row']) self._mutate_rows = api_callable.create_api_call( self.bigtable_stub.MutateRows, settings=defaults['mutate_rows']) self._check_and_mutate_row = api_callable.create_api_call( self.bigtable_stub.CheckAndMutateRow, settings=defaults['check_and_mutate_row']) self._read_modify_write_row = api_callable.create_api_call( self.bigtable_stub.ReadModifyWriteRow, settings=defaults['read_modify_write_row']) # Service calls def read_rows(self, table_name, rows=None, filter_=None, rows_limit=0, options=None): """ Streams back the contents of all requested rows, optionally applying the same Reader filter to each. Depending on their size, rows and cells may be broken up across multiple responses, but atomicity of each row will still be preserved. See the ReadRowsResponse documentation for details. Example: >>> from google.cloud.gapic.bigtable.v2 import bigtable_api >>> api = bigtable_api.BigtableApi() >>> table_name = api.table_path('[PROJECT]', '[INSTANCE]', '[TABLE]') >>> for element in api.read_rows(table_name): >>> # process element >>> pass Args: table_name (string): The unique name of the table from which to read. Values are of the form ``projects/<project>/instances/<instance>/tables/<table>``. rows (:class:`google.bigtable.v2.data_pb2.RowSet`): The row keys and/or ranges to read. If not specified, reads from all rows. filter_ (:class:`google.bigtable.v2.data_pb2.RowFilter`): The filter to apply to the contents of the specified row(s). If unset, reads the entirety of each row. rows_limit (long): The read will terminate after committing to N rows' worth of results. The default (zero) is to return all results. options (:class:`google.gax.CallOptions`): Overrides the default settings for this call, e.g, timeout, retries etc. Returns: iterator[:class:`google.bigtable.v2.bigtable_pb2.ReadRowsResponse`]. Raises: :exc:`google.gax.errors.GaxError` if the RPC is aborted. :exc:`ValueError` if the parameters are invalid. """ if rows is None: rows = data_pb2.RowSet() if filter_ is None: filter_ = data_pb2.RowFilter() request = bigtable_pb2.ReadRowsRequest(table_name=table_name, rows=rows, filter=filter_, rows_limit=rows_limit) return self._read_rows(request, options) def sample_row_keys(self, table_name, options=None): """ Returns a sample of row keys in the table. The returned row keys will delimit contiguous sections of the table of approximately equal size, which can be used to break up the data for distributed tasks like mapreduces. Example: >>> from google.cloud.gapic.bigtable.v2 import bigtable_api >>> api = bigtable_api.BigtableApi() >>> table_name = api.table_path('[PROJECT]', '[INSTANCE]', '[TABLE]') >>> for element in api.sample_row_keys(table_name): >>> # process element >>> pass Args: table_name (string): The unique name of the table from which to sample row keys. Values are of the form ``projects/<project>/instances/<instance>/tables/<table>``. options (:class:`google.gax.CallOptions`): Overrides the default settings for this call, e.g, timeout, retries etc. Returns: iterator[:class:`google.bigtable.v2.bigtable_pb2.SampleRowKeysResponse`]. Raises: :exc:`google.gax.errors.GaxError` if the RPC is aborted. :exc:`ValueError` if the parameters are invalid. """ request = bigtable_pb2.SampleRowKeysRequest(table_name=table_name) return self._sample_row_keys(request, options) def mutate_row(self, table_name, row_key, mutations, options=None): """ Mutates a row atomically. Cells already present in the row are left unchanged unless explicitly changed by ``mutation``. Example: >>> from google.cloud.gapic.bigtable.v2 import bigtable_api >>> from google.bigtable.v2 import data_pb2 >>> api = bigtable_api.BigtableApi() >>> table_name = api.table_path('[PROJECT]', '[INSTANCE]', '[TABLE]') >>> row_key = '' >>> mutations = [] >>> response = api.mutate_row(table_name, row_key, mutations) Args: table_name (string): The unique name of the table to which the mutation should be applied. Values are of the form ``projects/<project>/instances/<instance>/tables/<table>``. row_key (bytes): The key of the row to which the mutation should be applied. mutations (list[:class:`google.bigtable.v2.data_pb2.Mutation`]): Changes to be atomically applied to the specified row. Entries are applied in order, meaning that earlier mutations can be masked by later ones. Must contain at least one entry and at most 100000. options (:class:`google.gax.CallOptions`): Overrides the default settings for this call, e.g, timeout, retries etc. Raises: :exc:`google.gax.errors.GaxError` if the RPC is aborted. :exc:`ValueError` if the parameters are invalid. """ request = bigtable_pb2.MutateRowRequest(table_name=table_name, row_key=row_key, mutations=mutations) self._mutate_row(request, options) def mutate_rows(self, table_name, entries, options=None): """ Mutates multiple rows in a batch. Each individual row is mutated atomically as in MutateRow, but the entire batch is not executed atomically. Example: >>> from google.cloud.gapic.bigtable.v2 import bigtable_api >>> from google.bigtable.v2 import bigtable_pb2 >>> api = bigtable_api.BigtableApi() >>> table_name = api.table_path('[PROJECT]', '[INSTANCE]', '[TABLE]') >>> entries = [] >>> for element in api.mutate_rows(table_name, entries): >>> # process element >>> pass Args: table_name (string): The unique name of the table to which the mutations should be applied. entries (list[:class:`google.bigtable.v2.bigtable_pb2.MutateRowsRequest.Entry`]): The row keys and corresponding mutations to be applied in bulk. Each entry is applied as an atomic mutation, but the entries may be applied in arbitrary order (even between entries for the same row). At least one entry must be specified, and in total the entries can contain at most 100000 mutations. options (:class:`google.gax.CallOptions`): Overrides the default settings for this call, e.g, timeout, retries etc. Returns: iterator[:class:`google.bigtable.v2.bigtable_pb2.MutateRowsResponse`]. Raises: :exc:`google.gax.errors.GaxError` if the RPC is aborted. :exc:`ValueError` if the parameters are invalid. """ request = bigtable_pb2.MutateRowsRequest(table_name=table_name, entries=entries) return self._mutate_rows(request, options) def check_and_mutate_row(self, table_name, row_key, predicate_filter=None, true_mutations=None, false_mutations=None, options=None): """ Mutates a row atomically based on the output of a predicate Reader filter. Example: >>> from google.cloud.gapic.bigtable.v2 import bigtable_api >>> api = bigtable_api.BigtableApi() >>> table_name = api.table_path('[PROJECT]', '[INSTANCE]', '[TABLE]') >>> row_key = '' >>> response = api.check_and_mutate_row(table_name, row_key) Args: table_name (string): The unique name of the table to which the conditional mutation should be applied. Values are of the form ``projects/<project>/instances/<instance>/tables/<table>``. row_key (bytes): The key of the row to which the conditional mutation should be applied. predicate_filter (:class:`google.bigtable.v2.data_pb2.RowFilter`): The filter to be applied to the contents of the specified row. Depending on whether or not any results are yielded, either ``true_mutations`` or ``false_mutations`` will be executed. If unset, checks that the row contains any values at all. true_mutations (list[:class:`google.bigtable.v2.data_pb2.Mutation`]): Changes to be atomically applied to the specified row if ``predicate_filter`` yields at least one cell when applied to ``row_key``. Entries are applied in order, meaning that earlier mutations can be masked by later ones. Must contain at least one entry if ``false_mutations`` is empty, and at most 100000. false_mutations (list[:class:`google.bigtable.v2.data_pb2.Mutation`]): Changes to be atomically applied to the specified row if ``predicate_filter`` does not yield any cells when applied to ``row_key``. Entries are applied in order, meaning that earlier mutations can be masked by later ones. Must contain at least one entry if ``true_mutations`` is empty, and at most 100000. options (:class:`google.gax.CallOptions`): Overrides the default settings for this call, e.g, timeout, retries etc. Returns: A :class:`google.bigtable.v2.bigtable_pb2.CheckAndMutateRowResponse` instance. Raises: :exc:`google.gax.errors.GaxError` if the RPC is aborted. :exc:`ValueError` if the parameters are invalid. """ if predicate_filter is None: predicate_filter = data_pb2.RowFilter() if true_mutations is None: true_mutations = [] if false_mutations is None: false_mutations = [] request = bigtable_pb2.CheckAndMutateRowRequest( table_name=table_name, row_key=row_key, predicate_filter=predicate_filter, true_mutations=true_mutations, false_mutations=false_mutations) return self._check_and_mutate_row(request, options) def read_modify_write_row(self, table_name, row_key, rules, options=None): """ Modifies a row atomically. The method reads the latest existing timestamp and value from the specified columns and writes a new entry based on pre-defined read/modify/write rules. The new value for the timestamp is the greater of the existing timestamp or the current server time. The method returns the new contents of all modified cells. Example: >>> from google.cloud.gapic.bigtable.v2 import bigtable_api >>> from google.bigtable.v2 import data_pb2 >>> api = bigtable_api.BigtableApi() >>> table_name = api.table_path('[PROJECT]', '[INSTANCE]', '[TABLE]') >>> row_key = '' >>> rules = [] >>> response = api.read_modify_write_row(table_name, row_key, rules) Args: table_name (string): The unique name of the table to which the read/modify/write rules should be applied. Values are of the form ``projects/<project>/instances/<instance>/tables/<table>``. row_key (bytes): The key of the row to which the read/modify/write rules should be applied. rules (list[:class:`google.bigtable.v2.data_pb2.ReadModifyWriteRule`]): Rules specifying how the specified row's contents are to be transformed into writes. Entries are applied in order, meaning that earlier rules will affect the results of later ones. options (:class:`google.gax.CallOptions`): Overrides the default settings for this call, e.g, timeout, retries etc. Returns: A :class:`google.bigtable.v2.bigtable_pb2.ReadModifyWriteRowResponse` instance. Raises: :exc:`google.gax.errors.GaxError` if the RPC is aborted. :exc:`ValueError` if the parameters are invalid. """ request = bigtable_pb2.ReadModifyWriteRowRequest(table_name=table_name, row_key=row_key, rules=rules) return self._read_modify_write_row(request, options)
class IAMApi(object): """ Creates and manages service account objects. Service account is an account that belongs to your project instead of to an individual end user. It is used to authenticate calls to a Google API. To create a service account, specify the ``project_id`` and ``account_id`` for the account. The ``account_id`` is unique within the project, and used to generate the service account email address and a stable ``unique_id``. All other methods can identify accounts using the format ``projects/{project}/serviceAccounts/{account}``. Using ``-`` as a wildcard for the project will infer the project from the account. The ``account`` value can be the ``email`` address or the ``unique_id`` of the service account. """ SERVICE_ADDRESS = 'iam.googleapis.com' """The default address of the service.""" DEFAULT_SERVICE_PORT = 443 """The default port of the service.""" _CODE_GEN_NAME_VERSION = 'gapic/0.1.0' _GAX_VERSION = pkg_resources.get_distribution('google-gax').version _PAGE_DESCRIPTORS = { 'list_service_accounts': _PageDesc('page_token', 'next_page_token', 'accounts') } # The scopes needed to make gRPC calls to all of the methods defined in # this service _ALL_SCOPES = ( 'https://www.googleapis.com/auth/cloud-platform', 'https://www.googleapis.com/auth/iam', ) _PROJECT_PATH_TEMPLATE = path_template.PathTemplate('projects/{project}') _SERVICE_ACCOUNT_PATH_TEMPLATE = path_template.PathTemplate( 'projects/{project}/serviceAccounts/{service_account}') _KEY_PATH_TEMPLATE = path_template.PathTemplate( 'projects/{project}/serviceAccounts/{service_account}/keys/{key}') @classmethod def project_path(cls, project): """Returns a fully-qualified project resource name string.""" return cls._PROJECT_PATH_TEMPLATE.render({ 'project': project, }) @classmethod def service_account_path(cls, project, service_account): """Returns a fully-qualified service_account resource name string.""" return cls._SERVICE_ACCOUNT_PATH_TEMPLATE.render({ 'project': project, 'service_account': service_account, }) @classmethod def key_path(cls, project, service_account, key): """Returns a fully-qualified key resource name string.""" return cls._KEY_PATH_TEMPLATE.render({ 'project': project, 'service_account': service_account, 'key': key, }) @classmethod def match_project_from_project_name(cls, project_name): """Parses the project from a project resource. Args: project_name (string): A fully-qualified path representing a project resource. Returns: A string representing the project. """ return cls._PROJECT_PATH_TEMPLATE.match(project_name).get('project') @classmethod def match_project_from_service_account_name(cls, service_account_name): """Parses the project from a service_account resource. Args: service_account_name (string): A fully-qualified path representing a service_account resource. Returns: A string representing the project. """ return cls._SERVICE_ACCOUNT_PATH_TEMPLATE.match( service_account_name).get('project') @classmethod def match_service_account_from_service_account_name( cls, service_account_name): """Parses the service_account from a service_account resource. Args: service_account_name (string): A fully-qualified path representing a service_account resource. Returns: A string representing the service_account. """ return cls._SERVICE_ACCOUNT_PATH_TEMPLATE.match( service_account_name).get('service_account') @classmethod def match_project_from_key_name(cls, key_name): """Parses the project from a key resource. Args: key_name (string): A fully-qualified path representing a key resource. Returns: A string representing the project. """ return cls._KEY_PATH_TEMPLATE.match(key_name).get('project') @classmethod def match_service_account_from_key_name(cls, key_name): """Parses the service_account from a key resource. Args: key_name (string): A fully-qualified path representing a key resource. Returns: A string representing the service_account. """ return cls._KEY_PATH_TEMPLATE.match(key_name).get('service_account') @classmethod def match_key_from_key_name(cls, key_name): """Parses the key from a key resource. Args: key_name (string): A fully-qualified path representing a key resource. Returns: A string representing the key. """ return cls._KEY_PATH_TEMPLATE.match(key_name).get('key') def __init__(self, service_path=SERVICE_ADDRESS, port=DEFAULT_SERVICE_PORT, channel=None, metadata_transformer=None, ssl_creds=None, scopes=None, client_config=None, app_name='gax', app_version=_GAX_VERSION): """Constructor. Args: service_path (string): The domain name of the API remote host. port (int): The port on which to connect to the remote host. channel (:class:`grpc.Channel`): A ``Channel`` instance through which to make calls. ssl_creds (:class:`grpc.ChannelCredentials`): A ``ChannelCredentials`` instance for use with an SSL-enabled channel. client_config (dict): A dictionary for call options for each method. See :func:`google.gax.construct_settings` for the structure of this data. Falls back to the default config if not specified or the specified config is missing data points. metadata_transformer (Callable[[], list]): A function that creates the metadata for requests. app_name (string): The codename of the calling service. app_version (string): The version of the calling service. Returns: A IAMApi object. """ if scopes is None: scopes = self._ALL_SCOPES if client_config is None: client_config = {} goog_api_client = '{}/{} {} gax/{} python/{}'.format( app_name, app_version, self._CODE_GEN_NAME_VERSION, self._GAX_VERSION, platform.python_version()) metadata = [('x-goog-api-client', goog_api_client)] default_client_config = json.loads( pkg_resources.resource_string(__name__, 'iam_client_config.json').decode()) defaults = api_callable.construct_settings( 'google.iam.admin.v1.IAM', default_client_config, client_config, config.STATUS_CODE_NAMES, kwargs={'metadata': metadata}, page_descriptors=self._PAGE_DESCRIPTORS) self.iam_stub = config.create_stub( iam_pb2.IAMStub, service_path, port, ssl_creds=ssl_creds, channel=channel, metadata_transformer=metadata_transformer, scopes=scopes) self._list_service_accounts = api_callable.create_api_call( self.iam_stub.ListServiceAccounts, settings=defaults['list_service_accounts']) self._get_service_account = api_callable.create_api_call( self.iam_stub.GetServiceAccount, settings=defaults['get_service_account']) self._create_service_account = api_callable.create_api_call( self.iam_stub.CreateServiceAccount, settings=defaults['create_service_account']) self._update_service_account = api_callable.create_api_call( self.iam_stub.UpdateServiceAccount, settings=defaults['update_service_account']) self._delete_service_account = api_callable.create_api_call( self.iam_stub.DeleteServiceAccount, settings=defaults['delete_service_account']) self._list_service_account_keys = api_callable.create_api_call( self.iam_stub.ListServiceAccountKeys, settings=defaults['list_service_account_keys']) self._get_service_account_key = api_callable.create_api_call( self.iam_stub.GetServiceAccountKey, settings=defaults['get_service_account_key']) self._create_service_account_key = api_callable.create_api_call( self.iam_stub.CreateServiceAccountKey, settings=defaults['create_service_account_key']) self._delete_service_account_key = api_callable.create_api_call( self.iam_stub.DeleteServiceAccountKey, settings=defaults['delete_service_account_key']) self._sign_blob = api_callable.create_api_call( self.iam_stub.SignBlob, settings=defaults['sign_blob']) self._get_iam_policy = api_callable.create_api_call( self.iam_stub.GetIamPolicy, settings=defaults['get_iam_policy']) self._set_iam_policy = api_callable.create_api_call( self.iam_stub.SetIamPolicy, settings=defaults['set_iam_policy']) self._test_iam_permissions = api_callable.create_api_call( self.iam_stub.TestIamPermissions, settings=defaults['test_iam_permissions']) self._query_grantable_roles = api_callable.create_api_call( self.iam_stub.QueryGrantableRoles, settings=defaults['query_grantable_roles']) # Service calls def list_service_accounts(self, name, page_size=0, options=None): """ Lists ``ServiceAccounts`` for a project. Example: >>> from google.cloud.gapic.iam_admin.v1 import iam_api >>> from google.gax import CallOptions, INITIAL_PAGE >>> api = iam_api.IAMApi() >>> name = api.project_path('[PROJECT]') >>> >>> # Iterate over all results >>> for element in api.list_service_accounts(name): >>> # process element >>> pass >>> >>> # Or iterate over results one page at a time >>> for page in api.list_service_accounts(name, options=CallOptions(page_token=INITIAL_PAGE)): >>> for element in page: >>> # process element >>> pass Args: name (string): Required. The resource name of the project associated with the service accounts, such as ``projects/my-project-123``. page_size (int): The maximum number of resources contained in the underlying API response. If page streaming is performed per- resource, this parameter does not affect the return value. If page streaming is performed per-page, this determines the maximum number of resources in a page. options (:class:`google.gax.CallOptions`): Overrides the default settings for this call, e.g, timeout, retries etc. Returns: A :class:`google.gax.PageIterator` instance. By default, this is an iterable of :class:`google.iam.admin.v1.iam_pb2.ServiceAccount` instances. This object can also be configured to iterate over the pages of the response through the `CallOptions` parameter. Raises: :exc:`google.gax.errors.GaxError` if the RPC is aborted. :exc:`ValueError` if the parameters are invalid. """ request = iam_pb2.ListServiceAccountsRequest(name=name, page_size=page_size) return self._list_service_accounts(request, options) def get_service_account(self, name, options=None): """ Gets a ``ServiceAccount``. Example: >>> from google.cloud.gapic.iam_admin.v1 import iam_api >>> api = iam_api.IAMApi() >>> name = api.service_account_path('[PROJECT]', '[SERVICE_ACCOUNT]') >>> response = api.get_service_account(name) Args: name (string): The resource name of the service account in the following format: ``projects/{project}/serviceAccounts/{account}``. Using ``-`` as a wildcard for the project will infer the project from the account. The ``account`` value can be the ``email`` address or the ``unique_id`` of the service account. options (:class:`google.gax.CallOptions`): Overrides the default settings for this call, e.g, timeout, retries etc. Returns: A :class:`google.iam.admin.v1.iam_pb2.ServiceAccount` instance. Raises: :exc:`google.gax.errors.GaxError` if the RPC is aborted. :exc:`ValueError` if the parameters are invalid. """ request = iam_pb2.GetServiceAccountRequest(name=name) return self._get_service_account(request, options) def create_service_account(self, name, account_id, service_account=None, options=None): """ Creates a ``ServiceAccount`` and returns it. Example: >>> from google.cloud.gapic.iam_admin.v1 import iam_api >>> api = iam_api.IAMApi() >>> name = api.project_path('[PROJECT]') >>> account_id = '' >>> response = api.create_service_account(name, account_id) Args: name (string): Required. The resource name of the project associated with the service accounts, such as ``projects/my-project-123``. account_id (string): Required. The account id that is used to generate the service account email address and a stable unique id. It is unique within a project, must be 6-30 characters long, and match the regular expression ```a-z <https://cloud.google.com[-a-z0-9]*[a-z0-9]>`_`` to comply with RFC1035. service_account (:class:`google.iam.admin.v1.iam_pb2.ServiceAccount`): The ``ServiceAccount`` resource to create. Currently, only the following values are user assignable: ``display_name`` . options (:class:`google.gax.CallOptions`): Overrides the default settings for this call, e.g, timeout, retries etc. Returns: A :class:`google.iam.admin.v1.iam_pb2.ServiceAccount` instance. Raises: :exc:`google.gax.errors.GaxError` if the RPC is aborted. :exc:`ValueError` if the parameters are invalid. """ if service_account is None: service_account = iam_pb2.ServiceAccount() request = iam_pb2.CreateServiceAccountRequest( name=name, account_id=account_id, service_account=service_account) return self._create_service_account(request, options) def update_service_account(self, etag, name='', project_id='', unique_id='', email='', display_name='', oauth2_client_id='', options=None): """ Updates a ``ServiceAccount``. Currently, only the following fields are updatable: ``display_name`` . The ``etag`` is mandatory. Example: >>> from google.cloud.gapic.iam_admin.v1 import iam_api >>> api = iam_api.IAMApi() >>> etag = '' >>> response = api.update_service_account(etag) Args: name (string): The resource name of the service account in the following format: ``projects/{project}/serviceAccounts/{account}``. Requests using ``-`` as a wildcard for the project will infer the project from the ``account`` and the ``account`` value can be the ``email`` address or the ``unique_id`` of the service account. In responses the resource name will always be in the format ``projects/{project}/serviceAccounts/{email}``. project_id (string): @OutputOnly The id of the project that owns the service account. unique_id (string): @OutputOnly The unique and stable id of the service account. email (string): @OutputOnly The email address of the service account. display_name (string): Optional. A user-specified description of the service account. Must be fewer than 100 UTF-8 bytes. etag (bytes): Used to perform a consistent read-modify-write. oauth2_client_id (string): @OutputOnly. The OAuth2 client id for the service account. This is used in conjunction with the OAuth2 clientconfig API to make three legged OAuth2 (3LO) flows to access the data of Google users. options (:class:`google.gax.CallOptions`): Overrides the default settings for this call, e.g, timeout, retries etc. Returns: A :class:`google.iam.admin.v1.iam_pb2.ServiceAccount` instance. Raises: :exc:`google.gax.errors.GaxError` if the RPC is aborted. :exc:`ValueError` if the parameters are invalid. """ request = iam_pb2.ServiceAccount(etag=etag, name=name, project_id=project_id, unique_id=unique_id, email=email, display_name=display_name, oauth2_client_id=oauth2_client_id) return self._update_service_account(request, options) def delete_service_account(self, name, options=None): """ Deletes a ``ServiceAccount``. Example: >>> from google.cloud.gapic.iam_admin.v1 import iam_api >>> api = iam_api.IAMApi() >>> name = api.service_account_path('[PROJECT]', '[SERVICE_ACCOUNT]') >>> api.delete_service_account(name) Args: name (string): The resource name of the service account in the following format: ``projects/{project}/serviceAccounts/{account}``. Using ``-`` as a wildcard for the project will infer the project from the account. The ``account`` value can be the ``email`` address or the ``unique_id`` of the service account. options (:class:`google.gax.CallOptions`): Overrides the default settings for this call, e.g, timeout, retries etc. Raises: :exc:`google.gax.errors.GaxError` if the RPC is aborted. :exc:`ValueError` if the parameters are invalid. """ request = iam_pb2.DeleteServiceAccountRequest(name=name) self._delete_service_account(request, options) def list_service_account_keys(self, name, key_types=None, options=None): """ Lists ``ServiceAccountKeys``. Example: >>> from google.cloud.gapic.iam_admin.v1 import iam_api >>> api = iam_api.IAMApi() >>> name = api.service_account_path('[PROJECT]', '[SERVICE_ACCOUNT]') >>> response = api.list_service_account_keys(name) Args: name (string): The resource name of the service account in the following format: ``projects/{project}/serviceAccounts/{account}``. Using ``-`` as a wildcard for the project, will infer the project from the account. The ``account`` value can be the ``email`` address or the ``unique_id`` of the service account. key_types (list[enum :class:`google.cloud.gapic.iam_admin.v1.enums.ListServiceAccountKeysRequest.KeyType`]): Filters the types of keys the user wants to include in the list response. Duplicate key types are not allowed. If no key type is provided, all keys are returned. options (:class:`google.gax.CallOptions`): Overrides the default settings for this call, e.g, timeout, retries etc. Returns: A :class:`google.iam.admin.v1.iam_pb2.ListServiceAccountKeysResponse` instance. Raises: :exc:`google.gax.errors.GaxError` if the RPC is aborted. :exc:`ValueError` if the parameters are invalid. """ if key_types is None: key_types = [] request = iam_pb2.ListServiceAccountKeysRequest(name=name, key_types=key_types) return self._list_service_account_keys(request, options) def get_service_account_key(self, name, public_key_type=None, options=None): """ Gets the ``ServiceAccountKey`` by key id. Example: >>> from google.cloud.gapic.iam_admin.v1 import iam_api >>> api = iam_api.IAMApi() >>> name = api.key_path('[PROJECT]', '[SERVICE_ACCOUNT]', '[KEY]') >>> response = api.get_service_account_key(name) Args: name (string): The resource name of the service account key in the following format: ``projects/{project}/serviceAccounts/{account}/keys/{key}``. Using ``-`` as a wildcard for the project will infer the project from the account. The ``account`` value can be the ``email`` address or the ``unique_id`` of the service account. public_key_type (enum :class:`google.cloud.gapic.iam_admin.v1.enums.ServiceAccountPublicKeyType`): The output format of the public key requested. X509_PEM is the default output format. options (:class:`google.gax.CallOptions`): Overrides the default settings for this call, e.g, timeout, retries etc. Returns: A :class:`google.iam.admin.v1.iam_pb2.ServiceAccountKey` instance. Raises: :exc:`google.gax.errors.GaxError` if the RPC is aborted. :exc:`ValueError` if the parameters are invalid. """ if public_key_type is None: public_key_type = enums.ServiceAccountPublicKeyType.TYPE_NONE request = iam_pb2.GetServiceAccountKeyRequest( name=name, public_key_type=public_key_type) return self._get_service_account_key(request, options) def create_service_account_key(self, name, private_key_type=None, key_algorithm=None, options=None): """ Creates a ``ServiceAccountKey`` and returns it. Example: >>> from google.cloud.gapic.iam_admin.v1 import iam_api >>> api = iam_api.IAMApi() >>> name = api.service_account_path('[PROJECT]', '[SERVICE_ACCOUNT]') >>> response = api.create_service_account_key(name) Args: name (string): The resource name of the service account in the following format: ``projects/{project}/serviceAccounts/{account}``. Using ``-`` as a wildcard for the project will infer the project from the account. The ``account`` value can be the ``email`` address or the ``unique_id`` of the service account. private_key_type (enum :class:`google.cloud.gapic.iam_admin.v1.enums.ServiceAccountPrivateKeyType`): The output format of the private key. ``GOOGLE_CREDENTIALS_FILE`` is the default output format. key_algorithm (enum :class:`google.cloud.gapic.iam_admin.v1.enums.ServiceAccountKeyAlgorithm`): Which type of key and algorithm to use for the key. The default is currently a 4K RSA key. However this may change in the future. options (:class:`google.gax.CallOptions`): Overrides the default settings for this call, e.g, timeout, retries etc. Returns: A :class:`google.iam.admin.v1.iam_pb2.ServiceAccountKey` instance. Raises: :exc:`google.gax.errors.GaxError` if the RPC is aborted. :exc:`ValueError` if the parameters are invalid. """ if private_key_type is None: private_key_type = enums.ServiceAccountPrivateKeyType.TYPE_UNSPECIFIED if key_algorithm is None: key_algorithm = enums.ServiceAccountKeyAlgorithm.KEY_ALG_UNSPECIFIED request = iam_pb2.CreateServiceAccountKeyRequest( name=name, private_key_type=private_key_type, key_algorithm=key_algorithm) return self._create_service_account_key(request, options) def delete_service_account_key(self, name, options=None): """ Deletes a ``ServiceAccountKey``. Example: >>> from google.cloud.gapic.iam_admin.v1 import iam_api >>> api = iam_api.IAMApi() >>> name = api.key_path('[PROJECT]', '[SERVICE_ACCOUNT]', '[KEY]') >>> api.delete_service_account_key(name) Args: name (string): The resource name of the service account key in the following format: ``projects/{project}/serviceAccounts/{account}/keys/{key}``. Using ``-`` as a wildcard for the project will infer the project from the account. The ``account`` value can be the ``email`` address or the ``unique_id`` of the service account. options (:class:`google.gax.CallOptions`): Overrides the default settings for this call, e.g, timeout, retries etc. Raises: :exc:`google.gax.errors.GaxError` if the RPC is aborted. :exc:`ValueError` if the parameters are invalid. """ request = iam_pb2.DeleteServiceAccountKeyRequest(name=name) self._delete_service_account_key(request, options) def sign_blob(self, name, bytes_to_sign, options=None): """ Signs a blob using a service account's system-managed private key. Example: >>> from google.cloud.gapic.iam_admin.v1 import iam_api >>> api = iam_api.IAMApi() >>> name = api.service_account_path('[PROJECT]', '[SERVICE_ACCOUNT]') >>> bytes_to_sign = '' >>> response = api.sign_blob(name, bytes_to_sign) Args: name (string): The resource name of the service account in the following format: ``projects/{project}/serviceAccounts/{account}``. Using ``-`` as a wildcard for the project will infer the project from the account. The ``account`` value can be the ``email`` address or the ``unique_id`` of the service account. bytes_to_sign (bytes): The bytes to sign. options (:class:`google.gax.CallOptions`): Overrides the default settings for this call, e.g, timeout, retries etc. Returns: A :class:`google.iam.admin.v1.iam_pb2.SignBlobResponse` instance. Raises: :exc:`google.gax.errors.GaxError` if the RPC is aborted. :exc:`ValueError` if the parameters are invalid. """ request = iam_pb2.SignBlobRequest(name=name, bytes_to_sign=bytes_to_sign) return self._sign_blob(request, options) def get_iam_policy(self, resource, options=None): """ Returns the IAM access control policy for a ``ServiceAccount``. Example: >>> from google.cloud.gapic.iam_admin.v1 import iam_api >>> api = iam_api.IAMApi() >>> resource = api.service_account_path('[PROJECT]', '[SERVICE_ACCOUNT]') >>> response = api.get_iam_policy(resource) Args: resource (string): REQUIRED: The resource for which the policy is being requested. ``resource`` is usually specified as a path. For example, a Project resource is specified as ``projects/{project}``. options (:class:`google.gax.CallOptions`): Overrides the default settings for this call, e.g, timeout, retries etc. Returns: A :class:`google.iam.v1.policy_pb2.Policy` instance. Raises: :exc:`google.gax.errors.GaxError` if the RPC is aborted. :exc:`ValueError` if the parameters are invalid. """ request = iam_policy_pb2.GetIamPolicyRequest(resource=resource) return self._get_iam_policy(request, options) def set_iam_policy(self, resource, policy, options=None): """ Sets the IAM access control policy for a ``ServiceAccount``. Example: >>> from google.cloud.gapic.iam_admin.v1 import iam_api >>> from google.iam.v1 import policy_pb2 >>> api = iam_api.IAMApi() >>> resource = api.service_account_path('[PROJECT]', '[SERVICE_ACCOUNT]') >>> policy = policy_pb2.Policy() >>> response = api.set_iam_policy(resource, policy) Args: resource (string): REQUIRED: The resource for which the policy is being specified. ``resource`` is usually specified as a path. For example, a Project resource is specified as ``projects/{project}``. policy (:class:`google.iam.v1.policy_pb2.Policy`): REQUIRED: The complete policy to be applied to the ``resource``. The size of the policy is limited to a few 10s of KB. An empty policy is a valid policy but certain Cloud Platform services (such as Projects) might reject them. options (:class:`google.gax.CallOptions`): Overrides the default settings for this call, e.g, timeout, retries etc. Returns: A :class:`google.iam.v1.policy_pb2.Policy` instance. Raises: :exc:`google.gax.errors.GaxError` if the RPC is aborted. :exc:`ValueError` if the parameters are invalid. """ request = iam_policy_pb2.SetIamPolicyRequest(resource=resource, policy=policy) return self._set_iam_policy(request, options) def test_iam_permissions(self, resource, permissions, options=None): """ Tests the specified permissions against the IAM access control policy for a ``ServiceAccount``. Example: >>> from google.cloud.gapic.iam_admin.v1 import iam_api >>> api = iam_api.IAMApi() >>> resource = api.service_account_path('[PROJECT]', '[SERVICE_ACCOUNT]') >>> permissions = [] >>> response = api.test_iam_permissions(resource, permissions) Args: resource (string): REQUIRED: The resource for which the policy detail is being requested. ``resource`` is usually specified as a path. For example, a Project resource is specified as ``projects/{project}``. permissions (list[string]): The set of permissions to check for the ``resource``. Permissions with wildcards (such as '*' or 'storage.*') are not allowed. For more information see `IAM Overview <https://cloud.google.com/iam/docs/overview#permissions>`_. options (:class:`google.gax.CallOptions`): Overrides the default settings for this call, e.g, timeout, retries etc. Returns: A :class:`google.iam.v1.iam_policy_pb2.TestIamPermissionsResponse` instance. Raises: :exc:`google.gax.errors.GaxError` if the RPC is aborted. :exc:`ValueError` if the parameters are invalid. """ request = iam_policy_pb2.TestIamPermissionsRequest( resource=resource, permissions=permissions) return self._test_iam_permissions(request, options) def query_grantable_roles(self, full_resource_name, options=None): """ Queries roles that can be granted on a particular resource. A role is grantable if it can be used as the role in a binding for a policy for that resource. Example: >>> from google.cloud.gapic.iam_admin.v1 import iam_api >>> api = iam_api.IAMApi() >>> full_resource_name = '' >>> response = api.query_grantable_roles(full_resource_name) Args: full_resource_name (string): Required. The full resource name to query from the list of grantable roles. The name follows the Google Cloud Platform resource format. For example, a Cloud Platform project with id ``my-project`` will be named ``//cloudresourcemanager.googleapis.com/projects/my-project``. options (:class:`google.gax.CallOptions`): Overrides the default settings for this call, e.g, timeout, retries etc. Returns: A :class:`google.iam.admin.v1.iam_pb2.QueryGrantableRolesResponse` instance. Raises: :exc:`google.gax.errors.GaxError` if the RPC is aborted. :exc:`ValueError` if the parameters are invalid. """ request = iam_pb2.QueryGrantableRolesRequest( full_resource_name=full_resource_name) return self._query_grantable_roles(request, options)
class CloudFunctionsServiceClient(object): """A service that application uses to manipulate triggers and functions.""" SERVICE_ADDRESS = 'cloudfunctions.googleapis.com' """The default address of the service.""" DEFAULT_SERVICE_PORT = 443 """The default port of the service.""" _PAGE_DESCRIPTORS = { 'list_functions': _PageDesc('page_token', 'next_page_token', 'functions') } # The scopes needed to make gRPC calls to all of the methods defined in # this service _ALL_SCOPES = ('https://www.googleapis.com/auth/cloud-platform', ) _LOCATION_PATH_TEMPLATE = path_template.PathTemplate( 'projects/{project}/locations/{location}') _FUNCTION_PATH_TEMPLATE = path_template.PathTemplate( 'projects/{project}/locations/{location}/functions/{function}') @classmethod def location_path(cls, project, location): """Returns a fully-qualified location resource name string.""" return cls._LOCATION_PATH_TEMPLATE.render({ 'project': project, 'location': location, }) @classmethod def function_path(cls, project, location, function): """Returns a fully-qualified function resource name string.""" return cls._FUNCTION_PATH_TEMPLATE.render({ 'project': project, 'location': location, 'function': function, }) @classmethod def match_project_from_location_name(cls, location_name): """Parses the project from a location resource. Args: location_name (string): A fully-qualified path representing a location resource. Returns: A string representing the project. """ return cls._LOCATION_PATH_TEMPLATE.match(location_name).get('project') @classmethod def match_location_from_location_name(cls, location_name): """Parses the location from a location resource. Args: location_name (string): A fully-qualified path representing a location resource. Returns: A string representing the location. """ return cls._LOCATION_PATH_TEMPLATE.match(location_name).get('location') @classmethod def match_project_from_function_name(cls, function_name): """Parses the project from a function resource. Args: function_name (string): A fully-qualified path representing a function resource. Returns: A string representing the project. """ return cls._FUNCTION_PATH_TEMPLATE.match(function_name).get('project') @classmethod def match_location_from_function_name(cls, function_name): """Parses the location from a function resource. Args: function_name (string): A fully-qualified path representing a function resource. Returns: A string representing the location. """ return cls._FUNCTION_PATH_TEMPLATE.match(function_name).get('location') @classmethod def match_function_from_function_name(cls, function_name): """Parses the function from a function resource. Args: function_name (string): A fully-qualified path representing a function resource. Returns: A string representing the function. """ return cls._FUNCTION_PATH_TEMPLATE.match(function_name).get('function') def __init__(self, service_path=SERVICE_ADDRESS, port=DEFAULT_SERVICE_PORT, channel=None, credentials=None, ssl_credentials=None, scopes=None, client_config=None, app_name=None, app_version='', lib_name=None, lib_version='', metrics_headers=()): """Constructor. Args: service_path (string): The domain name of the API remote host. port (int): The port on which to connect to the remote host. channel (:class:`grpc.Channel`): A ``Channel`` instance through which to make calls. credentials (object): The authorization credentials to attach to requests. These credentials identify this application to the service. ssl_credentials (:class:`grpc.ChannelCredentials`): A ``ChannelCredentials`` instance for use with an SSL-enabled channel. scopes (list[string]): A list of OAuth2 scopes to attach to requests. client_config (dict): A dictionary for call options for each method. See :func:`google.gax.construct_settings` for the structure of this data. Falls back to the default config if not specified or the specified config is missing data points. app_name (string): The name of the application calling the service. Recommended for analytics purposes. app_version (string): The version of the application calling the service. Recommended for analytics purposes. lib_name (string): The API library software used for calling the service. (Unless you are writing an API client itself, leave this as default.) lib_version (string): The API library software version used for calling the service. (Unless you are writing an API client itself, leave this as default.) metrics_headers (dict): A dictionary of values for tracking client library metrics. Ultimately serializes to a string (e.g. 'foo/1.2.3 bar/3.14.1'). This argument should be considered private. Returns: A CloudFunctionsServiceClient object. """ # Unless the calling application specifically requested # OAuth scopes, request everything. if scopes is None: scopes = self._ALL_SCOPES # Initialize an empty client config, if none is set. if client_config is None: client_config = {} # Initialize metrics_headers as an ordered dictionary # (cuts down on cardinality of the resulting string slightly). metrics_headers = collections.OrderedDict(metrics_headers) metrics_headers['gl-python'] = platform.python_version() # The library may or may not be set, depending on what is # calling this client. Newer client libraries set the library name # and version. if lib_name: metrics_headers[lib_name] = lib_version # Finally, track the GAPIC package version. metrics_headers['gapic'] = pkg_resources.get_distribution( 'gapic-google-cloud-functions-v1beta2', ).version # Load the configuration defaults. default_client_config = json.loads( pkg_resources.resource_string( __name__, 'cloud_functions_service_client_config.json').decode()) defaults = api_callable.construct_settings( 'google.cloud.functions.v1beta2.CloudFunctionsService', default_client_config, client_config, config.STATUS_CODE_NAMES, metrics_headers=metrics_headers, page_descriptors=self._PAGE_DESCRIPTORS, ) self.cloud_functions_service_stub = config.create_stub( functions_pb2.CloudFunctionsServiceStub, channel=channel, service_path=service_path, service_port=port, credentials=credentials, scopes=scopes, ssl_credentials=ssl_credentials) self.operations_client = operations_client.OperationsClient( service_path=service_path, port=port, channel=channel, credentials=credentials, ssl_credentials=ssl_credentials, scopes=scopes, client_config=client_config, metrics_headers=metrics_headers, ) self._list_functions = api_callable.create_api_call( self.cloud_functions_service_stub.ListFunctions, settings=defaults['list_functions']) self._get_function = api_callable.create_api_call( self.cloud_functions_service_stub.GetFunction, settings=defaults['get_function']) self._create_function = api_callable.create_api_call( self.cloud_functions_service_stub.CreateFunction, settings=defaults['create_function']) self._update_function = api_callable.create_api_call( self.cloud_functions_service_stub.UpdateFunction, settings=defaults['update_function']) self._delete_function = api_callable.create_api_call( self.cloud_functions_service_stub.DeleteFunction, settings=defaults['delete_function']) self._call_function = api_callable.create_api_call( self.cloud_functions_service_stub.CallFunction, settings=defaults['call_function']) # Service calls def list_functions(self, location, page_size=0, options=None): """ Returns a list of functions that belong to the requested project. Example: >>> from google.cloud.functions.v1beta2 import cloud_functions_service_client >>> from google.gax import CallOptions, INITIAL_PAGE >>> api = cloud_functions_service_client.CloudFunctionsServiceClient() >>> location = api.location_path('[PROJECT]', '[LOCATION]') >>> >>> # Iterate over all results >>> for element in api.list_functions(location): >>> # process element >>> pass >>> >>> # Or iterate over results one page at a time >>> for page in api.list_functions(location, options=CallOptions(page_token=INITIAL_PAGE)): >>> for element in page: >>> # process element >>> pass Args: location (string): The project and location from which the function should be listed, specified in the format ``projects/*/locations/*`` If you want to list functions in all locations, use \"-\" in place of a location. page_size (int): The maximum number of resources contained in the underlying API response. If page streaming is performed per- resource, this parameter does not affect the return value. If page streaming is performed per-page, this determines the maximum number of resources in a page. options (:class:`google.gax.CallOptions`): Overrides the default settings for this call, e.g, timeout, retries etc. Returns: A :class:`google.gax.PageIterator` instance. By default, this is an iterable of :class:`google.cloud.proto.functions.v1beta2.functions_pb2.CloudFunction` instances. This object can also be configured to iterate over the pages of the response through the `CallOptions` parameter. Raises: :exc:`google.gax.errors.GaxError` if the RPC is aborted. :exc:`ValueError` if the parameters are invalid. """ # Create the request object. request = functions_pb2.ListFunctionsRequest(location=location, page_size=page_size) return self._list_functions(request, options) def get_function(self, name, options=None): """ Returns a function with the given name from the requested project. Example: >>> from google.cloud.functions.v1beta2 import cloud_functions_service_client >>> api = cloud_functions_service_client.CloudFunctionsServiceClient() >>> name = api.function_path('[PROJECT]', '[LOCATION]', '[FUNCTION]') >>> response = api.get_function(name) Args: name (string): The name of the function which details should be obtained. options (:class:`google.gax.CallOptions`): Overrides the default settings for this call, e.g, timeout, retries etc. Returns: A :class:`google.cloud.proto.functions.v1beta2.functions_pb2.CloudFunction` instance. Raises: :exc:`google.gax.errors.GaxError` if the RPC is aborted. :exc:`ValueError` if the parameters are invalid. """ # Create the request object. request = functions_pb2.GetFunctionRequest(name=name) return self._get_function(request, options) def create_function(self, location, function, options=None): """ Creates a new function. If a function with the given name already exists in the specified project, the long running operation will return ``ALREADY_EXISTS`` error. Example: >>> from google.cloud.functions.v1beta2 import cloud_functions_service_client >>> from google.cloud.proto.functions.v1beta2 import functions_pb2 >>> api = cloud_functions_service_client.CloudFunctionsServiceClient() >>> location = api.location_path('[PROJECT]', '[LOCATION]') >>> function = functions_pb2.CloudFunction() >>> response = api.create_function(location, function) >>> >>> def callback(operation_future): >>> # Handle result. >>> result = operation_future.result() >>> >>> response.add_done_callback(callback) >>> >>> # Handle metadata. >>> metadata = response.metadata() Args: location (string): The project and location in which the function should be created, specified in the format ``projects/*/locations/*`` function (:class:`google.cloud.proto.functions.v1beta2.functions_pb2.CloudFunction`): Function to be created. options (:class:`google.gax.CallOptions`): Overrides the default settings for this call, e.g, timeout, retries etc. Returns: A :class:`google.gax._OperationFuture` instance. Raises: :exc:`google.gax.errors.GaxError` if the RPC is aborted. :exc:`ValueError` if the parameters are invalid. """ # Create the request object. request = functions_pb2.CreateFunctionRequest(location=location, function=function) return google.gax._OperationFuture( self._create_function(request, options), self.operations_client, functions_pb2.CloudFunction, operations_pb2.OperationMetadataV1Beta2, options) def update_function(self, name, function, options=None): """ Updates existing function. Example: >>> from google.cloud.functions.v1beta2 import cloud_functions_service_client >>> from google.cloud.proto.functions.v1beta2 import functions_pb2 >>> api = cloud_functions_service_client.CloudFunctionsServiceClient() >>> name = api.function_path('[PROJECT]', '[LOCATION]', '[FUNCTION]') >>> function = functions_pb2.CloudFunction() >>> response = api.update_function(name, function) >>> >>> def callback(operation_future): >>> # Handle result. >>> result = operation_future.result() >>> >>> response.add_done_callback(callback) >>> >>> # Handle metadata. >>> metadata = response.metadata() Args: name (string): The name of the function to be updated. function (:class:`google.cloud.proto.functions.v1beta2.functions_pb2.CloudFunction`): New version of the function. options (:class:`google.gax.CallOptions`): Overrides the default settings for this call, e.g, timeout, retries etc. Returns: A :class:`google.gax._OperationFuture` instance. Raises: :exc:`google.gax.errors.GaxError` if the RPC is aborted. :exc:`ValueError` if the parameters are invalid. """ # Create the request object. request = functions_pb2.UpdateFunctionRequest(name=name, function=function) return google.gax._OperationFuture( self._update_function(request, options), self.operations_client, functions_pb2.CloudFunction, operations_pb2.OperationMetadataV1Beta2, options) def delete_function(self, name, options=None): """ Deletes a function with the given name from the specified project. If the given function is used by some trigger, the trigger will be updated to remove this function. Example: >>> from google.cloud.functions.v1beta2 import cloud_functions_service_client >>> api = cloud_functions_service_client.CloudFunctionsServiceClient() >>> name = api.function_path('[PROJECT]', '[LOCATION]', '[FUNCTION]') >>> response = api.delete_function(name) >>> >>> def callback(operation_future): >>> # Handle result. >>> result = operation_future.result() >>> >>> response.add_done_callback(callback) >>> >>> # Handle metadata. >>> metadata = response.metadata() Args: name (string): The name of the function which should be deleted. options (:class:`google.gax.CallOptions`): Overrides the default settings for this call, e.g, timeout, retries etc. Returns: A :class:`google.gax._OperationFuture` instance. Raises: :exc:`google.gax.errors.GaxError` if the RPC is aborted. :exc:`ValueError` if the parameters are invalid. """ # Create the request object. request = functions_pb2.DeleteFunctionRequest(name=name) return google.gax._OperationFuture( self._delete_function(request, options), self.operations_client, empty_pb2.Empty, operations_pb2.OperationMetadataV1Beta2, options) def call_function(self, name, data, options=None): """ Invokes synchronously deployed function. To be used for testing, very limited traffic allowed. Example: >>> from google.cloud.functions.v1beta2 import cloud_functions_service_client >>> api = cloud_functions_service_client.CloudFunctionsServiceClient() >>> name = api.function_path('[PROJECT]', '[LOCATION]', '[FUNCTION]') >>> data = '' >>> response = api.call_function(name, data) Args: name (string): The name of the function to be called. data (string): Input to be passed to the function. options (:class:`google.gax.CallOptions`): Overrides the default settings for this call, e.g, timeout, retries etc. Returns: A :class:`google.cloud.proto.functions.v1beta2.functions_pb2.CallFunctionResponse` instance. Raises: :exc:`google.gax.errors.GaxError` if the RPC is aborted. :exc:`ValueError` if the parameters are invalid. """ # Create the request object. request = functions_pb2.CallFunctionRequest(name=name, data=data) return self._call_function(request, options)
class MetricsServiceV2Client(object): """Service for configuring logs-based metrics.""" SERVICE_ADDRESS = 'logging.googleapis.com' """The default address of the service.""" DEFAULT_SERVICE_PORT = 443 """The default port of the service.""" _PAGE_DESCRIPTORS = { 'list_log_metrics': _PageDesc('page_token', 'next_page_token', 'metrics') } # The scopes needed to make gRPC calls to all of the methods defined in # this service _ALL_SCOPES = ( 'https://www.googleapis.com/auth/cloud-platform', 'https://www.googleapis.com/auth/cloud-platform.read-only', 'https://www.googleapis.com/auth/logging.admin', 'https://www.googleapis.com/auth/logging.read', 'https://www.googleapis.com/auth/logging.write', ) _PROJECT_PATH_TEMPLATE = path_template.PathTemplate('projects/{project}') _METRIC_PATH_TEMPLATE = path_template.PathTemplate( 'projects/{project}/metrics/{metric}') @classmethod def project_path(cls, project): """Returns a fully-qualified project resource name string.""" return cls._PROJECT_PATH_TEMPLATE.render({ 'project': project, }) @classmethod def metric_path(cls, project, metric): """Returns a fully-qualified metric resource name string.""" return cls._METRIC_PATH_TEMPLATE.render({ 'project': project, 'metric': metric, }) @classmethod def match_project_from_project_name(cls, project_name): """Parses the project from a project resource. Args: project_name (string): A fully-qualified path representing a project resource. Returns: A string representing the project. """ return cls._PROJECT_PATH_TEMPLATE.match(project_name).get('project') @classmethod def match_project_from_metric_name(cls, metric_name): """Parses the project from a metric resource. Args: metric_name (string): A fully-qualified path representing a metric resource. Returns: A string representing the project. """ return cls._METRIC_PATH_TEMPLATE.match(metric_name).get('project') @classmethod def match_metric_from_metric_name(cls, metric_name): """Parses the metric from a metric resource. Args: metric_name (string): A fully-qualified path representing a metric resource. Returns: A string representing the metric. """ return cls._METRIC_PATH_TEMPLATE.match(metric_name).get('metric') def __init__(self, service_path=SERVICE_ADDRESS, port=DEFAULT_SERVICE_PORT, channel=None, credentials=None, ssl_credentials=None, scopes=None, client_config=None, app_name=None, app_version='', lib_name=None, lib_version='', metrics_headers=()): """Constructor. Args: service_path (string): The domain name of the API remote host. port (int): The port on which to connect to the remote host. channel (:class:`grpc.Channel`): A ``Channel`` instance through which to make calls. credentials (object): The authorization credentials to attach to requests. These credentials identify this application to the service. ssl_credentials (:class:`grpc.ChannelCredentials`): A ``ChannelCredentials`` instance for use with an SSL-enabled channel. scopes (list[string]): A list of OAuth2 scopes to attach to requests. client_config (dict): A dictionary for call options for each method. See :func:`google.gax.construct_settings` for the structure of this data. Falls back to the default config if not specified or the specified config is missing data points. app_name (string): The name of the application calling the service. Recommended for analytics purposes. app_version (string): The version of the application calling the service. Recommended for analytics purposes. lib_name (string): The API library software used for calling the service. (Unless you are writing an API client itself, leave this as default.) lib_version (string): The API library software version used for calling the service. (Unless you are writing an API client itself, leave this as default.) metrics_headers (dict): A dictionary of values for tracking client library metrics. Ultimately serializes to a string (e.g. 'foo/1.2.3 bar/3.14.1'). This argument should be considered private. Returns: A MetricsServiceV2Client object. """ # Unless the calling application specifically requested # OAuth scopes, request everything. if scopes is None: scopes = self._ALL_SCOPES # Initialize an empty client config, if none is set. if client_config is None: client_config = {} # Initialize metrics_headers as an ordered dictionary # (cuts down on cardinality of the resulting string slightly). metrics_headers = collections.OrderedDict(metrics_headers) metrics_headers['gl-python'] = platform.python_version() # The library may or may not be set, depending on what is # calling this client. Newer client libraries set the library name # and version. if lib_name: metrics_headers[lib_name] = lib_version # Finally, track the GAPIC package version. metrics_headers['gapic'] = pkg_resources.get_distribution( 'gapic-google-cloud-logging-v2', ).version # Load the configuration defaults. default_client_config = json.loads( pkg_resources.resource_string( __name__, 'metrics_service_v2_client_config.json').decode()) defaults = api_callable.construct_settings( 'google.logging.v2.MetricsServiceV2', default_client_config, client_config, config.STATUS_CODE_NAMES, metrics_headers=metrics_headers, page_descriptors=self._PAGE_DESCRIPTORS, ) self.metrics_service_v2_stub = config.create_stub( logging_metrics_pb2.MetricsServiceV2Stub, channel=channel, service_path=service_path, service_port=port, credentials=credentials, scopes=scopes, ssl_credentials=ssl_credentials) self._list_log_metrics = api_callable.create_api_call( self.metrics_service_v2_stub.ListLogMetrics, settings=defaults['list_log_metrics']) self._get_log_metric = api_callable.create_api_call( self.metrics_service_v2_stub.GetLogMetric, settings=defaults['get_log_metric']) self._create_log_metric = api_callable.create_api_call( self.metrics_service_v2_stub.CreateLogMetric, settings=defaults['create_log_metric']) self._update_log_metric = api_callable.create_api_call( self.metrics_service_v2_stub.UpdateLogMetric, settings=defaults['update_log_metric']) self._delete_log_metric = api_callable.create_api_call( self.metrics_service_v2_stub.DeleteLogMetric, settings=defaults['delete_log_metric']) # Service calls def list_log_metrics(self, parent, page_size=None, options=None): """ Lists logs-based metrics. Example: >>> from google.cloud.gapic.logging.v2 import metrics_service_v2_client >>> from google.gax import CallOptions, INITIAL_PAGE >>> client = metrics_service_v2_client.MetricsServiceV2Client() >>> parent = client.project_path('[PROJECT]') >>> >>> # Iterate over all results >>> for element in client.list_log_metrics(parent): >>> # process element >>> pass >>> >>> # Or iterate over results one page at a time >>> for page in client.list_log_metrics(parent, options=CallOptions(page_token=INITIAL_PAGE)): >>> for element in page: >>> # process element >>> pass Args: parent (string): Required. The name of the project containing the metrics: :: \"projects/[PROJECT_ID]\" page_size (int): The maximum number of resources contained in the underlying API response. If page streaming is performed per- resource, this parameter does not affect the return value. If page streaming is performed per-page, this determines the maximum number of resources in a page. options (:class:`google.gax.CallOptions`): Overrides the default settings for this call, e.g, timeout, retries etc. Returns: A :class:`google.gax.PageIterator` instance. By default, this is an iterable of :class:`google.cloud.proto.logging.v2.logging_metrics_pb2.LogMetric` instances. This object can also be configured to iterate over the pages of the response through the `CallOptions` parameter. Raises: :exc:`google.gax.errors.GaxError` if the RPC is aborted. :exc:`ValueError` if the parameters are invalid. """ # Create the request object. request = logging_metrics_pb2.ListLogMetricsRequest( parent=parent, page_size=page_size) return self._list_log_metrics(request, options) def get_log_metric(self, metric_name, options=None): """ Gets a logs-based metric. Example: >>> from google.cloud.gapic.logging.v2 import metrics_service_v2_client >>> client = metrics_service_v2_client.MetricsServiceV2Client() >>> metric_name = client.metric_path('[PROJECT]', '[METRIC]') >>> response = client.get_log_metric(metric_name) Args: metric_name (string): The resource name of the desired metric: :: \"projects/[PROJECT_ID]/metrics/[METRIC_ID]\" options (:class:`google.gax.CallOptions`): Overrides the default settings for this call, e.g, timeout, retries etc. Returns: A :class:`google.cloud.proto.logging.v2.logging_metrics_pb2.LogMetric` instance. Raises: :exc:`google.gax.errors.GaxError` if the RPC is aborted. :exc:`ValueError` if the parameters are invalid. """ # Create the request object. request = logging_metrics_pb2.GetLogMetricRequest( metric_name=metric_name) return self._get_log_metric(request, options) def create_log_metric(self, parent, metric, options=None): """ Creates a logs-based metric. Example: >>> from google.cloud.gapic.logging.v2 import metrics_service_v2_client >>> from google.cloud.proto.logging.v2 import logging_metrics_pb2 >>> client = metrics_service_v2_client.MetricsServiceV2Client() >>> parent = client.project_path('[PROJECT]') >>> metric = logging_metrics_pb2.LogMetric() >>> response = client.create_log_metric(parent, metric) Args: parent (string): The resource name of the project in which to create the metric: :: \"projects/[PROJECT_ID]\" The new metric must be provided in the request. metric (:class:`google.cloud.proto.logging.v2.logging_metrics_pb2.LogMetric`): The new logs-based metric, which must not have an identifier that already exists. options (:class:`google.gax.CallOptions`): Overrides the default settings for this call, e.g, timeout, retries etc. Returns: A :class:`google.cloud.proto.logging.v2.logging_metrics_pb2.LogMetric` instance. Raises: :exc:`google.gax.errors.GaxError` if the RPC is aborted. :exc:`ValueError` if the parameters are invalid. """ # Create the request object. request = logging_metrics_pb2.CreateLogMetricRequest(parent=parent, metric=metric) return self._create_log_metric(request, options) def update_log_metric(self, metric_name, metric, options=None): """ Creates or updates a logs-based metric. Example: >>> from google.cloud.gapic.logging.v2 import metrics_service_v2_client >>> from google.cloud.proto.logging.v2 import logging_metrics_pb2 >>> client = metrics_service_v2_client.MetricsServiceV2Client() >>> metric_name = client.metric_path('[PROJECT]', '[METRIC]') >>> metric = logging_metrics_pb2.LogMetric() >>> response = client.update_log_metric(metric_name, metric) Args: metric_name (string): 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. metric (:class:`google.cloud.proto.logging.v2.logging_metrics_pb2.LogMetric`): The updated metric. options (:class:`google.gax.CallOptions`): Overrides the default settings for this call, e.g, timeout, retries etc. Returns: A :class:`google.cloud.proto.logging.v2.logging_metrics_pb2.LogMetric` instance. Raises: :exc:`google.gax.errors.GaxError` if the RPC is aborted. :exc:`ValueError` if the parameters are invalid. """ # Create the request object. request = logging_metrics_pb2.UpdateLogMetricRequest( metric_name=metric_name, metric=metric) return self._update_log_metric(request, options) def delete_log_metric(self, metric_name, options=None): """ Deletes a logs-based metric. Example: >>> from google.cloud.gapic.logging.v2 import metrics_service_v2_client >>> client = metrics_service_v2_client.MetricsServiceV2Client() >>> metric_name = client.metric_path('[PROJECT]', '[METRIC]') >>> client.delete_log_metric(metric_name) Args: metric_name (string): The resource name of the metric to delete: :: \"projects/[PROJECT_ID]/metrics/[METRIC_ID]\" options (:class:`google.gax.CallOptions`): Overrides the default settings for this call, e.g, timeout, retries etc. Raises: :exc:`google.gax.errors.GaxError` if the RPC is aborted. :exc:`ValueError` if the parameters are invalid. """ # Create the request object. request = logging_metrics_pb2.DeleteLogMetricRequest( metric_name=metric_name) self._delete_log_metric(request, options)
class ErrorGroupServiceApi(object): """Service for retrieving and updating individual error groups.""" SERVICE_ADDRESS = 'clouderrorreporting.googleapis.com' """The default address of the service.""" DEFAULT_SERVICE_PORT = 443 """The default port of the service.""" _CODE_GEN_NAME_VERSION = 'gapic/0.1.0' _GAX_VERSION = pkg_resources.get_distribution('google-gax').version # The scopes needed to make gRPC calls to all of the methods defined in # this service _ALL_SCOPES = ('https://www.googleapis.com/auth/cloud-platform', ) _GROUP_PATH_TEMPLATE = path_template.PathTemplate( 'projects/{project}/groups/{group}') @classmethod def group_path(cls, project, group): """Returns a fully-qualified group resource name string.""" return cls._GROUP_PATH_TEMPLATE.render({ 'project': project, 'group': group, }) @classmethod def match_project_from_group_name(cls, group_name): """Parses the project from a group resource. Args: group_name (string): A fully-qualified path representing a group resource. Returns: A string representing the project. """ return cls._GROUP_PATH_TEMPLATE.match(group_name).get('project') @classmethod def match_group_from_group_name(cls, group_name): """Parses the group from a group resource. Args: group_name (string): A fully-qualified path representing a group resource. Returns: A string representing the group. """ return cls._GROUP_PATH_TEMPLATE.match(group_name).get('group') def __init__(self, service_path=SERVICE_ADDRESS, port=DEFAULT_SERVICE_PORT, channel=None, metadata_transformer=None, ssl_creds=None, scopes=None, client_config=None, app_name='gax', app_version=_GAX_VERSION): """Constructor. Args: service_path (string): The domain name of the API remote host. port (int): The port on which to connect to the remote host. channel (:class:`grpc.Channel`): A ``Channel`` instance through which to make calls. ssl_creds (:class:`grpc.ChannelCredentials`): A ``ChannelCredentials`` instance for use with an SSL-enabled channel. client_config (dict): A dictionary for call options for each method. See :func:`google.gax.construct_settings` for the structure of this data. Falls back to the default config if not specified or the specified config is missing data points. metadata_transformer (Callable[[], list]): A function that creates the metadata for requests. app_name (string): The codename of the calling service. app_version (string): The version of the calling service. Returns: A ErrorGroupServiceApi object. """ if scopes is None: scopes = self._ALL_SCOPES if client_config is None: client_config = {} goog_api_client = '{}/{} {} gax/{} python/{}'.format( app_name, app_version, self._CODE_GEN_NAME_VERSION, self._GAX_VERSION, platform.python_version()) metadata = [('x-goog-api-client', goog_api_client)] default_client_config = json.loads( pkg_resources.resource_string( __name__, 'error_group_service_client_config.json').decode()) defaults = api_callable.construct_settings( 'google.devtools.clouderrorreporting.v1beta1.ErrorGroupService', default_client_config, client_config, config.STATUS_CODE_NAMES, kwargs={'metadata': metadata}) self.error_group_service_stub = config.create_stub( error_group_service_pb2.ErrorGroupServiceStub, service_path, port, ssl_creds=ssl_creds, channel=channel, metadata_transformer=metadata_transformer, scopes=scopes) self._get_group = api_callable.create_api_call( self.error_group_service_stub.GetGroup, settings=defaults['get_group']) self._update_group = api_callable.create_api_call( self.error_group_service_stub.UpdateGroup, settings=defaults['update_group']) # Service calls def get_group(self, group_name, options=None): """ Get the specified group. Example: >>> from google.cloud.gapic.errorreporting.v1beta1 import error_group_service_api >>> api = error_group_service_api.ErrorGroupServiceApi() >>> group_name = api.group_path('[PROJECT]', '[GROUP]') >>> response = api.get_group(group_name) Args: group_name (string): [Required] The group resource name. Written as <code>projects/<var>projectID</var>/groups/<var>group_name</var></code>. Call <a href=\"/error-reporting/reference/rest/v1beta1/projects.groupStats/list\"> <code>groupStats.list</code></a> to return a list of groups belonging to this project. Example: <code>projects/my-project-123/groups/my-group</code> options (:class:`google.gax.CallOptions`): Overrides the default settings for this call, e.g, timeout, retries etc. Returns: A :class:`google.devtools.clouderrorreporting.v1beta1.common_pb2.ErrorGroup` instance. Raises: :exc:`google.gax.errors.GaxError` if the RPC is aborted. :exc:`ValueError` if the parameters are invalid. """ request = error_group_service_pb2.GetGroupRequest( group_name=group_name) return self._get_group(request, options) def update_group(self, group, options=None): """ Replace the data for the specified group. Fails if the group does not exist. Example: >>> from google.cloud.gapic.errorreporting.v1beta1 import error_group_service_api >>> from google.devtools.clouderrorreporting.v1beta1 import common_pb2 >>> api = error_group_service_api.ErrorGroupServiceApi() >>> group = common_pb2.ErrorGroup() >>> response = api.update_group(group) Args: group (:class:`google.devtools.clouderrorreporting.v1beta1.common_pb2.ErrorGroup`): [Required] The group which replaces the resource on the server. options (:class:`google.gax.CallOptions`): Overrides the default settings for this call, e.g, timeout, retries etc. Returns: A :class:`google.devtools.clouderrorreporting.v1beta1.common_pb2.ErrorGroup` instance. Raises: :exc:`google.gax.errors.GaxError` if the RPC is aborted. :exc:`ValueError` if the parameters are invalid. """ request = error_group_service_pb2.UpdateGroupRequest(group=group) return self._update_group(request, options)
class OperationsApi(object): """ Manages long-running operations with an API service. When an API method normally takes long time to complete, it can be designed to return ``Operation`` to the client, and the client can use this interface to receive the real response asynchronously by polling the operation resource, or pass the operation resource to another API (such as Google Cloud Pub/Sub API) to receive the response. Any API service that returns long-running operations should implement the ``Operations`` interface so developers can have a consistent client experience. """ SERVICE_ADDRESS = 'longrunning.googleapis.com' """The default address of the service.""" DEFAULT_SERVICE_PORT = 443 """The default port of the service.""" _CODE_GEN_NAME_VERSION = 'gapic/0.1.0' _GAX_VERSION = pkg_resources.get_distribution('google-gax').version _PAGE_DESCRIPTORS = { 'list_operations': _PageDesc('page_token', 'next_page_token', 'operations') } # The scopes needed to make gRPC calls to all of the methods defined in # this service _ALL_SCOPES = () _OPERATION_PATH_PATH_TEMPLATE = path_template.PathTemplate( 'operations/{operation_path=**}') @classmethod def operation_path_path(cls, operation_path): """Returns a fully-qualified operation_path resource name string.""" return cls._OPERATION_PATH_PATH_TEMPLATE.render({ 'operation_path': operation_path, }) @classmethod def match_operation_path_from_operation_path_name(cls, operation_path_name): """Parses the operation_path from a operation_path resource. Args: operation_path_name (string): A fully-qualified path representing a operation_path resource. Returns: A string representing the operation_path. """ return cls._OPERATION_PATH_PATH_TEMPLATE.match( operation_path_name).get('operation_path') def __init__(self, service_path=SERVICE_ADDRESS, port=DEFAULT_SERVICE_PORT, channel=None, metadata_transformer=None, ssl_creds=None, scopes=None, client_config=None, app_name='gax', app_version=_GAX_VERSION): """Constructor. Args: service_path (string): The domain name of the API remote host. port (int): The port on which to connect to the remote host. channel (:class:`grpc.Channel`): A ``Channel`` instance through which to make calls. ssl_creds (:class:`grpc.ChannelCredentials`): A ``ChannelCredentials`` instance for use with an SSL-enabled channel. client_config (dict): A dictionary for call options for each method. See :func:`google.gax.construct_settings` for the structure of this data. Falls back to the default config if not specified or the specified config is missing data points. metadata_transformer (Callable[[], list]): A function that creates the metadata for requests. app_name (string): The codename of the calling service. app_version (string): The version of the calling service. Returns: A OperationsApi object. """ if scopes is None: scopes = self._ALL_SCOPES if client_config is None: client_config = {} goog_api_client = '{}/{} {} gax/{} python/{}'.format( app_name, app_version, self._CODE_GEN_NAME_VERSION, self._GAX_VERSION, platform.python_version()) metadata = [('x-goog-api-client', goog_api_client)] default_client_config = json.loads( pkg_resources.resource_string( __name__, 'operations_client_config.json').decode()) defaults = api_callable.construct_settings( 'google.longrunning.Operations', default_client_config, client_config, config.STATUS_CODE_NAMES, kwargs={'metadata': metadata}, page_descriptors=self._PAGE_DESCRIPTORS) self.operations_stub = config.create_stub( operations_pb2.OperationsStub, service_path, port, ssl_creds=ssl_creds, channel=channel, metadata_transformer=metadata_transformer, scopes=scopes) self._get_operation = api_callable.create_api_call( self.operations_stub.GetOperation, settings=defaults['get_operation']) self._list_operations = api_callable.create_api_call( self.operations_stub.ListOperations, settings=defaults['list_operations']) self._cancel_operation = api_callable.create_api_call( self.operations_stub.CancelOperation, settings=defaults['cancel_operation']) self._delete_operation = api_callable.create_api_call( self.operations_stub.DeleteOperation, settings=defaults['delete_operation']) # Service calls def get_operation(self, name, options=None): """ Gets the latest state of a long-running operation. Clients can use this method to poll the operation result at intervals as recommended by the API service. Example: >>> from google.cloud.gapic.longrunning import operations_api >>> api = operations_api.OperationsApi() >>> name = api.operation_path_path('[OPERATION_PATH]') >>> response = api.get_operation(name) Args: name (string): The name of the operation resource. options (:class:`google.gax.CallOptions`): Overrides the default settings for this call, e.g, timeout, retries etc. Returns: A :class:`google.longrunning.operations_pb2.Operation` instance. Raises: :exc:`google.gax.errors.GaxError` if the RPC is aborted. :exc:`ValueError` if the parameters are invalid. """ request = operations_pb2.GetOperationRequest(name=name) return self._get_operation(request, options) def list_operations(self, name, filter_, page_size=0, options=None): """ Lists operations that match the specified filter in the request. If the server doesn't support this method, it returns ``UNIMPLEMENTED``. NOTE: the ``name`` binding below allows API services to override the binding to use different resource name schemes, such as ``users/*/operations``. Example: >>> from google.cloud.gapic.longrunning import operations_api >>> from google.gax import CallOptions, INITIAL_PAGE >>> api = operations_api.OperationsApi() >>> name = '' >>> filter_ = '' >>> >>> # Iterate over all results >>> for element in api.list_operations(name, filter_): >>> # process element >>> pass >>> >>> # Or iterate over results one page at a time >>> for page in api.list_operations(name, filter_, options=CallOptions(page_token=INITIAL_PAGE)): >>> for element in page: >>> # process element >>> pass Args: name (string): The name of the operation collection. filter_ (string): The standard list filter. page_size (int): The maximum number of resources contained in the underlying API response. If page streaming is performed per- resource, this parameter does not affect the return value. If page streaming is performed per-page, this determines the maximum number of resources in a page. options (:class:`google.gax.CallOptions`): Overrides the default settings for this call, e.g, timeout, retries etc. Returns: A :class:`google.gax.PageIterator` instance. By default, this is an iterable of :class:`google.longrunning.operations_pb2.Operation` instances. This object can also be configured to iterate over the pages of the response through the `CallOptions` parameter. Raises: :exc:`google.gax.errors.GaxError` if the RPC is aborted. :exc:`ValueError` if the parameters are invalid. """ request = operations_pb2.ListOperationsRequest( name=name, filter=filter_, page_size=page_size) return self._list_operations(request, options) def cancel_operation(self, name, options=None): """ Starts asynchronous cancellation on a long-running operation. The server makes a best effort to cancel the operation, but success is not guaranteed. If the server doesn't support this method, it returns ``google.rpc.Code.UNIMPLEMENTED``. Clients can use ``Operations.GetOperation`` or other methods to check whether the cancellation succeeded or whether the operation completed despite cancellation. Example: >>> from google.cloud.gapic.longrunning import operations_api >>> api = operations_api.OperationsApi() >>> name = api.operation_path_path('[OPERATION_PATH]') >>> api.cancel_operation(name) Args: name (string): The name of the operation resource to be cancelled. options (:class:`google.gax.CallOptions`): Overrides the default settings for this call, e.g, timeout, retries etc. Raises: :exc:`google.gax.errors.GaxError` if the RPC is aborted. :exc:`ValueError` if the parameters are invalid. """ request = operations_pb2.CancelOperationRequest(name=name) self._cancel_operation(request, options) def delete_operation(self, name, options=None): """ Deletes a long-running operation. This method indicates that the client is no longer interested in the operation result. It does not cancel the operation. If the server doesn't support this method, it returns ``google.rpc.Code.UNIMPLEMENTED``. Example: >>> from google.cloud.gapic.longrunning import operations_api >>> api = operations_api.OperationsApi() >>> name = api.operation_path_path('[OPERATION_PATH]') >>> api.delete_operation(name) Args: name (string): The name of the operation resource to be deleted. options (:class:`google.gax.CallOptions`): Overrides the default settings for this call, e.g, timeout, retries etc. Raises: :exc:`google.gax.errors.GaxError` if the RPC is aborted. :exc:`ValueError` if the parameters are invalid. """ request = operations_pb2.DeleteOperationRequest(name=name) self._delete_operation(request, options)
class DatabaseAdminClient(object): """ Cloud Spanner Database Admin API The Cloud Spanner Database Admin API can be used to create, drop, and list databases. It also enables updating the schema of pre-existing databases. """ SERVICE_ADDRESS = 'spanner.googleapis.com' """The default address of the service.""" DEFAULT_SERVICE_PORT = 443 """The default port of the service.""" _PAGE_DESCRIPTORS = { 'list_databases': _PageDesc('page_token', 'next_page_token', 'databases') } # The scopes needed to make gRPC calls to all of the methods defined in # this service _ALL_SCOPES = ( 'https://www.googleapis.com/auth/cloud-platform', 'https://www.googleapis.com/auth/spanner.admin', ) _INSTANCE_PATH_TEMPLATE = path_template.PathTemplate( 'projects/{project}/instances/{instance}') _DATABASE_PATH_TEMPLATE = path_template.PathTemplate( 'projects/{project}/instances/{instance}/databases/{database}') @classmethod def instance_path(cls, project, instance): """Returns a fully-qualified instance resource name string.""" return cls._INSTANCE_PATH_TEMPLATE.render({ 'project': project, 'instance': instance, }) @classmethod def database_path(cls, project, instance, database): """Returns a fully-qualified database resource name string.""" return cls._DATABASE_PATH_TEMPLATE.render({ 'project': project, 'instance': instance, 'database': database, }) @classmethod def match_project_from_instance_name(cls, instance_name): """Parses the project from a instance resource. Args: instance_name (str): A fully-qualified path representing a instance resource. Returns: A string representing the project. """ return cls._INSTANCE_PATH_TEMPLATE.match(instance_name).get('project') @classmethod def match_instance_from_instance_name(cls, instance_name): """Parses the instance from a instance resource. Args: instance_name (str): A fully-qualified path representing a instance resource. Returns: A string representing the instance. """ return cls._INSTANCE_PATH_TEMPLATE.match(instance_name).get('instance') @classmethod def match_project_from_database_name(cls, database_name): """Parses the project from a database resource. Args: database_name (str): A fully-qualified path representing a database resource. Returns: A string representing the project. """ return cls._DATABASE_PATH_TEMPLATE.match(database_name).get('project') @classmethod def match_instance_from_database_name(cls, database_name): """Parses the instance from a database resource. Args: database_name (str): A fully-qualified path representing a database resource. Returns: A string representing the instance. """ return cls._DATABASE_PATH_TEMPLATE.match(database_name).get('instance') @classmethod def match_database_from_database_name(cls, database_name): """Parses the database from a database resource. Args: database_name (str): A fully-qualified path representing a database resource. Returns: A string representing the database. """ return cls._DATABASE_PATH_TEMPLATE.match(database_name).get('database') def __init__(self, channel=None, credentials=None, ssl_credentials=None, scopes=None, client_config=None, lib_name=None, lib_version='', metrics_headers=()): """Constructor. Args: channel (~grpc.Channel): A ``Channel`` instance through which to make calls. credentials (~google.auth.credentials.Credentials): The authorization credentials to attach to requests. These credentials identify this application to the service. ssl_credentials (~grpc.ChannelCredentials): A ``ChannelCredentials`` instance for use with an SSL-enabled channel. scopes (Sequence[str]): A list of OAuth2 scopes to attach to requests. client_config (dict): A dictionary for call options for each method. See :func:`google.gax.construct_settings` for the structure of this data. Falls back to the default config if not specified or the specified config is missing data points. lib_name (str): The API library software used for calling the service. (Unless you are writing an API client itself, leave this as default.) lib_version (str): The API library software version used for calling the service. (Unless you are writing an API client itself, leave this as default.) metrics_headers (dict): A dictionary of values for tracking client library metrics. Ultimately serializes to a string (e.g. 'foo/1.2.3 bar/3.14.1'). This argument should be considered private. """ # Unless the calling application specifically requested # OAuth scopes, request everything. if scopes is None: scopes = self._ALL_SCOPES # Initialize an empty client config, if none is set. if client_config is None: client_config = {} # Initialize metrics_headers as an ordered dictionary # (cuts down on cardinality of the resulting string slightly). metrics_headers = collections.OrderedDict(metrics_headers) metrics_headers['gl-python'] = platform.python_version() # The library may or may not be set, depending on what is # calling this client. Newer client libraries set the library name # and version. if lib_name: metrics_headers[lib_name] = lib_version # Finally, track the GAPIC package version. metrics_headers['gapic'] = pkg_resources.get_distribution( 'google-cloud-spanner', ).version # Load the configuration defaults. defaults = api_callable.construct_settings( 'google.spanner.admin.database.v1.DatabaseAdmin', database_admin_client_config.config, client_config, config.STATUS_CODE_NAMES, metrics_headers=metrics_headers, page_descriptors=self._PAGE_DESCRIPTORS, ) self.database_admin_stub = config.create_stub( spanner_database_admin_pb2.DatabaseAdminStub, channel=channel, service_path=self.SERVICE_ADDRESS, service_port=self.DEFAULT_SERVICE_PORT, credentials=credentials, scopes=scopes, ssl_credentials=ssl_credentials) self.operations_client = operations_client.OperationsClient( service_path=self.SERVICE_ADDRESS, channel=channel, credentials=credentials, ssl_credentials=ssl_credentials, scopes=scopes, client_config=client_config, metrics_headers=metrics_headers, ) self._list_databases = api_callable.create_api_call( self.database_admin_stub.ListDatabases, settings=defaults['list_databases']) self._create_database = api_callable.create_api_call( self.database_admin_stub.CreateDatabase, settings=defaults['create_database']) self._get_database = api_callable.create_api_call( self.database_admin_stub.GetDatabase, settings=defaults['get_database']) self._update_database_ddl = api_callable.create_api_call( self.database_admin_stub.UpdateDatabaseDdl, settings=defaults['update_database_ddl']) self._drop_database = api_callable.create_api_call( self.database_admin_stub.DropDatabase, settings=defaults['drop_database']) self._get_database_ddl = api_callable.create_api_call( self.database_admin_stub.GetDatabaseDdl, settings=defaults['get_database_ddl']) self._set_iam_policy = api_callable.create_api_call( self.database_admin_stub.SetIamPolicy, settings=defaults['set_iam_policy']) self._get_iam_policy = api_callable.create_api_call( self.database_admin_stub.GetIamPolicy, settings=defaults['get_iam_policy']) self._test_iam_permissions = api_callable.create_api_call( self.database_admin_stub.TestIamPermissions, settings=defaults['test_iam_permissions']) # Service calls def list_databases(self, parent, page_size=None, options=None): """ Lists Cloud Spanner databases. Example: >>> from google.cloud import spanner_admin_database_v1 >>> from google.gax import CallOptions, INITIAL_PAGE >>> >>> client = spanner_admin_database_v1.DatabaseAdminClient() >>> >>> parent = client.instance_path('[PROJECT]', '[INSTANCE]') >>> >>> >>> # Iterate over all results >>> for element in client.list_databases(parent): ... # process element ... pass >>> >>> # Or iterate over results one page at a time >>> for page in client.list_databases(parent, options=CallOptions(page_token=INITIAL_PAGE)): ... for element in page: ... # process element ... pass Args: parent (str): Required. The instance whose databases should be listed. Values are of the form ``projects/<project>/instances/<instance>``. page_size (int): The maximum number of resources contained in the underlying API response. If page streaming is performed per- resource, this parameter does not affect the return value. If page streaming is performed per-page, this determines the maximum number of resources in a page. options (~google.gax.CallOptions): Overrides the default settings for this call, e.g, timeout, retries etc. Returns: A :class:`~google.gax.PageIterator` instance. By default, this is an iterable of :class:`~google.cloud.spanner_admin_database_v1.types.Database` instances. This object can also be configured to iterate over the pages of the response through the `options` parameter. Raises: :exc:`google.gax.errors.GaxError` if the RPC is aborted. :exc:`ValueError` if the parameters are invalid. """ request = spanner_database_admin_pb2.ListDatabasesRequest( parent=parent, page_size=page_size) return self._list_databases(request, options) def create_database(self, parent, create_statement, extra_statements=None, options=None): """ Creates a new Cloud Spanner database and starts to prepare it for serving. The returned ``long-running operation`` will have a name of the format ``<database_name>/operations/<operation_id>`` and can be used to track preparation of the database. The ``metadata`` field type is ``CreateDatabaseMetadata``. The ``response`` field type is ``Database``, if successful. Example: >>> from google.cloud import spanner_admin_database_v1 >>> >>> client = spanner_admin_database_v1.DatabaseAdminClient() >>> >>> parent = client.instance_path('[PROJECT]', '[INSTANCE]') >>> create_statement = '' >>> >>> response = client.create_database(parent, create_statement) >>> >>> def callback(operation_future): ... # Handle result. ... result = operation_future.result() >>> >>> response.add_done_callback(callback) >>> >>> # Handle metadata. >>> metadata = response.metadata() Args: parent (str): Required. The name of the instance that will serve the new database. Values are of the form ``projects/<project>/instances/<instance>``. create_statement (str): 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. extra_statements (list[str]): 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. options (~google.gax.CallOptions): Overrides the default settings for this call, e.g, timeout, retries etc. Returns: A :class:`~google.cloud.spanner_admin_database_v1.types._OperationFuture` instance. Raises: :exc:`google.gax.errors.GaxError` if the RPC is aborted. :exc:`ValueError` if the parameters are invalid. """ request = spanner_database_admin_pb2.CreateDatabaseRequest( parent=parent, create_statement=create_statement, extra_statements=extra_statements) return google.gax._OperationFuture( self._create_database(request, options), self.operations_client, spanner_database_admin_pb2.Database, spanner_database_admin_pb2.CreateDatabaseMetadata, options) def get_database(self, name, options=None): """ Gets the state of a Cloud Spanner database. Example: >>> from google.cloud import spanner_admin_database_v1 >>> >>> client = spanner_admin_database_v1.DatabaseAdminClient() >>> >>> name = client.database_path('[PROJECT]', '[INSTANCE]', '[DATABASE]') >>> >>> response = client.get_database(name) Args: name (str): Required. The name of the requested database. Values are of the form ``projects/<project>/instances/<instance>/databases/<database>``. options (~google.gax.CallOptions): Overrides the default settings for this call, e.g, timeout, retries etc. Returns: A :class:`~google.cloud.spanner_admin_database_v1.types.Database` instance. Raises: :exc:`google.gax.errors.GaxError` if the RPC is aborted. :exc:`ValueError` if the parameters are invalid. """ request = spanner_database_admin_pb2.GetDatabaseRequest(name=name) return self._get_database(request, options) def update_database_ddl(self, database, statements, operation_id=None, options=None): """ Updates the schema of a Cloud Spanner database by creating/altering/dropping tables, columns, indexes, etc. The returned ``long-running operation`` will have a name of the format ``<database_name>/operations/<operation_id>`` and can be used to track execution of the schema change(s). The ``metadata`` field type is ``UpdateDatabaseDdlMetadata``. The operation has no response. Example: >>> from google.cloud import spanner_admin_database_v1 >>> >>> client = spanner_admin_database_v1.DatabaseAdminClient() >>> >>> database = client.database_path('[PROJECT]', '[INSTANCE]', '[DATABASE]') >>> statements = [] >>> >>> response = client.update_database_ddl(database, statements) >>> >>> def callback(operation_future): ... # Handle result. ... result = operation_future.result() >>> >>> response.add_done_callback(callback) >>> >>> # Handle metadata. >>> metadata = response.metadata() Args: database (str): Required. The database to update. statements (list[str]): DDL statements to be applied to the database. operation_id (str): 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 ``Operation``. Specifying an explicit operation ID simplifies determining whether the statements were executed in the event that the ``UpdateDatabaseDdl`` call is replayed, or the return value is otherwise lost: the ``database`` and ``operation_id`` fields can be combined to form the ``name`` of the resulting ``longrunning.Operation``: ``<database>/operations/<operation_id>``. ``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, ``UpdateDatabaseDdl`` returns ``ALREADY_EXISTS``. options (~google.gax.CallOptions): Overrides the default settings for this call, e.g, timeout, retries etc. Returns: A :class:`~google.cloud.spanner_admin_database_v1.types._OperationFuture` instance. Raises: :exc:`google.gax.errors.GaxError` if the RPC is aborted. :exc:`ValueError` if the parameters are invalid. """ request = spanner_database_admin_pb2.UpdateDatabaseDdlRequest( database=database, statements=statements, operation_id=operation_id) return google.gax._OperationFuture( self._update_database_ddl(request, options), self.operations_client, empty_pb2.Empty, spanner_database_admin_pb2.UpdateDatabaseDdlMetadata, options) def drop_database(self, database, options=None): """ Drops (aka deletes) a Cloud Spanner database. Example: >>> from google.cloud import spanner_admin_database_v1 >>> >>> client = spanner_admin_database_v1.DatabaseAdminClient() >>> >>> database = client.database_path('[PROJECT]', '[INSTANCE]', '[DATABASE]') >>> >>> client.drop_database(database) Args: database (str): Required. The database to be dropped. options (~google.gax.CallOptions): Overrides the default settings for this call, e.g, timeout, retries etc. Raises: :exc:`google.gax.errors.GaxError` if the RPC is aborted. :exc:`ValueError` if the parameters are invalid. """ request = spanner_database_admin_pb2.DropDatabaseRequest( database=database) self._drop_database(request, options) def get_database_ddl(self, database, options=None): """ Returns the schema of a Cloud Spanner database as a list of formatted DDL statements. This method does not show pending schema updates, those may be queried using the ``Operations`` API. Example: >>> from google.cloud import spanner_admin_database_v1 >>> >>> client = spanner_admin_database_v1.DatabaseAdminClient() >>> >>> database = client.database_path('[PROJECT]', '[INSTANCE]', '[DATABASE]') >>> >>> response = client.get_database_ddl(database) Args: database (str): Required. The database whose schema we wish to get. options (~google.gax.CallOptions): Overrides the default settings for this call, e.g, timeout, retries etc. Returns: A :class:`~google.cloud.spanner_admin_database_v1.types.GetDatabaseDdlResponse` instance. Raises: :exc:`google.gax.errors.GaxError` if the RPC is aborted. :exc:`ValueError` if the parameters are invalid. """ request = spanner_database_admin_pb2.GetDatabaseDdlRequest( database=database) return self._get_database_ddl(request, options) def set_iam_policy(self, resource, policy, options=None): """ Sets the access control policy on a database resource. Replaces any existing policy. Authorization requires ``spanner.databases.setIamPolicy`` permission on ``resource``. Example: >>> from google.cloud import spanner_admin_database_v1 >>> >>> client = spanner_admin_database_v1.DatabaseAdminClient() >>> >>> resource = client.database_path('[PROJECT]', '[INSTANCE]', '[DATABASE]') >>> policy = {} >>> >>> response = client.set_iam_policy(resource, policy) Args: resource (str): REQUIRED: The resource for which the policy is being specified. ``resource`` is usually specified as a path. For example, a Project resource is specified as ``projects/{project}``. policy (Union[dict, ~google.cloud.spanner_admin_database_v1.types.Policy]): REQUIRED: The complete policy to be applied to the ``resource``. The size of the policy is limited to a few 10s of KB. An empty policy is a valid policy but certain Cloud Platform services (such as Projects) might reject them. If a dict is provided, it must be of the same form as the protobuf message :class:`~google.cloud.spanner_admin_database_v1.types.Policy` options (~google.gax.CallOptions): Overrides the default settings for this call, e.g, timeout, retries etc. Returns: A :class:`~google.cloud.spanner_admin_database_v1.types.Policy` instance. Raises: :exc:`google.gax.errors.GaxError` if the RPC is aborted. :exc:`ValueError` if the parameters are invalid. """ request = iam_policy_pb2.SetIamPolicyRequest(resource=resource, policy=policy) return self._set_iam_policy(request, options) def get_iam_policy(self, resource, options=None): """ Gets the access control policy for a database resource. Returns an empty policy if a database exists but does not have a policy set. Authorization requires ``spanner.databases.getIamPolicy`` permission on ``resource``. Example: >>> from google.cloud import spanner_admin_database_v1 >>> >>> client = spanner_admin_database_v1.DatabaseAdminClient() >>> >>> resource = client.database_path('[PROJECT]', '[INSTANCE]', '[DATABASE]') >>> >>> response = client.get_iam_policy(resource) Args: resource (str): REQUIRED: The resource for which the policy is being requested. ``resource`` is usually specified as a path. For example, a Project resource is specified as ``projects/{project}``. options (~google.gax.CallOptions): Overrides the default settings for this call, e.g, timeout, retries etc. Returns: A :class:`~google.cloud.spanner_admin_database_v1.types.Policy` instance. Raises: :exc:`google.gax.errors.GaxError` if the RPC is aborted. :exc:`ValueError` if the parameters are invalid. """ request = iam_policy_pb2.GetIamPolicyRequest(resource=resource) return self._get_iam_policy(request, options) def test_iam_permissions(self, resource, permissions, options=None): """ Returns permissions that the caller has on the specified database resource. Attempting this RPC on a non-existent Cloud Spanner database will result in a NOT_FOUND error if the user has ``spanner.databases.list`` permission on the containing Cloud Spanner instance. Otherwise returns an empty set of permissions. Example: >>> from google.cloud import spanner_admin_database_v1 >>> >>> client = spanner_admin_database_v1.DatabaseAdminClient() >>> >>> resource = client.database_path('[PROJECT]', '[INSTANCE]', '[DATABASE]') >>> permissions = [] >>> >>> response = client.test_iam_permissions(resource, permissions) Args: resource (str): REQUIRED: The resource for which the policy detail is being requested. ``resource`` is usually specified as a path. For example, a Project resource is specified as ``projects/{project}``. permissions (list[str]): The set of permissions to check for the ``resource``. Permissions with wildcards (such as '*' or 'storage.*') are not allowed. For more information see `IAM Overview <https://cloud.google.com/iam/docs/overview#permissions>`_. options (~google.gax.CallOptions): Overrides the default settings for this call, e.g, timeout, retries etc. Returns: A :class:`~google.cloud.spanner_admin_database_v1.types.TestIamPermissionsResponse` instance. Raises: :exc:`google.gax.errors.GaxError` if the RPC is aborted. :exc:`ValueError` if the parameters are invalid. """ request = iam_policy_pb2.TestIamPermissionsRequest( resource=resource, permissions=permissions) return self._test_iam_permissions(request, options)
class SpannerClient(object): """ Cloud Spanner API The Cloud Spanner API can be used to manage sessions and execute transactions on data stored in Cloud Spanner databases. """ SERVICE_ADDRESS = 'spanner.googleapis.com' """The default address of the service.""" DEFAULT_SERVICE_PORT = 443 """The default port of the service.""" # The scopes needed to make gRPC calls to all of the methods defined in # this service _ALL_SCOPES = ( 'https://www.googleapis.com/auth/cloud-platform', 'https://www.googleapis.com/auth/spanner.data', ) _DATABASE_PATH_TEMPLATE = path_template.PathTemplate( 'projects/{project}/instances/{instance}/databases/{database}') _SESSION_PATH_TEMPLATE = path_template.PathTemplate( 'projects/{project}/instances/{instance}/databases/{database}/sessions/{session}' ) @classmethod def database_path(cls, project, instance, database): """Returns a fully-qualified database resource name string.""" return cls._DATABASE_PATH_TEMPLATE.render({ 'project': project, 'instance': instance, 'database': database, }) @classmethod def session_path(cls, project, instance, database, session): """Returns a fully-qualified session resource name string.""" return cls._SESSION_PATH_TEMPLATE.render({ 'project': project, 'instance': instance, 'database': database, 'session': session, }) @classmethod def match_project_from_database_name(cls, database_name): """Parses the project from a database resource. Args: database_name (str): A fully-qualified path representing a database resource. Returns: A string representing the project. """ return cls._DATABASE_PATH_TEMPLATE.match(database_name).get('project') @classmethod def match_instance_from_database_name(cls, database_name): """Parses the instance from a database resource. Args: database_name (str): A fully-qualified path representing a database resource. Returns: A string representing the instance. """ return cls._DATABASE_PATH_TEMPLATE.match(database_name).get('instance') @classmethod def match_database_from_database_name(cls, database_name): """Parses the database from a database resource. Args: database_name (str): A fully-qualified path representing a database resource. Returns: A string representing the database. """ return cls._DATABASE_PATH_TEMPLATE.match(database_name).get('database') @classmethod def match_project_from_session_name(cls, session_name): """Parses the project from a session resource. Args: session_name (str): A fully-qualified path representing a session resource. Returns: A string representing the project. """ return cls._SESSION_PATH_TEMPLATE.match(session_name).get('project') @classmethod def match_instance_from_session_name(cls, session_name): """Parses the instance from a session resource. Args: session_name (str): A fully-qualified path representing a session resource. Returns: A string representing the instance. """ return cls._SESSION_PATH_TEMPLATE.match(session_name).get('instance') @classmethod def match_database_from_session_name(cls, session_name): """Parses the database from a session resource. Args: session_name (str): A fully-qualified path representing a session resource. Returns: A string representing the database. """ return cls._SESSION_PATH_TEMPLATE.match(session_name).get('database') @classmethod def match_session_from_session_name(cls, session_name): """Parses the session from a session resource. Args: session_name (str): A fully-qualified path representing a session resource. Returns: A string representing the session. """ return cls._SESSION_PATH_TEMPLATE.match(session_name).get('session') def __init__(self, channel=None, credentials=None, ssl_credentials=None, scopes=None, client_config=None, lib_name=None, lib_version='', metrics_headers=()): """Constructor. Args: channel (~grpc.Channel): A ``Channel`` instance through which to make calls. credentials (~google.auth.credentials.Credentials): The authorization credentials to attach to requests. These credentials identify this application to the service. ssl_credentials (~grpc.ChannelCredentials): A ``ChannelCredentials`` instance for use with an SSL-enabled channel. scopes (Sequence[str]): A list of OAuth2 scopes to attach to requests. client_config (dict): A dictionary for call options for each method. See :func:`google.gax.construct_settings` for the structure of this data. Falls back to the default config if not specified or the specified config is missing data points. lib_name (str): The API library software used for calling the service. (Unless you are writing an API client itself, leave this as default.) lib_version (str): The API library software version used for calling the service. (Unless you are writing an API client itself, leave this as default.) metrics_headers (dict): A dictionary of values for tracking client library metrics. Ultimately serializes to a string (e.g. 'foo/1.2.3 bar/3.14.1'). This argument should be considered private. """ # Unless the calling application specifically requested # OAuth scopes, request everything. if scopes is None: scopes = self._ALL_SCOPES # Initialize an empty client config, if none is set. if client_config is None: client_config = {} # Initialize metrics_headers as an ordered dictionary # (cuts down on cardinality of the resulting string slightly). metrics_headers = collections.OrderedDict(metrics_headers) metrics_headers['gl-python'] = platform.python_version() # The library may or may not be set, depending on what is # calling this client. Newer client libraries set the library name # and version. if lib_name: metrics_headers[lib_name] = lib_version # Finally, track the GAPIC package version. metrics_headers['gapic'] = pkg_resources.get_distribution( 'google-cloud-spanner', ).version # Load the configuration defaults. defaults = api_callable.construct_settings( 'google.spanner.v1.Spanner', spanner_client_config.config, client_config, config.STATUS_CODE_NAMES, metrics_headers=metrics_headers, ) self.spanner_stub = config.create_stub( spanner_pb2.SpannerStub, channel=channel, service_path=self.SERVICE_ADDRESS, service_port=self.DEFAULT_SERVICE_PORT, credentials=credentials, scopes=scopes, ssl_credentials=ssl_credentials) self._create_session = api_callable.create_api_call( self.spanner_stub.CreateSession, settings=defaults['create_session']) self._get_session = api_callable.create_api_call( self.spanner_stub.GetSession, settings=defaults['get_session']) self._delete_session = api_callable.create_api_call( self.spanner_stub.DeleteSession, settings=defaults['delete_session']) self._execute_sql = api_callable.create_api_call( self.spanner_stub.ExecuteSql, settings=defaults['execute_sql']) self._execute_streaming_sql = api_callable.create_api_call( self.spanner_stub.ExecuteStreamingSql, settings=defaults['execute_streaming_sql']) self._read = api_callable.create_api_call( self.spanner_stub.Read, settings=defaults['read']) self._streaming_read = api_callable.create_api_call( self.spanner_stub.StreamingRead, settings=defaults['streaming_read']) self._begin_transaction = api_callable.create_api_call( self.spanner_stub.BeginTransaction, settings=defaults['begin_transaction']) self._commit = api_callable.create_api_call( self.spanner_stub.Commit, settings=defaults['commit']) self._rollback = api_callable.create_api_call( self.spanner_stub.Rollback, settings=defaults['rollback']) # Service calls def create_session(self, database, options=None): """ Creates a new session. A session can be used to perform transactions that read and/or modify data in a Cloud Spanner database. Sessions are meant to be reused for many consecutive transactions. Sessions can only execute one transaction at a time. To execute multiple concurrent read-write/write-only transactions, create multiple sessions. Note that standalone reads and queries use a transaction internally, and count toward the one transaction limit. Cloud Spanner limits the number of sessions that can exist at any given time; thus, it is a good idea to delete idle and/or unneeded sessions. Aside from explicit deletes, Cloud Spanner can delete sessions for which no operations are sent for more than an hour. If a session is deleted, requests to it return ``NOT_FOUND``. Idle sessions can be kept alive by sending a trivial SQL query periodically, e.g., ``\"SELECT 1\"``. Example: >>> from google.cloud import spanner_v1 >>> >>> client = spanner_v1.SpannerClient() >>> >>> database = client.database_path('[PROJECT]', '[INSTANCE]', '[DATABASE]') >>> >>> response = client.create_session(database) Args: database (str): Required. The database in which the new session is created. options (~google.gax.CallOptions): Overrides the default settings for this call, e.g, timeout, retries etc. Returns: A :class:`~google.cloud.spanner_v1.types.Session` instance. Raises: :exc:`google.gax.errors.GaxError` if the RPC is aborted. :exc:`ValueError` if the parameters are invalid. """ request = spanner_pb2.CreateSessionRequest(database=database) return self._create_session(request, options) def get_session(self, name, options=None): """ Gets a session. Returns ``NOT_FOUND`` if the session does not exist. This is mainly useful for determining whether a session is still alive. Example: >>> from google.cloud import spanner_v1 >>> >>> client = spanner_v1.SpannerClient() >>> >>> name = client.session_path('[PROJECT]', '[INSTANCE]', '[DATABASE]', '[SESSION]') >>> >>> response = client.get_session(name) Args: name (str): Required. The name of the session to retrieve. options (~google.gax.CallOptions): Overrides the default settings for this call, e.g, timeout, retries etc. Returns: A :class:`~google.cloud.spanner_v1.types.Session` instance. Raises: :exc:`google.gax.errors.GaxError` if the RPC is aborted. :exc:`ValueError` if the parameters are invalid. """ request = spanner_pb2.GetSessionRequest(name=name) return self._get_session(request, options) def delete_session(self, name, options=None): """ Ends a session, releasing server resources associated with it. Example: >>> from google.cloud import spanner_v1 >>> >>> client = spanner_v1.SpannerClient() >>> >>> name = client.session_path('[PROJECT]', '[INSTANCE]', '[DATABASE]', '[SESSION]') >>> >>> client.delete_session(name) Args: name (str): Required. The name of the session to delete. options (~google.gax.CallOptions): Overrides the default settings for this call, e.g, timeout, retries etc. Raises: :exc:`google.gax.errors.GaxError` if the RPC is aborted. :exc:`ValueError` if the parameters are invalid. """ request = spanner_pb2.DeleteSessionRequest(name=name) self._delete_session(request, options) def execute_sql(self, session, sql, transaction=None, params=None, param_types=None, resume_token=None, query_mode=None, options=None): """ Executes an SQL query, returning all rows in a single reply. This method cannot be used to return a result set larger than 10 MiB; if the query yields more data than that, the query fails with a ``FAILED_PRECONDITION`` error. Queries inside read-write transactions might return ``ABORTED``. If this occurs, the application should restart the transaction from the beginning. See ``Transaction`` for more details. Larger result sets can be fetched in streaming fashion by calling ``ExecuteStreamingSql`` instead. Example: >>> from google.cloud import spanner_v1 >>> >>> client = spanner_v1.SpannerClient() >>> >>> session = client.session_path('[PROJECT]', '[INSTANCE]', '[DATABASE]', '[SESSION]') >>> sql = '' >>> >>> response = client.execute_sql(session, sql) Args: session (str): Required. The session in which the SQL query should be performed. sql (str): Required. The SQL query string. transaction (Union[dict, ~google.cloud.spanner_v1.types.TransactionSelector]): The transaction to use. If none is provided, the default is a temporary read-only transaction with strong concurrency. If a dict is provided, it must be of the same form as the protobuf message :class:`~google.cloud.spanner_v1.types.TransactionSelector` params (Union[dict, ~google.cloud.spanner_v1.types.Struct]): 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. If a dict is provided, it must be of the same form as the protobuf message :class:`~google.cloud.spanner_v1.types.Struct` param_types (dict[str -> Union[dict, ~google.cloud.spanner_v1.types.Type]]): 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 ``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 ``Type`` for more information about SQL types. If a dict is provided, it must be of the same form as the protobuf message :class:`~google.cloud.spanner_v1.types.Type` resume_token (bytes): If this request is resuming a previously interrupted SQL query execution, ``resume_token`` should be copied from the last ``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. query_mode (~google.cloud.spanner_v1.types.QueryMode): Used to control the amount of debugging information returned in ``ResultSetStats``. options (~google.gax.CallOptions): Overrides the default settings for this call, e.g, timeout, retries etc. Returns: A :class:`~google.cloud.spanner_v1.types.ResultSet` instance. Raises: :exc:`google.gax.errors.GaxError` if the RPC is aborted. :exc:`ValueError` if the parameters are invalid. """ request = spanner_pb2.ExecuteSqlRequest( session=session, sql=sql, transaction=transaction, params=params, param_types=param_types, resume_token=resume_token, query_mode=query_mode) return self._execute_sql(request, options) def execute_streaming_sql(self, session, sql, transaction=None, params=None, param_types=None, resume_token=None, query_mode=None, options=None): """ Like ``ExecuteSql``, except returns the result set as a stream. Unlike ``ExecuteSql``, there is no limit on the size of the returned result set. However, no individual row in the result set can exceed 100 MiB, and no column value can exceed 10 MiB. Example: >>> from google.cloud import spanner_v1 >>> >>> client = spanner_v1.SpannerClient() >>> >>> session = client.session_path('[PROJECT]', '[INSTANCE]', '[DATABASE]', '[SESSION]') >>> sql = '' >>> >>> for element in client.execute_streaming_sql(session, sql): ... # process element ... pass Args: session (str): Required. The session in which the SQL query should be performed. sql (str): Required. The SQL query string. transaction (Union[dict, ~google.cloud.spanner_v1.types.TransactionSelector]): The transaction to use. If none is provided, the default is a temporary read-only transaction with strong concurrency. If a dict is provided, it must be of the same form as the protobuf message :class:`~google.cloud.spanner_v1.types.TransactionSelector` params (Union[dict, ~google.cloud.spanner_v1.types.Struct]): 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. If a dict is provided, it must be of the same form as the protobuf message :class:`~google.cloud.spanner_v1.types.Struct` param_types (dict[str -> Union[dict, ~google.cloud.spanner_v1.types.Type]]): 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 ``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 ``Type`` for more information about SQL types. If a dict is provided, it must be of the same form as the protobuf message :class:`~google.cloud.spanner_v1.types.Type` resume_token (bytes): If this request is resuming a previously interrupted SQL query execution, ``resume_token`` should be copied from the last ``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. query_mode (~google.cloud.spanner_v1.types.QueryMode): Used to control the amount of debugging information returned in ``ResultSetStats``. options (~google.gax.CallOptions): Overrides the default settings for this call, e.g, timeout, retries etc. Returns: Iterable[~google.cloud.spanner_v1.types.PartialResultSet]. Raises: :exc:`google.gax.errors.GaxError` if the RPC is aborted. :exc:`ValueError` if the parameters are invalid. """ request = spanner_pb2.ExecuteSqlRequest( session=session, sql=sql, transaction=transaction, params=params, param_types=param_types, resume_token=resume_token, query_mode=query_mode) return self._execute_streaming_sql(request, options) def read(self, session, table, columns, key_set, transaction=None, index=None, limit=None, resume_token=None, options=None): """ Reads rows from the database using key lookups and scans, as a simple key/value style alternative to ``ExecuteSql``. This method cannot be used to return a result set larger than 10 MiB; if the read matches more data than that, the read fails with a ``FAILED_PRECONDITION`` error. Reads inside read-write transactions might return ``ABORTED``. If this occurs, the application should restart the transaction from the beginning. See ``Transaction`` for more details. Larger result sets can be yielded in streaming fashion by calling ``StreamingRead`` instead. Example: >>> from google.cloud import spanner_v1 >>> >>> client = spanner_v1.SpannerClient() >>> >>> session = client.session_path('[PROJECT]', '[INSTANCE]', '[DATABASE]', '[SESSION]') >>> table = '' >>> columns = [] >>> key_set = {} >>> >>> response = client.read(session, table, columns, key_set) Args: session (str): Required. The session in which the read should be performed. table (str): Required. The name of the table in the database to be read. columns (list[str]): The columns of ``table`` to be returned for each row matching this request. key_set (Union[dict, ~google.cloud.spanner_v1.types.KeySet]): Required. ``key_set`` identifies the rows to be yielded. ``key_set`` names the primary keys of the rows in ``table`` to be yielded, unless ``index`` is present. If ``index`` is present, then ``key_set`` instead names index keys in ``index``. Rows are yielded in table primary key order (if ``index`` is empty) or index key order (if ``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. If a dict is provided, it must be of the same form as the protobuf message :class:`~google.cloud.spanner_v1.types.KeySet` transaction (Union[dict, ~google.cloud.spanner_v1.types.TransactionSelector]): The transaction to use. If none is provided, the default is a temporary read-only transaction with strong concurrency. If a dict is provided, it must be of the same form as the protobuf message :class:`~google.cloud.spanner_v1.types.TransactionSelector` index (str): If non-empty, the name of an index on ``table``. This index is used instead of the table primary key when interpreting ``key_set`` and sorting result rows. See ``key_set`` for further information. limit (long): If greater than zero, only the first ``limit`` rows are yielded. If ``limit`` is zero, the default is no limit. resume_token (bytes): If this request is resuming a previously interrupted read, ``resume_token`` should be copied from the last ``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. options (~google.gax.CallOptions): Overrides the default settings for this call, e.g, timeout, retries etc. Returns: A :class:`~google.cloud.spanner_v1.types.ResultSet` instance. Raises: :exc:`google.gax.errors.GaxError` if the RPC is aborted. :exc:`ValueError` if the parameters are invalid. """ request = spanner_pb2.ReadRequest( session=session, table=table, columns=columns, key_set=key_set, transaction=transaction, index=index, limit=limit, resume_token=resume_token) return self._read(request, options) def streaming_read(self, session, table, columns, key_set, transaction=None, index=None, limit=None, resume_token=None, options=None): """ Like ``Read``, except returns the result set as a stream. Unlike ``Read``, there is no limit on the size of the returned result set. However, no individual row in the result set can exceed 100 MiB, and no column value can exceed 10 MiB. Example: >>> from google.cloud import spanner_v1 >>> >>> client = spanner_v1.SpannerClient() >>> >>> session = client.session_path('[PROJECT]', '[INSTANCE]', '[DATABASE]', '[SESSION]') >>> table = '' >>> columns = [] >>> key_set = {} >>> >>> for element in client.streaming_read(session, table, columns, key_set): ... # process element ... pass Args: session (str): Required. The session in which the read should be performed. table (str): Required. The name of the table in the database to be read. columns (list[str]): The columns of ``table`` to be returned for each row matching this request. key_set (Union[dict, ~google.cloud.spanner_v1.types.KeySet]): Required. ``key_set`` identifies the rows to be yielded. ``key_set`` names the primary keys of the rows in ``table`` to be yielded, unless ``index`` is present. If ``index`` is present, then ``key_set`` instead names index keys in ``index``. Rows are yielded in table primary key order (if ``index`` is empty) or index key order (if ``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. If a dict is provided, it must be of the same form as the protobuf message :class:`~google.cloud.spanner_v1.types.KeySet` transaction (Union[dict, ~google.cloud.spanner_v1.types.TransactionSelector]): The transaction to use. If none is provided, the default is a temporary read-only transaction with strong concurrency. If a dict is provided, it must be of the same form as the protobuf message :class:`~google.cloud.spanner_v1.types.TransactionSelector` index (str): If non-empty, the name of an index on ``table``. This index is used instead of the table primary key when interpreting ``key_set`` and sorting result rows. See ``key_set`` for further information. limit (long): If greater than zero, only the first ``limit`` rows are yielded. If ``limit`` is zero, the default is no limit. resume_token (bytes): If this request is resuming a previously interrupted read, ``resume_token`` should be copied from the last ``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. options (~google.gax.CallOptions): Overrides the default settings for this call, e.g, timeout, retries etc. Returns: Iterable[~google.cloud.spanner_v1.types.PartialResultSet]. Raises: :exc:`google.gax.errors.GaxError` if the RPC is aborted. :exc:`ValueError` if the parameters are invalid. """ request = spanner_pb2.ReadRequest( session=session, table=table, columns=columns, key_set=key_set, transaction=transaction, index=index, limit=limit, resume_token=resume_token) return self._streaming_read(request, options) def begin_transaction(self, session, options_, options=None): """ Begins a new transaction. This step can often be skipped: ``Read``, ``ExecuteSql`` and ``Commit`` can begin a new transaction as a side-effect. Example: >>> from google.cloud import spanner_v1 >>> >>> client = spanner_v1.SpannerClient() >>> >>> session = client.session_path('[PROJECT]', '[INSTANCE]', '[DATABASE]', '[SESSION]') >>> options_ = {} >>> >>> response = client.begin_transaction(session, options_) Args: session (str): Required. The session in which the transaction runs. options_ (Union[dict, ~google.cloud.spanner_v1.types.TransactionOptions]): Required. Options for the new transaction. If a dict is provided, it must be of the same form as the protobuf message :class:`~google.cloud.spanner_v1.types.TransactionOptions` options (~google.gax.CallOptions): Overrides the default settings for this call, e.g, timeout, retries etc. Returns: A :class:`~google.cloud.spanner_v1.types.Transaction` instance. Raises: :exc:`google.gax.errors.GaxError` if the RPC is aborted. :exc:`ValueError` if the parameters are invalid. """ request = spanner_pb2.BeginTransactionRequest( session=session, options=options_) return self._begin_transaction(request, options) def commit(self, session, mutations, transaction_id=None, single_use_transaction=None, options=None): """ Commits a transaction. The request includes the mutations to be applied to rows in the database. ``Commit`` might return an ``ABORTED`` error. This can occur at any time; commonly, the cause is conflicts with concurrent transactions. However, it can also happen for a variety of other reasons. If ``Commit`` returns ``ABORTED``, the caller should re-attempt the transaction from the beginning, re-using the same session. Example: >>> from google.cloud import spanner_v1 >>> >>> client = spanner_v1.SpannerClient() >>> >>> session = client.session_path('[PROJECT]', '[INSTANCE]', '[DATABASE]', '[SESSION]') >>> mutations = [] >>> >>> response = client.commit(session, mutations) Args: session (str): Required. The session in which the transaction to be committed is running. mutations (list[Union[dict, ~google.cloud.spanner_v1.types.Mutation]]): The mutations to be executed when this transaction commits. All mutations are applied atomically, in the order they appear in this list. If a dict is provided, it must be of the same form as the protobuf message :class:`~google.cloud.spanner_v1.types.Mutation` transaction_id (bytes): Commit a previously-started transaction. single_use_transaction (Union[dict, ~google.cloud.spanner_v1.types.TransactionOptions]): 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 ``BeginTransaction`` and ``Commit`` instead. If a dict is provided, it must be of the same form as the protobuf message :class:`~google.cloud.spanner_v1.types.TransactionOptions` options (~google.gax.CallOptions): Overrides the default settings for this call, e.g, timeout, retries etc. Returns: A :class:`~google.cloud.spanner_v1.types.CommitResponse` instance. Raises: :exc:`google.gax.errors.GaxError` if the RPC is aborted. :exc:`ValueError` if the parameters are invalid. """ # Sanity check: We have some fields which are mutually exclusive; # raise ValueError if more than one is sent. oneof.check_oneof( transaction_id=transaction_id, single_use_transaction=single_use_transaction, ) request = spanner_pb2.CommitRequest( session=session, mutations=mutations, transaction_id=transaction_id, single_use_transaction=single_use_transaction) return self._commit(request, options) def rollback(self, session, transaction_id, options=None): """ Rolls back a transaction, releasing any locks it holds. It is a good idea to call this for any transaction that includes one or more ``Read`` or ``ExecuteSql`` requests and ultimately decides not to commit. ``Rollback`` returns ``OK`` if it successfully aborts the transaction, the transaction was already aborted, or the transaction is not found. ``Rollback`` never returns ``ABORTED``. Example: >>> from google.cloud import spanner_v1 >>> >>> client = spanner_v1.SpannerClient() >>> >>> session = client.session_path('[PROJECT]', '[INSTANCE]', '[DATABASE]', '[SESSION]') >>> transaction_id = b'' >>> >>> client.rollback(session, transaction_id) Args: session (str): Required. The session in which the transaction to roll back is running. transaction_id (bytes): Required. The transaction to roll back. options (~google.gax.CallOptions): Overrides the default settings for this call, e.g, timeout, retries etc. Raises: :exc:`google.gax.errors.GaxError` if the RPC is aborted. :exc:`ValueError` if the parameters are invalid. """ request = spanner_pb2.RollbackRequest( session=session, transaction_id=transaction_id) self._rollback(request, options)
class MetricServiceApi(object): """ Manages metric descriptors, monitored resource descriptors, and time series data. """ SERVICE_ADDRESS = 'monitoring.googleapis.com' """The default address of the service.""" DEFAULT_SERVICE_PORT = 443 """The default port of the service.""" _CODE_GEN_NAME_VERSION = 'gapic/0.1.0' _GAX_VERSION = pkg_resources.get_distribution('google-gax').version _PAGE_DESCRIPTORS = { 'list_monitored_resource_descriptors': _PageDesc('page_token', 'next_page_token', 'resource_descriptors'), 'list_metric_descriptors': _PageDesc('page_token', 'next_page_token', 'metric_descriptors'), 'list_time_series': _PageDesc('page_token', 'next_page_token', 'time_series') } # The scopes needed to make gRPC calls to all of the methods defined in # this service _ALL_SCOPES = () _PROJECT_PATH_TEMPLATE = path_template.PathTemplate('projects/{project}') _METRIC_DESCRIPTOR_PATH_PATH_TEMPLATE = path_template.PathTemplate( 'projects/{project}/metricDescriptors/{metric_descriptor_path=**}') _MONITORED_RESOURCE_DESCRIPTOR_PATH_TEMPLATE = path_template.PathTemplate( 'projects/{project}/monitoredResourceDescriptors/{monitored_resource_descriptor}' ) @classmethod def project_path(cls, project): """Returns a fully-qualified project resource name string.""" return cls._PROJECT_PATH_TEMPLATE.render({ 'project': project, }) @classmethod def metric_descriptor_path_path(cls, project, metric_descriptor_path): """Returns a fully-qualified metric_descriptor_path resource name string.""" return cls._METRIC_DESCRIPTOR_PATH_PATH_TEMPLATE.render({ 'project': project, 'metric_descriptor_path': metric_descriptor_path, }) @classmethod def monitored_resource_descriptor_path(cls, project, monitored_resource_descriptor): """Returns a fully-qualified monitored_resource_descriptor resource name string.""" return cls._MONITORED_RESOURCE_DESCRIPTOR_PATH_TEMPLATE.render({ 'project': project, 'monitored_resource_descriptor': monitored_resource_descriptor, }) @classmethod def match_project_from_project_name(cls, project_name): """Parses the project from a project resource. Args: project_name (string): A fully-qualified path representing a project resource. Returns: A string representing the project. """ return cls._PROJECT_PATH_TEMPLATE.match(project_name).get('project') @classmethod def match_project_from_metric_descriptor_path_name( cls, metric_descriptor_path_name): """Parses the project from a metric_descriptor_path resource. Args: metric_descriptor_path_name (string): A fully-qualified path representing a metric_descriptor_path resource. Returns: A string representing the project. """ return cls._METRIC_DESCRIPTOR_PATH_PATH_TEMPLATE.match( metric_descriptor_path_name).get('project') @classmethod def match_metric_descriptor_path_from_metric_descriptor_path_name( cls, metric_descriptor_path_name): """Parses the metric_descriptor_path from a metric_descriptor_path resource. Args: metric_descriptor_path_name (string): A fully-qualified path representing a metric_descriptor_path resource. Returns: A string representing the metric_descriptor_path. """ return cls._METRIC_DESCRIPTOR_PATH_PATH_TEMPLATE.match( metric_descriptor_path_name).get('metric_descriptor_path') @classmethod def match_project_from_monitored_resource_descriptor_name( cls, monitored_resource_descriptor_name): """Parses the project from a monitored_resource_descriptor resource. Args: monitored_resource_descriptor_name (string): A fully-qualified path representing a monitored_resource_descriptor resource. Returns: A string representing the project. """ return cls._MONITORED_RESOURCE_DESCRIPTOR_PATH_TEMPLATE.match( monitored_resource_descriptor_name).get('project') @classmethod def match_monitored_resource_descriptor_from_monitored_resource_descriptor_name( cls, monitored_resource_descriptor_name): """Parses the monitored_resource_descriptor from a monitored_resource_descriptor resource. Args: monitored_resource_descriptor_name (string): A fully-qualified path representing a monitored_resource_descriptor resource. Returns: A string representing the monitored_resource_descriptor. """ return cls._MONITORED_RESOURCE_DESCRIPTOR_PATH_TEMPLATE.match( monitored_resource_descriptor_name).get( 'monitored_resource_descriptor') def __init__(self, service_path=SERVICE_ADDRESS, port=DEFAULT_SERVICE_PORT, channel=None, metadata_transformer=None, ssl_creds=None, scopes=None, client_config=None, app_name='gax', app_version=_GAX_VERSION): """Constructor. Args: service_path (string): The domain name of the API remote host. port (int): The port on which to connect to the remote host. channel (:class:`grpc.Channel`): A ``Channel`` instance through which to make calls. ssl_creds (:class:`grpc.ChannelCredentials`): A ``ChannelCredentials`` instance for use with an SSL-enabled channel. client_config (dict): A dictionary for call options for each method. See :func:`google.gax.construct_settings` for the structure of this data. Falls back to the default config if not specified or the specified config is missing data points. metadata_transformer (Callable[[], list]): A function that creates the metadata for requests. app_name (string): The codename of the calling service. app_version (string): The version of the calling service. Returns: A MetricServiceApi object. """ if scopes is None: scopes = self._ALL_SCOPES if client_config is None: client_config = {} goog_api_client = '{}/{} {} gax/{} python/{}'.format( app_name, app_version, self._CODE_GEN_NAME_VERSION, self._GAX_VERSION, platform.python_version()) metadata = [('x-goog-api-client', goog_api_client)] default_client_config = json.loads( pkg_resources.resource_string( __name__, 'metric_service_client_config.json').decode()) defaults = api_callable.construct_settings( 'google.monitoring.v3.MetricService', default_client_config, client_config, config.STATUS_CODE_NAMES, kwargs={'metadata': metadata}, page_descriptors=self._PAGE_DESCRIPTORS) self.metric_service_stub = config.create_stub( metric_service_pb2.MetricServiceStub, service_path, port, ssl_creds=ssl_creds, channel=channel, metadata_transformer=metadata_transformer, scopes=scopes) self._list_monitored_resource_descriptors = api_callable.create_api_call( self.metric_service_stub.ListMonitoredResourceDescriptors, settings=defaults['list_monitored_resource_descriptors']) self._get_monitored_resource_descriptor = api_callable.create_api_call( self.metric_service_stub.GetMonitoredResourceDescriptor, settings=defaults['get_monitored_resource_descriptor']) self._list_metric_descriptors = api_callable.create_api_call( self.metric_service_stub.ListMetricDescriptors, settings=defaults['list_metric_descriptors']) self._get_metric_descriptor = api_callable.create_api_call( self.metric_service_stub.GetMetricDescriptor, settings=defaults['get_metric_descriptor']) self._create_metric_descriptor = api_callable.create_api_call( self.metric_service_stub.CreateMetricDescriptor, settings=defaults['create_metric_descriptor']) self._delete_metric_descriptor = api_callable.create_api_call( self.metric_service_stub.DeleteMetricDescriptor, settings=defaults['delete_metric_descriptor']) self._list_time_series = api_callable.create_api_call( self.metric_service_stub.ListTimeSeries, settings=defaults['list_time_series']) self._create_time_series = api_callable.create_api_call( self.metric_service_stub.CreateTimeSeries, settings=defaults['create_time_series']) # Service calls def list_monitored_resource_descriptors(self, name, filter_='', page_size=0, options=None): """ Lists monitored resource descriptors that match a filter. This method does not require a Stackdriver account. Example: >>> from google.cloud.gapic.monitoring.v3 import metric_service_api >>> from google.gax import CallOptions, INITIAL_PAGE >>> api = metric_service_api.MetricServiceApi() >>> name = api.project_path('[PROJECT]') >>> >>> # Iterate over all results >>> for element in api.list_monitored_resource_descriptors(name): >>> # process element >>> pass >>> >>> # Or iterate over results one page at a time >>> for page in api.list_monitored_resource_descriptors(name, options=CallOptions(page_token=INITIAL_PAGE)): >>> for element in page: >>> # process element >>> pass Args: name (string): The project on which to execute the request. The format is ``\"projects/{project_id_or_number}\"``. filter_ (string): An optional `filter <https://cloud.google.com/monitoring/api/v3/filters>`_ describing the descriptors to be returned. The filter can reference the descriptor's type and labels. For example, the following filter returns only Google Compute Engine descriptors that have an ``id`` label: resource.type = starts_with(\"gce_\") AND resource.label:id page_size (int): The maximum number of resources contained in the underlying API response. If page streaming is performed per- resource, this parameter does not affect the return value. If page streaming is performed per-page, this determines the maximum number of resources in a page. options (:class:`google.gax.CallOptions`): Overrides the default settings for this call, e.g, timeout, retries etc. Returns: A :class:`google.gax.PageIterator` instance. By default, this is an iterable of :class:`google.api.monitored_resource_pb2.MonitoredResourceDescriptor` instances. This object can also be configured to iterate over the pages of the response through the `CallOptions` parameter. Raises: :exc:`google.gax.errors.GaxError` if the RPC is aborted. :exc:`ValueError` if the parameters are invalid. """ request = metric_service_pb2.ListMonitoredResourceDescriptorsRequest( name=name, filter=filter_, page_size=page_size) return self._list_monitored_resource_descriptors(request, options) def get_monitored_resource_descriptor(self, name, options=None): """ Gets a single monitored resource descriptor. This method does not require a Stackdriver account. Example: >>> from google.cloud.gapic.monitoring.v3 import metric_service_api >>> api = metric_service_api.MetricServiceApi() >>> name = api.monitored_resource_descriptor_path('[PROJECT]', '[MONITORED_RESOURCE_DESCRIPTOR]') >>> response = api.get_monitored_resource_descriptor(name) Args: name (string): The monitored resource descriptor to get. The format is ``\"projects/{project_id_or_number}/monitoredResourceDescriptors/{resource_type}\"``. The ``{resource_type}`` is a predefined type, such as ``cloudsql_database``. options (:class:`google.gax.CallOptions`): Overrides the default settings for this call, e.g, timeout, retries etc. Returns: A :class:`google.api.monitored_resource_pb2.MonitoredResourceDescriptor` instance. Raises: :exc:`google.gax.errors.GaxError` if the RPC is aborted. :exc:`ValueError` if the parameters are invalid. """ request = metric_service_pb2.GetMonitoredResourceDescriptorRequest( name=name) return self._get_monitored_resource_descriptor(request, options) def list_metric_descriptors(self, name, filter_='', page_size=0, options=None): """ Lists metric descriptors that match a filter. This method does not require a Stackdriver account. Example: >>> from google.cloud.gapic.monitoring.v3 import metric_service_api >>> from google.gax import CallOptions, INITIAL_PAGE >>> api = metric_service_api.MetricServiceApi() >>> name = api.project_path('[PROJECT]') >>> >>> # Iterate over all results >>> for element in api.list_metric_descriptors(name): >>> # process element >>> pass >>> >>> # Or iterate over results one page at a time >>> for page in api.list_metric_descriptors(name, options=CallOptions(page_token=INITIAL_PAGE)): >>> for element in page: >>> # process element >>> pass Args: name (string): The project on which to execute the request. The format is ``\"projects/{project_id_or_number}\"``. filter_ (string): If this field is empty, all custom and system-defined metric descriptors are returned. Otherwise, the `filter <https://cloud.google.com/monitoring/api/v3/filters>`_ specifies which metric descriptors are to be returned. For example, the following filter matches all `custom metrics <https://cloud.google.com/monitoring/custom-metrics>`_: metric.type = starts_with(\"custom.googleapis.com/\") page_size (int): The maximum number of resources contained in the underlying API response. If page streaming is performed per- resource, this parameter does not affect the return value. If page streaming is performed per-page, this determines the maximum number of resources in a page. options (:class:`google.gax.CallOptions`): Overrides the default settings for this call, e.g, timeout, retries etc. Returns: A :class:`google.gax.PageIterator` instance. By default, this is an iterable of :class:`google.api.metric_pb2.MetricDescriptor` instances. This object can also be configured to iterate over the pages of the response through the `CallOptions` parameter. Raises: :exc:`google.gax.errors.GaxError` if the RPC is aborted. :exc:`ValueError` if the parameters are invalid. """ request = metric_service_pb2.ListMetricDescriptorsRequest( name=name, filter=filter_, page_size=page_size) return self._list_metric_descriptors(request, options) def get_metric_descriptor(self, name, options=None): """ Gets a single metric descriptor. This method does not require a Stackdriver account. Example: >>> from google.cloud.gapic.monitoring.v3 import metric_service_api >>> api = metric_service_api.MetricServiceApi() >>> name = api.metric_descriptor_path_path('[PROJECT]', '[METRIC_DESCRIPTOR_PATH]') >>> response = api.get_metric_descriptor(name) Args: name (string): The metric descriptor on which to execute the request. The format is ``\"projects/{project_id_or_number}/metricDescriptors/{metric_id}\"``. An example value of ``{metric_id}`` is ``\"compute.googleapis.com/instance/disk/read_bytes_count\"``. options (:class:`google.gax.CallOptions`): Overrides the default settings for this call, e.g, timeout, retries etc. Returns: A :class:`google.api.metric_pb2.MetricDescriptor` instance. Raises: :exc:`google.gax.errors.GaxError` if the RPC is aborted. :exc:`ValueError` if the parameters are invalid. """ request = metric_service_pb2.GetMetricDescriptorRequest(name=name) return self._get_metric_descriptor(request, options) def create_metric_descriptor(self, name, metric_descriptor, options=None): """ Creates a new metric descriptor. User-created metric descriptors define `custom metrics <https://cloud.google.com/monitoring/custom-metrics>`_. Example: >>> from google.cloud.gapic.monitoring.v3 import metric_service_api >>> from google.api import metric_pb2 as api_metric_pb2 >>> api = metric_service_api.MetricServiceApi() >>> name = api.project_path('[PROJECT]') >>> metric_descriptor = api_metric_pb2.MetricDescriptor() >>> response = api.create_metric_descriptor(name, metric_descriptor) Args: name (string): The project on which to execute the request. The format is ``\"projects/{project_id_or_number}\"``. metric_descriptor (:class:`google.api.metric_pb2.MetricDescriptor`): The new `custom metric <https://cloud.google.com/monitoring/custom-metrics>`_ descriptor. options (:class:`google.gax.CallOptions`): Overrides the default settings for this call, e.g, timeout, retries etc. Returns: A :class:`google.api.metric_pb2.MetricDescriptor` instance. Raises: :exc:`google.gax.errors.GaxError` if the RPC is aborted. :exc:`ValueError` if the parameters are invalid. """ request = metric_service_pb2.CreateMetricDescriptorRequest( name=name, metric_descriptor=metric_descriptor) return self._create_metric_descriptor(request, options) def delete_metric_descriptor(self, name, options=None): """ Deletes a metric descriptor. Only user-created `custom metrics <https://cloud.google.com/monitoring/custom-metrics>`_ can be deleted. Example: >>> from google.cloud.gapic.monitoring.v3 import metric_service_api >>> api = metric_service_api.MetricServiceApi() >>> name = api.metric_descriptor_path_path('[PROJECT]', '[METRIC_DESCRIPTOR_PATH]') >>> api.delete_metric_descriptor(name) Args: name (string): The metric descriptor on which to execute the request. The format is ``\"projects/{project_id_or_number}/metricDescriptors/{metric_id}\"``. An example of ``{metric_id}`` is: ``\"custom.googleapis.com/my_test_metric\"``. options (:class:`google.gax.CallOptions`): Overrides the default settings for this call, e.g, timeout, retries etc. Raises: :exc:`google.gax.errors.GaxError` if the RPC is aborted. :exc:`ValueError` if the parameters are invalid. """ request = metric_service_pb2.DeleteMetricDescriptorRequest(name=name) self._delete_metric_descriptor(request, options) def list_time_series(self, name, filter_, interval, view, aggregation=None, order_by='', page_size=0, options=None): """ Lists time series that match a filter. This method does not require a Stackdriver account. Example: >>> from google.cloud.gapic.monitoring.v3 import metric_service_api >>> from google.cloud.gapic.monitoring.v3 import enums >>> from google.monitoring.v3 import common_pb2 >>> from google.gax import CallOptions, INITIAL_PAGE >>> api = metric_service_api.MetricServiceApi() >>> name = api.project_path('[PROJECT]') >>> filter_ = '' >>> interval = common_pb2.TimeInterval() >>> view = enums.ListTimeSeriesRequest.TimeSeriesView.FULL >>> >>> # Iterate over all results >>> for element in api.list_time_series(name, filter_, interval, view): >>> # process element >>> pass >>> >>> # Or iterate over results one page at a time >>> for page in api.list_time_series(name, filter_, interval, view, options=CallOptions(page_token=INITIAL_PAGE)): >>> for element in page: >>> # process element >>> pass Args: name (string): The project on which to execute the request. The format is \"projects/{project_id_or_number}\". filter_ (string): A `monitoring filter <https://cloud.google.com/monitoring/api/v3/filters>`_ that specifies which time series should be returned. The filter must specify a single metric type, and can additionally specify metric labels and other information. For example: metric.type = \"compute.googleapis.com/instance/cpu/usage_time\" AND metric.label.instance_name = \"my-instance-name\" interval (:class:`google.monitoring.v3.common_pb2.TimeInterval`): The time interval for which results should be returned. Only time series that contain data points in the specified interval are included in the response. aggregation (:class:`google.monitoring.v3.common_pb2.Aggregation`): By default, the raw time series data is returned. Use this field to combine multiple time series for different views of the data. order_by (string): Specifies the order in which the points of the time series should be returned. By default, results are not ordered. Currently, this field must be left blank. view (enum :class:`google.cloud.gapic.monitoring.v3.enums.ListTimeSeriesRequest.TimeSeriesView`): Specifies which information is returned about the time series. page_size (int): The maximum number of resources contained in the underlying API response. If page streaming is performed per- resource, this parameter does not affect the return value. If page streaming is performed per-page, this determines the maximum number of resources in a page. options (:class:`google.gax.CallOptions`): Overrides the default settings for this call, e.g, timeout, retries etc. Returns: A :class:`google.gax.PageIterator` instance. By default, this is an iterable of :class:`google.monitoring.v3.metric_pb2.TimeSeries` instances. This object can also be configured to iterate over the pages of the response through the `CallOptions` parameter. Raises: :exc:`google.gax.errors.GaxError` if the RPC is aborted. :exc:`ValueError` if the parameters are invalid. """ if aggregation is None: aggregation = common_pb2.Aggregation() request = metric_service_pb2.ListTimeSeriesRequest( name=name, filter=filter_, interval=interval, view=view, aggregation=aggregation, order_by=order_by, page_size=page_size) return self._list_time_series(request, options) def create_time_series(self, name, time_series, options=None): """ Creates or adds data to one or more time series. The response is empty if all time series in the request were written. If any time series could not be written, a corresponding failure message is included in the error response. Example: >>> from google.cloud.gapic.monitoring.v3 import metric_service_api >>> from google.monitoring.v3 import metric_pb2 as v3_metric_pb2 >>> api = metric_service_api.MetricServiceApi() >>> name = api.project_path('[PROJECT]') >>> time_series = [] >>> api.create_time_series(name, time_series) Args: name (string): The project on which to execute the request. The format is ``\"projects/{project_id_or_number}\"``. time_series (list[:class:`google.monitoring.v3.metric_pb2.TimeSeries`]): The new data to be added to a list of time series. Adds at most one data point to each of several time series. The new data point must be more recent than any other point in its time series. Each ``TimeSeries`` value must fully specify a unique time series by supplying all label values for the metric and the monitored resource. options (:class:`google.gax.CallOptions`): Overrides the default settings for this call, e.g, timeout, retries etc. Raises: :exc:`google.gax.errors.GaxError` if the RPC is aborted. :exc:`ValueError` if the parameters are invalid. """ request = metric_service_pb2.CreateTimeSeriesRequest( name=name, time_series=time_series) self._create_time_series(request, options)
class ReportErrorsServiceClient(object): """An API for reporting error events.""" SERVICE_ADDRESS = 'clouderrorreporting.googleapis.com' """The default address of the service.""" DEFAULT_SERVICE_PORT = 443 """The default port of the service.""" # The scopes needed to make gRPC calls to all of the methods defined in # this service _ALL_SCOPES = ('https://www.googleapis.com/auth/cloud-platform', ) _PROJECT_PATH_TEMPLATE = path_template.PathTemplate('projects/{project}') @classmethod def project_path(cls, project): """Returns a fully-qualified project resource name string.""" return cls._PROJECT_PATH_TEMPLATE.render({ 'project': project, }) @classmethod def match_project_from_project_name(cls, project_name): """Parses the project from a project resource. Args: project_name (string): A fully-qualified path representing a project resource. Returns: A string representing the project. """ return cls._PROJECT_PATH_TEMPLATE.match(project_name).get('project') def __init__(self, service_path=SERVICE_ADDRESS, port=DEFAULT_SERVICE_PORT, channel=None, credentials=None, ssl_credentials=None, scopes=None, client_config=None, app_name=None, app_version='', lib_name=None, lib_version='', metrics_headers=()): """Constructor. Args: service_path (string): The domain name of the API remote host. port (int): The port on which to connect to the remote host. channel (:class:`grpc.Channel`): A ``Channel`` instance through which to make calls. credentials (object): The authorization credentials to attach to requests. These credentials identify this application to the service. ssl_credentials (:class:`grpc.ChannelCredentials`): A ``ChannelCredentials`` instance for use with an SSL-enabled channel. scopes (list[string]): A list of OAuth2 scopes to attach to requests. client_config (dict): A dictionary for call options for each method. See :func:`google.gax.construct_settings` for the structure of this data. Falls back to the default config if not specified or the specified config is missing data points. app_name (string): The name of the application calling the service. Recommended for analytics purposes. app_version (string): The version of the application calling the service. Recommended for analytics purposes. lib_name (string): The API library software used for calling the service. (Unless you are writing an API client itself, leave this as default.) lib_version (string): The API library software version used for calling the service. (Unless you are writing an API client itself, leave this as default.) metrics_headers (dict): A dictionary of values for tracking client library metrics. Ultimately serializes to a string (e.g. 'foo/1.2.3 bar/3.14.1'). This argument should be considered private. Returns: A ReportErrorsServiceClient object. """ # Unless the calling application specifically requested # OAuth scopes, request everything. if scopes is None: scopes = self._ALL_SCOPES # Initialize an empty client config, if none is set. if client_config is None: client_config = {} # Initialize metrics_headers as an ordered dictionary # (cuts down on cardinality of the resulting string slightly). metrics_headers = collections.OrderedDict(metrics_headers) metrics_headers['gl-python'] = platform.python_version() # The library may or may not be set, depending on what is # calling this client. Newer client libraries set the library name # and version. if lib_name: metrics_headers[lib_name] = lib_version # Finally, track the GAPIC package version. metrics_headers['gapic'] = pkg_resources.get_distribution( 'gapic-google-cloud-error-reporting-v1beta1', ).version # Load the configuration defaults. default_client_config = json.loads( pkg_resources.resource_string( __name__, 'report_errors_service_client_config.json').decode()) defaults = api_callable.construct_settings( 'google.devtools.clouderrorreporting.v1beta1.ReportErrorsService', default_client_config, client_config, config.STATUS_CODE_NAMES, metrics_headers=metrics_headers, ) self.report_errors_service_stub = config.create_stub( report_errors_service_pb2.ReportErrorsServiceStub, channel=channel, service_path=service_path, service_port=port, credentials=credentials, scopes=scopes, ssl_credentials=ssl_credentials) self._report_error_event = api_callable.create_api_call( self.report_errors_service_stub.ReportErrorEvent, settings=defaults['report_error_event']) # Service calls def report_error_event(self, project_name, event, options=None): """ Report an individual error event. This endpoint accepts <strong>either</strong> an OAuth token, <strong>or</strong> an <a href=\"https://support.google.com/cloud/answer/6158862\">API key</a> for authentication. To use an API key, append it to the URL as the value of a ``key`` parameter. For example: <pre>POST https://clouderrorreporting.googleapis.com/v1beta1/projects/example-project/events:report?key=123ABC456</pre> Example: >>> from google.cloud.gapic.errorreporting.v1beta1 import report_errors_service_client >>> from google.cloud.proto.devtools.clouderrorreporting.v1beta1 import report_errors_service_pb2 >>> api = report_errors_service_client.ReportErrorsServiceClient() >>> project_name = api.project_path('[PROJECT]') >>> event = report_errors_service_pb2.ReportedErrorEvent() >>> response = api.report_error_event(project_name, event) Args: project_name (string): [Required] The resource name of the Google Cloud Platform project. Written as ``projects/`` plus the `Google Cloud Platform project ID <https://support.google.com/cloud/answer/6158840>`_. Example: ``projects/my-project-123``. event (:class:`google.cloud.proto.devtools.clouderrorreporting.v1beta1.report_errors_service_pb2.ReportedErrorEvent`): [Required] The error event to be reported. options (:class:`google.gax.CallOptions`): Overrides the default settings for this call, e.g, timeout, retries etc. Returns: A :class:`google.cloud.proto.devtools.clouderrorreporting.v1beta1.report_errors_service_pb2.ReportErrorEventResponse` instance. Raises: :exc:`google.gax.errors.GaxError` if the RPC is aborted. :exc:`ValueError` if the parameters are invalid. """ # Create the request object. request = report_errors_service_pb2.ReportErrorEventRequest( project_name=project_name, event=event) return self._report_error_event(request, options)
class ConfigServiceV2Api(object): """ Service for configuring sinks used to export log entries outside Stackdriver Logging. """ SERVICE_ADDRESS = 'logging.googleapis.com' """The default address of the service.""" DEFAULT_SERVICE_PORT = 443 """The default port of the service.""" _CODE_GEN_NAME_VERSION = 'gapic/0.1.0' _GAX_VERSION = pkg_resources.get_distribution('google-gax').version _PAGE_DESCRIPTORS = { 'list_sinks': _PageDesc('page_token', 'next_page_token', 'sinks') } # The scopes needed to make gRPC calls to all of the methods defined in # this service _ALL_SCOPES = ( 'https://www.googleapis.com/auth/cloud-platform', 'https://www.googleapis.com/auth/cloud-platform.read-only', 'https://www.googleapis.com/auth/logging.admin', 'https://www.googleapis.com/auth/logging.read', 'https://www.googleapis.com/auth/logging.write', ) _PARENT_PATH_TEMPLATE = path_template.PathTemplate('projects/{project}') _SINK_PATH_TEMPLATE = path_template.PathTemplate( 'projects/{project}/sinks/{sink}') @classmethod def parent_path(cls, project): """Returns a fully-qualified parent resource name string.""" return cls._PARENT_PATH_TEMPLATE.render({ 'project': project, }) @classmethod def sink_path(cls, project, sink): """Returns a fully-qualified sink resource name string.""" return cls._SINK_PATH_TEMPLATE.render({ 'project': project, 'sink': sink, }) @classmethod def match_project_from_parent_name(cls, parent_name): """Parses the project from a parent resource. Args: parent_name (string): A fully-qualified path representing a parent resource. Returns: A string representing the project. """ return cls._PARENT_PATH_TEMPLATE.match(parent_name).get('project') @classmethod def match_project_from_sink_name(cls, sink_name): """Parses the project from a sink resource. Args: sink_name (string): A fully-qualified path representing a sink resource. Returns: A string representing the project. """ return cls._SINK_PATH_TEMPLATE.match(sink_name).get('project') @classmethod def match_sink_from_sink_name(cls, sink_name): """Parses the sink from a sink resource. Args: sink_name (string): A fully-qualified path representing a sink resource. Returns: A string representing the sink. """ return cls._SINK_PATH_TEMPLATE.match(sink_name).get('sink') def __init__(self, service_path=SERVICE_ADDRESS, port=DEFAULT_SERVICE_PORT, channel=None, metadata_transformer=None, ssl_creds=None, scopes=None, client_config=None, app_name='gax', app_version=_GAX_VERSION): """Constructor. Args: service_path (string): The domain name of the API remote host. port (int): The port on which to connect to the remote host. channel (:class:`grpc.Channel`): A ``Channel`` instance through which to make calls. ssl_creds (:class:`grpc.ChannelCredentials`): A ``ChannelCredentials`` instance for use with an SSL-enabled channel. client_config (dict): A dictionary for call options for each method. See :func:`google.gax.construct_settings` for the structure of this data. Falls back to the default config if not specified or the specified config is missing data points. metadata_transformer (Callable[[], list]): A function that creates the metadata for requests. app_name (string): The codename of the calling service. app_version (string): The version of the calling service. Returns: A ConfigServiceV2Api object. """ if scopes is None: scopes = self._ALL_SCOPES if client_config is None: client_config = {} goog_api_client = '{}/{} {} gax/{} python/{}'.format( app_name, app_version, self._CODE_GEN_NAME_VERSION, self._GAX_VERSION, platform.python_version()) metadata = [('x-goog-api-client', goog_api_client)] default_client_config = json.loads( pkg_resources.resource_string( __name__, 'config_service_v2_client_config.json').decode()) defaults = api_callable.construct_settings( 'google.logging.v2.ConfigServiceV2', default_client_config, client_config, config.STATUS_CODE_NAMES, kwargs={'metadata': metadata}, page_descriptors=self._PAGE_DESCRIPTORS) self.config_service_v2_stub = config.create_stub( logging_config_pb2.ConfigServiceV2Stub, service_path, port, ssl_creds=ssl_creds, channel=channel, metadata_transformer=metadata_transformer, scopes=scopes) self._list_sinks = api_callable.create_api_call( self.config_service_v2_stub.ListSinks, settings=defaults['list_sinks']) self._get_sink = api_callable.create_api_call( self.config_service_v2_stub.GetSink, settings=defaults['get_sink']) self._create_sink = api_callable.create_api_call( self.config_service_v2_stub.CreateSink, settings=defaults['create_sink']) self._update_sink = api_callable.create_api_call( self.config_service_v2_stub.UpdateSink, settings=defaults['update_sink']) self._delete_sink = api_callable.create_api_call( self.config_service_v2_stub.DeleteSink, settings=defaults['delete_sink']) # Service calls def list_sinks(self, parent, page_size=0, options=None): """ Lists sinks. Example: >>> from google.cloud.gapic.logging.v2 import config_service_v2_api >>> from google.gax import CallOptions, INITIAL_PAGE >>> api = config_service_v2_api.ConfigServiceV2Api() >>> parent = api.parent_path('[PROJECT]') >>> >>> # Iterate over all results >>> for element in api.list_sinks(parent): >>> # process element >>> pass >>> >>> # Or iterate over results one page at a time >>> for page in api.list_sinks(parent, options=CallOptions(page_token=INITIAL_PAGE)): >>> for element in page: >>> # process element >>> pass Args: parent (string): Required. The cloud resource containing the sinks. Example: ``\"projects/my-logging-project\"``. page_size (int): The maximum number of resources contained in the underlying API response. If page streaming is performed per- resource, this parameter does not affect the return value. If page streaming is performed per-page, this determines the maximum number of resources in a page. options (:class:`google.gax.CallOptions`): Overrides the default settings for this call, e.g, timeout, retries etc. Returns: A :class:`google.gax.PageIterator` instance. By default, this is an iterable of :class:`google.logging.v2.logging_config_pb2.LogSink` instances. This object can also be configured to iterate over the pages of the response through the `CallOptions` parameter. Raises: :exc:`google.gax.errors.GaxError` if the RPC is aborted. :exc:`ValueError` if the parameters are invalid. """ request = logging_config_pb2.ListSinksRequest(parent=parent, page_size=page_size) return self._list_sinks(request, options) def get_sink(self, sink_name, options=None): """ Gets a sink. Example: >>> from google.cloud.gapic.logging.v2 import config_service_v2_api >>> api = config_service_v2_api.ConfigServiceV2Api() >>> sink_name = api.sink_path('[PROJECT]', '[SINK]') >>> response = api.get_sink(sink_name) Args: sink_name (string): Required. The resource name of the sink to return. Example: ``\"projects/my-project-id/sinks/my-sink-id\"``. options (:class:`google.gax.CallOptions`): Overrides the default settings for this call, e.g, timeout, retries etc. Returns: A :class:`google.logging.v2.logging_config_pb2.LogSink` instance. Raises: :exc:`google.gax.errors.GaxError` if the RPC is aborted. :exc:`ValueError` if the parameters are invalid. """ request = logging_config_pb2.GetSinkRequest(sink_name=sink_name) return self._get_sink(request, options) def create_sink(self, parent, sink, options=None): """ Creates a sink. Example: >>> from google.cloud.gapic.logging.v2 import config_service_v2_api >>> from google.logging.v2 import logging_config_pb2 >>> api = config_service_v2_api.ConfigServiceV2Api() >>> parent = api.parent_path('[PROJECT]') >>> sink = logging_config_pb2.LogSink() >>> response = api.create_sink(parent, sink) Args: parent (string): Required. The resource in which to create the sink. Example: ``\"projects/my-project-id\"``. The new sink must be provided in the request. sink (:class:`google.logging.v2.logging_config_pb2.LogSink`): Required. The new sink, whose ``name`` parameter is a sink identifier that is not already in use. options (:class:`google.gax.CallOptions`): Overrides the default settings for this call, e.g, timeout, retries etc. Returns: A :class:`google.logging.v2.logging_config_pb2.LogSink` instance. Raises: :exc:`google.gax.errors.GaxError` if the RPC is aborted. :exc:`ValueError` if the parameters are invalid. """ request = logging_config_pb2.CreateSinkRequest(parent=parent, sink=sink) return self._create_sink(request, options) def update_sink(self, sink_name, sink, options=None): """ Updates or creates a sink. Example: >>> from google.cloud.gapic.logging.v2 import config_service_v2_api >>> from google.logging.v2 import logging_config_pb2 >>> api = config_service_v2_api.ConfigServiceV2Api() >>> sink_name = api.sink_path('[PROJECT]', '[SINK]') >>> sink = logging_config_pb2.LogSink() >>> response = api.update_sink(sink_name, sink) Args: sink_name (string): Required. The resource name of the sink to update, including the parent resource and the sink identifier. If the sink does not exist, this method creates the sink. Example: ``\"projects/my-project-id/sinks/my-sink-id\"``. sink (:class:`google.logging.v2.logging_config_pb2.LogSink`): Required. The updated sink, whose name is the same identifier that appears as part of ``sinkName``. If ``sinkName`` does not exist, then this method creates a new sink. options (:class:`google.gax.CallOptions`): Overrides the default settings for this call, e.g, timeout, retries etc. Returns: A :class:`google.logging.v2.logging_config_pb2.LogSink` instance. Raises: :exc:`google.gax.errors.GaxError` if the RPC is aborted. :exc:`ValueError` if the parameters are invalid. """ request = logging_config_pb2.UpdateSinkRequest(sink_name=sink_name, sink=sink) return self._update_sink(request, options) def delete_sink(self, sink_name, options=None): """ Deletes a sink. Example: >>> from google.cloud.gapic.logging.v2 import config_service_v2_api >>> api = config_service_v2_api.ConfigServiceV2Api() >>> sink_name = api.sink_path('[PROJECT]', '[SINK]') >>> api.delete_sink(sink_name) Args: sink_name (string): Required. The resource name of the sink to delete, including the parent resource and the sink identifier. Example: ``\"projects/my-project-id/sinks/my-sink-id\"``. It is an error if the sink does not exist. options (:class:`google.gax.CallOptions`): Overrides the default settings for this call, e.g, timeout, retries etc. Raises: :exc:`google.gax.errors.GaxError` if the RPC is aborted. :exc:`ValueError` if the parameters are invalid. """ request = logging_config_pb2.DeleteSinkRequest(sink_name=sink_name) self._delete_sink(request, options)
class ErrorStatsServiceApi(object): """ An API for retrieving and managing error statistics as well as data for individual events. """ SERVICE_ADDRESS = 'clouderrorreporting.googleapis.com' """The default address of the service.""" DEFAULT_SERVICE_PORT = 443 """The default port of the service.""" _CODE_GEN_NAME_VERSION = 'gapic/0.1.0' _GAX_VERSION = pkg_resources.get_distribution('google-gax').version _PAGE_DESCRIPTORS = { 'list_group_stats': _PageDesc('page_token', 'next_page_token', 'error_group_stats'), 'list_events': _PageDesc('page_token', 'next_page_token', 'error_events') } # The scopes needed to make gRPC calls to all of the methods defined in # this service _ALL_SCOPES = ('https://www.googleapis.com/auth/cloud-platform', ) _PROJECT_PATH_TEMPLATE = path_template.PathTemplate('projects/{project}') @classmethod def project_path(cls, project): """Returns a fully-qualified project resource name string.""" return cls._PROJECT_PATH_TEMPLATE.render({ 'project': project, }) @classmethod def match_project_from_project_name(cls, project_name): """Parses the project from a project resource. Args: project_name (string): A fully-qualified path representing a project resource. Returns: A string representing the project. """ return cls._PROJECT_PATH_TEMPLATE.match(project_name).get('project') def __init__(self, service_path=SERVICE_ADDRESS, port=DEFAULT_SERVICE_PORT, channel=None, metadata_transformer=None, ssl_creds=None, scopes=None, client_config=None, app_name='gax', app_version=_GAX_VERSION): """Constructor. Args: service_path (string): The domain name of the API remote host. port (int): The port on which to connect to the remote host. channel (:class:`grpc.Channel`): A ``Channel`` instance through which to make calls. ssl_creds (:class:`grpc.ChannelCredentials`): A ``ChannelCredentials`` instance for use with an SSL-enabled channel. client_config (dict): A dictionary for call options for each method. See :func:`google.gax.construct_settings` for the structure of this data. Falls back to the default config if not specified or the specified config is missing data points. metadata_transformer (Callable[[], list]): A function that creates the metadata for requests. app_name (string): The codename of the calling service. app_version (string): The version of the calling service. Returns: A ErrorStatsServiceApi object. """ if scopes is None: scopes = self._ALL_SCOPES if client_config is None: client_config = {} goog_api_client = '{}/{} {} gax/{} python/{}'.format( app_name, app_version, self._CODE_GEN_NAME_VERSION, self._GAX_VERSION, platform.python_version()) metadata = [('x-goog-api-client', goog_api_client)] default_client_config = json.loads( pkg_resources.resource_string( __name__, 'error_stats_service_client_config.json').decode()) defaults = api_callable.construct_settings( 'google.devtools.clouderrorreporting.v1beta1.ErrorStatsService', default_client_config, client_config, config.STATUS_CODE_NAMES, kwargs={'metadata': metadata}, page_descriptors=self._PAGE_DESCRIPTORS) self.error_stats_service_stub = config.create_stub( error_stats_service_pb2.ErrorStatsServiceStub, service_path, port, ssl_creds=ssl_creds, channel=channel, metadata_transformer=metadata_transformer, scopes=scopes) self._list_group_stats = api_callable.create_api_call( self.error_stats_service_stub.ListGroupStats, settings=defaults['list_group_stats']) self._list_events = api_callable.create_api_call( self.error_stats_service_stub.ListEvents, settings=defaults['list_events']) self._delete_events = api_callable.create_api_call( self.error_stats_service_stub.DeleteEvents, settings=defaults['delete_events']) # Service calls def list_group_stats(self, project_name, time_range, group_id=None, service_filter=None, timed_count_duration=None, alignment=None, alignment_time=None, order=None, page_size=0, options=None): """ Lists the specified groups. Example: >>> from google.cloud.gapic.errorreporting.v1beta1 import error_stats_service_api >>> from google.devtools.clouderrorreporting.v1beta1 import error_stats_service_pb2 >>> from google.gax import CallOptions, INITIAL_PAGE >>> api = error_stats_service_api.ErrorStatsServiceApi() >>> project_name = api.project_path('[PROJECT]') >>> time_range = error_stats_service_pb2.QueryTimeRange() >>> >>> # Iterate over all results >>> for element in api.list_group_stats(project_name, time_range): >>> # process element >>> pass >>> >>> # Or iterate over results one page at a time >>> for page in api.list_group_stats(project_name, time_range, options=CallOptions(page_token=INITIAL_PAGE)): >>> for element in page: >>> # process element >>> pass Args: project_name (string): [Required] The resource name of the Google Cloud Platform project. Written as <code>projects/</code> plus the <a href=\"https://support.google.com/cloud/answer/6158840\">Google Cloud Platform project ID</a>. Example: <code>projects/my-project-123</code>. group_id (list[string]): [Optional] List all <code>ErrorGroupStats</code> with these IDs. service_filter (:class:`google.devtools.clouderrorreporting.v1beta1.error_stats_service_pb2.ServiceContextFilter`): [Optional] List only <code>ErrorGroupStats</code> which belong to a service context that matches the filter. Data for all service contexts is returned if this field is not specified. time_range (:class:`google.devtools.clouderrorreporting.v1beta1.error_stats_service_pb2.QueryTimeRange`): [Required] List data for the given time range. Only <code>ErrorGroupStats</code> with a non-zero count in the given time range are returned, unless the request contains an explicit group_id list. If a group_id list is given, also <code>ErrorGroupStats</code> with zero occurrences are returned. timed_count_duration (:class:`google.protobuf.duration_pb2.Duration`): [Optional] The preferred duration for a single returned ``TimedCount``. If not set, no timed counts are returned. alignment (enum :class:`google.cloud.gapic.errorreporting.v1beta1.enums.TimedCountAlignment`): [Optional] The alignment of the timed counts to be returned. Default is ``ALIGNMENT_EQUAL_AT_END``. alignment_time (:class:`google.protobuf.timestamp_pb2.Timestamp`): [Optional] Time where the timed counts shall be aligned if rounded alignment is chosen. Default is 00:00 UTC. order (enum :class:`google.cloud.gapic.errorreporting.v1beta1.enums.ErrorGroupOrder`): [Optional] The sort order in which the results are returned. Default is ``COUNT_DESC``. page_size (int): The maximum number of resources contained in the underlying API response. If page streaming is performed per- resource, this parameter does not affect the return value. If page streaming is performed per-page, this determines the maximum number of resources in a page. options (:class:`google.gax.CallOptions`): Overrides the default settings for this call, e.g, timeout, retries etc. Returns: A :class:`google.gax.PageIterator` instance. By default, this is an iterable of :class:`google.devtools.clouderrorreporting.v1beta1.error_stats_service_pb2.ErrorGroupStats` instances. This object can also be configured to iterate over the pages of the response through the `CallOptions` parameter. Raises: :exc:`google.gax.errors.GaxError` if the RPC is aborted. :exc:`ValueError` if the parameters are invalid. """ if group_id is None: group_id = [] if service_filter is None: service_filter = error_stats_service_pb2.ServiceContextFilter() if timed_count_duration is None: timed_count_duration = duration_pb2.Duration() if alignment is None: alignment = enums.TimedCountAlignment.ERROR_COUNT_ALIGNMENT_UNSPECIFIED if alignment_time is None: alignment_time = timestamp_pb2.Timestamp() if order is None: order = enums.ErrorGroupOrder.GROUP_ORDER_UNSPECIFIED request = error_stats_service_pb2.ListGroupStatsRequest( project_name=project_name, time_range=time_range, group_id=group_id, service_filter=service_filter, timed_count_duration=timed_count_duration, alignment=alignment, alignment_time=alignment_time, order=order, page_size=page_size) return self._list_group_stats(request, options) def list_events(self, project_name, group_id, service_filter=None, time_range=None, page_size=0, options=None): """ Lists the specified events. Example: >>> from google.cloud.gapic.errorreporting.v1beta1 import error_stats_service_api >>> from google.gax import CallOptions, INITIAL_PAGE >>> api = error_stats_service_api.ErrorStatsServiceApi() >>> project_name = api.project_path('[PROJECT]') >>> group_id = '' >>> >>> # Iterate over all results >>> for element in api.list_events(project_name, group_id): >>> # process element >>> pass >>> >>> # Or iterate over results one page at a time >>> for page in api.list_events(project_name, group_id, options=CallOptions(page_token=INITIAL_PAGE)): >>> for element in page: >>> # process element >>> pass Args: project_name (string): [Required] The resource name of the Google Cloud Platform project. Written as ``projects/`` plus the `Google Cloud Platform project ID <https://support.google.com/cloud/answer/6158840>`_. Example: ``projects/my-project-123``. group_id (string): [Required] The group for which events shall be returned. service_filter (:class:`google.devtools.clouderrorreporting.v1beta1.error_stats_service_pb2.ServiceContextFilter`): [Optional] List only ErrorGroups which belong to a service context that matches the filter. Data for all service contexts is returned if this field is not specified. time_range (:class:`google.devtools.clouderrorreporting.v1beta1.error_stats_service_pb2.QueryTimeRange`): [Optional] List only data for the given time range. page_size (int): The maximum number of resources contained in the underlying API response. If page streaming is performed per- resource, this parameter does not affect the return value. If page streaming is performed per-page, this determines the maximum number of resources in a page. options (:class:`google.gax.CallOptions`): Overrides the default settings for this call, e.g, timeout, retries etc. Returns: A :class:`google.gax.PageIterator` instance. By default, this is an iterable of :class:`google.devtools.clouderrorreporting.v1beta1.common_pb2.ErrorEvent` instances. This object can also be configured to iterate over the pages of the response through the `CallOptions` parameter. Raises: :exc:`google.gax.errors.GaxError` if the RPC is aborted. :exc:`ValueError` if the parameters are invalid. """ if service_filter is None: service_filter = error_stats_service_pb2.ServiceContextFilter() if time_range is None: time_range = error_stats_service_pb2.QueryTimeRange() request = error_stats_service_pb2.ListEventsRequest( project_name=project_name, group_id=group_id, service_filter=service_filter, time_range=time_range, page_size=page_size) return self._list_events(request, options) def delete_events(self, project_name, options=None): """ Deletes all error events of a given project. Example: >>> from google.cloud.gapic.errorreporting.v1beta1 import error_stats_service_api >>> api = error_stats_service_api.ErrorStatsServiceApi() >>> project_name = api.project_path('[PROJECT]') >>> response = api.delete_events(project_name) Args: project_name (string): [Required] The resource name of the Google Cloud Platform project. Written as ``projects/`` plus the `Google Cloud Platform project ID <https://support.google.com/cloud/answer/6158840>`_. Example: ``projects/my-project-123``. options (:class:`google.gax.CallOptions`): Overrides the default settings for this call, e.g, timeout, retries etc. Raises: :exc:`google.gax.errors.GaxError` if the RPC is aborted. :exc:`ValueError` if the parameters are invalid. """ request = error_stats_service_pb2.DeleteEventsRequest( project_name=project_name) self._delete_events(request, options)
class ErrorStatsServiceClient(object): """ An API for retrieving and managing error statistics as well as data for individual events. """ SERVICE_ADDRESS = 'clouderrorreporting.googleapis.com' """The default address of the service.""" DEFAULT_SERVICE_PORT = 443 """The default port of the service.""" _PAGE_DESCRIPTORS = { 'list_group_stats': _PageDesc('page_token', 'next_page_token', 'error_group_stats'), 'list_events': _PageDesc('page_token', 'next_page_token', 'error_events') } # The scopes needed to make gRPC calls to all of the methods defined in # this service _ALL_SCOPES = ('https://www.googleapis.com/auth/cloud-platform', ) _PROJECT_PATH_TEMPLATE = path_template.PathTemplate('projects/{project}') @classmethod def project_path(cls, project): """Returns a fully-qualified project resource name string.""" return cls._PROJECT_PATH_TEMPLATE.render({ 'project': project, }) @classmethod def match_project_from_project_name(cls, project_name): """Parses the project from a project resource. Args: project_name (string): A fully-qualified path representing a project resource. Returns: A string representing the project. """ return cls._PROJECT_PATH_TEMPLATE.match(project_name).get('project') def __init__(self, service_path=SERVICE_ADDRESS, port=DEFAULT_SERVICE_PORT, channel=None, credentials=None, ssl_credentials=None, scopes=None, client_config=None, app_name=None, app_version='', lib_name=None, lib_version='', metrics_headers=()): """Constructor. Args: service_path (string): The domain name of the API remote host. port (int): The port on which to connect to the remote host. channel (:class:`grpc.Channel`): A ``Channel`` instance through which to make calls. credentials (object): The authorization credentials to attach to requests. These credentials identify this application to the service. ssl_credentials (:class:`grpc.ChannelCredentials`): A ``ChannelCredentials`` instance for use with an SSL-enabled channel. scopes (list[string]): A list of OAuth2 scopes to attach to requests. client_config (dict): A dictionary for call options for each method. See :func:`google.gax.construct_settings` for the structure of this data. Falls back to the default config if not specified or the specified config is missing data points. app_name (string): The name of the application calling the service. Recommended for analytics purposes. app_version (string): The version of the application calling the service. Recommended for analytics purposes. lib_name (string): The API library software used for calling the service. (Unless you are writing an API client itself, leave this as default.) lib_version (string): The API library software version used for calling the service. (Unless you are writing an API client itself, leave this as default.) metrics_headers (dict): A dictionary of values for tracking client library metrics. Ultimately serializes to a string (e.g. 'foo/1.2.3 bar/3.14.1'). This argument should be considered private. Returns: A ErrorStatsServiceClient object. """ # Unless the calling application specifically requested # OAuth scopes, request everything. if scopes is None: scopes = self._ALL_SCOPES # Initialize an empty client config, if none is set. if client_config is None: client_config = {} # Initialize metrics_headers as an ordered dictionary # (cuts down on cardinality of the resulting string slightly). metrics_headers = collections.OrderedDict(metrics_headers) metrics_headers['gl-python'] = platform.python_version() # The library may or may not be set, depending on what is # calling this client. Newer client libraries set the library name # and version. if lib_name: metrics_headers[lib_name] = lib_version # Finally, track the GAPIC package version. metrics_headers['gapic'] = pkg_resources.get_distribution( 'gapic-google-cloud-error-reporting-v1beta1', ).version # Load the configuration defaults. default_client_config = json.loads( pkg_resources.resource_string( __name__, 'error_stats_service_client_config.json').decode()) defaults = api_callable.construct_settings( 'google.devtools.clouderrorreporting.v1beta1.ErrorStatsService', default_client_config, client_config, config.STATUS_CODE_NAMES, metrics_headers=metrics_headers, page_descriptors=self._PAGE_DESCRIPTORS, ) self.error_stats_service_stub = config.create_stub( error_stats_service_pb2.ErrorStatsServiceStub, channel=channel, service_path=service_path, service_port=port, credentials=credentials, scopes=scopes, ssl_credentials=ssl_credentials) self._list_group_stats = api_callable.create_api_call( self.error_stats_service_stub.ListGroupStats, settings=defaults['list_group_stats']) self._list_events = api_callable.create_api_call( self.error_stats_service_stub.ListEvents, settings=defaults['list_events']) self._delete_events = api_callable.create_api_call( self.error_stats_service_stub.DeleteEvents, settings=defaults['delete_events']) # Service calls def list_group_stats(self, project_name, time_range, group_id=None, service_filter=None, timed_count_duration=None, alignment=None, alignment_time=None, order=None, page_size=None, options=None): """ Lists the specified groups. Example: >>> from google.cloud.gapic.errorreporting.v1beta1 import error_stats_service_client >>> from google.cloud.proto.devtools.clouderrorreporting.v1beta1 import error_stats_service_pb2 >>> from google.gax import CallOptions, INITIAL_PAGE >>> client = error_stats_service_client.ErrorStatsServiceClient() >>> project_name = client.project_path('[PROJECT]') >>> time_range = error_stats_service_pb2.QueryTimeRange() >>> >>> # Iterate over all results >>> for element in client.list_group_stats(project_name, time_range): >>> # process element >>> pass >>> >>> # Or iterate over results one page at a time >>> for page in client.list_group_stats(project_name, time_range, options=CallOptions(page_token=INITIAL_PAGE)): >>> for element in page: >>> # process element >>> pass Args: project_name (string): [Required] The resource name of the Google Cloud Platform project. Written as <code>projects/</code> plus the <a href=\"https://support.google.com/cloud/answer/6158840\">Google Cloud Platform project ID</a>. Example: <code>projects/my-project-123</code>. time_range (:class:`google.cloud.proto.devtools.clouderrorreporting.v1beta1.error_stats_service_pb2.QueryTimeRange`): [Optional] List data for the given time range. If not set a default time range is used. The field time_range_begin in the response will specify the beginning of this time range. Only <code>ErrorGroupStats</code> with a non-zero count in the given time range are returned, unless the request contains an explicit group_id list. If a group_id list is given, also <code>ErrorGroupStats</code> with zero occurrences are returned. group_id (list[string]): [Optional] List all <code>ErrorGroupStats</code> with these IDs. service_filter (:class:`google.cloud.proto.devtools.clouderrorreporting.v1beta1.error_stats_service_pb2.ServiceContextFilter`): [Optional] List only <code>ErrorGroupStats</code> which belong to a service context that matches the filter. Data for all service contexts is returned if this field is not specified. timed_count_duration (:class:`google.protobuf.duration_pb2.Duration`): [Optional] The preferred duration for a single returned ``TimedCount``. If not set, no timed counts are returned. alignment (enum :class:`google.cloud.gapic.errorreporting.v1beta1.enums.TimedCountAlignment`): [Optional] The alignment of the timed counts to be returned. Default is ``ALIGNMENT_EQUAL_AT_END``. alignment_time (:class:`google.protobuf.timestamp_pb2.Timestamp`): [Optional] Time where the timed counts shall be aligned if rounded alignment is chosen. Default is 00:00 UTC. order (enum :class:`google.cloud.gapic.errorreporting.v1beta1.enums.ErrorGroupOrder`): [Optional] The sort order in which the results are returned. Default is ``COUNT_DESC``. page_size (int): The maximum number of resources contained in the underlying API response. If page streaming is performed per- resource, this parameter does not affect the return value. If page streaming is performed per-page, this determines the maximum number of resources in a page. options (:class:`google.gax.CallOptions`): Overrides the default settings for this call, e.g, timeout, retries etc. Returns: A :class:`google.gax.PageIterator` instance. By default, this is an iterable of :class:`google.cloud.proto.devtools.clouderrorreporting.v1beta1.error_stats_service_pb2.ErrorGroupStats` instances. This object can also be configured to iterate over the pages of the response through the `CallOptions` parameter. Raises: :exc:`google.gax.errors.GaxError` if the RPC is aborted. :exc:`ValueError` if the parameters are invalid. """ # Create the request object. request = error_stats_service_pb2.ListGroupStatsRequest( project_name=project_name, time_range=time_range, group_id=group_id, service_filter=service_filter, timed_count_duration=timed_count_duration, alignment=alignment, alignment_time=alignment_time, order=order, page_size=page_size) return self._list_group_stats(request, options) def list_events(self, project_name, group_id, service_filter=None, time_range=None, page_size=None, options=None): """ Lists the specified events. Example: >>> from google.cloud.gapic.errorreporting.v1beta1 import error_stats_service_client >>> from google.gax import CallOptions, INITIAL_PAGE >>> client = error_stats_service_client.ErrorStatsServiceClient() >>> project_name = client.project_path('[PROJECT]') >>> group_id = '' >>> >>> # Iterate over all results >>> for element in client.list_events(project_name, group_id): >>> # process element >>> pass >>> >>> # Or iterate over results one page at a time >>> for page in client.list_events(project_name, group_id, options=CallOptions(page_token=INITIAL_PAGE)): >>> for element in page: >>> # process element >>> pass Args: project_name (string): [Required] The resource name of the Google Cloud Platform project. Written as ``projects/`` plus the [Google Cloud Platform project ID](https://support.google.com/cloud/answer/6158840). Example: ``projects/my-project-123``. group_id (string): [Required] The group for which events shall be returned. service_filter (:class:`google.cloud.proto.devtools.clouderrorreporting.v1beta1.error_stats_service_pb2.ServiceContextFilter`): [Optional] List only ErrorGroups which belong to a service context that matches the filter. Data for all service contexts is returned if this field is not specified. time_range (:class:`google.cloud.proto.devtools.clouderrorreporting.v1beta1.error_stats_service_pb2.QueryTimeRange`): [Optional] List only data for the given time range. If not set a default time range is used. The field time_range_begin in the response will specify the beginning of this time range. page_size (int): The maximum number of resources contained in the underlying API response. If page streaming is performed per- resource, this parameter does not affect the return value. If page streaming is performed per-page, this determines the maximum number of resources in a page. options (:class:`google.gax.CallOptions`): Overrides the default settings for this call, e.g, timeout, retries etc. Returns: A :class:`google.gax.PageIterator` instance. By default, this is an iterable of :class:`google.cloud.proto.devtools.clouderrorreporting.v1beta1.common_pb2.ErrorEvent` instances. This object can also be configured to iterate over the pages of the response through the `CallOptions` parameter. Raises: :exc:`google.gax.errors.GaxError` if the RPC is aborted. :exc:`ValueError` if the parameters are invalid. """ # Create the request object. request = error_stats_service_pb2.ListEventsRequest( project_name=project_name, group_id=group_id, service_filter=service_filter, time_range=time_range, page_size=page_size) return self._list_events(request, options) def delete_events(self, project_name, options=None): """ Deletes all error events of a given project. Example: >>> from google.cloud.gapic.errorreporting.v1beta1 import error_stats_service_client >>> client = error_stats_service_client.ErrorStatsServiceClient() >>> project_name = client.project_path('[PROJECT]') >>> response = client.delete_events(project_name) Args: project_name (string): [Required] The resource name of the Google Cloud Platform project. Written as ``projects/`` plus the [Google Cloud Platform project ID](https://support.google.com/cloud/answer/6158840). Example: ``projects/my-project-123``. options (:class:`google.gax.CallOptions`): Overrides the default settings for this call, e.g, timeout, retries etc. Returns: A :class:`google.cloud.proto.devtools.clouderrorreporting.v1beta1.error_stats_service_pb2.DeleteEventsResponse` instance. Raises: :exc:`google.gax.errors.GaxError` if the RPC is aborted. :exc:`ValueError` if the parameters are invalid. """ # Create the request object. request = error_stats_service_pb2.DeleteEventsRequest( project_name=project_name) return self._delete_events(request, options)
class ConfigServiceV2Client(object): """ Service for configuring sinks used to export log entries outside of Stackdriver Logging. """ SERVICE_ADDRESS = 'logging.googleapis.com' """The default address of the service.""" DEFAULT_SERVICE_PORT = 443 """The default port of the service.""" _PAGE_DESCRIPTORS = { 'list_sinks': _PageDesc('page_token', 'next_page_token', 'sinks') } # The scopes needed to make gRPC calls to all of the methods defined in # this service _ALL_SCOPES = ( 'https://www.googleapis.com/auth/cloud-platform', 'https://www.googleapis.com/auth/cloud-platform.read-only', 'https://www.googleapis.com/auth/logging.admin', 'https://www.googleapis.com/auth/logging.read', 'https://www.googleapis.com/auth/logging.write', ) _PROJECT_PATH_TEMPLATE = path_template.PathTemplate('projects/{project}') _SINK_PATH_TEMPLATE = path_template.PathTemplate( 'projects/{project}/sinks/{sink}') @classmethod def project_path(cls, project): """Returns a fully-qualified project resource name string.""" return cls._PROJECT_PATH_TEMPLATE.render({ 'project': project, }) @classmethod def sink_path(cls, project, sink): """Returns a fully-qualified sink resource name string.""" return cls._SINK_PATH_TEMPLATE.render({ 'project': project, 'sink': sink, }) @classmethod def match_project_from_project_name(cls, project_name): """Parses the project from a project resource. Args: project_name (string): A fully-qualified path representing a project resource. Returns: A string representing the project. """ return cls._PROJECT_PATH_TEMPLATE.match(project_name).get('project') @classmethod def match_project_from_sink_name(cls, sink_name): """Parses the project from a sink resource. Args: sink_name (string): A fully-qualified path representing a sink resource. Returns: A string representing the project. """ return cls._SINK_PATH_TEMPLATE.match(sink_name).get('project') @classmethod def match_sink_from_sink_name(cls, sink_name): """Parses the sink from a sink resource. Args: sink_name (string): A fully-qualified path representing a sink resource. Returns: A string representing the sink. """ return cls._SINK_PATH_TEMPLATE.match(sink_name).get('sink') def __init__(self, service_path=SERVICE_ADDRESS, port=DEFAULT_SERVICE_PORT, channel=None, credentials=None, ssl_credentials=None, scopes=None, client_config=None, app_name=None, app_version='', lib_name=None, lib_version='', metrics_headers=()): """Constructor. Args: service_path (string): The domain name of the API remote host. port (int): The port on which to connect to the remote host. channel (:class:`grpc.Channel`): A ``Channel`` instance through which to make calls. credentials (object): The authorization credentials to attach to requests. These credentials identify this application to the service. ssl_credentials (:class:`grpc.ChannelCredentials`): A ``ChannelCredentials`` instance for use with an SSL-enabled channel. scopes (list[string]): A list of OAuth2 scopes to attach to requests. client_config (dict): A dictionary for call options for each method. See :func:`google.gax.construct_settings` for the structure of this data. Falls back to the default config if not specified or the specified config is missing data points. app_name (string): The name of the application calling the service. Recommended for analytics purposes. app_version (string): The version of the application calling the service. Recommended for analytics purposes. lib_name (string): The API library software used for calling the service. (Unless you are writing an API client itself, leave this as default.) lib_version (string): The API library software version used for calling the service. (Unless you are writing an API client itself, leave this as default.) metrics_headers (dict): A dictionary of values for tracking client library metrics. Ultimately serializes to a string (e.g. 'foo/1.2.3 bar/3.14.1'). This argument should be considered private. Returns: A ConfigServiceV2Client object. """ # Unless the calling application specifically requested # OAuth scopes, request everything. if scopes is None: scopes = self._ALL_SCOPES # Initialize an empty client config, if none is set. if client_config is None: client_config = {} # Initialize metrics_headers as an ordered dictionary # (cuts down on cardinality of the resulting string slightly). metrics_headers = collections.OrderedDict(metrics_headers) metrics_headers['gl-python'] = platform.python_version() # The library may or may not be set, depending on what is # calling this client. Newer client libraries set the library name # and version. if lib_name: metrics_headers[lib_name] = lib_version # Finally, track the GAPIC package version. metrics_headers['gapic'] = pkg_resources.get_distribution( 'gapic-google-cloud-logging-v2', ).version # Load the configuration defaults. default_client_config = json.loads( pkg_resources.resource_string( __name__, 'config_service_v2_client_config.json').decode()) defaults = api_callable.construct_settings( 'google.logging.v2.ConfigServiceV2', default_client_config, client_config, config.STATUS_CODE_NAMES, metrics_headers=metrics_headers, page_descriptors=self._PAGE_DESCRIPTORS, ) self.config_service_v2_stub = config.create_stub( logging_config_pb2.ConfigServiceV2Stub, channel=channel, service_path=service_path, service_port=port, credentials=credentials, scopes=scopes, ssl_credentials=ssl_credentials) self._list_sinks = api_callable.create_api_call( self.config_service_v2_stub.ListSinks, settings=defaults['list_sinks']) self._get_sink = api_callable.create_api_call( self.config_service_v2_stub.GetSink, settings=defaults['get_sink']) self._create_sink = api_callable.create_api_call( self.config_service_v2_stub.CreateSink, settings=defaults['create_sink']) self._update_sink = api_callable.create_api_call( self.config_service_v2_stub.UpdateSink, settings=defaults['update_sink']) self._delete_sink = api_callable.create_api_call( self.config_service_v2_stub.DeleteSink, settings=defaults['delete_sink']) # Service calls def list_sinks(self, parent, page_size=0, options=None): """ Lists sinks. Example: >>> from google.cloud.gapic.logging.v2 import config_service_v2_client >>> from google.gax import CallOptions, INITIAL_PAGE >>> api = config_service_v2_client.ConfigServiceV2Client() >>> parent = api.project_path('[PROJECT]') >>> >>> # Iterate over all results >>> for element in api.list_sinks(parent): >>> # process element >>> pass >>> >>> # Or iterate over results one page at a time >>> for page in api.list_sinks(parent, options=CallOptions(page_token=INITIAL_PAGE)): >>> for element in page: >>> # process element >>> pass Args: parent (string): Required. The parent resource whose sinks are to be listed. Examples: ``\"projects/my-logging-project\"``, ``\"organizations/123456789\"``. page_size (int): The maximum number of resources contained in the underlying API response. If page streaming is performed per- resource, this parameter does not affect the return value. If page streaming is performed per-page, this determines the maximum number of resources in a page. options (:class:`google.gax.CallOptions`): Overrides the default settings for this call, e.g, timeout, retries etc. Returns: A :class:`google.gax.PageIterator` instance. By default, this is an iterable of :class:`google.cloud.proto.logging.v2.logging_config_pb2.LogSink` instances. This object can also be configured to iterate over the pages of the response through the `CallOptions` parameter. Raises: :exc:`google.gax.errors.GaxError` if the RPC is aborted. :exc:`ValueError` if the parameters are invalid. """ # Create the request object. request = logging_config_pb2.ListSinksRequest(parent=parent, page_size=page_size) return self._list_sinks(request, options) def get_sink(self, sink_name, options=None): """ Gets a sink. Example: >>> from google.cloud.gapic.logging.v2 import config_service_v2_client >>> api = config_service_v2_client.ConfigServiceV2Client() >>> sink_name = api.sink_path('[PROJECT]', '[SINK]') >>> response = api.get_sink(sink_name) Args: sink_name (string): Required. The parent resource name of the sink: :: \"projects/[PROJECT_ID]/sinks/[SINK_ID]\" \"organizations/[ORGANIZATION_ID]/sinks/[SINK_ID]\" Example: ``\"projects/my-project-id/sinks/my-sink-id\"``. options (:class:`google.gax.CallOptions`): Overrides the default settings for this call, e.g, timeout, retries etc. Returns: A :class:`google.cloud.proto.logging.v2.logging_config_pb2.LogSink` instance. Raises: :exc:`google.gax.errors.GaxError` if the RPC is aborted. :exc:`ValueError` if the parameters are invalid. """ # Create the request object. request = logging_config_pb2.GetSinkRequest(sink_name=sink_name) return self._get_sink(request, options) def create_sink(self, parent, sink, unique_writer_identity=False, options=None): """ Creates a sink that exports specified log entries to a destination. The export of newly-ingested log entries begins immediately, unless the current time is outside the sink's start and end times or the sink's ``writer_identity`` is not permitted to write to the destination. A sink can export log entries only from the resource owning the sink. Example: >>> from google.cloud.gapic.logging.v2 import config_service_v2_client >>> from google.cloud.proto.logging.v2 import logging_config_pb2 >>> api = config_service_v2_client.ConfigServiceV2Client() >>> parent = api.project_path('[PROJECT]') >>> sink = logging_config_pb2.LogSink() >>> response = api.create_sink(parent, sink) Args: parent (string): Required. The resource in which to create the sink: :: \"projects/[PROJECT_ID]\" \"organizations/[ORGANIZATION_ID]\" Examples: ``\"projects/my-logging-project\"``, ``\"organizations/123456789\"``. sink (:class:`google.cloud.proto.logging.v2.logging_config_pb2.LogSink`): Required. The new sink, whose ``name`` parameter is a sink identifier that is not already in use. unique_writer_identity (bool): 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 ``[email protected]``, the same identity used 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 ``LogSink``. options (:class:`google.gax.CallOptions`): Overrides the default settings for this call, e.g, timeout, retries etc. Returns: A :class:`google.cloud.proto.logging.v2.logging_config_pb2.LogSink` instance. Raises: :exc:`google.gax.errors.GaxError` if the RPC is aborted. :exc:`ValueError` if the parameters are invalid. """ # Create the request object. request = logging_config_pb2.CreateSinkRequest( parent=parent, sink=sink, unique_writer_identity=unique_writer_identity) return self._create_sink(request, options) def update_sink(self, sink_name, sink, unique_writer_identity=False, options=None): """ Updates a sink. If the named sink doesn't exist, then this method is identical to `sinks.create <https://cloud.google.com/logging/docs/api/reference/rest/v2/projects.sinks/create>`_. If the named sink does exist, then this method replaces the following fields in the existing sink with values from the new sink: ``destination``, ``filter``, ``output_version_format``, ``start_time``, and ``end_time``. The updated filter might also have a new ``writer_identity``; see the ``unique_writer_identity`` field. Example: >>> from google.cloud.gapic.logging.v2 import config_service_v2_client >>> from google.cloud.proto.logging.v2 import logging_config_pb2 >>> api = config_service_v2_client.ConfigServiceV2Client() >>> sink_name = api.sink_path('[PROJECT]', '[SINK]') >>> sink = logging_config_pb2.LogSink() >>> response = api.update_sink(sink_name, sink) Args: sink_name (string): 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]\" Example: ``\"projects/my-project-id/sinks/my-sink-id\"``. sink (:class:`google.cloud.proto.logging.v2.logging_config_pb2.LogSink`): 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. unique_writer_identity (bool): 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 was 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 was true and the new value is false. options (:class:`google.gax.CallOptions`): Overrides the default settings for this call, e.g, timeout, retries etc. Returns: A :class:`google.cloud.proto.logging.v2.logging_config_pb2.LogSink` instance. Raises: :exc:`google.gax.errors.GaxError` if the RPC is aborted. :exc:`ValueError` if the parameters are invalid. """ # Create the request object. request = logging_config_pb2.UpdateSinkRequest( sink_name=sink_name, sink=sink, unique_writer_identity=unique_writer_identity) return self._update_sink(request, options) def delete_sink(self, sink_name, options=None): """ Deletes a sink. If the sink has a unique ``writer_identity``, then that service account is also deleted. Example: >>> from google.cloud.gapic.logging.v2 import config_service_v2_client >>> api = config_service_v2_client.ConfigServiceV2Client() >>> sink_name = api.sink_path('[PROJECT]', '[SINK]') >>> api.delete_sink(sink_name) Args: sink_name (string): 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]\" It is an error if the sink does not exist. Example: ``\"projects/my-project-id/sinks/my-sink-id\"``. It is an error if the sink does not exist. options (:class:`google.gax.CallOptions`): Overrides the default settings for this call, e.g, timeout, retries etc. Raises: :exc:`google.gax.errors.GaxError` if the RPC is aborted. :exc:`ValueError` if the parameters are invalid. """ # Create the request object. request = logging_config_pb2.DeleteSinkRequest(sink_name=sink_name) self._delete_sink(request, options)
class SubscriberClient(object): """ The service that an application uses to manipulate subscriptions and to consume messages from a subscription via the ``Pull`` method. """ SERVICE_ADDRESS = 'pubsub.googleapis.com' """The default address of the service.""" DEFAULT_SERVICE_PORT = 443 """The default port of the service.""" _PAGE_DESCRIPTORS = { 'list_subscriptions': _PageDesc('page_token', 'next_page_token', 'subscriptions'), 'list_snapshots': _PageDesc('page_token', 'next_page_token', 'snapshots') } # The scopes needed to make gRPC calls to all of the methods defined in # this service _ALL_SCOPES = ( 'https://www.googleapis.com/auth/cloud-platform', 'https://www.googleapis.com/auth/pubsub', ) _PROJECT_PATH_TEMPLATE = path_template.PathTemplate('projects/{project}') _SNAPSHOT_PATH_TEMPLATE = path_template.PathTemplate( 'projects/{project}/snapshots/{snapshot}') _SUBSCRIPTION_PATH_TEMPLATE = path_template.PathTemplate( 'projects/{project}/subscriptions/{subscription}') _TOPIC_PATH_TEMPLATE = path_template.PathTemplate( 'projects/{project}/topics/{topic}') @classmethod def project_path(cls, project): """Returns a fully-qualified project resource name string.""" return cls._PROJECT_PATH_TEMPLATE.render({ 'project': project, }) @classmethod def snapshot_path(cls, project, snapshot): """Returns a fully-qualified snapshot resource name string.""" return cls._SNAPSHOT_PATH_TEMPLATE.render({ 'project': project, 'snapshot': snapshot, }) @classmethod def subscription_path(cls, project, subscription): """Returns a fully-qualified subscription resource name string.""" return cls._SUBSCRIPTION_PATH_TEMPLATE.render({ 'project': project, 'subscription': subscription, }) @classmethod def topic_path(cls, project, topic): """Returns a fully-qualified topic resource name string.""" return cls._TOPIC_PATH_TEMPLATE.render({ 'project': project, 'topic': topic, }) @classmethod def match_project_from_project_name(cls, project_name): """Parses the project from a project resource. Args: project_name (string): A fully-qualified path representing a project resource. Returns: A string representing the project. """ return cls._PROJECT_PATH_TEMPLATE.match(project_name).get('project') @classmethod def match_project_from_snapshot_name(cls, snapshot_name): """Parses the project from a snapshot resource. Args: snapshot_name (string): A fully-qualified path representing a snapshot resource. Returns: A string representing the project. """ return cls._SNAPSHOT_PATH_TEMPLATE.match(snapshot_name).get('project') @classmethod def match_snapshot_from_snapshot_name(cls, snapshot_name): """Parses the snapshot from a snapshot resource. Args: snapshot_name (string): A fully-qualified path representing a snapshot resource. Returns: A string representing the snapshot. """ return cls._SNAPSHOT_PATH_TEMPLATE.match(snapshot_name).get('snapshot') @classmethod def match_project_from_subscription_name(cls, subscription_name): """Parses the project from a subscription resource. Args: subscription_name (string): A fully-qualified path representing a subscription resource. Returns: A string representing the project. """ return cls._SUBSCRIPTION_PATH_TEMPLATE.match(subscription_name).get( 'project') @classmethod def match_subscription_from_subscription_name(cls, subscription_name): """Parses the subscription from a subscription resource. Args: subscription_name (string): A fully-qualified path representing a subscription resource. Returns: A string representing the subscription. """ return cls._SUBSCRIPTION_PATH_TEMPLATE.match(subscription_name).get( 'subscription') @classmethod def match_project_from_topic_name(cls, topic_name): """Parses the project from a topic resource. Args: topic_name (string): A fully-qualified path representing a topic resource. Returns: A string representing the project. """ return cls._TOPIC_PATH_TEMPLATE.match(topic_name).get('project') @classmethod def match_topic_from_topic_name(cls, topic_name): """Parses the topic from a topic resource. Args: topic_name (string): A fully-qualified path representing a topic resource. Returns: A string representing the topic. """ return cls._TOPIC_PATH_TEMPLATE.match(topic_name).get('topic') def __init__(self, service_path=SERVICE_ADDRESS, port=DEFAULT_SERVICE_PORT, channel=None, credentials=None, ssl_credentials=None, scopes=None, client_config=None, app_name=None, app_version='', lib_name=None, lib_version='', metrics_headers=()): """Constructor. Args: service_path (string): The domain name of the API remote host. port (int): The port on which to connect to the remote host. channel (:class:`grpc.Channel`): A ``Channel`` instance through which to make calls. credentials (object): The authorization credentials to attach to requests. These credentials identify this application to the service. ssl_credentials (:class:`grpc.ChannelCredentials`): A ``ChannelCredentials`` instance for use with an SSL-enabled channel. scopes (list[string]): A list of OAuth2 scopes to attach to requests. client_config (dict): A dictionary for call options for each method. See :func:`google.gax.construct_settings` for the structure of this data. Falls back to the default config if not specified or the specified config is missing data points. app_name (string): The name of the application calling the service. Recommended for analytics purposes. app_version (string): The version of the application calling the service. Recommended for analytics purposes. lib_name (string): The API library software used for calling the service. (Unless you are writing an API client itself, leave this as default.) lib_version (string): The API library software version used for calling the service. (Unless you are writing an API client itself, leave this as default.) metrics_headers (dict): A dictionary of values for tracking client library metrics. Ultimately serializes to a string (e.g. 'foo/1.2.3 bar/3.14.1'). This argument should be considered private. Returns: A SubscriberClient object. """ # Unless the calling application specifically requested # OAuth scopes, request everything. if scopes is None: scopes = self._ALL_SCOPES # Initialize an empty client config, if none is set. if client_config is None: client_config = {} # Initialize metrics_headers as an ordered dictionary # (cuts down on cardinality of the resulting string slightly). metrics_headers = collections.OrderedDict(metrics_headers) metrics_headers['gl-python'] = platform.python_version() # The library may or may not be set, depending on what is # calling this client. Newer client libraries set the library name # and version. if lib_name: metrics_headers[lib_name] = lib_version # Finally, track the GAPIC package version. metrics_headers['gapic'] = pkg_resources.get_distribution( 'google-cloud-pubsub', ).version # Load the configuration defaults. default_client_config = json.loads( pkg_resources.resource_string( __name__, 'subscriber_client_config.json').decode()) defaults = api_callable.construct_settings( 'google.pubsub.v1.Subscriber', default_client_config, client_config, config.STATUS_CODE_NAMES, metrics_headers=metrics_headers, page_descriptors=self._PAGE_DESCRIPTORS, ) self.iam_policy_stub = config.create_stub( iam_policy_pb2.IAMPolicyStub, channel=channel, service_path=service_path, service_port=port, credentials=credentials, scopes=scopes, ssl_credentials=ssl_credentials) self.subscriber_stub = config.create_stub( pubsub_pb2.SubscriberStub, channel=channel, service_path=service_path, service_port=port, credentials=credentials, scopes=scopes, ssl_credentials=ssl_credentials) self._create_subscription = api_callable.create_api_call( self.subscriber_stub.CreateSubscription, settings=defaults['create_subscription']) self._get_subscription = api_callable.create_api_call( self.subscriber_stub.GetSubscription, settings=defaults['get_subscription']) self._update_subscription = api_callable.create_api_call( self.subscriber_stub.UpdateSubscription, settings=defaults['update_subscription']) self._list_subscriptions = api_callable.create_api_call( self.subscriber_stub.ListSubscriptions, settings=defaults['list_subscriptions']) self._delete_subscription = api_callable.create_api_call( self.subscriber_stub.DeleteSubscription, settings=defaults['delete_subscription']) self._modify_ack_deadline = api_callable.create_api_call( self.subscriber_stub.ModifyAckDeadline, settings=defaults['modify_ack_deadline']) self._acknowledge = api_callable.create_api_call( self.subscriber_stub.Acknowledge, settings=defaults['acknowledge']) self._pull = api_callable.create_api_call(self.subscriber_stub.Pull, settings=defaults['pull']) self._streaming_pull = api_callable.create_api_call( self.subscriber_stub.StreamingPull, settings=defaults['streaming_pull']) self._modify_push_config = api_callable.create_api_call( self.subscriber_stub.ModifyPushConfig, settings=defaults['modify_push_config']) self._list_snapshots = api_callable.create_api_call( self.subscriber_stub.ListSnapshots, settings=defaults['list_snapshots']) self._create_snapshot = api_callable.create_api_call( self.subscriber_stub.CreateSnapshot, settings=defaults['create_snapshot']) self._delete_snapshot = api_callable.create_api_call( self.subscriber_stub.DeleteSnapshot, settings=defaults['delete_snapshot']) self._seek = api_callable.create_api_call(self.subscriber_stub.Seek, settings=defaults['seek']) self._set_iam_policy = api_callable.create_api_call( self.iam_policy_stub.SetIamPolicy, settings=defaults['set_iam_policy']) self._get_iam_policy = api_callable.create_api_call( self.iam_policy_stub.GetIamPolicy, settings=defaults['get_iam_policy']) self._test_iam_permissions = api_callable.create_api_call( self.iam_policy_stub.TestIamPermissions, settings=defaults['test_iam_permissions']) # Service calls def create_subscription(self, name, topic, push_config=None, ack_deadline_seconds=None, retain_acked_messages=None, message_retention_duration=None, options=None): """ Creates a subscription to a given topic. If the subscription already exists, returns ``ALREADY_EXISTS``. If the corresponding topic doesn't exist, returns ``NOT_FOUND``. If the name is not provided in the request, the server will assign a random name for this subscription on the same project as the topic, conforming to the `resource name format <https://cloud.google.com/pubsub/docs/overview#names>`_. The generated name is populated in the returned Subscription object. Note that for REST API requests, you must specify a name in the request. Example: >>> from google.cloud.gapic.pubsub.v1 import subscriber_client >>> client = subscriber_client.SubscriberClient() >>> name = client.subscription_path('[PROJECT]', '[SUBSCRIPTION]') >>> topic = client.topic_path('[PROJECT]', '[TOPIC]') >>> response = client.create_subscription(name, topic) Args: name (string): 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\"``. topic (string): 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. push_config (:class:`google.cloud.proto.pubsub.v1.pubsub_pb2.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. ack_deadline_seconds (int): 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. retain_acked_messages (bool): 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. message_retention_duration (:class:`google.protobuf.duration_pb2.Duration`): 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. options (:class:`google.gax.CallOptions`): Overrides the default settings for this call, e.g, timeout, retries etc. Returns: A :class:`google.cloud.proto.pubsub.v1.pubsub_pb2.Subscription` instance. Raises: :exc:`google.gax.errors.GaxError` if the RPC is aborted. :exc:`ValueError` if the parameters are invalid. """ # Create the request object. request = pubsub_pb2.Subscription( name=name, topic=topic, push_config=push_config, ack_deadline_seconds=ack_deadline_seconds, retain_acked_messages=retain_acked_messages, message_retention_duration=message_retention_duration) return self._create_subscription(request, options) def get_subscription(self, subscription, options=None): """ Gets the configuration details of a subscription. Example: >>> from google.cloud.gapic.pubsub.v1 import subscriber_client >>> client = subscriber_client.SubscriberClient() >>> subscription = client.subscription_path('[PROJECT]', '[SUBSCRIPTION]') >>> response = client.get_subscription(subscription) Args: subscription (string): The name of the subscription to get. Format is ``projects/{project}/subscriptions/{sub}``. options (:class:`google.gax.CallOptions`): Overrides the default settings for this call, e.g, timeout, retries etc. Returns: A :class:`google.cloud.proto.pubsub.v1.pubsub_pb2.Subscription` instance. Raises: :exc:`google.gax.errors.GaxError` if the RPC is aborted. :exc:`ValueError` if the parameters are invalid. """ # Create the request object. request = pubsub_pb2.GetSubscriptionRequest(subscription=subscription) return self._get_subscription(request, options) def update_subscription(self, subscription, update_mask, options=None): """ Updates an existing subscription. Note that certain properties of a subscription, such as its topic, are not modifiable. Example: >>> from google.cloud.gapic.pubsub.v1 import subscriber_client >>> from google.cloud.proto.pubsub.v1 import pubsub_pb2 >>> from google.protobuf import field_mask_pb2 >>> client = subscriber_client.SubscriberClient() >>> subscription = pubsub_pb2.Subscription() >>> update_mask = field_mask_pb2.FieldMask() >>> response = client.update_subscription(subscription, update_mask) Args: subscription (:class:`google.cloud.proto.pubsub.v1.pubsub_pb2.Subscription`): The updated subscription object. update_mask (:class:`google.protobuf.field_mask_pb2.FieldMask`): Indicates which fields in the provided subscription to update. Must be specified and non-empty. options (:class:`google.gax.CallOptions`): Overrides the default settings for this call, e.g, timeout, retries etc. Returns: A :class:`google.cloud.proto.pubsub.v1.pubsub_pb2.Subscription` instance. Raises: :exc:`google.gax.errors.GaxError` if the RPC is aborted. :exc:`ValueError` if the parameters are invalid. """ # Create the request object. request = pubsub_pb2.UpdateSubscriptionRequest( subscription=subscription, update_mask=update_mask) return self._update_subscription(request, options) def list_subscriptions(self, project, page_size=None, options=None): """ Lists matching subscriptions. Example: >>> from google.cloud.gapic.pubsub.v1 import subscriber_client >>> from google.gax import CallOptions, INITIAL_PAGE >>> client = subscriber_client.SubscriberClient() >>> project = client.project_path('[PROJECT]') >>> >>> # Iterate over all results >>> for element in client.list_subscriptions(project): >>> # process element >>> pass >>> >>> # Or iterate over results one page at a time >>> for page in client.list_subscriptions(project, options=CallOptions(page_token=INITIAL_PAGE)): >>> for element in page: >>> # process element >>> pass Args: project (string): The name of the cloud project that subscriptions belong to. Format is ``projects/{project}``. page_size (int): The maximum number of resources contained in the underlying API response. If page streaming is performed per- resource, this parameter does not affect the return value. If page streaming is performed per-page, this determines the maximum number of resources in a page. options (:class:`google.gax.CallOptions`): Overrides the default settings for this call, e.g, timeout, retries etc. Returns: A :class:`google.gax.PageIterator` instance. By default, this is an iterable of :class:`google.cloud.proto.pubsub.v1.pubsub_pb2.Subscription` instances. This object can also be configured to iterate over the pages of the response through the `CallOptions` parameter. Raises: :exc:`google.gax.errors.GaxError` if the RPC is aborted. :exc:`ValueError` if the parameters are invalid. """ # Create the request object. request = pubsub_pb2.ListSubscriptionsRequest(project=project, page_size=page_size) return self._list_subscriptions(request, options) def delete_subscription(self, subscription, options=None): """ Deletes an existing subscription. All messages retained in the subscription are immediately dropped. Calls to ``Pull`` after deletion will return ``NOT_FOUND``. After a subscription is deleted, a new one may be created with the same name, but the new one has no association with the old subscription or its topic unless the same topic is specified. Example: >>> from google.cloud.gapic.pubsub.v1 import subscriber_client >>> client = subscriber_client.SubscriberClient() >>> subscription = client.subscription_path('[PROJECT]', '[SUBSCRIPTION]') >>> client.delete_subscription(subscription) Args: subscription (string): The subscription to delete. Format is ``projects/{project}/subscriptions/{sub}``. options (:class:`google.gax.CallOptions`): Overrides the default settings for this call, e.g, timeout, retries etc. Raises: :exc:`google.gax.errors.GaxError` if the RPC is aborted. :exc:`ValueError` if the parameters are invalid. """ # Create the request object. request = pubsub_pb2.DeleteSubscriptionRequest( subscription=subscription) self._delete_subscription(request, options) def modify_ack_deadline(self, subscription, ack_ids, ack_deadline_seconds, options=None): """ Modifies the ack deadline for a specific message. This method is useful to indicate that more time is needed to process a message by the subscriber, or to make the message available for redelivery if the processing was interrupted. Note that this does not modify the subscription-level ``ackDeadlineSeconds`` used for subsequent messages. Example: >>> from google.cloud.gapic.pubsub.v1 import subscriber_client >>> client = subscriber_client.SubscriberClient() >>> subscription = client.subscription_path('[PROJECT]', '[SUBSCRIPTION]') >>> ack_ids = [] >>> ack_deadline_seconds = 0 >>> client.modify_ack_deadline(subscription, ack_ids, ack_deadline_seconds) Args: subscription (string): The name of the subscription. Format is ``projects/{project}/subscriptions/{sub}``. ack_ids (list[string]): List of acknowledgment IDs. ack_deadline_seconds (int): 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). options (:class:`google.gax.CallOptions`): Overrides the default settings for this call, e.g, timeout, retries etc. Raises: :exc:`google.gax.errors.GaxError` if the RPC is aborted. :exc:`ValueError` if the parameters are invalid. """ # Create the request object. request = pubsub_pb2.ModifyAckDeadlineRequest( subscription=subscription, ack_ids=ack_ids, ack_deadline_seconds=ack_deadline_seconds) self._modify_ack_deadline(request, options) def acknowledge(self, subscription, ack_ids, options=None): """ Acknowledges the messages associated with the ``ack_ids`` in the ``AcknowledgeRequest``. The Pub/Sub system can remove the relevant messages from the subscription. Acknowledging a message whose ack deadline has expired may succeed, but such a message may be redelivered later. Acknowledging a message more than once will not result in an error. Example: >>> from google.cloud.gapic.pubsub.v1 import subscriber_client >>> client = subscriber_client.SubscriberClient() >>> subscription = client.subscription_path('[PROJECT]', '[SUBSCRIPTION]') >>> ack_ids = [] >>> client.acknowledge(subscription, ack_ids) Args: subscription (string): The subscription whose message is being acknowledged. Format is ``projects/{project}/subscriptions/{sub}``. ack_ids (list[string]): The acknowledgment ID for the messages being acknowledged that was returned by the Pub/Sub system in the ``Pull`` response. Must not be empty. options (:class:`google.gax.CallOptions`): Overrides the default settings for this call, e.g, timeout, retries etc. Raises: :exc:`google.gax.errors.GaxError` if the RPC is aborted. :exc:`ValueError` if the parameters are invalid. """ # Create the request object. request = pubsub_pb2.AcknowledgeRequest(subscription=subscription, ack_ids=ack_ids) self._acknowledge(request, options) def pull(self, subscription, max_messages, return_immediately=None, options=None): """ Pulls messages from the server. Returns an empty list if there are no messages available in the backlog. The server may return ``UNAVAILABLE`` if there are too many concurrent pull requests pending for the given subscription. Example: >>> from google.cloud.gapic.pubsub.v1 import subscriber_client >>> client = subscriber_client.SubscriberClient() >>> subscription = client.subscription_path('[PROJECT]', '[SUBSCRIPTION]') >>> max_messages = 0 >>> response = client.pull(subscription, max_messages) Args: subscription (string): The subscription from which messages should be pulled. Format is ``projects/{project}/subscriptions/{sub}``. max_messages (int): The maximum number of messages returned for this request. The Pub/Sub system may return fewer than the number specified. return_immediately (bool): 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. options (:class:`google.gax.CallOptions`): Overrides the default settings for this call, e.g, timeout, retries etc. Returns: A :class:`google.cloud.proto.pubsub.v1.pubsub_pb2.PullResponse` instance. Raises: :exc:`google.gax.errors.GaxError` if the RPC is aborted. :exc:`ValueError` if the parameters are invalid. """ # Create the request object. request = pubsub_pb2.PullRequest(subscription=subscription, max_messages=max_messages, return_immediately=return_immediately) return self._pull(request, options) def streaming_pull(self, requests, options=None): """ (EXPERIMENTAL) StreamingPull is an experimental feature. This RPC will respond with UNIMPLEMENTED errors unless you have been invited to test this feature. Contact [email protected] with any questions. Establishes a stream with the server, which sends messages down to the client. The client streams acknowledgements and ack deadline modifications back to the server. The server will close the stream and return the status on any error. The server may close the stream with status ``OK`` to reassign server-side resources, in which case, the client should re-establish the stream. ``UNAVAILABLE`` may also be returned in the case of a transient error (e.g., a server restart). These should also be retried by the client. Flow control can be achieved by configuring the underlying RPC channel. EXPERIMENTAL: This method interface might change in the future. Example: >>> from google.cloud.gapic.pubsub.v1 import subscriber_client >>> from google.cloud.proto.pubsub.v1 import pubsub_pb2 >>> client = subscriber_client.SubscriberClient() >>> subscription = client.subscription_path('[PROJECT]', '[SUBSCRIPTION]') >>> stream_ack_deadline_seconds = 0 >>> request = pubsub_pb2.StreamingPullRequest(subscription=subscription, stream_ack_deadline_seconds=stream_ack_deadline_seconds) >>> requests = [request] >>> for element in client.streaming_pull(requests): >>> # process element >>> pass Args: requests (iterator[:class:`google.cloud.proto.pubsub.v1.pubsub_pb2.StreamingPullRequest`]): The input objects. options (:class:`google.gax.CallOptions`): Overrides the default settings for this call, e.g, timeout, retries etc. Returns: iterator[:class:`google.cloud.proto.pubsub.v1.pubsub_pb2.StreamingPullResponse`]. Raises: :exc:`google.gax.errors.GaxError` if the RPC is aborted. :exc:`ValueError` if the parameters are invalid. """ return self._streaming_pull(requests, options) def modify_push_config(self, subscription, push_config, options=None): """ Modifies the ``PushConfig`` for a specified subscription. This may be used to change a push subscription to a pull one (signified by an empty ``PushConfig``) or vice versa, or change the endpoint URL and other attributes of a push subscription. Messages will accumulate for delivery continuously through the call regardless of changes to the ``PushConfig``. Example: >>> from google.cloud.gapic.pubsub.v1 import subscriber_client >>> from google.cloud.proto.pubsub.v1 import pubsub_pb2 >>> client = subscriber_client.SubscriberClient() >>> subscription = client.subscription_path('[PROJECT]', '[SUBSCRIPTION]') >>> push_config = pubsub_pb2.PushConfig() >>> client.modify_push_config(subscription, push_config) Args: subscription (string): The name of the subscription. Format is ``projects/{project}/subscriptions/{sub}``. push_config (:class:`google.cloud.proto.pubsub.v1.pubsub_pb2.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. options (:class:`google.gax.CallOptions`): Overrides the default settings for this call, e.g, timeout, retries etc. Raises: :exc:`google.gax.errors.GaxError` if the RPC is aborted. :exc:`ValueError` if the parameters are invalid. """ # Create the request object. request = pubsub_pb2.ModifyPushConfigRequest(subscription=subscription, push_config=push_config) self._modify_push_config(request, options) def list_snapshots(self, project, page_size=None, options=None): """ Lists the existing snapshots. Example: >>> from google.cloud.gapic.pubsub.v1 import subscriber_client >>> from google.gax import CallOptions, INITIAL_PAGE >>> client = subscriber_client.SubscriberClient() >>> project = client.project_path('[PROJECT]') >>> >>> # Iterate over all results >>> for element in client.list_snapshots(project): >>> # process element >>> pass >>> >>> # Or iterate over results one page at a time >>> for page in client.list_snapshots(project, options=CallOptions(page_token=INITIAL_PAGE)): >>> for element in page: >>> # process element >>> pass Args: project (string): The name of the cloud project that snapshots belong to. Format is ``projects/{project}``. page_size (int): The maximum number of resources contained in the underlying API response. If page streaming is performed per- resource, this parameter does not affect the return value. If page streaming is performed per-page, this determines the maximum number of resources in a page. options (:class:`google.gax.CallOptions`): Overrides the default settings for this call, e.g, timeout, retries etc. Returns: A :class:`google.gax.PageIterator` instance. By default, this is an iterable of :class:`google.cloud.proto.pubsub.v1.pubsub_pb2.Snapshot` instances. This object can also be configured to iterate over the pages of the response through the `CallOptions` parameter. Raises: :exc:`google.gax.errors.GaxError` if the RPC is aborted. :exc:`ValueError` if the parameters are invalid. """ # Create the request object. request = pubsub_pb2.ListSnapshotsRequest(project=project, page_size=page_size) return self._list_snapshots(request, options) def create_snapshot(self, name, subscription, options=None): """ Creates a snapshot from the requested subscription. If the snapshot already exists, returns ``ALREADY_EXISTS``. If the requested subscription doesn't exist, returns ``NOT_FOUND``. 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, conforming to the `resource name format <https://cloud.google.com/pubsub/docs/overview#names>`_. The generated name is populated in the returned Snapshot object. Note that for REST API requests, you must specify a name in the request. Example: >>> from google.cloud.gapic.pubsub.v1 import subscriber_client >>> client = subscriber_client.SubscriberClient() >>> name = client.snapshot_path('[PROJECT]', '[SNAPSHOT]') >>> subscription = client.subscription_path('[PROJECT]', '[SUBSCRIPTION]') >>> response = client.create_snapshot(name, subscription) Args: name (string): 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}``. subscription (string): The subscription whose backlog the snapshot retains. Specifically, the created snapshot is guaranteed to retain: - 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: - Any messages published to the subscription's topic following the successful completion of the CreateSnapshot request. Format is ``projects/{project}/subscriptions/{sub}``. options (:class:`google.gax.CallOptions`): Overrides the default settings for this call, e.g, timeout, retries etc. Returns: A :class:`google.cloud.proto.pubsub.v1.pubsub_pb2.Snapshot` instance. Raises: :exc:`google.gax.errors.GaxError` if the RPC is aborted. :exc:`ValueError` if the parameters are invalid. """ # Create the request object. request = pubsub_pb2.CreateSnapshotRequest(name=name, subscription=subscription) return self._create_snapshot(request, options) def delete_snapshot(self, snapshot, options=None): """ Removes an existing snapshot. All messages retained in the snapshot are immediately dropped. After a snapshot is deleted, a new one may be created with the same name, but the new one has no association with the old snapshot or its subscription, unless the same subscription is specified. Example: >>> from google.cloud.gapic.pubsub.v1 import subscriber_client >>> client = subscriber_client.SubscriberClient() >>> snapshot = client.snapshot_path('[PROJECT]', '[SNAPSHOT]') >>> client.delete_snapshot(snapshot) Args: snapshot (string): The name of the snapshot to delete. Format is ``projects/{project}/snapshots/{snap}``. options (:class:`google.gax.CallOptions`): Overrides the default settings for this call, e.g, timeout, retries etc. Raises: :exc:`google.gax.errors.GaxError` if the RPC is aborted. :exc:`ValueError` if the parameters are invalid. """ # Create the request object. request = pubsub_pb2.DeleteSnapshotRequest(snapshot=snapshot) self._delete_snapshot(request, options) def seek(self, subscription, time=None, snapshot=None, options=None): """ Seeks an existing subscription to a point in time or to a given snapshot, whichever is provided in the request. Example: >>> from google.cloud.gapic.pubsub.v1 import subscriber_client >>> client = subscriber_client.SubscriberClient() >>> subscription = client.subscription_path('[PROJECT]', '[SUBSCRIPTION]') >>> response = client.seek(subscription) Args: subscription (string): The subscription to affect. time (:class:`google.protobuf.timestamp_pb2.Timestamp`): 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. snapshot (string): 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}``. options (:class:`google.gax.CallOptions`): Overrides the default settings for this call, e.g, timeout, retries etc. Returns: A :class:`google.cloud.proto.pubsub.v1.pubsub_pb2.SeekResponse` instance. Raises: :exc:`google.gax.errors.GaxError` if the RPC is aborted. :exc:`ValueError` if the parameters are invalid. """ # Sanity check: We have some fields which are mutually exclusive; # raise ValueError if more than one is sent. oneof.check_oneof( time=time, snapshot=snapshot, ) # Create the request object. request = pubsub_pb2.SeekRequest(subscription=subscription, time=time, snapshot=snapshot) return self._seek(request, options) def set_iam_policy(self, resource, policy, options=None): """ Sets the access control policy on the specified resource. Replaces any existing policy. Example: >>> from google.cloud.gapic.pubsub.v1 import subscriber_client >>> from google.iam.v1 import policy_pb2 >>> client = subscriber_client.SubscriberClient() >>> resource = client.subscription_path('[PROJECT]', '[SUBSCRIPTION]') >>> policy = policy_pb2.Policy() >>> response = client.set_iam_policy(resource, policy) Args: resource (string): REQUIRED: The resource for which the policy is being specified. ``resource`` is usually specified as a path. For example, a Project resource is specified as ``projects/{project}``. policy (:class:`google.iam.v1.policy_pb2.Policy`): REQUIRED: The complete policy to be applied to the ``resource``. The size of the policy is limited to a few 10s of KB. An empty policy is a valid policy but certain Cloud Platform services (such as Projects) might reject them. options (:class:`google.gax.CallOptions`): Overrides the default settings for this call, e.g, timeout, retries etc. Returns: A :class:`google.iam.v1.policy_pb2.Policy` instance. Raises: :exc:`google.gax.errors.GaxError` if the RPC is aborted. :exc:`ValueError` if the parameters are invalid. """ # Create the request object. request = iam_policy_pb2.SetIamPolicyRequest(resource=resource, policy=policy) return self._set_iam_policy(request, options) def get_iam_policy(self, resource, options=None): """ Gets the access control policy for a resource. Returns an empty policy if the resource exists and does not have a policy set. Example: >>> from google.cloud.gapic.pubsub.v1 import subscriber_client >>> client = subscriber_client.SubscriberClient() >>> resource = client.subscription_path('[PROJECT]', '[SUBSCRIPTION]') >>> response = client.get_iam_policy(resource) Args: resource (string): REQUIRED: The resource for which the policy is being requested. ``resource`` is usually specified as a path. For example, a Project resource is specified as ``projects/{project}``. options (:class:`google.gax.CallOptions`): Overrides the default settings for this call, e.g, timeout, retries etc. Returns: A :class:`google.iam.v1.policy_pb2.Policy` instance. Raises: :exc:`google.gax.errors.GaxError` if the RPC is aborted. :exc:`ValueError` if the parameters are invalid. """ # Create the request object. request = iam_policy_pb2.GetIamPolicyRequest(resource=resource) return self._get_iam_policy(request, options) def test_iam_permissions(self, resource, permissions, options=None): """ Returns permissions that a caller has on the specified resource. If the resource does not exist, this will return an empty set of permissions, not a NOT_FOUND error. Example: >>> from google.cloud.gapic.pubsub.v1 import subscriber_client >>> client = subscriber_client.SubscriberClient() >>> resource = client.subscription_path('[PROJECT]', '[SUBSCRIPTION]') >>> permissions = [] >>> response = client.test_iam_permissions(resource, permissions) Args: resource (string): REQUIRED: The resource for which the policy detail is being requested. ``resource`` is usually specified as a path. For example, a Project resource is specified as ``projects/{project}``. permissions (list[string]): The set of permissions to check for the ``resource``. Permissions with wildcards (such as '*' or 'storage.*') are not allowed. For more information see `IAM Overview <https://cloud.google.com/iam/docs/overview#permissions>`_. options (:class:`google.gax.CallOptions`): Overrides the default settings for this call, e.g, timeout, retries etc. Returns: A :class:`google.iam.v1.iam_policy_pb2.TestIamPermissionsResponse` instance. Raises: :exc:`google.gax.errors.GaxError` if the RPC is aborted. :exc:`ValueError` if the parameters are invalid. """ # Create the request object. request = iam_policy_pb2.TestIamPermissionsRequest( resource=resource, permissions=permissions) return self._test_iam_permissions(request, options)
class PublisherClient(object): """ The service that an application uses to manipulate topics, and to send messages to a topic. """ SERVICE_ADDRESS = 'pubsub.googleapis.com' """The default address of the service.""" DEFAULT_SERVICE_PORT = 443 """The default port of the service.""" _PAGE_DESCRIPTORS = { 'list_topics': _PageDesc('page_token', 'next_page_token', 'topics'), 'list_topic_subscriptions': _PageDesc('page_token', 'next_page_token', 'subscriptions') } # The scopes needed to make gRPC calls to all of the methods defined in # this service _ALL_SCOPES = ( 'https://www.googleapis.com/auth/cloud-platform', 'https://www.googleapis.com/auth/pubsub', ) _PROJECT_PATH_TEMPLATE = path_template.PathTemplate('projects/{project}') _TOPIC_PATH_TEMPLATE = path_template.PathTemplate( 'projects/{project}/topics/{topic}') @classmethod def project_path(cls, project): """Returns a fully-qualified project resource name string.""" return cls._PROJECT_PATH_TEMPLATE.render({'project': project, }) @classmethod def topic_path(cls, project, topic): """Returns a fully-qualified topic resource name string.""" return cls._TOPIC_PATH_TEMPLATE.render({ 'project': project, 'topic': topic, }) @classmethod def match_project_from_project_name(cls, project_name): """Parses the project from a project resource. Args: project_name (string): A fully-qualified path representing a project resource. Returns: A string representing the project. """ return cls._PROJECT_PATH_TEMPLATE.match(project_name).get('project') @classmethod def match_project_from_topic_name(cls, topic_name): """Parses the project from a topic resource. Args: topic_name (string): A fully-qualified path representing a topic resource. Returns: A string representing the project. """ return cls._TOPIC_PATH_TEMPLATE.match(topic_name).get('project') @classmethod def match_topic_from_topic_name(cls, topic_name): """Parses the topic from a topic resource. Args: topic_name (string): A fully-qualified path representing a topic resource. Returns: A string representing the topic. """ return cls._TOPIC_PATH_TEMPLATE.match(topic_name).get('topic') def __init__(self, service_path=SERVICE_ADDRESS, port=DEFAULT_SERVICE_PORT, channel=None, credentials=None, ssl_credentials=None, scopes=None, client_config=None, app_name=None, app_version='', lib_name=None, lib_version='', metrics_headers=()): """Constructor. Args: service_path (string): The domain name of the API remote host. port (int): The port on which to connect to the remote host. channel (:class:`grpc.Channel`): A ``Channel`` instance through which to make calls. credentials (object): The authorization credentials to attach to requests. These credentials identify this application to the service. ssl_credentials (:class:`grpc.ChannelCredentials`): A ``ChannelCredentials`` instance for use with an SSL-enabled channel. scopes (list[string]): A list of OAuth2 scopes to attach to requests. client_config (dict): A dictionary for call options for each method. See :func:`google.gax.construct_settings` for the structure of this data. Falls back to the default config if not specified or the specified config is missing data points. app_name (string): The name of the application calling the service. Recommended for analytics purposes. app_version (string): The version of the application calling the service. Recommended for analytics purposes. lib_name (string): The API library software used for calling the service. (Unless you are writing an API client itself, leave this as default.) lib_version (string): The API library software version used for calling the service. (Unless you are writing an API client itself, leave this as default.) metrics_headers (dict): A dictionary of values for tracking client library metrics. Ultimately serializes to a string (e.g. 'foo/1.2.3 bar/3.14.1'). This argument should be considered private. Returns: A PublisherClient object. """ # Unless the calling application specifically requested # OAuth scopes, request everything. if scopes is None: scopes = self._ALL_SCOPES # Initialize an empty client config, if none is set. if client_config is None: client_config = {} # Initialize metrics_headers as an ordered dictionary # (cuts down on cardinality of the resulting string slightly). metrics_headers = collections.OrderedDict(metrics_headers) metrics_headers['gl-python'] = platform.python_version() # The library may or may not be set, depending on what is # calling this client. Newer client libraries set the library name # and version. if lib_name: metrics_headers[lib_name] = lib_version # Finally, track the GAPIC package version. metrics_headers['gapic'] = pkg_resources.get_distribution( 'gapic-google-cloud-pubsub-v1', ).version # Load the configuration defaults. default_client_config = json.loads( pkg_resources.resource_string( __name__, 'publisher_client_config.json').decode()) defaults = api_callable.construct_settings( 'google.pubsub.v1.Publisher', default_client_config, client_config, config.STATUS_CODE_NAMES, metrics_headers=metrics_headers, page_descriptors=self._PAGE_DESCRIPTORS, ) self.iam_policy_stub = config.create_stub( iam_policy_pb2.IAMPolicyStub, channel=channel, service_path=service_path, service_port=port, credentials=credentials, scopes=scopes, ssl_credentials=ssl_credentials) self.publisher_stub = config.create_stub( pubsub_pb2.PublisherStub, channel=channel, service_path=service_path, service_port=port, credentials=credentials, scopes=scopes, ssl_credentials=ssl_credentials) self._create_topic = api_callable.create_api_call( self.publisher_stub.CreateTopic, settings=defaults['create_topic']) self._publish = api_callable.create_api_call( self.publisher_stub.Publish, settings=defaults['publish']) self._get_topic = api_callable.create_api_call( self.publisher_stub.GetTopic, settings=defaults['get_topic']) self._list_topics = api_callable.create_api_call( self.publisher_stub.ListTopics, settings=defaults['list_topics']) self._list_topic_subscriptions = api_callable.create_api_call( self.publisher_stub.ListTopicSubscriptions, settings=defaults['list_topic_subscriptions']) self._delete_topic = api_callable.create_api_call( self.publisher_stub.DeleteTopic, settings=defaults['delete_topic']) self._set_iam_policy = api_callable.create_api_call( self.iam_policy_stub.SetIamPolicy, settings=defaults['set_iam_policy']) self._get_iam_policy = api_callable.create_api_call( self.iam_policy_stub.GetIamPolicy, settings=defaults['get_iam_policy']) self._test_iam_permissions = api_callable.create_api_call( self.iam_policy_stub.TestIamPermissions, settings=defaults['test_iam_permissions']) # Service calls def create_topic(self, name, options=None): """ Creates the given topic with the given name. Example: >>> from google.cloud.gapic.pubsub.v1 import publisher_client >>> api = publisher_client.PublisherClient() >>> name = api.topic_path('[PROJECT]', '[TOPIC]') >>> response = api.create_topic(name) Args: name (string): 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\"``. options (:class:`google.gax.CallOptions`): Overrides the default settings for this call, e.g, timeout, retries etc. Returns: A :class:`google.cloud.proto.pubsub.v1.pubsub_pb2.Topic` instance. Raises: :exc:`google.gax.errors.GaxError` if the RPC is aborted. :exc:`ValueError` if the parameters are invalid. """ # Create the request object. request = pubsub_pb2.Topic(name=name) return self._create_topic(request, options) def publish(self, topic, messages, options=None): """ Adds one or more messages to the topic. Returns ``NOT_FOUND`` if the topic does not exist. The message payload must not be empty; it must contain either a non-empty data field, or at least one attribute. Example: >>> from google.cloud.gapic.pubsub.v1 import publisher_client >>> from google.cloud.proto.pubsub.v1 import pubsub_pb2 >>> api = publisher_client.PublisherClient() >>> topic = api.topic_path('[PROJECT]', '[TOPIC]') >>> data = b'' >>> messages_element = pubsub_pb2.PubsubMessage(data) >>> messages = [messages_element] >>> response = api.publish(topic, messages) Args: topic (string): The messages in the request will be published on this topic. Format is ``projects/{project}/topics/{topic}``. messages (list[:class:`google.cloud.proto.pubsub.v1.pubsub_pb2.PubsubMessage`]): The messages to publish. options (:class:`google.gax.CallOptions`): Overrides the default settings for this call, e.g, timeout, retries etc. Returns: A :class:`google.cloud.proto.pubsub.v1.pubsub_pb2.PublishResponse` instance. Raises: :exc:`google.gax.errors.GaxError` if the RPC is aborted. :exc:`ValueError` if the parameters are invalid. """ # Create the request object. request = pubsub_pb2.PublishRequest(topic=topic, messages=messages) return self._publish(request, options) def get_topic(self, topic, options=None): """ Gets the configuration of a topic. Example: >>> from google.cloud.gapic.pubsub.v1 import publisher_client >>> api = publisher_client.PublisherClient() >>> topic = api.topic_path('[PROJECT]', '[TOPIC]') >>> response = api.get_topic(topic) Args: topic (string): The name of the topic to get. Format is ``projects/{project}/topics/{topic}``. options (:class:`google.gax.CallOptions`): Overrides the default settings for this call, e.g, timeout, retries etc. Returns: A :class:`google.cloud.proto.pubsub.v1.pubsub_pb2.Topic` instance. Raises: :exc:`google.gax.errors.GaxError` if the RPC is aborted. :exc:`ValueError` if the parameters are invalid. """ # Create the request object. request = pubsub_pb2.GetTopicRequest(topic=topic) return self._get_topic(request, options) def list_topics(self, project, page_size=0, options=None): """ Lists matching topics. Example: >>> from google.cloud.gapic.pubsub.v1 import publisher_client >>> from google.gax import CallOptions, INITIAL_PAGE >>> api = publisher_client.PublisherClient() >>> project = api.project_path('[PROJECT]') >>> >>> # Iterate over all results >>> for element in api.list_topics(project): >>> # process element >>> pass >>> >>> # Or iterate over results one page at a time >>> for page in api.list_topics(project, options=CallOptions(page_token=INITIAL_PAGE)): >>> for element in page: >>> # process element >>> pass Args: project (string): The name of the cloud project that topics belong to. Format is ``projects/{project}``. page_size (int): The maximum number of resources contained in the underlying API response. If page streaming is performed per- resource, this parameter does not affect the return value. If page streaming is performed per-page, this determines the maximum number of resources in a page. options (:class:`google.gax.CallOptions`): Overrides the default settings for this call, e.g, timeout, retries etc. Returns: A :class:`google.gax.PageIterator` instance. By default, this is an iterable of :class:`google.cloud.proto.pubsub.v1.pubsub_pb2.Topic` instances. This object can also be configured to iterate over the pages of the response through the `CallOptions` parameter. Raises: :exc:`google.gax.errors.GaxError` if the RPC is aborted. :exc:`ValueError` if the parameters are invalid. """ # Create the request object. request = pubsub_pb2.ListTopicsRequest( project=project, page_size=page_size) return self._list_topics(request, options) def list_topic_subscriptions(self, topic, page_size=0, options=None): """ Lists the name of the subscriptions for this topic. Example: >>> from google.cloud.gapic.pubsub.v1 import publisher_client >>> from google.gax import CallOptions, INITIAL_PAGE >>> api = publisher_client.PublisherClient() >>> topic = api.topic_path('[PROJECT]', '[TOPIC]') >>> >>> # Iterate over all results >>> for element in api.list_topic_subscriptions(topic): >>> # process element >>> pass >>> >>> # Or iterate over results one page at a time >>> for page in api.list_topic_subscriptions(topic, options=CallOptions(page_token=INITIAL_PAGE)): >>> for element in page: >>> # process element >>> pass Args: topic (string): The name of the topic that subscriptions are attached to. Format is ``projects/{project}/topics/{topic}``. page_size (int): The maximum number of resources contained in the underlying API response. If page streaming is performed per- resource, this parameter does not affect the return value. If page streaming is performed per-page, this determines the maximum number of resources in a page. options (:class:`google.gax.CallOptions`): Overrides the default settings for this call, e.g, timeout, retries etc. Returns: A :class:`google.gax.PageIterator` instance. By default, this is an iterable of string instances. This object can also be configured to iterate over the pages of the response through the `CallOptions` parameter. Raises: :exc:`google.gax.errors.GaxError` if the RPC is aborted. :exc:`ValueError` if the parameters are invalid. """ # Create the request object. request = pubsub_pb2.ListTopicSubscriptionsRequest( topic=topic, page_size=page_size) return self._list_topic_subscriptions(request, options) def delete_topic(self, topic, options=None): """ Deletes the topic with the given name. Returns ``NOT_FOUND`` if the topic does not exist. After a topic is deleted, a new topic may be created with the same name; this is an entirely new topic with none of the old configuration or subscriptions. Existing subscriptions to this topic are not deleted, but their ``topic`` field is set to ``_deleted-topic_``. Example: >>> from google.cloud.gapic.pubsub.v1 import publisher_client >>> api = publisher_client.PublisherClient() >>> topic = api.topic_path('[PROJECT]', '[TOPIC]') >>> api.delete_topic(topic) Args: topic (string): Name of the topic to delete. Format is ``projects/{project}/topics/{topic}``. options (:class:`google.gax.CallOptions`): Overrides the default settings for this call, e.g, timeout, retries etc. Raises: :exc:`google.gax.errors.GaxError` if the RPC is aborted. :exc:`ValueError` if the parameters are invalid. """ # Create the request object. request = pubsub_pb2.DeleteTopicRequest(topic=topic) self._delete_topic(request, options) def set_iam_policy(self, resource, policy, options=None): """ Sets the access control policy on the specified resource. Replaces any existing policy. Example: >>> from google.cloud.gapic.pubsub.v1 import publisher_client >>> from google.iam.v1 import policy_pb2 >>> api = publisher_client.PublisherClient() >>> resource = api.topic_path('[PROJECT]', '[TOPIC]') >>> policy = policy_pb2.Policy() >>> response = api.set_iam_policy(resource, policy) Args: resource (string): REQUIRED: The resource for which the policy is being specified. ``resource`` is usually specified as a path. For example, a Project resource is specified as ``projects/{project}``. policy (:class:`google.iam.v1.policy_pb2.Policy`): REQUIRED: The complete policy to be applied to the ``resource``. The size of the policy is limited to a few 10s of KB. An empty policy is a valid policy but certain Cloud Platform services (such as Projects) might reject them. options (:class:`google.gax.CallOptions`): Overrides the default settings for this call, e.g, timeout, retries etc. Returns: A :class:`google.iam.v1.policy_pb2.Policy` instance. Raises: :exc:`google.gax.errors.GaxError` if the RPC is aborted. :exc:`ValueError` if the parameters are invalid. """ # Create the request object. request = iam_policy_pb2.SetIamPolicyRequest( resource=resource, policy=policy) return self._set_iam_policy(request, options) def get_iam_policy(self, resource, options=None): """ Gets the access control policy for a resource. Returns an empty policy if the resource exists and does not have a policy set. Example: >>> from google.cloud.gapic.pubsub.v1 import publisher_client >>> api = publisher_client.PublisherClient() >>> resource = api.topic_path('[PROJECT]', '[TOPIC]') >>> response = api.get_iam_policy(resource) Args: resource (string): REQUIRED: The resource for which the policy is being requested. ``resource`` is usually specified as a path. For example, a Project resource is specified as ``projects/{project}``. options (:class:`google.gax.CallOptions`): Overrides the default settings for this call, e.g, timeout, retries etc. Returns: A :class:`google.iam.v1.policy_pb2.Policy` instance. Raises: :exc:`google.gax.errors.GaxError` if the RPC is aborted. :exc:`ValueError` if the parameters are invalid. """ # Create the request object. request = iam_policy_pb2.GetIamPolicyRequest(resource=resource) return self._get_iam_policy(request, options) def test_iam_permissions(self, resource, permissions, options=None): """ Returns permissions that a caller has on the specified resource. If the resource does not exist, this will return an empty set of permissions, not a NOT_FOUND error. Example: >>> from google.cloud.gapic.pubsub.v1 import publisher_client >>> api = publisher_client.PublisherClient() >>> resource = api.topic_path('[PROJECT]', '[TOPIC]') >>> permissions = [] >>> response = api.test_iam_permissions(resource, permissions) Args: resource (string): REQUIRED: The resource for which the policy detail is being requested. ``resource`` is usually specified as a path. For example, a Project resource is specified as ``projects/{project}``. permissions (list[string]): The set of permissions to check for the ``resource``. Permissions with wildcards (such as '*' or 'storage.*') are not allowed. For more information see `IAM Overview <https://cloud.google.com/iam/docs/overview#permissions>`_. options (:class:`google.gax.CallOptions`): Overrides the default settings for this call, e.g, timeout, retries etc. Returns: A :class:`google.iam.v1.iam_policy_pb2.TestIamPermissionsResponse` instance. Raises: :exc:`google.gax.errors.GaxError` if the RPC is aborted. :exc:`ValueError` if the parameters are invalid. """ # Create the request object. request = iam_policy_pb2.TestIamPermissionsRequest( resource=resource, permissions=permissions) return self._test_iam_permissions(request, options)
class MetricsServiceV2Client(object): """Service for configuring logs-based metrics.""" SERVICE_ADDRESS = 'logging.googleapis.com' """The default address of the service.""" DEFAULT_SERVICE_PORT = 443 """The default port of the service.""" _CODE_GEN_NAME_VERSION = 'gapic/0.1.0' _GAX_VERSION = pkg_resources.get_distribution('google-gax').version _PAGE_DESCRIPTORS = { 'list_log_metrics': _PageDesc('page_token', 'next_page_token', 'metrics') } # The scopes needed to make gRPC calls to all of the methods defined in # this service _ALL_SCOPES = ( 'https://www.googleapis.com/auth/cloud-platform', 'https://www.googleapis.com/auth/cloud-platform.read-only', 'https://www.googleapis.com/auth/logging.admin', 'https://www.googleapis.com/auth/logging.read', 'https://www.googleapis.com/auth/logging.write', ) _PROJECT_PATH_TEMPLATE = path_template.PathTemplate('projects/{project}') _METRIC_PATH_TEMPLATE = path_template.PathTemplate( 'projects/{project}/metrics/{metric}') @classmethod def project_path(cls, project): """Returns a fully-qualified project resource name string.""" return cls._PROJECT_PATH_TEMPLATE.render({ 'project': project, }) @classmethod def metric_path(cls, project, metric): """Returns a fully-qualified metric resource name string.""" return cls._METRIC_PATH_TEMPLATE.render({ 'project': project, 'metric': metric, }) @classmethod def match_project_from_project_name(cls, project_name): """Parses the project from a project resource. Args: project_name (string): A fully-qualified path representing a project resource. Returns: A string representing the project. """ return cls._PROJECT_PATH_TEMPLATE.match(project_name).get('project') @classmethod def match_project_from_metric_name(cls, metric_name): """Parses the project from a metric resource. Args: metric_name (string): A fully-qualified path representing a metric resource. Returns: A string representing the project. """ return cls._METRIC_PATH_TEMPLATE.match(metric_name).get('project') @classmethod def match_metric_from_metric_name(cls, metric_name): """Parses the metric from a metric resource. Args: metric_name (string): A fully-qualified path representing a metric resource. Returns: A string representing the metric. """ return cls._METRIC_PATH_TEMPLATE.match(metric_name).get('metric') def __init__(self, service_path=SERVICE_ADDRESS, port=DEFAULT_SERVICE_PORT, channel=None, credentials=None, ssl_credentials=None, scopes=None, client_config=None, app_name='gax', app_version=_GAX_VERSION): """Constructor. Args: service_path (string): The domain name of the API remote host. port (int): The port on which to connect to the remote host. channel (:class:`grpc.Channel`): A ``Channel`` instance through which to make calls. credentials (object): The authorization credentials to attach to requests. These credentials identify this application to the service. ssl_credentials (:class:`grpc.ChannelCredentials`): A ``ChannelCredentials`` instance for use with an SSL-enabled channel. scopes (list[string]): A list of OAuth2 scopes to attach to requests. client_config (dict): A dictionary for call options for each method. See :func:`google.gax.construct_settings` for the structure of this data. Falls back to the default config if not specified or the specified config is missing data points. app_name (string): The codename of the calling service. app_version (string): The version of the calling service. Returns: A MetricsServiceV2Client object. """ if scopes is None: scopes = self._ALL_SCOPES if client_config is None: client_config = {} goog_api_client = '{}/{} {} gax/{} python/{}'.format( app_name, app_version, self._CODE_GEN_NAME_VERSION, self._GAX_VERSION, platform.python_version()) metadata = [('x-goog-api-client', goog_api_client)] default_client_config = json.loads( pkg_resources.resource_string( __name__, 'metrics_service_v2_client_config.json').decode()) defaults = api_callable.construct_settings( 'google.logging.v2.MetricsServiceV2', default_client_config, client_config, config.STATUS_CODE_NAMES, kwargs={'metadata': metadata}, page_descriptors=self._PAGE_DESCRIPTORS) self.metrics_service_v2_stub = config.create_stub( logging_metrics_pb2.MetricsServiceV2Stub, channel=channel, service_path=service_path, service_port=port, credentials=credentials, scopes=scopes, ssl_credentials=ssl_credentials) self._list_log_metrics = api_callable.create_api_call( self.metrics_service_v2_stub.ListLogMetrics, settings=defaults['list_log_metrics']) self._get_log_metric = api_callable.create_api_call( self.metrics_service_v2_stub.GetLogMetric, settings=defaults['get_log_metric']) self._create_log_metric = api_callable.create_api_call( self.metrics_service_v2_stub.CreateLogMetric, settings=defaults['create_log_metric']) self._update_log_metric = api_callable.create_api_call( self.metrics_service_v2_stub.UpdateLogMetric, settings=defaults['update_log_metric']) self._delete_log_metric = api_callable.create_api_call( self.metrics_service_v2_stub.DeleteLogMetric, settings=defaults['delete_log_metric']) # Service calls def list_log_metrics(self, parent, page_size=0, options=None): """ Lists logs-based metrics. Example: >>> from google.cloud.gapic.logging.v2 import metrics_service_v2_client >>> from google.gax import CallOptions, INITIAL_PAGE >>> api = metrics_service_v2_client.MetricsServiceV2Client() >>> parent = api.project_path('[PROJECT]') >>> >>> # Iterate over all results >>> for element in api.list_log_metrics(parent): >>> # process element >>> pass >>> >>> # Or iterate over results one page at a time >>> for page in api.list_log_metrics(parent, options=CallOptions(page_token=INITIAL_PAGE)): >>> for element in page: >>> # process element >>> pass Args: parent (string): Required. The name of the project containing the metrics: :: \"projects/[PROJECT_ID]\" page_size (int): The maximum number of resources contained in the underlying API response. If page streaming is performed per- resource, this parameter does not affect the return value. If page streaming is performed per-page, this determines the maximum number of resources in a page. options (:class:`google.gax.CallOptions`): Overrides the default settings for this call, e.g, timeout, retries etc. Returns: A :class:`google.gax.PageIterator` instance. By default, this is an iterable of :class:`google.cloud.grpc.logging.v2.logging_metrics_pb2.LogMetric` instances. This object can also be configured to iterate over the pages of the response through the `CallOptions` parameter. Raises: :exc:`google.gax.errors.GaxError` if the RPC is aborted. :exc:`ValueError` if the parameters are invalid. """ request = logging_metrics_pb2.ListLogMetricsRequest( parent=parent, page_size=page_size) return self._list_log_metrics(request, options) def get_log_metric(self, metric_name, options=None): """ Gets a logs-based metric. Example: >>> from google.cloud.gapic.logging.v2 import metrics_service_v2_client >>> api = metrics_service_v2_client.MetricsServiceV2Client() >>> metric_name = api.metric_path('[PROJECT]', '[METRIC]') >>> response = api.get_log_metric(metric_name) Args: metric_name (string): The resource name of the desired metric: :: \"projects/[PROJECT_ID]/metrics/[METRIC_ID]\" options (:class:`google.gax.CallOptions`): Overrides the default settings for this call, e.g, timeout, retries etc. Returns: A :class:`google.cloud.grpc.logging.v2.logging_metrics_pb2.LogMetric` instance. Raises: :exc:`google.gax.errors.GaxError` if the RPC is aborted. :exc:`ValueError` if the parameters are invalid. """ request = logging_metrics_pb2.GetLogMetricRequest( metric_name=metric_name) return self._get_log_metric(request, options) def create_log_metric(self, parent, metric, options=None): """ Creates a logs-based metric. Example: >>> from google.cloud.gapic.logging.v2 import metrics_service_v2_client >>> from google.cloud.grpc.logging.v2 import logging_metrics_pb2 >>> api = metrics_service_v2_client.MetricsServiceV2Client() >>> parent = api.project_path('[PROJECT]') >>> metric = logging_metrics_pb2.LogMetric() >>> response = api.create_log_metric(parent, metric) Args: parent (string): The resource name of the project in which to create the metric: :: \"projects/[PROJECT_ID]\" The new metric must be provided in the request. metric (:class:`google.cloud.grpc.logging.v2.logging_metrics_pb2.LogMetric`): The new logs-based metric, which must not have an identifier that already exists. options (:class:`google.gax.CallOptions`): Overrides the default settings for this call, e.g, timeout, retries etc. Returns: A :class:`google.cloud.grpc.logging.v2.logging_metrics_pb2.LogMetric` instance. Raises: :exc:`google.gax.errors.GaxError` if the RPC is aborted. :exc:`ValueError` if the parameters are invalid. """ request = logging_metrics_pb2.CreateLogMetricRequest(parent=parent, metric=metric) return self._create_log_metric(request, options) def update_log_metric(self, metric_name, metric, options=None): """ Creates or updates a logs-based metric. Example: >>> from google.cloud.gapic.logging.v2 import metrics_service_v2_client >>> from google.cloud.grpc.logging.v2 import logging_metrics_pb2 >>> api = metrics_service_v2_client.MetricsServiceV2Client() >>> metric_name = api.metric_path('[PROJECT]', '[METRIC]') >>> metric = logging_metrics_pb2.LogMetric() >>> response = api.update_log_metric(metric_name, metric) Args: metric_name (string): 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. metric (:class:`google.cloud.grpc.logging.v2.logging_metrics_pb2.LogMetric`): The updated metric. options (:class:`google.gax.CallOptions`): Overrides the default settings for this call, e.g, timeout, retries etc. Returns: A :class:`google.cloud.grpc.logging.v2.logging_metrics_pb2.LogMetric` instance. Raises: :exc:`google.gax.errors.GaxError` if the RPC is aborted. :exc:`ValueError` if the parameters are invalid. """ request = logging_metrics_pb2.UpdateLogMetricRequest( metric_name=metric_name, metric=metric) return self._update_log_metric(request, options) def delete_log_metric(self, metric_name, options=None): """ Deletes a logs-based metric. Example: >>> from google.cloud.gapic.logging.v2 import metrics_service_v2_client >>> api = metrics_service_v2_client.MetricsServiceV2Client() >>> metric_name = api.metric_path('[PROJECT]', '[METRIC]') >>> api.delete_log_metric(metric_name) Args: metric_name (string): The resource name of the metric to delete: :: \"projects/[PROJECT_ID]/metrics/[METRIC_ID]\" options (:class:`google.gax.CallOptions`): Overrides the default settings for this call, e.g, timeout, retries etc. Raises: :exc:`google.gax.errors.GaxError` if the RPC is aborted. :exc:`ValueError` if the parameters are invalid. """ request = logging_metrics_pb2.DeleteLogMetricRequest( metric_name=metric_name) self._delete_log_metric(request, options)
class GroupServiceApi(object): """ The Group API lets you inspect and manage your `groups <https://cloud.google.comgoogle.monitoring.v3.Group>`_. A group is a named filter that is used to identify a collection of monitored resources. Groups are typically used to mirror the physical and/or logical topology of the environment. Because group membership is computed dynamically, monitored resources that are started in the future are automatically placed in matching groups. By using a group to name monitored resources in, for example, an alert policy, the target of that alert policy is updated automatically as monitored resources are added and removed from the infrastructure. """ SERVICE_ADDRESS = 'monitoring.googleapis.com' """The default address of the service.""" DEFAULT_SERVICE_PORT = 443 """The default port of the service.""" _CODE_GEN_NAME_VERSION = 'gapic/0.1.0' _GAX_VERSION = pkg_resources.get_distribution('google-gax').version _PAGE_DESCRIPTORS = { 'list_groups': _PageDesc('page_token', 'next_page_token', 'group'), 'list_group_members': _PageDesc('page_token', 'next_page_token', 'members') } # The scopes needed to make gRPC calls to all of the methods defined in # this service _ALL_SCOPES = () _PROJECT_PATH_TEMPLATE = path_template.PathTemplate('projects/{project}') _GROUP_PATH_TEMPLATE = path_template.PathTemplate( 'projects/{project}/groups/{group}') @classmethod def project_path(cls, project): """Returns a fully-qualified project resource name string.""" return cls._PROJECT_PATH_TEMPLATE.render({ 'project': project, }) @classmethod def group_path(cls, project, group): """Returns a fully-qualified group resource name string.""" return cls._GROUP_PATH_TEMPLATE.render({ 'project': project, 'group': group, }) @classmethod def match_project_from_project_name(cls, project_name): """Parses the project from a project resource. Args: project_name (string): A fully-qualified path representing a project resource. Returns: A string representing the project. """ return cls._PROJECT_PATH_TEMPLATE.match(project_name).get('project') @classmethod def match_project_from_group_name(cls, group_name): """Parses the project from a group resource. Args: group_name (string): A fully-qualified path representing a group resource. Returns: A string representing the project. """ return cls._GROUP_PATH_TEMPLATE.match(group_name).get('project') @classmethod def match_group_from_group_name(cls, group_name): """Parses the group from a group resource. Args: group_name (string): A fully-qualified path representing a group resource. Returns: A string representing the group. """ return cls._GROUP_PATH_TEMPLATE.match(group_name).get('group') def __init__(self, service_path=SERVICE_ADDRESS, port=DEFAULT_SERVICE_PORT, channel=None, metadata_transformer=None, ssl_creds=None, scopes=None, client_config=None, app_name='gax', app_version=_GAX_VERSION): """Constructor. Args: service_path (string): The domain name of the API remote host. port (int): The port on which to connect to the remote host. channel (:class:`grpc.Channel`): A ``Channel`` instance through which to make calls. ssl_creds (:class:`grpc.ChannelCredentials`): A ``ChannelCredentials`` instance for use with an SSL-enabled channel. client_config (dict): A dictionary for call options for each method. See :func:`google.gax.construct_settings` for the structure of this data. Falls back to the default config if not specified or the specified config is missing data points. metadata_transformer (Callable[[], list]): A function that creates the metadata for requests. app_name (string): The codename of the calling service. app_version (string): The version of the calling service. Returns: A GroupServiceApi object. """ if scopes is None: scopes = self._ALL_SCOPES if client_config is None: client_config = {} goog_api_client = '{}/{} {} gax/{} python/{}'.format( app_name, app_version, self._CODE_GEN_NAME_VERSION, self._GAX_VERSION, platform.python_version()) metadata = [('x-goog-api-client', goog_api_client)] default_client_config = json.loads( pkg_resources.resource_string( __name__, 'group_service_client_config.json').decode()) defaults = api_callable.construct_settings( 'google.monitoring.v3.GroupService', default_client_config, client_config, config.STATUS_CODE_NAMES, kwargs={'metadata': metadata}, page_descriptors=self._PAGE_DESCRIPTORS) self.group_service_stub = config.create_stub( group_service_pb2.GroupServiceStub, service_path, port, ssl_creds=ssl_creds, channel=channel, metadata_transformer=metadata_transformer, scopes=scopes) self._list_groups = api_callable.create_api_call( self.group_service_stub.ListGroups, settings=defaults['list_groups']) self._get_group = api_callable.create_api_call( self.group_service_stub.GetGroup, settings=defaults['get_group']) self._create_group = api_callable.create_api_call( self.group_service_stub.CreateGroup, settings=defaults['create_group']) self._update_group = api_callable.create_api_call( self.group_service_stub.UpdateGroup, settings=defaults['update_group']) self._delete_group = api_callable.create_api_call( self.group_service_stub.DeleteGroup, settings=defaults['delete_group']) self._list_group_members = api_callable.create_api_call( self.group_service_stub.ListGroupMembers, settings=defaults['list_group_members']) # Service calls def list_groups(self, name, children_of_group='', ancestors_of_group='', descendants_of_group='', page_size=0, options=None): """ Lists the existing groups. Example: >>> from google.cloud.gapic.monitoring.v3 import group_service_api >>> from google.gax import CallOptions, INITIAL_PAGE >>> api = group_service_api.GroupServiceApi() >>> name = api.project_path('[PROJECT]') >>> >>> # Iterate over all results >>> for element in api.list_groups(name): >>> # process element >>> pass >>> >>> # Or iterate over results one page at a time >>> for page in api.list_groups(name, options=CallOptions(page_token=INITIAL_PAGE)): >>> for element in page: >>> # process element >>> pass Args: name (string): The project whose groups are to be listed. The format is ``\"projects/{project_id_or_number}\"``. children_of_group (string): A group name: ``\"projects/{project_id_or_number}/groups/{group_id}\"``. Returns groups whose ``parentName`` field contains the group name. If no groups have this parent, the results are empty. ancestors_of_group (string): A group name: ``\"projects/{project_id_or_number}/groups/{group_id}\"``. Returns groups that are ancestors of the specified group. The groups are returned in order, starting with the immediate parent and ending with the most distant ancestor. If the specified group has no immediate parent, the results are empty. descendants_of_group (string): A group name: ``\"projects/{project_id_or_number}/groups/{group_id}\"``. Returns the descendants of the specified group. This is a superset of the results returned by the ``childrenOfGroup`` filter, and includes children-of-children, and so forth. page_size (int): The maximum number of resources contained in the underlying API response. If page streaming is performed per- resource, this parameter does not affect the return value. If page streaming is performed per-page, this determines the maximum number of resources in a page. options (:class:`google.gax.CallOptions`): Overrides the default settings for this call, e.g, timeout, retries etc. Returns: A :class:`google.gax.PageIterator` instance. By default, this is an iterable of :class:`google.monitoring.v3.group_pb2.Group` instances. This object can also be configured to iterate over the pages of the response through the `CallOptions` parameter. Raises: :exc:`google.gax.errors.GaxError` if the RPC is aborted. :exc:`ValueError` if the parameters are invalid. """ request = group_service_pb2.ListGroupsRequest( name=name, children_of_group=children_of_group, ancestors_of_group=ancestors_of_group, descendants_of_group=descendants_of_group, page_size=page_size) return self._list_groups(request, options) def get_group(self, name, options=None): """ Gets a single group. Example: >>> from google.cloud.gapic.monitoring.v3 import group_service_api >>> api = group_service_api.GroupServiceApi() >>> name = api.group_path('[PROJECT]', '[GROUP]') >>> response = api.get_group(name) Args: name (string): The group to retrieve. The format is ``\"projects/{project_id_or_number}/groups/{group_id}\"``. options (:class:`google.gax.CallOptions`): Overrides the default settings for this call, e.g, timeout, retries etc. Returns: A :class:`google.monitoring.v3.group_pb2.Group` instance. Raises: :exc:`google.gax.errors.GaxError` if the RPC is aborted. :exc:`ValueError` if the parameters are invalid. """ request = group_service_pb2.GetGroupRequest(name=name) return self._get_group(request, options) def create_group(self, name, group, validate_only=False, options=None): """ Creates a new group. Example: >>> from google.cloud.gapic.monitoring.v3 import group_service_api >>> from google.monitoring.v3 import group_pb2 >>> api = group_service_api.GroupServiceApi() >>> name = api.project_path('[PROJECT]') >>> group = group_pb2.Group() >>> response = api.create_group(name, group) Args: name (string): The project in which to create the group. The format is ``\"projects/{project_id_or_number}\"``. group (:class:`google.monitoring.v3.group_pb2.Group`): A group definition. It is an error to define the ``name`` field because the system assigns the name. validate_only (bool): If true, validate this request but do not create the group. options (:class:`google.gax.CallOptions`): Overrides the default settings for this call, e.g, timeout, retries etc. Returns: A :class:`google.monitoring.v3.group_pb2.Group` instance. Raises: :exc:`google.gax.errors.GaxError` if the RPC is aborted. :exc:`ValueError` if the parameters are invalid. """ request = group_service_pb2.CreateGroupRequest( name=name, group=group, validate_only=validate_only) return self._create_group(request, options) def update_group(self, group, validate_only=False, options=None): """ Updates an existing group. You can change any group attributes except ``name``. Example: >>> from google.cloud.gapic.monitoring.v3 import group_service_api >>> from google.monitoring.v3 import group_pb2 >>> api = group_service_api.GroupServiceApi() >>> group = group_pb2.Group() >>> response = api.update_group(group) Args: group (:class:`google.monitoring.v3.group_pb2.Group`): The new definition of the group. All fields of the existing group, excepting ``name``, are replaced with the corresponding fields of this group. validate_only (bool): If true, validate this request but do not update the existing group. options (:class:`google.gax.CallOptions`): Overrides the default settings for this call, e.g, timeout, retries etc. Returns: A :class:`google.monitoring.v3.group_pb2.Group` instance. Raises: :exc:`google.gax.errors.GaxError` if the RPC is aborted. :exc:`ValueError` if the parameters are invalid. """ request = group_service_pb2.UpdateGroupRequest( group=group, validate_only=validate_only) return self._update_group(request, options) def delete_group(self, name, options=None): """ Deletes an existing group. Example: >>> from google.cloud.gapic.monitoring.v3 import group_service_api >>> api = group_service_api.GroupServiceApi() >>> name = api.group_path('[PROJECT]', '[GROUP]') >>> api.delete_group(name) Args: name (string): The group to delete. The format is ``\"projects/{project_id_or_number}/groups/{group_id}\"``. options (:class:`google.gax.CallOptions`): Overrides the default settings for this call, e.g, timeout, retries etc. Raises: :exc:`google.gax.errors.GaxError` if the RPC is aborted. :exc:`ValueError` if the parameters are invalid. """ request = group_service_pb2.DeleteGroupRequest(name=name) self._delete_group(request, options) def list_group_members(self, name, page_size=0, filter_='', interval=None, options=None): """ Lists the monitored resources that are members of a group. Example: >>> from google.cloud.gapic.monitoring.v3 import group_service_api >>> from google.gax import CallOptions, INITIAL_PAGE >>> api = group_service_api.GroupServiceApi() >>> name = api.group_path('[PROJECT]', '[GROUP]') >>> >>> # Iterate over all results >>> for element in api.list_group_members(name): >>> # process element >>> pass >>> >>> # Or iterate over results one page at a time >>> for page in api.list_group_members(name, options=CallOptions(page_token=INITIAL_PAGE)): >>> for element in page: >>> # process element >>> pass Args: name (string): The group whose members are listed. The format is ``\"projects/{project_id_or_number}/groups/{group_id}\"``. page_size (int): The maximum number of resources contained in the underlying API response. If page streaming is performed per- resource, this parameter does not affect the return value. If page streaming is performed per-page, this determines the maximum number of resources in a page. filter_ (string): An optional `list filter <https://cloud.google.com/monitoring/api/learn_more#filtering>`_ describing the members to be returned. The filter may reference the type, labels, and metadata of monitored resources that comprise the group. For example, to return only resources representing Compute Engine VM instances, use this filter: resource.type = \"gce_instance\" interval (:class:`google.monitoring.v3.common_pb2.TimeInterval`): An optional time interval for which results should be returned. Only members that were part of the group during the specified interval are included in the response. If no interval is provided then the group membership over the last minute is returned. options (:class:`google.gax.CallOptions`): Overrides the default settings for this call, e.g, timeout, retries etc. Returns: A :class:`google.gax.PageIterator` instance. By default, this is an iterable of :class:`google.api.monitored_resource_pb2.MonitoredResource` instances. This object can also be configured to iterate over the pages of the response through the `CallOptions` parameter. Raises: :exc:`google.gax.errors.GaxError` if the RPC is aborted. :exc:`ValueError` if the parameters are invalid. """ if interval is None: interval = common_pb2.TimeInterval() request = group_service_pb2.ListGroupMembersRequest( name=name, page_size=page_size, filter=filter_, interval=interval) return self._list_group_members(request, options)