diff --git a/google/cloud/datacatalog_v1/__init__.py b/google/cloud/datacatalog_v1/__init__.py index c793267f..37c5f8a3 100644 --- a/google/cloud/datacatalog_v1/__init__.py +++ b/google/cloud/datacatalog_v1/__init__.py @@ -25,6 +25,9 @@ PolicyTagManagerSerializationAsyncClient, ) +from .types.bigquery import BigQueryConnectionSpec +from .types.bigquery import BigQueryRoutineSpec +from .types.bigquery import CloudSqlBigQueryConnectionSpec from .types.common import IntegratedSystem from .types.data_source import DataSource from .types.datacatalog import CreateEntryGroupRequest @@ -33,6 +36,7 @@ from .types.datacatalog import CreateTagTemplateFieldRequest from .types.datacatalog import CreateTagTemplateRequest from .types.datacatalog import DatabaseTableSpec +from .types.datacatalog import DataSourceConnectionSpec from .types.datacatalog import DeleteEntryGroupRequest from .types.datacatalog import DeleteEntryRequest from .types.datacatalog import DeleteTagRequest @@ -52,6 +56,7 @@ from .types.datacatalog import LookupEntryRequest from .types.datacatalog import RenameTagTemplateFieldEnumValueRequest from .types.datacatalog import RenameTagTemplateFieldRequest +from .types.datacatalog import RoutineSpec from .types.datacatalog import SearchCatalogRequest from .types.datacatalog import SearchCatalogResponse from .types.datacatalog import UpdateEntryGroupRequest @@ -82,6 +87,7 @@ from .types.policytagmanagerserialization import ImportTaxonomiesRequest from .types.policytagmanagerserialization import ImportTaxonomiesResponse from .types.policytagmanagerserialization import InlineSource +from .types.policytagmanagerserialization import ReplaceTaxonomyRequest from .types.policytagmanagerserialization import SerializedPolicyTag from .types.policytagmanagerserialization import SerializedTaxonomy from .types.schema import ColumnSchema @@ -99,13 +105,18 @@ from .types.tags import TagTemplate from .types.tags import TagTemplateField from .types.timestamps import SystemTimestamps +from .types.usage import UsageSignal +from .types.usage import UsageStats __all__ = ( "DataCatalogAsyncClient", "PolicyTagManagerAsyncClient", "PolicyTagManagerSerializationAsyncClient", + "BigQueryConnectionSpec", "BigQueryDateShardedSpec", + "BigQueryRoutineSpec", "BigQueryTableSpec", + "CloudSqlBigQueryConnectionSpec", "ColumnSchema", "CreateEntryGroupRequest", "CreateEntryRequest", @@ -117,6 +128,7 @@ "CrossRegionalSource", "DataCatalogClient", "DataSource", + "DataSourceConnectionSpec", "DatabaseTableSpec", "DeleteEntryGroupRequest", "DeleteEntryRequest", @@ -158,6 +170,8 @@ "PolicyTagManagerSerializationClient", "RenameTagTemplateFieldEnumValueRequest", "RenameTagTemplateFieldRequest", + "ReplaceTaxonomyRequest", + "RoutineSpec", "Schema", "SearchCatalogRequest", "SearchCatalogResponse", @@ -180,5 +194,7 @@ "UpdateTagTemplateFieldRequest", "UpdateTagTemplateRequest", "UpdateTaxonomyRequest", + "UsageSignal", + "UsageStats", "ViewSpec", ) diff --git a/google/cloud/datacatalog_v1/gapic_metadata.json b/google/cloud/datacatalog_v1/gapic_metadata.json index fed22e35..99e0398a 100644 --- a/google/cloud/datacatalog_v1/gapic_metadata.json +++ b/google/cloud/datacatalog_v1/gapic_metadata.json @@ -457,6 +457,11 @@ "methods": [ "import_taxonomies" ] + }, + "ReplaceTaxonomy": { + "methods": [ + "replace_taxonomy" + ] } } }, @@ -472,6 +477,11 @@ "methods": [ "import_taxonomies" ] + }, + "ReplaceTaxonomy": { + "methods": [ + "replace_taxonomy" + ] } } } diff --git a/google/cloud/datacatalog_v1/services/data_catalog/async_client.py b/google/cloud/datacatalog_v1/services/data_catalog/async_client.py index 6eca9dcc..e9499b91 100644 --- a/google/cloud/datacatalog_v1/services/data_catalog/async_client.py +++ b/google/cloud/datacatalog_v1/services/data_catalog/async_client.py @@ -36,6 +36,7 @@ from google.cloud.datacatalog_v1.types import table_spec from google.cloud.datacatalog_v1.types import tags from google.cloud.datacatalog_v1.types import timestamps +from google.cloud.datacatalog_v1.types import usage from google.iam.v1 import iam_policy_pb2 # type: ignore from google.iam.v1 import policy_pb2 # type: ignore from google.protobuf import field_mask_pb2 # type: ignore @@ -45,8 +46,8 @@ class DataCatalogAsyncClient: - """Data Catalog API service allows clients to discover, - understand, and manage their data. + """Data Catalog API service allows you to discover, understand, + and manage your data. """ _client: DataCatalogClient @@ -196,54 +197,53 @@ async def search_catalog( timeout: float = None, metadata: Sequence[Tuple[str, str]] = (), ) -> pagers.SearchCatalogAsyncPager: - r"""Searches Data Catalog for multiple resources like entries, tags - that match a query. + r"""Searches Data Catalog for multiple resources like entries and + tags that match a query. - This is a custom method - (https://cloud.google.com/apis/design/custom_methods) and does - not return the complete resource, only the resource identifier - and high level fields. Clients can subsequently call ``Get`` - methods. + This is a [Custom Method] + (https://cloud.google.com/apis/design/custom_methods) that + doesn't return all information on a resource, only its ID and + high level fields. To get more information, you can subsequently + call specific get methods. - Note that Data Catalog search queries do not guarantee full - recall. Query results that match your query may not be returned, - even in subsequent result pages. Also note that results returned - (and not returned) can vary across repeated search queries. + Note: Data Catalog search queries don't guarantee full recall. + Results that match your query might not be returned, even in + subsequent result pages. Additionally, returned (and not + returned) results can vary if you repeat search queries. - See `Data Catalog Search - Syntax `__ - for more information. + For more information, see [Data Catalog search syntax] + (https://cloud.google.com/data-catalog/docs/how-to/search-reference). Args: request (:class:`google.cloud.datacatalog_v1.types.SearchCatalogRequest`): The request object. Request message for [SearchCatalog][google.cloud.datacatalog.v1.DataCatalog.SearchCatalog]. scope (:class:`google.cloud.datacatalog_v1.types.SearchCatalogRequest.Scope`): - Required. The scope of this search request. A ``scope`` - that has empty ``include_org_ids``, - ``include_project_ids`` AND false - ``include_gcp_public_datasets`` is considered invalid. - Data Catalog will return an error in such a case. + Required. The scope of this search request. + + The ``scope`` is invalid if ``include_org_ids``, + ``include_project_ids`` are empty AND + ``include_gcp_public_datasets`` is set to ``false``. In + this case, the request returns an error. This corresponds to the ``scope`` field on the ``request`` instance; if ``request`` is provided, this should not be set. query (:class:`str`): - Optional. The query string in search query syntax. An - empty query string will result in all data assets (in - the specified scope) that the user has access to. + Optional. The query string with a minimum of 3 + characters and specific syntax. For more information, + see `Data Catalog search + syntax `__. - Query strings can be simple as "x" or more qualified as: + An empty query string returns all data assets (in the + specified scope) that you have access to. - - name:x - - column:x - - description:y + A query string can be a simple ``xyz`` or qualified by + predicates: - Note: Query tokens need to have a minimum of 3 - characters for substring matching to work correctly. See - `Data Catalog Search - Syntax `__ - for more information. + - ``name:x`` + - ``column:y`` + - ``description:z`` This corresponds to the ``query`` field on the ``request`` instance; if ``request`` is provided, this @@ -322,41 +322,48 @@ async def create_entry_group( timeout: float = None, metadata: Sequence[Tuple[str, str]] = (), ) -> datacatalog.EntryGroup: - r"""Creates an EntryGroup. + r"""Creates an entry group. An entry group contains logically related entries together with - Cloud Identity and Access Management policies that specify the - users who can create, edit, and view entries within the entry - group. + `Cloud Identity and Access + Management `__ policies. These + policies specify users who can create, edit, and view entries + within entry groups. + + Data Catalog automatically creates entry groups with names that + start with the ``@`` symbol for the following resources: + + - BigQuery entries (``@bigquery``) + - Pub/Sub topics (``@pubsub``) + - Dataproc Metastore services + (``@dataproc_metastore_{SERVICE_NAME_HASH}``) + + You can create your own entry groups for Cloud Storage fileset + entries and custom entries together with the corresponding IAM + policies. User-created entry groups can't contain the ``@`` + symbol, it is reserved for automatically created groups. - Data Catalog automatically creates an entry group for BigQuery - entries ("@bigquery") and Pub/Sub topics ("@pubsub"). Users - create their own entry group to contain Cloud Storage fileset - entries or custom type entries, and the IAM policies associated - with those entries. Entry groups, like entries, can be searched. + Entry groups, like entries, can be searched. A maximum of 10,000 entry groups may be created per organization across all locations. - Users should enable the Data Catalog API in the project - identified by the ``parent`` parameter (see [Data Catalog - Resource Project] - (https://cloud.google.com/data-catalog/docs/concepts/resource-project) - for more information). + You must enable the Data Catalog API in the project identified + by the ``parent`` parameter. For more information, see `Data + Catalog resource + project `__. Args: request (:class:`google.cloud.datacatalog_v1.types.CreateEntryGroupRequest`): The request object. Request message for [CreateEntryGroup][google.cloud.datacatalog.v1.DataCatalog.CreateEntryGroup]. parent (:class:`str`): - Required. The name of the project this entry group - belongs to. Example: - - ``projects/{project_id}/locations/{location}`` - - Note: The entry group itself and its child resources - might not be stored in the location specified in its - name. + Required. The names of the project + and location that the new entry group + belongs to. Note: The entry group + itself and its child resources might not + be stored in the location specified in + its name. This corresponds to the ``parent`` field on the ``request`` instance; if ``request`` is provided, this @@ -374,7 +381,7 @@ async def create_entry_group( should not be set. entry_group (:class:`google.cloud.datacatalog_v1.types.EntryGroup`): The entry group to create. Defaults - to an empty entry group. + to empty. This corresponds to the ``entry_group`` field on the ``request`` instance; if ``request`` is provided, this @@ -387,7 +394,8 @@ async def create_entry_group( Returns: google.cloud.datacatalog_v1.types.EntryGroup: - EntryGroup Metadata. + Entry group metadata. + An EntryGroup resource represents a logical grouping of zero or more Data Catalog [Entry][google.cloud.datacatalog.v1.Entry] resources. @@ -444,22 +452,22 @@ async def get_entry_group( timeout: float = None, metadata: Sequence[Tuple[str, str]] = (), ) -> datacatalog.EntryGroup: - r"""Gets an EntryGroup. + r"""Gets an entry group. Args: request (:class:`google.cloud.datacatalog_v1.types.GetEntryGroupRequest`): The request object. Request message for [GetEntryGroup][google.cloud.datacatalog.v1.DataCatalog.GetEntryGroup]. name (:class:`str`): - Required. The name of the entry group. For example, - ``projects/{project_id}/locations/{location}/entryGroups/{entry_group_id}``. + Required. The name of the entry group + to get. This corresponds to the ``name`` field on the ``request`` instance; if ``request`` is provided, this should not be set. read_mask (:class:`google.protobuf.field_mask_pb2.FieldMask`): - The fields to return. If not set or - empty, all fields are returned. + The fields to return. If empty or + omitted, all fields are returned. This corresponds to the ``read_mask`` field on the ``request`` instance; if ``request`` is provided, this @@ -472,7 +480,8 @@ async def get_entry_group( Returns: google.cloud.datacatalog_v1.types.EntryGroup: - EntryGroup Metadata. + Entry group metadata. + An EntryGroup resource represents a logical grouping of zero or more Data Catalog [Entry][google.cloud.datacatalog.v1.Entry] resources. @@ -536,19 +545,20 @@ async def update_entry_group( timeout: float = None, metadata: Sequence[Tuple[str, str]] = (), ) -> datacatalog.EntryGroup: - r"""Updates an EntryGroup. The user should enable the Data Catalog - API in the project identified by the ``entry_group.name`` - parameter (see [Data Catalog Resource Project] - (https://cloud.google.com/data-catalog/docs/concepts/resource-project) - for more information). + r"""Updates an entry group. + + You must enable the Data Catalog API in the project identified + by the ``entry_group.name`` parameter. For more information, see + `Data Catalog resource + project `__. Args: request (:class:`google.cloud.datacatalog_v1.types.UpdateEntryGroupRequest`): The request object. Request message for [UpdateEntryGroup][google.cloud.datacatalog.v1.DataCatalog.UpdateEntryGroup]. entry_group (:class:`google.cloud.datacatalog_v1.types.EntryGroup`): - Required. The updated entry group. - "name" field must be set. + Required. Updates for the entry group. The ``name`` + field must be set. This corresponds to the ``entry_group`` field on the ``request`` instance; if ``request`` is provided, this @@ -573,7 +583,8 @@ async def update_entry_group( Returns: google.cloud.datacatalog_v1.types.EntryGroup: - EntryGroup Metadata. + Entry group metadata. + An EntryGroup resource represents a logical grouping of zero or more Data Catalog [Entry][google.cloud.datacatalog.v1.Entry] resources. @@ -629,20 +640,20 @@ async def delete_entry_group( timeout: float = None, metadata: Sequence[Tuple[str, str]] = (), ) -> None: - r"""Deletes an EntryGroup. Only entry groups that do not contain - entries can be deleted. Users should enable the Data Catalog API - in the project identified by the ``name`` parameter (see [Data - Catalog Resource Project] - (https://cloud.google.com/data-catalog/docs/concepts/resource-project) - for more information). + r"""Deletes an entry group. + + You must enable the Data Catalog API in the project identified + by the ``name`` parameter. For more information, see `Data + Catalog resource + project `__. Args: request (:class:`google.cloud.datacatalog_v1.types.DeleteEntryGroupRequest`): The request object. Request message for [DeleteEntryGroup][google.cloud.datacatalog.v1.DataCatalog.DeleteEntryGroup]. name (:class:`str`): - Required. The name of the entry group. For example, - ``projects/{project_id}/locations/{location}/entryGroups/{entry_group_id}``. + Required. The name of the entry group + to delete. This corresponds to the ``name`` field on the ``request`` instance; if ``request`` is provided, this @@ -705,11 +716,9 @@ async def list_entry_groups( The request object. Request message for [ListEntryGroups][google.cloud.datacatalog.v1.DataCatalog.ListEntryGroups]. parent (:class:`str`): - Required. The name of the location that contains the - entry groups, which can be provided in URL format. - Example: - - - projects/{project_id}/locations/{location} + Required. The name of the location + that contains the entry groups to list. + Can be provided as a URL. This corresponds to the ``parent`` field on the ``request`` instance; if ``request`` is provided, this @@ -792,29 +801,30 @@ async def create_entry( timeout: float = None, metadata: Sequence[Tuple[str, str]] = (), ) -> datacatalog.Entry: - r"""Creates an entry. Only entries of types 'FILESET', 'CLUSTER', - 'DATA_STREAM' or with a user-specified type can be created. + r"""Creates an entry. - Users should enable the Data Catalog API in the project - identified by the ``parent`` parameter (see [Data Catalog - Resource Project] - (https://cloud.google.com/data-catalog/docs/concepts/resource-project) - for more information). + You can create entries only with 'FILESET', 'CLUSTER', + 'DATA_STREAM', or custom types. Data Catalog automatically + creates entries with other types during metadata ingestion from + integrated systems. - A maximum of 100,000 entries may be created per entry group. + You must enable the Data Catalog API in the project identified + by the ``parent`` parameter. For more information, see `Data + Catalog resource + project `__. + + An entry group can have a maximum of 100,000 entries. Args: request (:class:`google.cloud.datacatalog_v1.types.CreateEntryRequest`): The request object. Request message for [CreateEntry][google.cloud.datacatalog.v1.DataCatalog.CreateEntry]. parent (:class:`str`): - Required. The name of the entry group this entry belongs - to. Example: - - ``projects/{project_id}/locations/{location}/entryGroups/{entry_group_id}`` - - Note: The entry itself and its child resources might not - be stored in the location specified in its name. + Required. The name of the entry group + this entry belongs to. + Note: The entry itself and its child + resources might not be stored in the + location specified in its name. This corresponds to the ``parent`` field on the ``request`` instance; if ``request`` is provided, this @@ -842,17 +852,16 @@ async def create_entry( Returns: google.cloud.datacatalog_v1.types.Entry: - Entry Metadata. - A Data Catalog Entry resource represents another - resource in Google Cloud Platform (such as a BigQuery - dataset or a Pub/Sub topic) or outside of Google - Cloud Platform. Clients can use the linked_resource - field in the Entry resource to refer to the original - resource ID of the source system. - - An Entry resource contains resource details, such as - its schema. An Entry can also be used to attach - flexible metadata, such as a + Entry metadata. + A Data Catalog entry represents another resource in + Google Cloud Platform (such as a BigQuery dataset or + a Pub/Sub topic) or outside of it. You can use the + linked_resource field in the entry resource to refer + to the original resource ID of the source system. + + An entry resource contains resource details, for + example, its schema. Additionally, you can attach + flexible metadata to an entry in the form of a [Tag][google.cloud.datacatalog.v1.Tag]. """ @@ -907,19 +916,20 @@ async def update_entry( timeout: float = None, metadata: Sequence[Tuple[str, str]] = (), ) -> datacatalog.Entry: - r"""Updates an existing entry. Users should enable the Data Catalog - API in the project identified by the ``entry.name`` parameter - (see [Data Catalog Resource Project] - (https://cloud.google.com/data-catalog/docs/concepts/resource-project) - for more information). + r"""Updates an existing entry. + + You must enable the Data Catalog API in the project identified + by the ``entry.name`` parameter. For more information, see `Data + Catalog resource + project `__. Args: request (:class:`google.cloud.datacatalog_v1.types.UpdateEntryRequest`): The request object. Request message for [UpdateEntry][google.cloud.datacatalog.v1.DataCatalog.UpdateEntry]. entry (:class:`google.cloud.datacatalog_v1.types.Entry`): - Required. The updated entry. The - "name" field must be set. + Required. Updates for the entry. The ``name`` field must + be set. This corresponds to the ``entry`` field on the ``request`` instance; if ``request`` is provided, this @@ -932,29 +942,29 @@ async def update_entry( and omitted in the request body, their values are emptied. - The following fields are modifiable: + You can modify only the fields listed below. - - For entries with type ``DATA_STREAM``: + For entries with type ``DATA_STREAM``: - - ``schema`` + - ``schema`` - - For entries with type ``FILESET``: + For entries with type ``FILESET``: - - ``schema`` - - ``display_name`` - - ``description`` - - ``gcs_fileset_spec`` - - ``gcs_fileset_spec.file_patterns`` + - ``schema`` + - ``display_name`` + - ``description`` + - ``gcs_fileset_spec`` + - ``gcs_fileset_spec.file_patterns`` - - For entries with ``user_specified_type``: + For entries with ``user_specified_type``: - - ``schema`` - - ``display_name`` - - ``description`` - - ``user_specified_type`` - - ``user_specified_system`` - - ``linked_resource`` - - ``source_system_timestamps`` + - ``schema`` + - ``display_name`` + - ``description`` + - ``user_specified_type`` + - ``user_specified_system`` + - ``linked_resource`` + - ``source_system_timestamps`` This corresponds to the ``update_mask`` field on the ``request`` instance; if ``request`` is provided, this @@ -967,17 +977,16 @@ async def update_entry( Returns: google.cloud.datacatalog_v1.types.Entry: - Entry Metadata. - A Data Catalog Entry resource represents another - resource in Google Cloud Platform (such as a BigQuery - dataset or a Pub/Sub topic) or outside of Google - Cloud Platform. Clients can use the linked_resource - field in the Entry resource to refer to the original - resource ID of the source system. - - An Entry resource contains resource details, such as - its schema. An Entry can also be used to attach - flexible metadata, such as a + Entry metadata. + A Data Catalog entry represents another resource in + Google Cloud Platform (such as a BigQuery dataset or + a Pub/Sub topic) or outside of it. You can use the + linked_resource field in the entry resource to refer + to the original resource ID of the source system. + + An entry resource contains resource details, for + example, its schema. Additionally, you can attach + flexible metadata to an entry in the form of a [Tag][google.cloud.datacatalog.v1.Tag]. """ @@ -1031,22 +1040,24 @@ async def delete_entry( timeout: float = None, metadata: Sequence[Tuple[str, str]] = (), ) -> None: - r"""Deletes an existing entry. Only entries created through + r"""Deletes an existing entry. + + You can delete only the entries created by the [CreateEntry][google.cloud.datacatalog.v1.DataCatalog.CreateEntry] - method can be deleted. Users should enable the Data Catalog API - in the project identified by the ``name`` parameter (see [Data - Catalog Resource Project] - (https://cloud.google.com/data-catalog/docs/concepts/resource-project) - for more information). + method. + + You must enable the Data Catalog API in the project identified + by the ``name`` parameter. For more information, see `Data + Catalog resource + project `__. Args: request (:class:`google.cloud.datacatalog_v1.types.DeleteEntryRequest`): The request object. Request message for [DeleteEntry][google.cloud.datacatalog.v1.DataCatalog.DeleteEntry]. name (:class:`str`): - Required. The name of the entry. Example: - - - projects/{project_id}/locations/{location}/entryGroups/{entry_group_id}/entries/{entry_id} + Required. The name of the entry to + delete. This corresponds to the ``name`` field on the ``request`` instance; if ``request`` is provided, this @@ -1109,9 +1120,8 @@ async def get_entry( The request object. Request message for [GetEntry][google.cloud.datacatalog.v1.DataCatalog.GetEntry]. name (:class:`str`): - Required. The name of the entry. Example: - - - projects/{project_id}/locations/{location}/entryGroups/{entry_group_id}/entries/{entry_id} + Required. The name of the entry to + get. This corresponds to the ``name`` field on the ``request`` instance; if ``request`` is provided, this @@ -1124,17 +1134,16 @@ async def get_entry( Returns: google.cloud.datacatalog_v1.types.Entry: - Entry Metadata. - A Data Catalog Entry resource represents another - resource in Google Cloud Platform (such as a BigQuery - dataset or a Pub/Sub topic) or outside of Google - Cloud Platform. Clients can use the linked_resource - field in the Entry resource to refer to the original - resource ID of the source system. - - An Entry resource contains resource details, such as - its schema. An Entry can also be used to attach - flexible metadata, such as a + Entry metadata. + A Data Catalog entry represents another resource in + Google Cloud Platform (such as a BigQuery dataset or + a Pub/Sub topic) or outside of it. You can use the + linked_resource field in the entry resource to refer + to the original resource ID of the source system. + + An entry resource contains resource details, for + example, its schema. Additionally, you can attach + flexible metadata to an entry in the form of a [Tag][google.cloud.datacatalog.v1.Tag]. """ @@ -1192,10 +1201,9 @@ async def lookup_entry( timeout: float = None, metadata: Sequence[Tuple[str, str]] = (), ) -> datacatalog.Entry: - r"""Get an entry by target resource name. This method - allows clients to use the resource name from the source - Google Cloud Platform service to get the Data Catalog - Entry. + r"""Gets an entry by its target resource name. + The resource name comes from the source Google Cloud + Platform service. Args: request (:class:`google.cloud.datacatalog_v1.types.LookupEntryRequest`): @@ -1209,17 +1217,16 @@ async def lookup_entry( Returns: google.cloud.datacatalog_v1.types.Entry: - Entry Metadata. - A Data Catalog Entry resource represents another - resource in Google Cloud Platform (such as a BigQuery - dataset or a Pub/Sub topic) or outside of Google - Cloud Platform. Clients can use the linked_resource - field in the Entry resource to refer to the original - resource ID of the source system. - - An Entry resource contains resource details, such as - its schema. An Entry can also be used to attach - flexible metadata, such as a + Entry metadata. + A Data Catalog entry represents another resource in + Google Cloud Platform (such as a BigQuery dataset or + a Pub/Sub topic) or outside of it. You can use the + linked_resource field in the entry resource to refer + to the original resource ID of the source system. + + An entry resource contains resource details, for + example, its schema. Additionally, you can attach + flexible metadata to an entry in the form of a [Tag][google.cloud.datacatalog.v1.Tag]. """ @@ -1265,10 +1272,9 @@ async def list_entries( The request object. Request message for [ListEntries][google.cloud.datacatalog.v1.DataCatalog.ListEntries]. parent (:class:`str`): - Required. The name of the entry group that contains the - entries, which can be provided in URL format. Example: - - - projects/{project_id}/locations/{location}/entryGroups/{entry_group_id} + Required. The name of the entry group + that contains the entries to list. + Can be provided in URL format. This corresponds to the ``parent`` field on the ``request`` instance; if ``request`` is provided, this @@ -1351,11 +1357,12 @@ async def create_tag_template( timeout: float = None, metadata: Sequence[Tuple[str, str]] = (), ) -> tags.TagTemplate: - r"""Creates a tag template. The user should enable the Data Catalog - API in the project identified by the ``parent`` parameter (see - `Data Catalog Resource - Project `__ - for more information). + r"""Creates a tag template. + + You must enable the Data Catalog API in the project identified + by the ``parent`` parameter. For more information, see [Data + Catalog resource project] + (https://cloud.google.com/data-catalog/docs/concepts/resource-project). Args: request (:class:`google.cloud.datacatalog_v1.types.CreateTagTemplateRequest`): @@ -1366,10 +1373,6 @@ async def create_tag_template( location `region `__. - Example: - - - projects/{project_id}/locations/us-central1 - This corresponds to the ``parent`` field on the ``request`` instance; if ``request`` is provided, this should not be set. @@ -1397,14 +1400,16 @@ async def create_tag_template( Returns: google.cloud.datacatalog_v1.types.TagTemplate: - A tag template defines a tag, which can have one or more typed fields. - The template is used to create and attach the tag to - GCP resources. [Tag template - roles](\ https://cloud.google.com/iam/docs/understanding-roles#data-catalog-roles) + A tag template defines a tag that can have one or more + typed fields. + + The template is used to create tags that are attached + to GCP resources. [Tag template roles] + (https://cloud.google.com/iam/docs/understanding-roles#data-catalog-roles) provide permissions to create, edit, and use the - template. See, for example, the [TagTemplate - User](\ https://cloud.google.com/data-catalog/docs/how-to/template-user) - role, which includes permission to use the tag + template. For example, see the [TagTemplate User] + (https://cloud.google.com/data-catalog/docs/how-to/template-user) + role that includes a permission to use the tag template to tag resources. """ @@ -1465,9 +1470,8 @@ async def get_tag_template( The request object. Request message for [GetTagTemplate][google.cloud.datacatalog.v1.DataCatalog.GetTagTemplate]. name (:class:`str`): - Required. The name of the tag template. Example: - - - projects/{project_id}/locations/{location}/tagTemplates/{tag_template_id} + Required. The name of the tag + template to get. This corresponds to the ``name`` field on the ``request`` instance; if ``request`` is provided, this @@ -1480,14 +1484,16 @@ async def get_tag_template( Returns: google.cloud.datacatalog_v1.types.TagTemplate: - A tag template defines a tag, which can have one or more typed fields. - The template is used to create and attach the tag to - GCP resources. [Tag template - roles](\ https://cloud.google.com/iam/docs/understanding-roles#data-catalog-roles) + A tag template defines a tag that can have one or more + typed fields. + + The template is used to create tags that are attached + to GCP resources. [Tag template roles] + (https://cloud.google.com/iam/docs/understanding-roles#data-catalog-roles) provide permissions to create, edit, and use the - template. See, for example, the [TagTemplate - User](\ https://cloud.google.com/data-catalog/docs/how-to/template-user) - role, which includes permission to use the tag + template. For example, see the [TagTemplate User] + (https://cloud.google.com/data-catalog/docs/how-to/template-user) + role that includes a permission to use the tag template to tag resources. """ @@ -1538,23 +1544,24 @@ async def update_tag_template( timeout: float = None, metadata: Sequence[Tuple[str, str]] = (), ) -> tags.TagTemplate: - r"""Updates a tag template. This method cannot be used to update the - fields of a template. The tag template fields are represented as - separate resources and should be updated using their own - create/update/delete methods. Users should enable the Data - Catalog API in the project identified by the - ``tag_template.name`` parameter (see [Data Catalog Resource - Project] - (https://cloud.google.com/data-catalog/docs/concepts/resource-project) - for more information). + r"""Updates a tag template. + + You can't update template fields with this method. These fields + are separate resources with their own create, update, and delete + methods. + + You must enable the Data Catalog API in the project identified + by the ``tag_template.name`` parameter. For more information, + see `Data Catalog resource + project `__. Args: request (:class:`google.cloud.datacatalog_v1.types.UpdateTagTemplateRequest`): The request object. Request message for [UpdateTagTemplate][google.cloud.datacatalog.v1.DataCatalog.UpdateTagTemplate]. tag_template (:class:`google.cloud.datacatalog_v1.types.TagTemplate`): - Required. The template to update. The - "name" field must be set. + Required. The template to update. The ``name`` field + must be set. This corresponds to the ``tag_template`` field on the ``request`` instance; if ``request`` is provided, this @@ -1564,10 +1571,10 @@ async def update_tag_template( template. Currently, only ``display_name`` can be overwritten. - In general, if this parameter is absent or empty, all - modifiable fields are overwritten. If such fields are - non-required and omitted in the request body, their - values are emptied. + If this parameter is absent or empty, all modifiable + fields are overwritten. If such fields are non-required + and omitted in the request body, their values are + emptied. This corresponds to the ``update_mask`` field on the ``request`` instance; if ``request`` is provided, this @@ -1580,14 +1587,16 @@ async def update_tag_template( Returns: google.cloud.datacatalog_v1.types.TagTemplate: - A tag template defines a tag, which can have one or more typed fields. - The template is used to create and attach the tag to - GCP resources. [Tag template - roles](\ https://cloud.google.com/iam/docs/understanding-roles#data-catalog-roles) + A tag template defines a tag that can have one or more + typed fields. + + The template is used to create tags that are attached + to GCP resources. [Tag template roles] + (https://cloud.google.com/iam/docs/understanding-roles#data-catalog-roles) provide permissions to create, edit, and use the - template. See, for example, the [TagTemplate - User](\ https://cloud.google.com/data-catalog/docs/how-to/template-user) - role, which includes permission to use the tag + template. For example, see the [TagTemplate User] + (https://cloud.google.com/data-catalog/docs/how-to/template-user) + role that includes a permission to use the tag template to tag resources. """ @@ -1642,30 +1651,29 @@ async def delete_tag_template( timeout: float = None, metadata: Sequence[Tuple[str, str]] = (), ) -> None: - r"""Deletes a tag template and all tags using the template. Users - should enable the Data Catalog API in the project identified by - the ``name`` parameter (see [Data Catalog Resource Project] - (https://cloud.google.com/data-catalog/docs/concepts/resource-project) - for more information). + r"""Deletes a tag template and all tags that use it. + + You must enable the Data Catalog API in the project identified + by the ``name`` parameter. For more information, see `Data + Catalog resource + project `__. Args: request (:class:`google.cloud.datacatalog_v1.types.DeleteTagTemplateRequest`): The request object. Request message for [DeleteTagTemplate][google.cloud.datacatalog.v1.DataCatalog.DeleteTagTemplate]. name (:class:`str`): - Required. The name of the tag template to delete. - Example: - - - projects/{project_id}/locations/{location}/tagTemplates/{tag_template_id} + Required. The name of the tag + template to delete. This corresponds to the ``name`` field on the ``request`` instance; if ``request`` is provided, this should not be set. force (:class:`bool`): - Required. Currently, this field must always be set to - ``true``. This confirms the deletion of any possible - tags using this template. ``force = false`` will be - supported in the future. + Required. If true, deletes all tags that use this + template. + + Currently, ``true`` is the only supported value. This corresponds to the ``force`` field on the ``request`` instance; if ``request`` is provided, this @@ -1725,11 +1733,12 @@ async def create_tag_template_field( timeout: float = None, metadata: Sequence[Tuple[str, str]] = (), ) -> tags.TagTemplateField: - r"""Creates a field in a tag template. The user should enable the - Data Catalog API in the project identified by the ``parent`` - parameter (see `Data Catalog Resource - Project `__ - for more information). + r"""Creates a field in a tag template. + + You must enable the Data Catalog API in the project identified + by the ``parent`` parameter. For more information, see `Data + Catalog resource + project `__. Args: request (:class:`google.cloud.datacatalog_v1.types.CreateTagTemplateFieldRequest`): @@ -1740,10 +1749,6 @@ async def create_tag_template_field( location `region `__. - Example: - - - projects/{project_id}/locations/us-central1/tagTemplates/{tag_template_id} - This corresponds to the ``parent`` field on the ``request`` instance; if ``request`` is provided, this should not be set. @@ -1833,21 +1838,22 @@ async def update_tag_template_field( timeout: float = None, metadata: Sequence[Tuple[str, str]] = (), ) -> tags.TagTemplateField: - r"""Updates a field in a tag template. This method cannot be used to - update the field type. Users should enable the Data Catalog API - in the project identified by the ``name`` parameter (see [Data - Catalog Resource Project] - (https://cloud.google.com/data-catalog/docs/concepts/resource-project) - for more information). + r"""Updates a field in a tag template. + + You can't update the field type with this method. + + You must enable the Data Catalog API in the project identified + by the ``name`` parameter. For more information, see `Data + Catalog resource + project `__. Args: request (:class:`google.cloud.datacatalog_v1.types.UpdateTagTemplateFieldRequest`): The request object. Request message for [UpdateTagTemplateField][google.cloud.datacatalog.v1.DataCatalog.UpdateTagTemplateField]. name (:class:`str`): - Required. The name of the tag template field. Example: - - - projects/{project_id}/locations/{location}/tagTemplates/{tag_template_id}/fields/{tag_template_field_id} + Required. The name of the tag + template field. This corresponds to the ``name`` field on the ``request`` instance; if ``request`` is provided, this @@ -1943,20 +1949,20 @@ async def rename_tag_template_field( timeout: float = None, metadata: Sequence[Tuple[str, str]] = (), ) -> tags.TagTemplateField: - r"""Renames a field in a tag template. The user should enable the - Data Catalog API in the project identified by the ``name`` - parameter (see `Data Catalog Resource - Project `__ - for more information). + r"""Renames a field in a tag template. + + You must enable the Data Catalog API in the project identified + by the ``name`` parameter. For more information, see [Data + Catalog resource project] + (https://cloud.google.com/data-catalog/docs/concepts/resource-project). Args: request (:class:`google.cloud.datacatalog_v1.types.RenameTagTemplateFieldRequest`): The request object. Request message for [RenameTagTemplateField][google.cloud.datacatalog.v1.DataCatalog.RenameTagTemplateField]. name (:class:`str`): - Required. The name of the tag template. Example: - - - projects/{project_id}/locations/{location}/tagTemplates/{tag_template_id}/fields/{tag_template_field_id} + Required. The name of the tag + template. This corresponds to the ``name`` field on the ``request`` instance; if ``request`` is provided, this @@ -2029,17 +2035,16 @@ async def rename_tag_template_field_enum_value( timeout: float = None, metadata: Sequence[Tuple[str, str]] = (), ) -> tags.TagTemplateField: - r"""Renames an enum value in a tag template. The enum - values have to be unique within one enum field. + r"""Renames an enum value in a tag template. + Within a single enum field, enum values must be unique. Args: request (:class:`google.cloud.datacatalog_v1.types.RenameTagTemplateFieldEnumValueRequest`): The request object. Request message for [RenameTagTemplateFieldEnumValue][google.cloud.datacatalog.v1.DataCatalog.RenameTagTemplateFieldEnumValue]. name (:class:`str`): - Required. The name of the enum field value. Example: - - - projects/{project_id}/locations/{location}/tagTemplates/{tag_template_id}/fields/{tag_template_field_id}/enumValues/{enum_value_display_name} + Required. The name of the enum field + value. This corresponds to the ``name`` field on the ``request`` instance; if ``request`` is provided, this @@ -2112,31 +2117,30 @@ async def delete_tag_template_field( timeout: float = None, metadata: Sequence[Tuple[str, str]] = (), ) -> None: - r"""Deletes a field in a tag template and all uses of that field. - Users should enable the Data Catalog API in the project - identified by the ``name`` parameter (see [Data Catalog Resource - Project] - (https://cloud.google.com/data-catalog/docs/concepts/resource-project) - for more information). + r"""Deletes a field in a tag template and all uses of this field + from the tags based on this template. + + You must enable the Data Catalog API in the project identified + by the ``name`` parameter. For more information, see `Data + Catalog resource + project `__. Args: request (:class:`google.cloud.datacatalog_v1.types.DeleteTagTemplateFieldRequest`): The request object. Request message for [DeleteTagTemplateField][google.cloud.datacatalog.v1.DataCatalog.DeleteTagTemplateField]. name (:class:`str`): - Required. The name of the tag template field to delete. - Example: - - - projects/{project_id}/locations/{location}/tagTemplates/{tag_template_id}/fields/{tag_template_field_id} + Required. The name of the tag + template field to delete. This corresponds to the ``name`` field on the ``request`` instance; if ``request`` is provided, this should not be set. force (:class:`bool`): - Required. Currently, this field must always be set to - ``true``. This confirms the deletion of this field from - any tags using this field. ``force = false`` will be - supported in the future. + Required. If true, deletes this field from any tags that + use it. + + Currently, ``true`` is the only supported value. This corresponds to the ``force`` field on the ``request`` instance; if ``request`` is provided, this @@ -2195,26 +2199,36 @@ async def create_tag( timeout: float = None, metadata: Sequence[Tuple[str, str]] = (), ) -> tags.Tag: - r"""Creates a tag on an [Entry][google.cloud.datacatalog.v1.Entry]. + r"""Creates a tag and assigns it to: + + - An [Entry][google.cloud.datacatalog.v1.Entry] if the method + name is + ``projects.locations.entryGroups.entries.tags.create``. + - Or [EntryGroup][google.cloud.datacatalog.v1.EntryGroup]if the + method name is + ``projects.locations.entryGroups.tags.create``. + Note: The project identified by the ``parent`` parameter for the - `tag `__ - and the `tag - template `__ - used to create the tag must be from the same organization. + [tag] + (https://cloud.google.com/data-catalog/docs/reference/rest/v1/projects.locations.entryGroups.entries.tags/create#path-parameters) + and the [tag template] + (https://cloud.google.com/data-catalog/docs/reference/rest/v1/projects.locations.tagTemplates/create#path-parameters) + used to create the tag must be in the same organization. Args: request (:class:`google.cloud.datacatalog_v1.types.CreateTagRequest`): The request object. Request message for [CreateTag][google.cloud.datacatalog.v1.DataCatalog.CreateTag]. parent (:class:`str`): - Required. The name of the resource to attach this tag - to. Tags can be attached to entries. An entry can have - up to 1000 attached tags. Example: - - ``projects/{project_id}/locations/{location}/entryGroups/{entry_group_id}/entries/{entry_id}`` + Required. The name of the resource to + attach this tag to. + Tags can be attached to entries or entry + groups. An entry can have up to 1000 + attached tags. - Note: The tag and its child resources might not be - stored in the location specified in its name. + Note: The tag and its child resources + might not be stored in the location + specified in its name. This corresponds to the ``parent`` field on the ``request`` instance; if ``request`` is provided, this @@ -2232,9 +2246,8 @@ async def create_tag( Returns: google.cloud.datacatalog_v1.types.Tag: - Tags are used to attach custom metadata to Data Catalog resources. Tags - conform to the specifications within their tag - template. + Tags contain custom metadata and are attached to Data Catalog resources. Tags + conform with the specification of their tag template. See [Data Catalog IAM](\ https://cloud.google.com/data-catalog/docs/concepts/iam) @@ -2325,9 +2338,8 @@ async def update_tag( Returns: google.cloud.datacatalog_v1.types.Tag: - Tags are used to attach custom metadata to Data Catalog resources. Tags - conform to the specifications within their tag - template. + Tags contain custom metadata and are attached to Data Catalog resources. Tags + conform with the specification of their tag template. See [Data Catalog IAM](\ https://cloud.google.com/data-catalog/docs/concepts/iam) @@ -2390,9 +2402,8 @@ async def delete_tag( The request object. Request message for [DeleteTag][google.cloud.datacatalog.v1.DataCatalog.DeleteTag]. name (:class:`str`): - Required. The name of the tag to delete. Example: - - - projects/{project_id}/locations/{location}/entryGroups/{entry_group_id}/entries/{entry_id}/tags/{tag_id} + Required. The name of the tag to + delete. This corresponds to the ``name`` field on the ``request`` instance; if ``request`` is provided, this @@ -2448,7 +2459,8 @@ async def list_tags( timeout: float = None, metadata: Sequence[Tuple[str, str]] = (), ) -> pagers.ListTagsAsyncPager: - r"""Lists the tags on an [Entry][google.cloud.datacatalog.v1.Entry]. + r"""Lists tags assigned to an + [Entry][google.cloud.datacatalog.v1.Entry]. Args: request (:class:`google.cloud.datacatalog_v1.types.ListTagsRequest`): @@ -2456,14 +2468,12 @@ async def list_tags( [ListTags][google.cloud.datacatalog.v1.DataCatalog.ListTags]. parent (:class:`str`): Required. The name of the Data Catalog resource to list - the tags of. The resource could be an - [Entry][google.cloud.datacatalog.v1.Entry] or an - [EntryGroup][google.cloud.datacatalog.v1.EntryGroup]. + the tags of. - Examples: - - - projects/{project_id}/locations/{location}/entryGroups/{entry_group_id} - - projects/{project_id}/locations/{location}/entryGroups/{entry_group_id}/entries/{entry_id} + The resource can be an + [Entry][google.cloud.datacatalog.v1.Entry] or an + [EntryGroup][google.cloud.datacatalog.v1.EntryGroup] + (without ``/entries/{entries}`` at the end). This corresponds to the ``parent`` field on the ``request`` instance; if ``request`` is provided, this @@ -2544,21 +2554,24 @@ async def set_iam_policy( timeout: float = None, metadata: Sequence[Tuple[str, str]] = (), ) -> policy_pb2.Policy: - r"""Sets the access control policy for a resource. Replaces any - existing policy. Supported resources are: + r"""Sets an access control policy for a resource. Replaces any + existing policy. + + Supported resources are: + + - Tag templates + - Entry groups - - Tag templates. - - Entries. - - Entry groups. Note, this method cannot be used to manage - policies for BigQuery, Pub/Sub and any external Google Cloud - Platform resources synced to Data Catalog. + Note: This method sets policies only within Data Catalog and + can't be used to manage policies in BigQuery, Pub/Sub, Dataproc + Metastore, and any external Google Cloud Platform resources + synced with the Data Catalog. - Callers must have following Google IAM permission + To call this method, you must have the following Google IAM + permissions: - ``datacatalog.tagTemplates.setIamPolicy`` to set policies on tag templates. - - ``datacatalog.entries.setIamPolicy`` to set policies on - entries. - ``datacatalog.entryGroups.setIamPolicy`` to set policies on entry groups. @@ -2686,25 +2699,28 @@ async def get_iam_policy( timeout: float = None, metadata: Sequence[Tuple[str, str]] = (), ) -> policy_pb2.Policy: - r"""Gets the access control policy for a resource. A ``NOT_FOUND`` - error is returned if the resource does not exist. An empty - policy is returned if the resource exists but does not have a - policy set on it. + r"""Gets the access control policy for a resource. + + May return: + + - A\ ``NOT_FOUND`` error if the resource doesn't exist or you + don't have the permission to view it. + - An empty policy if the resource exists but doesn't have a set + policy. Supported resources are: - - Tag templates. - - Entries. - - Entry groups. Note, this method cannot be used to manage - policies for BigQuery, Pub/Sub and any external Google Cloud - Platform resources synced to Data Catalog. + - Tag templates + - Entry groups - Callers must have following Google IAM permission + Note: This method doesn't get policies from Google Cloud + Platform resources ingested into Data Catalog. + + To call this method, you must have the following Google IAM + permissions: - ``datacatalog.tagTemplates.getIamPolicy`` to get policies on tag templates. - - ``datacatalog.entries.getIamPolicy`` to get policies on - entries. - ``datacatalog.entryGroups.getIamPolicy`` to get policies on entry groups. @@ -2840,20 +2856,20 @@ async def test_iam_permissions( timeout: float = None, metadata: Sequence[Tuple[str, str]] = (), ) -> iam_policy_pb2.TestIamPermissionsResponse: - r"""Returns the caller's permissions on a resource. If the resource - does not exist, an empty set of permissions is returned (We - don't return a ``NOT_FOUND`` error). - + r"""Gets your permissions on a resource. + Returns an empty set of permissions if the resource + doesn't exist. Supported resources are: - - Tag templates. - - Entries. - - Entry groups. Note, this method cannot be used to manage - policies for BigQuery, Pub/Sub and any external Google Cloud - Platform resources synced to Data Catalog. + - Tag templates + - Entry groups - A caller is not required to have Google IAM permission to make - this request. + Note: This method gets policies only within Data Catalog + and can't be used to get policies from BigQuery, + Pub/Sub, Dataproc Metastore, and any external Google + Cloud Platform resources ingested into Data Catalog. + No Google IAM permissions are required to call this + method. Args: request (:class:`google.iam.v1.iam_policy_pb2.TestIamPermissionsRequest`): diff --git a/google/cloud/datacatalog_v1/services/data_catalog/client.py b/google/cloud/datacatalog_v1/services/data_catalog/client.py index d693de0f..17afca10 100644 --- a/google/cloud/datacatalog_v1/services/data_catalog/client.py +++ b/google/cloud/datacatalog_v1/services/data_catalog/client.py @@ -40,6 +40,7 @@ from google.cloud.datacatalog_v1.types import table_spec from google.cloud.datacatalog_v1.types import tags from google.cloud.datacatalog_v1.types import timestamps +from google.cloud.datacatalog_v1.types import usage from google.iam.v1 import iam_policy_pb2 # type: ignore from google.iam.v1 import policy_pb2 # type: ignore from google.protobuf import field_mask_pb2 # type: ignore @@ -80,8 +81,8 @@ def get_transport_class(cls, label: str = None,) -> Type[DataCatalogTransport]: class DataCatalogClient(metaclass=DataCatalogClientMeta): - """Data Catalog API service allows clients to discover, - understand, and manage their data. + """Data Catalog API service allows you to discover, understand, + and manage your data. """ @staticmethod @@ -469,54 +470,53 @@ def search_catalog( timeout: float = None, metadata: Sequence[Tuple[str, str]] = (), ) -> pagers.SearchCatalogPager: - r"""Searches Data Catalog for multiple resources like entries, tags - that match a query. + r"""Searches Data Catalog for multiple resources like entries and + tags that match a query. - This is a custom method - (https://cloud.google.com/apis/design/custom_methods) and does - not return the complete resource, only the resource identifier - and high level fields. Clients can subsequently call ``Get`` - methods. + This is a [Custom Method] + (https://cloud.google.com/apis/design/custom_methods) that + doesn't return all information on a resource, only its ID and + high level fields. To get more information, you can subsequently + call specific get methods. - Note that Data Catalog search queries do not guarantee full - recall. Query results that match your query may not be returned, - even in subsequent result pages. Also note that results returned - (and not returned) can vary across repeated search queries. + Note: Data Catalog search queries don't guarantee full recall. + Results that match your query might not be returned, even in + subsequent result pages. Additionally, returned (and not + returned) results can vary if you repeat search queries. - See `Data Catalog Search - Syntax `__ - for more information. + For more information, see [Data Catalog search syntax] + (https://cloud.google.com/data-catalog/docs/how-to/search-reference). Args: request (google.cloud.datacatalog_v1.types.SearchCatalogRequest): The request object. Request message for [SearchCatalog][google.cloud.datacatalog.v1.DataCatalog.SearchCatalog]. scope (google.cloud.datacatalog_v1.types.SearchCatalogRequest.Scope): - Required. The scope of this search request. A ``scope`` - that has empty ``include_org_ids``, - ``include_project_ids`` AND false - ``include_gcp_public_datasets`` is considered invalid. - Data Catalog will return an error in such a case. + Required. The scope of this search request. + + The ``scope`` is invalid if ``include_org_ids``, + ``include_project_ids`` are empty AND + ``include_gcp_public_datasets`` is set to ``false``. In + this case, the request returns an error. This corresponds to the ``scope`` field on the ``request`` instance; if ``request`` is provided, this should not be set. query (str): - Optional. The query string in search query syntax. An - empty query string will result in all data assets (in - the specified scope) that the user has access to. + Optional. The query string with a minimum of 3 + characters and specific syntax. For more information, + see `Data Catalog search + syntax `__. - Query strings can be simple as "x" or more qualified as: + An empty query string returns all data assets (in the + specified scope) that you have access to. - - name:x - - column:x - - description:y + A query string can be a simple ``xyz`` or qualified by + predicates: - Note: Query tokens need to have a minimum of 3 - characters for substring matching to work correctly. See - `Data Catalog Search - Syntax `__ - for more information. + - ``name:x`` + - ``column:y`` + - ``description:z`` This corresponds to the ``query`` field on the ``request`` instance; if ``request`` is provided, this @@ -586,41 +586,48 @@ def create_entry_group( timeout: float = None, metadata: Sequence[Tuple[str, str]] = (), ) -> datacatalog.EntryGroup: - r"""Creates an EntryGroup. + r"""Creates an entry group. An entry group contains logically related entries together with - Cloud Identity and Access Management policies that specify the - users who can create, edit, and view entries within the entry - group. + `Cloud Identity and Access + Management `__ policies. These + policies specify users who can create, edit, and view entries + within entry groups. + + Data Catalog automatically creates entry groups with names that + start with the ``@`` symbol for the following resources: + + - BigQuery entries (``@bigquery``) + - Pub/Sub topics (``@pubsub``) + - Dataproc Metastore services + (``@dataproc_metastore_{SERVICE_NAME_HASH}``) + + You can create your own entry groups for Cloud Storage fileset + entries and custom entries together with the corresponding IAM + policies. User-created entry groups can't contain the ``@`` + symbol, it is reserved for automatically created groups. - Data Catalog automatically creates an entry group for BigQuery - entries ("@bigquery") and Pub/Sub topics ("@pubsub"). Users - create their own entry group to contain Cloud Storage fileset - entries or custom type entries, and the IAM policies associated - with those entries. Entry groups, like entries, can be searched. + Entry groups, like entries, can be searched. A maximum of 10,000 entry groups may be created per organization across all locations. - Users should enable the Data Catalog API in the project - identified by the ``parent`` parameter (see [Data Catalog - Resource Project] - (https://cloud.google.com/data-catalog/docs/concepts/resource-project) - for more information). + You must enable the Data Catalog API in the project identified + by the ``parent`` parameter. For more information, see `Data + Catalog resource + project `__. Args: request (google.cloud.datacatalog_v1.types.CreateEntryGroupRequest): The request object. Request message for [CreateEntryGroup][google.cloud.datacatalog.v1.DataCatalog.CreateEntryGroup]. parent (str): - Required. The name of the project this entry group - belongs to. Example: - - ``projects/{project_id}/locations/{location}`` - - Note: The entry group itself and its child resources - might not be stored in the location specified in its - name. + Required. The names of the project + and location that the new entry group + belongs to. Note: The entry group + itself and its child resources might not + be stored in the location specified in + its name. This corresponds to the ``parent`` field on the ``request`` instance; if ``request`` is provided, this @@ -638,7 +645,7 @@ def create_entry_group( should not be set. entry_group (google.cloud.datacatalog_v1.types.EntryGroup): The entry group to create. Defaults - to an empty entry group. + to empty. This corresponds to the ``entry_group`` field on the ``request`` instance; if ``request`` is provided, this @@ -651,7 +658,8 @@ def create_entry_group( Returns: google.cloud.datacatalog_v1.types.EntryGroup: - EntryGroup Metadata. + Entry group metadata. + An EntryGroup resource represents a logical grouping of zero or more Data Catalog [Entry][google.cloud.datacatalog.v1.Entry] resources. @@ -708,22 +716,22 @@ def get_entry_group( timeout: float = None, metadata: Sequence[Tuple[str, str]] = (), ) -> datacatalog.EntryGroup: - r"""Gets an EntryGroup. + r"""Gets an entry group. Args: request (google.cloud.datacatalog_v1.types.GetEntryGroupRequest): The request object. Request message for [GetEntryGroup][google.cloud.datacatalog.v1.DataCatalog.GetEntryGroup]. name (str): - Required. The name of the entry group. For example, - ``projects/{project_id}/locations/{location}/entryGroups/{entry_group_id}``. + Required. The name of the entry group + to get. This corresponds to the ``name`` field on the ``request`` instance; if ``request`` is provided, this should not be set. read_mask (google.protobuf.field_mask_pb2.FieldMask): - The fields to return. If not set or - empty, all fields are returned. + The fields to return. If empty or + omitted, all fields are returned. This corresponds to the ``read_mask`` field on the ``request`` instance; if ``request`` is provided, this @@ -736,7 +744,8 @@ def get_entry_group( Returns: google.cloud.datacatalog_v1.types.EntryGroup: - EntryGroup Metadata. + Entry group metadata. + An EntryGroup resource represents a logical grouping of zero or more Data Catalog [Entry][google.cloud.datacatalog.v1.Entry] resources. @@ -791,19 +800,20 @@ def update_entry_group( timeout: float = None, metadata: Sequence[Tuple[str, str]] = (), ) -> datacatalog.EntryGroup: - r"""Updates an EntryGroup. The user should enable the Data Catalog - API in the project identified by the ``entry_group.name`` - parameter (see [Data Catalog Resource Project] - (https://cloud.google.com/data-catalog/docs/concepts/resource-project) - for more information). + r"""Updates an entry group. + + You must enable the Data Catalog API in the project identified + by the ``entry_group.name`` parameter. For more information, see + `Data Catalog resource + project `__. Args: request (google.cloud.datacatalog_v1.types.UpdateEntryGroupRequest): The request object. Request message for [UpdateEntryGroup][google.cloud.datacatalog.v1.DataCatalog.UpdateEntryGroup]. entry_group (google.cloud.datacatalog_v1.types.EntryGroup): - Required. The updated entry group. - "name" field must be set. + Required. Updates for the entry group. The ``name`` + field must be set. This corresponds to the ``entry_group`` field on the ``request`` instance; if ``request`` is provided, this @@ -828,7 +838,8 @@ def update_entry_group( Returns: google.cloud.datacatalog_v1.types.EntryGroup: - EntryGroup Metadata. + Entry group metadata. + An EntryGroup resource represents a logical grouping of zero or more Data Catalog [Entry][google.cloud.datacatalog.v1.Entry] resources. @@ -884,20 +895,20 @@ def delete_entry_group( timeout: float = None, metadata: Sequence[Tuple[str, str]] = (), ) -> None: - r"""Deletes an EntryGroup. Only entry groups that do not contain - entries can be deleted. Users should enable the Data Catalog API - in the project identified by the ``name`` parameter (see [Data - Catalog Resource Project] - (https://cloud.google.com/data-catalog/docs/concepts/resource-project) - for more information). + r"""Deletes an entry group. + + You must enable the Data Catalog API in the project identified + by the ``name`` parameter. For more information, see `Data + Catalog resource + project `__. Args: request (google.cloud.datacatalog_v1.types.DeleteEntryGroupRequest): The request object. Request message for [DeleteEntryGroup][google.cloud.datacatalog.v1.DataCatalog.DeleteEntryGroup]. name (str): - Required. The name of the entry group. For example, - ``projects/{project_id}/locations/{location}/entryGroups/{entry_group_id}``. + Required. The name of the entry group + to delete. This corresponds to the ``name`` field on the ``request`` instance; if ``request`` is provided, this @@ -960,11 +971,9 @@ def list_entry_groups( The request object. Request message for [ListEntryGroups][google.cloud.datacatalog.v1.DataCatalog.ListEntryGroups]. parent (str): - Required. The name of the location that contains the - entry groups, which can be provided in URL format. - Example: - - - projects/{project_id}/locations/{location} + Required. The name of the location + that contains the entry groups to list. + Can be provided as a URL. This corresponds to the ``parent`` field on the ``request`` instance; if ``request`` is provided, this @@ -1038,29 +1047,30 @@ def create_entry( timeout: float = None, metadata: Sequence[Tuple[str, str]] = (), ) -> datacatalog.Entry: - r"""Creates an entry. Only entries of types 'FILESET', 'CLUSTER', - 'DATA_STREAM' or with a user-specified type can be created. + r"""Creates an entry. - Users should enable the Data Catalog API in the project - identified by the ``parent`` parameter (see [Data Catalog - Resource Project] - (https://cloud.google.com/data-catalog/docs/concepts/resource-project) - for more information). + You can create entries only with 'FILESET', 'CLUSTER', + 'DATA_STREAM', or custom types. Data Catalog automatically + creates entries with other types during metadata ingestion from + integrated systems. - A maximum of 100,000 entries may be created per entry group. + You must enable the Data Catalog API in the project identified + by the ``parent`` parameter. For more information, see `Data + Catalog resource + project `__. + + An entry group can have a maximum of 100,000 entries. Args: request (google.cloud.datacatalog_v1.types.CreateEntryRequest): The request object. Request message for [CreateEntry][google.cloud.datacatalog.v1.DataCatalog.CreateEntry]. parent (str): - Required. The name of the entry group this entry belongs - to. Example: - - ``projects/{project_id}/locations/{location}/entryGroups/{entry_group_id}`` - - Note: The entry itself and its child resources might not - be stored in the location specified in its name. + Required. The name of the entry group + this entry belongs to. + Note: The entry itself and its child + resources might not be stored in the + location specified in its name. This corresponds to the ``parent`` field on the ``request`` instance; if ``request`` is provided, this @@ -1088,17 +1098,16 @@ def create_entry( Returns: google.cloud.datacatalog_v1.types.Entry: - Entry Metadata. - A Data Catalog Entry resource represents another - resource in Google Cloud Platform (such as a BigQuery - dataset or a Pub/Sub topic) or outside of Google - Cloud Platform. Clients can use the linked_resource - field in the Entry resource to refer to the original - resource ID of the source system. - - An Entry resource contains resource details, such as - its schema. An Entry can also be used to attach - flexible metadata, such as a + Entry metadata. + A Data Catalog entry represents another resource in + Google Cloud Platform (such as a BigQuery dataset or + a Pub/Sub topic) or outside of it. You can use the + linked_resource field in the entry resource to refer + to the original resource ID of the source system. + + An entry resource contains resource details, for + example, its schema. Additionally, you can attach + flexible metadata to an entry in the form of a [Tag][google.cloud.datacatalog.v1.Tag]. """ @@ -1153,19 +1162,20 @@ def update_entry( timeout: float = None, metadata: Sequence[Tuple[str, str]] = (), ) -> datacatalog.Entry: - r"""Updates an existing entry. Users should enable the Data Catalog - API in the project identified by the ``entry.name`` parameter - (see [Data Catalog Resource Project] - (https://cloud.google.com/data-catalog/docs/concepts/resource-project) - for more information). + r"""Updates an existing entry. + + You must enable the Data Catalog API in the project identified + by the ``entry.name`` parameter. For more information, see `Data + Catalog resource + project `__. Args: request (google.cloud.datacatalog_v1.types.UpdateEntryRequest): The request object. Request message for [UpdateEntry][google.cloud.datacatalog.v1.DataCatalog.UpdateEntry]. entry (google.cloud.datacatalog_v1.types.Entry): - Required. The updated entry. The - "name" field must be set. + Required. Updates for the entry. The ``name`` field must + be set. This corresponds to the ``entry`` field on the ``request`` instance; if ``request`` is provided, this @@ -1178,29 +1188,29 @@ def update_entry( and omitted in the request body, their values are emptied. - The following fields are modifiable: + You can modify only the fields listed below. - - For entries with type ``DATA_STREAM``: + For entries with type ``DATA_STREAM``: - - ``schema`` + - ``schema`` - - For entries with type ``FILESET``: + For entries with type ``FILESET``: - - ``schema`` - - ``display_name`` - - ``description`` - - ``gcs_fileset_spec`` - - ``gcs_fileset_spec.file_patterns`` + - ``schema`` + - ``display_name`` + - ``description`` + - ``gcs_fileset_spec`` + - ``gcs_fileset_spec.file_patterns`` - - For entries with ``user_specified_type``: + For entries with ``user_specified_type``: - - ``schema`` - - ``display_name`` - - ``description`` - - ``user_specified_type`` - - ``user_specified_system`` - - ``linked_resource`` - - ``source_system_timestamps`` + - ``schema`` + - ``display_name`` + - ``description`` + - ``user_specified_type`` + - ``user_specified_system`` + - ``linked_resource`` + - ``source_system_timestamps`` This corresponds to the ``update_mask`` field on the ``request`` instance; if ``request`` is provided, this @@ -1213,17 +1223,16 @@ def update_entry( Returns: google.cloud.datacatalog_v1.types.Entry: - Entry Metadata. - A Data Catalog Entry resource represents another - resource in Google Cloud Platform (such as a BigQuery - dataset or a Pub/Sub topic) or outside of Google - Cloud Platform. Clients can use the linked_resource - field in the Entry resource to refer to the original - resource ID of the source system. - - An Entry resource contains resource details, such as - its schema. An Entry can also be used to attach - flexible metadata, such as a + Entry metadata. + A Data Catalog entry represents another resource in + Google Cloud Platform (such as a BigQuery dataset or + a Pub/Sub topic) or outside of it. You can use the + linked_resource field in the entry resource to refer + to the original resource ID of the source system. + + An entry resource contains resource details, for + example, its schema. Additionally, you can attach + flexible metadata to an entry in the form of a [Tag][google.cloud.datacatalog.v1.Tag]. """ @@ -1277,22 +1286,24 @@ def delete_entry( timeout: float = None, metadata: Sequence[Tuple[str, str]] = (), ) -> None: - r"""Deletes an existing entry. Only entries created through + r"""Deletes an existing entry. + + You can delete only the entries created by the [CreateEntry][google.cloud.datacatalog.v1.DataCatalog.CreateEntry] - method can be deleted. Users should enable the Data Catalog API - in the project identified by the ``name`` parameter (see [Data - Catalog Resource Project] - (https://cloud.google.com/data-catalog/docs/concepts/resource-project) - for more information). + method. + + You must enable the Data Catalog API in the project identified + by the ``name`` parameter. For more information, see `Data + Catalog resource + project `__. Args: request (google.cloud.datacatalog_v1.types.DeleteEntryRequest): The request object. Request message for [DeleteEntry][google.cloud.datacatalog.v1.DataCatalog.DeleteEntry]. name (str): - Required. The name of the entry. Example: - - - projects/{project_id}/locations/{location}/entryGroups/{entry_group_id}/entries/{entry_id} + Required. The name of the entry to + delete. This corresponds to the ``name`` field on the ``request`` instance; if ``request`` is provided, this @@ -1355,9 +1366,8 @@ def get_entry( The request object. Request message for [GetEntry][google.cloud.datacatalog.v1.DataCatalog.GetEntry]. name (str): - Required. The name of the entry. Example: - - - projects/{project_id}/locations/{location}/entryGroups/{entry_group_id}/entries/{entry_id} + Required. The name of the entry to + get. This corresponds to the ``name`` field on the ``request`` instance; if ``request`` is provided, this @@ -1370,17 +1380,16 @@ def get_entry( Returns: google.cloud.datacatalog_v1.types.Entry: - Entry Metadata. - A Data Catalog Entry resource represents another - resource in Google Cloud Platform (such as a BigQuery - dataset or a Pub/Sub topic) or outside of Google - Cloud Platform. Clients can use the linked_resource - field in the Entry resource to refer to the original - resource ID of the source system. - - An Entry resource contains resource details, such as - its schema. An Entry can also be used to attach - flexible metadata, such as a + Entry metadata. + A Data Catalog entry represents another resource in + Google Cloud Platform (such as a BigQuery dataset or + a Pub/Sub topic) or outside of it. You can use the + linked_resource field in the entry resource to refer + to the original resource ID of the source system. + + An entry resource contains resource details, for + example, its schema. Additionally, you can attach + flexible metadata to an entry in the form of a [Tag][google.cloud.datacatalog.v1.Tag]. """ @@ -1429,10 +1438,9 @@ def lookup_entry( timeout: float = None, metadata: Sequence[Tuple[str, str]] = (), ) -> datacatalog.Entry: - r"""Get an entry by target resource name. This method - allows clients to use the resource name from the source - Google Cloud Platform service to get the Data Catalog - Entry. + r"""Gets an entry by its target resource name. + The resource name comes from the source Google Cloud + Platform service. Args: request (google.cloud.datacatalog_v1.types.LookupEntryRequest): @@ -1446,17 +1454,16 @@ def lookup_entry( Returns: google.cloud.datacatalog_v1.types.Entry: - Entry Metadata. - A Data Catalog Entry resource represents another - resource in Google Cloud Platform (such as a BigQuery - dataset or a Pub/Sub topic) or outside of Google - Cloud Platform. Clients can use the linked_resource - field in the Entry resource to refer to the original - resource ID of the source system. - - An Entry resource contains resource details, such as - its schema. An Entry can also be used to attach - flexible metadata, such as a + Entry metadata. + A Data Catalog entry represents another resource in + Google Cloud Platform (such as a BigQuery dataset or + a Pub/Sub topic) or outside of it. You can use the + linked_resource field in the entry resource to refer + to the original resource ID of the source system. + + An entry resource contains resource details, for + example, its schema. Additionally, you can attach + flexible metadata to an entry in the form of a [Tag][google.cloud.datacatalog.v1.Tag]. """ @@ -1494,10 +1501,9 @@ def list_entries( The request object. Request message for [ListEntries][google.cloud.datacatalog.v1.DataCatalog.ListEntries]. parent (str): - Required. The name of the entry group that contains the - entries, which can be provided in URL format. Example: - - - projects/{project_id}/locations/{location}/entryGroups/{entry_group_id} + Required. The name of the entry group + that contains the entries to list. + Can be provided in URL format. This corresponds to the ``parent`` field on the ``request`` instance; if ``request`` is provided, this @@ -1571,11 +1577,12 @@ def create_tag_template( timeout: float = None, metadata: Sequence[Tuple[str, str]] = (), ) -> tags.TagTemplate: - r"""Creates a tag template. The user should enable the Data Catalog - API in the project identified by the ``parent`` parameter (see - `Data Catalog Resource - Project `__ - for more information). + r"""Creates a tag template. + + You must enable the Data Catalog API in the project identified + by the ``parent`` parameter. For more information, see [Data + Catalog resource project] + (https://cloud.google.com/data-catalog/docs/concepts/resource-project). Args: request (google.cloud.datacatalog_v1.types.CreateTagTemplateRequest): @@ -1586,10 +1593,6 @@ def create_tag_template( location `region `__. - Example: - - - projects/{project_id}/locations/us-central1 - This corresponds to the ``parent`` field on the ``request`` instance; if ``request`` is provided, this should not be set. @@ -1617,14 +1620,16 @@ def create_tag_template( Returns: google.cloud.datacatalog_v1.types.TagTemplate: - A tag template defines a tag, which can have one or more typed fields. - The template is used to create and attach the tag to - GCP resources. [Tag template - roles](\ https://cloud.google.com/iam/docs/understanding-roles#data-catalog-roles) + A tag template defines a tag that can have one or more + typed fields. + + The template is used to create tags that are attached + to GCP resources. [Tag template roles] + (https://cloud.google.com/iam/docs/understanding-roles#data-catalog-roles) provide permissions to create, edit, and use the - template. See, for example, the [TagTemplate - User](\ https://cloud.google.com/data-catalog/docs/how-to/template-user) - role, which includes permission to use the tag + template. For example, see the [TagTemplate User] + (https://cloud.google.com/data-catalog/docs/how-to/template-user) + role that includes a permission to use the tag template to tag resources. """ @@ -1685,9 +1690,8 @@ def get_tag_template( The request object. Request message for [GetTagTemplate][google.cloud.datacatalog.v1.DataCatalog.GetTagTemplate]. name (str): - Required. The name of the tag template. Example: - - - projects/{project_id}/locations/{location}/tagTemplates/{tag_template_id} + Required. The name of the tag + template to get. This corresponds to the ``name`` field on the ``request`` instance; if ``request`` is provided, this @@ -1700,14 +1704,16 @@ def get_tag_template( Returns: google.cloud.datacatalog_v1.types.TagTemplate: - A tag template defines a tag, which can have one or more typed fields. - The template is used to create and attach the tag to - GCP resources. [Tag template - roles](\ https://cloud.google.com/iam/docs/understanding-roles#data-catalog-roles) + A tag template defines a tag that can have one or more + typed fields. + + The template is used to create tags that are attached + to GCP resources. [Tag template roles] + (https://cloud.google.com/iam/docs/understanding-roles#data-catalog-roles) provide permissions to create, edit, and use the - template. See, for example, the [TagTemplate - User](\ https://cloud.google.com/data-catalog/docs/how-to/template-user) - role, which includes permission to use the tag + template. For example, see the [TagTemplate User] + (https://cloud.google.com/data-catalog/docs/how-to/template-user) + role that includes a permission to use the tag template to tag resources. """ @@ -1758,23 +1764,24 @@ def update_tag_template( timeout: float = None, metadata: Sequence[Tuple[str, str]] = (), ) -> tags.TagTemplate: - r"""Updates a tag template. This method cannot be used to update the - fields of a template. The tag template fields are represented as - separate resources and should be updated using their own - create/update/delete methods. Users should enable the Data - Catalog API in the project identified by the - ``tag_template.name`` parameter (see [Data Catalog Resource - Project] - (https://cloud.google.com/data-catalog/docs/concepts/resource-project) - for more information). + r"""Updates a tag template. + + You can't update template fields with this method. These fields + are separate resources with their own create, update, and delete + methods. + + You must enable the Data Catalog API in the project identified + by the ``tag_template.name`` parameter. For more information, + see `Data Catalog resource + project `__. Args: request (google.cloud.datacatalog_v1.types.UpdateTagTemplateRequest): The request object. Request message for [UpdateTagTemplate][google.cloud.datacatalog.v1.DataCatalog.UpdateTagTemplate]. tag_template (google.cloud.datacatalog_v1.types.TagTemplate): - Required. The template to update. The - "name" field must be set. + Required. The template to update. The ``name`` field + must be set. This corresponds to the ``tag_template`` field on the ``request`` instance; if ``request`` is provided, this @@ -1784,10 +1791,10 @@ def update_tag_template( template. Currently, only ``display_name`` can be overwritten. - In general, if this parameter is absent or empty, all - modifiable fields are overwritten. If such fields are - non-required and omitted in the request body, their - values are emptied. + If this parameter is absent or empty, all modifiable + fields are overwritten. If such fields are non-required + and omitted in the request body, their values are + emptied. This corresponds to the ``update_mask`` field on the ``request`` instance; if ``request`` is provided, this @@ -1800,14 +1807,16 @@ def update_tag_template( Returns: google.cloud.datacatalog_v1.types.TagTemplate: - A tag template defines a tag, which can have one or more typed fields. - The template is used to create and attach the tag to - GCP resources. [Tag template - roles](\ https://cloud.google.com/iam/docs/understanding-roles#data-catalog-roles) + A tag template defines a tag that can have one or more + typed fields. + + The template is used to create tags that are attached + to GCP resources. [Tag template roles] + (https://cloud.google.com/iam/docs/understanding-roles#data-catalog-roles) provide permissions to create, edit, and use the - template. See, for example, the [TagTemplate - User](\ https://cloud.google.com/data-catalog/docs/how-to/template-user) - role, which includes permission to use the tag + template. For example, see the [TagTemplate User] + (https://cloud.google.com/data-catalog/docs/how-to/template-user) + role that includes a permission to use the tag template to tag resources. """ @@ -1862,30 +1871,29 @@ def delete_tag_template( timeout: float = None, metadata: Sequence[Tuple[str, str]] = (), ) -> None: - r"""Deletes a tag template and all tags using the template. Users - should enable the Data Catalog API in the project identified by - the ``name`` parameter (see [Data Catalog Resource Project] - (https://cloud.google.com/data-catalog/docs/concepts/resource-project) - for more information). + r"""Deletes a tag template and all tags that use it. + + You must enable the Data Catalog API in the project identified + by the ``name`` parameter. For more information, see `Data + Catalog resource + project `__. Args: request (google.cloud.datacatalog_v1.types.DeleteTagTemplateRequest): The request object. Request message for [DeleteTagTemplate][google.cloud.datacatalog.v1.DataCatalog.DeleteTagTemplate]. name (str): - Required. The name of the tag template to delete. - Example: - - - projects/{project_id}/locations/{location}/tagTemplates/{tag_template_id} + Required. The name of the tag + template to delete. This corresponds to the ``name`` field on the ``request`` instance; if ``request`` is provided, this should not be set. force (bool): - Required. Currently, this field must always be set to - ``true``. This confirms the deletion of any possible - tags using this template. ``force = false`` will be - supported in the future. + Required. If true, deletes all tags that use this + template. + + Currently, ``true`` is the only supported value. This corresponds to the ``force`` field on the ``request`` instance; if ``request`` is provided, this @@ -1945,11 +1953,12 @@ def create_tag_template_field( timeout: float = None, metadata: Sequence[Tuple[str, str]] = (), ) -> tags.TagTemplateField: - r"""Creates a field in a tag template. The user should enable the - Data Catalog API in the project identified by the ``parent`` - parameter (see `Data Catalog Resource - Project `__ - for more information). + r"""Creates a field in a tag template. + + You must enable the Data Catalog API in the project identified + by the ``parent`` parameter. For more information, see `Data + Catalog resource + project `__. Args: request (google.cloud.datacatalog_v1.types.CreateTagTemplateFieldRequest): @@ -1960,10 +1969,6 @@ def create_tag_template_field( location `region `__. - Example: - - - projects/{project_id}/locations/us-central1/tagTemplates/{tag_template_id} - This corresponds to the ``parent`` field on the ``request`` instance; if ``request`` is provided, this should not be set. @@ -2055,21 +2060,22 @@ def update_tag_template_field( timeout: float = None, metadata: Sequence[Tuple[str, str]] = (), ) -> tags.TagTemplateField: - r"""Updates a field in a tag template. This method cannot be used to - update the field type. Users should enable the Data Catalog API - in the project identified by the ``name`` parameter (see [Data - Catalog Resource Project] - (https://cloud.google.com/data-catalog/docs/concepts/resource-project) - for more information). + r"""Updates a field in a tag template. + + You can't update the field type with this method. + + You must enable the Data Catalog API in the project identified + by the ``name`` parameter. For more information, see `Data + Catalog resource + project `__. Args: request (google.cloud.datacatalog_v1.types.UpdateTagTemplateFieldRequest): The request object. Request message for [UpdateTagTemplateField][google.cloud.datacatalog.v1.DataCatalog.UpdateTagTemplateField]. name (str): - Required. The name of the tag template field. Example: - - - projects/{project_id}/locations/{location}/tagTemplates/{tag_template_id}/fields/{tag_template_field_id} + Required. The name of the tag + template field. This corresponds to the ``name`` field on the ``request`` instance; if ``request`` is provided, this @@ -2167,20 +2173,20 @@ def rename_tag_template_field( timeout: float = None, metadata: Sequence[Tuple[str, str]] = (), ) -> tags.TagTemplateField: - r"""Renames a field in a tag template. The user should enable the - Data Catalog API in the project identified by the ``name`` - parameter (see `Data Catalog Resource - Project `__ - for more information). + r"""Renames a field in a tag template. + + You must enable the Data Catalog API in the project identified + by the ``name`` parameter. For more information, see [Data + Catalog resource project] + (https://cloud.google.com/data-catalog/docs/concepts/resource-project). Args: request (google.cloud.datacatalog_v1.types.RenameTagTemplateFieldRequest): The request object. Request message for [RenameTagTemplateField][google.cloud.datacatalog.v1.DataCatalog.RenameTagTemplateField]. name (str): - Required. The name of the tag template. Example: - - - projects/{project_id}/locations/{location}/tagTemplates/{tag_template_id}/fields/{tag_template_field_id} + Required. The name of the tag + template. This corresponds to the ``name`` field on the ``request`` instance; if ``request`` is provided, this @@ -2255,17 +2261,16 @@ def rename_tag_template_field_enum_value( timeout: float = None, metadata: Sequence[Tuple[str, str]] = (), ) -> tags.TagTemplateField: - r"""Renames an enum value in a tag template. The enum - values have to be unique within one enum field. + r"""Renames an enum value in a tag template. + Within a single enum field, enum values must be unique. Args: request (google.cloud.datacatalog_v1.types.RenameTagTemplateFieldEnumValueRequest): The request object. Request message for [RenameTagTemplateFieldEnumValue][google.cloud.datacatalog.v1.DataCatalog.RenameTagTemplateFieldEnumValue]. name (str): - Required. The name of the enum field value. Example: - - - projects/{project_id}/locations/{location}/tagTemplates/{tag_template_id}/fields/{tag_template_field_id}/enumValues/{enum_value_display_name} + Required. The name of the enum field + value. This corresponds to the ``name`` field on the ``request`` instance; if ``request`` is provided, this @@ -2340,31 +2345,30 @@ def delete_tag_template_field( timeout: float = None, metadata: Sequence[Tuple[str, str]] = (), ) -> None: - r"""Deletes a field in a tag template and all uses of that field. - Users should enable the Data Catalog API in the project - identified by the ``name`` parameter (see [Data Catalog Resource - Project] - (https://cloud.google.com/data-catalog/docs/concepts/resource-project) - for more information). + r"""Deletes a field in a tag template and all uses of this field + from the tags based on this template. + + You must enable the Data Catalog API in the project identified + by the ``name`` parameter. For more information, see `Data + Catalog resource + project `__. Args: request (google.cloud.datacatalog_v1.types.DeleteTagTemplateFieldRequest): The request object. Request message for [DeleteTagTemplateField][google.cloud.datacatalog.v1.DataCatalog.DeleteTagTemplateField]. name (str): - Required. The name of the tag template field to delete. - Example: - - - projects/{project_id}/locations/{location}/tagTemplates/{tag_template_id}/fields/{tag_template_field_id} + Required. The name of the tag + template field to delete. This corresponds to the ``name`` field on the ``request`` instance; if ``request`` is provided, this should not be set. force (bool): - Required. Currently, this field must always be set to - ``true``. This confirms the deletion of this field from - any tags using this field. ``force = false`` will be - supported in the future. + Required. If true, deletes this field from any tags that + use it. + + Currently, ``true`` is the only supported value. This corresponds to the ``force`` field on the ``request`` instance; if ``request`` is provided, this @@ -2425,26 +2429,36 @@ def create_tag( timeout: float = None, metadata: Sequence[Tuple[str, str]] = (), ) -> tags.Tag: - r"""Creates a tag on an [Entry][google.cloud.datacatalog.v1.Entry]. + r"""Creates a tag and assigns it to: + + - An [Entry][google.cloud.datacatalog.v1.Entry] if the method + name is + ``projects.locations.entryGroups.entries.tags.create``. + - Or [EntryGroup][google.cloud.datacatalog.v1.EntryGroup]if the + method name is + ``projects.locations.entryGroups.tags.create``. + Note: The project identified by the ``parent`` parameter for the - `tag `__ - and the `tag - template `__ - used to create the tag must be from the same organization. + [tag] + (https://cloud.google.com/data-catalog/docs/reference/rest/v1/projects.locations.entryGroups.entries.tags/create#path-parameters) + and the [tag template] + (https://cloud.google.com/data-catalog/docs/reference/rest/v1/projects.locations.tagTemplates/create#path-parameters) + used to create the tag must be in the same organization. Args: request (google.cloud.datacatalog_v1.types.CreateTagRequest): The request object. Request message for [CreateTag][google.cloud.datacatalog.v1.DataCatalog.CreateTag]. parent (str): - Required. The name of the resource to attach this tag - to. Tags can be attached to entries. An entry can have - up to 1000 attached tags. Example: - - ``projects/{project_id}/locations/{location}/entryGroups/{entry_group_id}/entries/{entry_id}`` + Required. The name of the resource to + attach this tag to. + Tags can be attached to entries or entry + groups. An entry can have up to 1000 + attached tags. - Note: The tag and its child resources might not be - stored in the location specified in its name. + Note: The tag and its child resources + might not be stored in the location + specified in its name. This corresponds to the ``parent`` field on the ``request`` instance; if ``request`` is provided, this @@ -2462,9 +2476,8 @@ def create_tag( Returns: google.cloud.datacatalog_v1.types.Tag: - Tags are used to attach custom metadata to Data Catalog resources. Tags - conform to the specifications within their tag - template. + Tags contain custom metadata and are attached to Data Catalog resources. Tags + conform with the specification of their tag template. See [Data Catalog IAM](\ https://cloud.google.com/data-catalog/docs/concepts/iam) @@ -2555,9 +2568,8 @@ def update_tag( Returns: google.cloud.datacatalog_v1.types.Tag: - Tags are used to attach custom metadata to Data Catalog resources. Tags - conform to the specifications within their tag - template. + Tags contain custom metadata and are attached to Data Catalog resources. Tags + conform with the specification of their tag template. See [Data Catalog IAM](\ https://cloud.google.com/data-catalog/docs/concepts/iam) @@ -2620,9 +2632,8 @@ def delete_tag( The request object. Request message for [DeleteTag][google.cloud.datacatalog.v1.DataCatalog.DeleteTag]. name (str): - Required. The name of the tag to delete. Example: - - - projects/{project_id}/locations/{location}/entryGroups/{entry_group_id}/entries/{entry_id}/tags/{tag_id} + Required. The name of the tag to + delete. This corresponds to the ``name`` field on the ``request`` instance; if ``request`` is provided, this @@ -2678,7 +2689,8 @@ def list_tags( timeout: float = None, metadata: Sequence[Tuple[str, str]] = (), ) -> pagers.ListTagsPager: - r"""Lists the tags on an [Entry][google.cloud.datacatalog.v1.Entry]. + r"""Lists tags assigned to an + [Entry][google.cloud.datacatalog.v1.Entry]. Args: request (google.cloud.datacatalog_v1.types.ListTagsRequest): @@ -2686,14 +2698,12 @@ def list_tags( [ListTags][google.cloud.datacatalog.v1.DataCatalog.ListTags]. parent (str): Required. The name of the Data Catalog resource to list - the tags of. The resource could be an - [Entry][google.cloud.datacatalog.v1.Entry] or an - [EntryGroup][google.cloud.datacatalog.v1.EntryGroup]. + the tags of. - Examples: - - - projects/{project_id}/locations/{location}/entryGroups/{entry_group_id} - - projects/{project_id}/locations/{location}/entryGroups/{entry_group_id}/entries/{entry_id} + The resource can be an + [Entry][google.cloud.datacatalog.v1.Entry] or an + [EntryGroup][google.cloud.datacatalog.v1.EntryGroup] + (without ``/entries/{entries}`` at the end). This corresponds to the ``parent`` field on the ``request`` instance; if ``request`` is provided, this @@ -2765,21 +2775,24 @@ def set_iam_policy( timeout: float = None, metadata: Sequence[Tuple[str, str]] = (), ) -> policy_pb2.Policy: - r"""Sets the access control policy for a resource. Replaces any - existing policy. Supported resources are: + r"""Sets an access control policy for a resource. Replaces any + existing policy. + + Supported resources are: + + - Tag templates + - Entry groups - - Tag templates. - - Entries. - - Entry groups. Note, this method cannot be used to manage - policies for BigQuery, Pub/Sub and any external Google Cloud - Platform resources synced to Data Catalog. + Note: This method sets policies only within Data Catalog and + can't be used to manage policies in BigQuery, Pub/Sub, Dataproc + Metastore, and any external Google Cloud Platform resources + synced with the Data Catalog. - Callers must have following Google IAM permission + To call this method, you must have the following Google IAM + permissions: - ``datacatalog.tagTemplates.setIamPolicy`` to set policies on tag templates. - - ``datacatalog.entries.setIamPolicy`` to set policies on - entries. - ``datacatalog.entryGroups.setIamPolicy`` to set policies on entry groups. @@ -2906,25 +2919,28 @@ def get_iam_policy( timeout: float = None, metadata: Sequence[Tuple[str, str]] = (), ) -> policy_pb2.Policy: - r"""Gets the access control policy for a resource. A ``NOT_FOUND`` - error is returned if the resource does not exist. An empty - policy is returned if the resource exists but does not have a - policy set on it. + r"""Gets the access control policy for a resource. + + May return: + + - A\ ``NOT_FOUND`` error if the resource doesn't exist or you + don't have the permission to view it. + - An empty policy if the resource exists but doesn't have a set + policy. Supported resources are: - - Tag templates. - - Entries. - - Entry groups. Note, this method cannot be used to manage - policies for BigQuery, Pub/Sub and any external Google Cloud - Platform resources synced to Data Catalog. + - Tag templates + - Entry groups - Callers must have following Google IAM permission + Note: This method doesn't get policies from Google Cloud + Platform resources ingested into Data Catalog. + + To call this method, you must have the following Google IAM + permissions: - ``datacatalog.tagTemplates.getIamPolicy`` to get policies on tag templates. - - ``datacatalog.entries.getIamPolicy`` to get policies on - entries. - ``datacatalog.entryGroups.getIamPolicy`` to get policies on entry groups. @@ -3050,20 +3066,20 @@ def test_iam_permissions( timeout: float = None, metadata: Sequence[Tuple[str, str]] = (), ) -> iam_policy_pb2.TestIamPermissionsResponse: - r"""Returns the caller's permissions on a resource. If the resource - does not exist, an empty set of permissions is returned (We - don't return a ``NOT_FOUND`` error). - + r"""Gets your permissions on a resource. + Returns an empty set of permissions if the resource + doesn't exist. Supported resources are: - - Tag templates. - - Entries. - - Entry groups. Note, this method cannot be used to manage - policies for BigQuery, Pub/Sub and any external Google Cloud - Platform resources synced to Data Catalog. + - Tag templates + - Entry groups - A caller is not required to have Google IAM permission to make - this request. + Note: This method gets policies only within Data Catalog + and can't be used to get policies from BigQuery, + Pub/Sub, Dataproc Metastore, and any external Google + Cloud Platform resources ingested into Data Catalog. + No Google IAM permissions are required to call this + method. Args: request (google.iam.v1.iam_policy_pb2.TestIamPermissionsRequest): diff --git a/google/cloud/datacatalog_v1/services/data_catalog/transports/grpc.py b/google/cloud/datacatalog_v1/services/data_catalog/transports/grpc.py index 264cb8c1..a8ba94a4 100644 --- a/google/cloud/datacatalog_v1/services/data_catalog/transports/grpc.py +++ b/google/cloud/datacatalog_v1/services/data_catalog/transports/grpc.py @@ -35,8 +35,8 @@ class DataCatalogGrpcTransport(DataCatalogTransport): """gRPC backend transport for DataCatalog. - Data Catalog API service allows clients to discover, - understand, and manage their data. + Data Catalog API service allows you to discover, understand, + and manage your data. This class defines the same methods as the primary client, so the primary client can load the underlying transport implementation @@ -238,23 +238,22 @@ def search_catalog( ]: r"""Return a callable for the search catalog method over gRPC. - Searches Data Catalog for multiple resources like entries, tags - that match a query. + Searches Data Catalog for multiple resources like entries and + tags that match a query. - This is a custom method - (https://cloud.google.com/apis/design/custom_methods) and does - not return the complete resource, only the resource identifier - and high level fields. Clients can subsequently call ``Get`` - methods. + This is a [Custom Method] + (https://cloud.google.com/apis/design/custom_methods) that + doesn't return all information on a resource, only its ID and + high level fields. To get more information, you can subsequently + call specific get methods. - Note that Data Catalog search queries do not guarantee full - recall. Query results that match your query may not be returned, - even in subsequent result pages. Also note that results returned - (and not returned) can vary across repeated search queries. + Note: Data Catalog search queries don't guarantee full recall. + Results that match your query might not be returned, even in + subsequent result pages. Additionally, returned (and not + returned) results can vary if you repeat search queries. - See `Data Catalog Search - Syntax `__ - for more information. + For more information, see [Data Catalog search syntax] + (https://cloud.google.com/data-catalog/docs/how-to/search-reference). Returns: Callable[[~.SearchCatalogRequest], @@ -280,27 +279,36 @@ def create_entry_group( ) -> Callable[[datacatalog.CreateEntryGroupRequest], datacatalog.EntryGroup]: r"""Return a callable for the create entry group method over gRPC. - Creates an EntryGroup. + Creates an entry group. An entry group contains logically related entries together with - Cloud Identity and Access Management policies that specify the - users who can create, edit, and view entries within the entry - group. + `Cloud Identity and Access + Management `__ policies. These + policies specify users who can create, edit, and view entries + within entry groups. + + Data Catalog automatically creates entry groups with names that + start with the ``@`` symbol for the following resources: + + - BigQuery entries (``@bigquery``) + - Pub/Sub topics (``@pubsub``) + - Dataproc Metastore services + (``@dataproc_metastore_{SERVICE_NAME_HASH}``) + + You can create your own entry groups for Cloud Storage fileset + entries and custom entries together with the corresponding IAM + policies. User-created entry groups can't contain the ``@`` + symbol, it is reserved for automatically created groups. - Data Catalog automatically creates an entry group for BigQuery - entries ("@bigquery") and Pub/Sub topics ("@pubsub"). Users - create their own entry group to contain Cloud Storage fileset - entries or custom type entries, and the IAM policies associated - with those entries. Entry groups, like entries, can be searched. + Entry groups, like entries, can be searched. A maximum of 10,000 entry groups may be created per organization across all locations. - Users should enable the Data Catalog API in the project - identified by the ``parent`` parameter (see [Data Catalog - Resource Project] - (https://cloud.google.com/data-catalog/docs/concepts/resource-project) - for more information). + You must enable the Data Catalog API in the project identified + by the ``parent`` parameter. For more information, see `Data + Catalog resource + project `__. Returns: Callable[[~.CreateEntryGroupRequest], @@ -326,7 +334,7 @@ def get_entry_group( ) -> Callable[[datacatalog.GetEntryGroupRequest], datacatalog.EntryGroup]: r"""Return a callable for the get entry group method over gRPC. - Gets an EntryGroup. + Gets an entry group. Returns: Callable[[~.GetEntryGroupRequest], @@ -352,11 +360,12 @@ def update_entry_group( ) -> Callable[[datacatalog.UpdateEntryGroupRequest], datacatalog.EntryGroup]: r"""Return a callable for the update entry group method over gRPC. - Updates an EntryGroup. The user should enable the Data Catalog - API in the project identified by the ``entry_group.name`` - parameter (see [Data Catalog Resource Project] - (https://cloud.google.com/data-catalog/docs/concepts/resource-project) - for more information). + Updates an entry group. + + You must enable the Data Catalog API in the project identified + by the ``entry_group.name`` parameter. For more information, see + `Data Catalog resource + project `__. Returns: Callable[[~.UpdateEntryGroupRequest], @@ -382,12 +391,12 @@ def delete_entry_group( ) -> Callable[[datacatalog.DeleteEntryGroupRequest], empty_pb2.Empty]: r"""Return a callable for the delete entry group method over gRPC. - Deletes an EntryGroup. Only entry groups that do not contain - entries can be deleted. Users should enable the Data Catalog API - in the project identified by the ``name`` parameter (see [Data - Catalog Resource Project] - (https://cloud.google.com/data-catalog/docs/concepts/resource-project) - for more information). + Deletes an entry group. + + You must enable the Data Catalog API in the project identified + by the ``name`` parameter. For more information, see `Data + Catalog resource + project `__. Returns: Callable[[~.DeleteEntryGroupRequest], @@ -441,16 +450,19 @@ def create_entry( ) -> Callable[[datacatalog.CreateEntryRequest], datacatalog.Entry]: r"""Return a callable for the create entry method over gRPC. - Creates an entry. Only entries of types 'FILESET', 'CLUSTER', - 'DATA_STREAM' or with a user-specified type can be created. + Creates an entry. - Users should enable the Data Catalog API in the project - identified by the ``parent`` parameter (see [Data Catalog - Resource Project] - (https://cloud.google.com/data-catalog/docs/concepts/resource-project) - for more information). + You can create entries only with 'FILESET', 'CLUSTER', + 'DATA_STREAM', or custom types. Data Catalog automatically + creates entries with other types during metadata ingestion from + integrated systems. - A maximum of 100,000 entries may be created per entry group. + You must enable the Data Catalog API in the project identified + by the ``parent`` parameter. For more information, see `Data + Catalog resource + project `__. + + An entry group can have a maximum of 100,000 entries. Returns: Callable[[~.CreateEntryRequest], @@ -476,11 +488,12 @@ def update_entry( ) -> Callable[[datacatalog.UpdateEntryRequest], datacatalog.Entry]: r"""Return a callable for the update entry method over gRPC. - Updates an existing entry. Users should enable the Data Catalog - API in the project identified by the ``entry.name`` parameter - (see [Data Catalog Resource Project] - (https://cloud.google.com/data-catalog/docs/concepts/resource-project) - for more information). + Updates an existing entry. + + You must enable the Data Catalog API in the project identified + by the ``entry.name`` parameter. For more information, see `Data + Catalog resource + project `__. Returns: Callable[[~.UpdateEntryRequest], @@ -506,13 +519,16 @@ def delete_entry( ) -> Callable[[datacatalog.DeleteEntryRequest], empty_pb2.Empty]: r"""Return a callable for the delete entry method over gRPC. - Deletes an existing entry. Only entries created through + Deletes an existing entry. + + You can delete only the entries created by the [CreateEntry][google.cloud.datacatalog.v1.DataCatalog.CreateEntry] - method can be deleted. Users should enable the Data Catalog API - in the project identified by the ``name`` parameter (see [Data - Catalog Resource Project] - (https://cloud.google.com/data-catalog/docs/concepts/resource-project) - for more information). + method. + + You must enable the Data Catalog API in the project identified + by the ``name`` parameter. For more information, see `Data + Catalog resource + project `__. Returns: Callable[[~.DeleteEntryRequest], @@ -562,10 +578,9 @@ def lookup_entry( ) -> Callable[[datacatalog.LookupEntryRequest], datacatalog.Entry]: r"""Return a callable for the lookup entry method over gRPC. - Get an entry by target resource name. This method - allows clients to use the resource name from the source - Google Cloud Platform service to get the Data Catalog - Entry. + Gets an entry by its target resource name. + The resource name comes from the source Google Cloud + Platform service. Returns: Callable[[~.LookupEntryRequest], @@ -617,11 +632,12 @@ def create_tag_template( ) -> Callable[[datacatalog.CreateTagTemplateRequest], tags.TagTemplate]: r"""Return a callable for the create tag template method over gRPC. - Creates a tag template. The user should enable the Data Catalog - API in the project identified by the ``parent`` parameter (see - `Data Catalog Resource - Project `__ - for more information). + Creates a tag template. + + You must enable the Data Catalog API in the project identified + by the ``parent`` parameter. For more information, see [Data + Catalog resource project] + (https://cloud.google.com/data-catalog/docs/concepts/resource-project). Returns: Callable[[~.CreateTagTemplateRequest], @@ -673,15 +689,16 @@ def update_tag_template( ) -> Callable[[datacatalog.UpdateTagTemplateRequest], tags.TagTemplate]: r"""Return a callable for the update tag template method over gRPC. - Updates a tag template. This method cannot be used to update the - fields of a template. The tag template fields are represented as - separate resources and should be updated using their own - create/update/delete methods. Users should enable the Data - Catalog API in the project identified by the - ``tag_template.name`` parameter (see [Data Catalog Resource - Project] - (https://cloud.google.com/data-catalog/docs/concepts/resource-project) - for more information). + Updates a tag template. + + You can't update template fields with this method. These fields + are separate resources with their own create, update, and delete + methods. + + You must enable the Data Catalog API in the project identified + by the ``tag_template.name`` parameter. For more information, + see `Data Catalog resource + project `__. Returns: Callable[[~.UpdateTagTemplateRequest], @@ -707,11 +724,12 @@ def delete_tag_template( ) -> Callable[[datacatalog.DeleteTagTemplateRequest], empty_pb2.Empty]: r"""Return a callable for the delete tag template method over gRPC. - Deletes a tag template and all tags using the template. Users - should enable the Data Catalog API in the project identified by - the ``name`` parameter (see [Data Catalog Resource Project] - (https://cloud.google.com/data-catalog/docs/concepts/resource-project) - for more information). + Deletes a tag template and all tags that use it. + + You must enable the Data Catalog API in the project identified + by the ``name`` parameter. For more information, see `Data + Catalog resource + project `__. Returns: Callable[[~.DeleteTagTemplateRequest], @@ -737,11 +755,12 @@ def create_tag_template_field( ) -> Callable[[datacatalog.CreateTagTemplateFieldRequest], tags.TagTemplateField]: r"""Return a callable for the create tag template field method over gRPC. - Creates a field in a tag template. The user should enable the - Data Catalog API in the project identified by the ``parent`` - parameter (see `Data Catalog Resource - Project `__ - for more information). + Creates a field in a tag template. + + You must enable the Data Catalog API in the project identified + by the ``parent`` parameter. For more information, see `Data + Catalog resource + project `__. Returns: Callable[[~.CreateTagTemplateFieldRequest], @@ -767,12 +786,14 @@ def update_tag_template_field( ) -> Callable[[datacatalog.UpdateTagTemplateFieldRequest], tags.TagTemplateField]: r"""Return a callable for the update tag template field method over gRPC. - Updates a field in a tag template. This method cannot be used to - update the field type. Users should enable the Data Catalog API - in the project identified by the ``name`` parameter (see [Data - Catalog Resource Project] - (https://cloud.google.com/data-catalog/docs/concepts/resource-project) - for more information). + Updates a field in a tag template. + + You can't update the field type with this method. + + You must enable the Data Catalog API in the project identified + by the ``name`` parameter. For more information, see `Data + Catalog resource + project `__. Returns: Callable[[~.UpdateTagTemplateFieldRequest], @@ -798,11 +819,12 @@ def rename_tag_template_field( ) -> Callable[[datacatalog.RenameTagTemplateFieldRequest], tags.TagTemplateField]: r"""Return a callable for the rename tag template field method over gRPC. - Renames a field in a tag template. The user should enable the - Data Catalog API in the project identified by the ``name`` - parameter (see `Data Catalog Resource - Project `__ - for more information). + Renames a field in a tag template. + + You must enable the Data Catalog API in the project identified + by the ``name`` parameter. For more information, see [Data + Catalog resource project] + (https://cloud.google.com/data-catalog/docs/concepts/resource-project). Returns: Callable[[~.RenameTagTemplateFieldRequest], @@ -831,8 +853,8 @@ def rename_tag_template_field_enum_value( r"""Return a callable for the rename tag template field enum value method over gRPC. - Renames an enum value in a tag template. The enum - values have to be unique within one enum field. + Renames an enum value in a tag template. + Within a single enum field, enum values must be unique. Returns: Callable[[~.RenameTagTemplateFieldEnumValueRequest], @@ -860,12 +882,13 @@ def delete_tag_template_field( ) -> Callable[[datacatalog.DeleteTagTemplateFieldRequest], empty_pb2.Empty]: r"""Return a callable for the delete tag template field method over gRPC. - Deletes a field in a tag template and all uses of that field. - Users should enable the Data Catalog API in the project - identified by the ``name`` parameter (see [Data Catalog Resource - Project] - (https://cloud.google.com/data-catalog/docs/concepts/resource-project) - for more information). + Deletes a field in a tag template and all uses of this field + from the tags based on this template. + + You must enable the Data Catalog API in the project identified + by the ``name`` parameter. For more information, see `Data + Catalog resource + project `__. Returns: Callable[[~.DeleteTagTemplateFieldRequest], @@ -889,12 +912,21 @@ def delete_tag_template_field( def create_tag(self) -> Callable[[datacatalog.CreateTagRequest], tags.Tag]: r"""Return a callable for the create tag method over gRPC. - Creates a tag on an [Entry][google.cloud.datacatalog.v1.Entry]. + Creates a tag and assigns it to: + + - An [Entry][google.cloud.datacatalog.v1.Entry] if the method + name is + ``projects.locations.entryGroups.entries.tags.create``. + - Or [EntryGroup][google.cloud.datacatalog.v1.EntryGroup]if the + method name is + ``projects.locations.entryGroups.tags.create``. + Note: The project identified by the ``parent`` parameter for the - `tag `__ - and the `tag - template `__ - used to create the tag must be from the same organization. + [tag] + (https://cloud.google.com/data-catalog/docs/reference/rest/v1/projects.locations.entryGroups.entries.tags/create#path-parameters) + and the [tag template] + (https://cloud.google.com/data-catalog/docs/reference/rest/v1/projects.locations.tagTemplates/create#path-parameters) + used to create the tag must be in the same organization. Returns: Callable[[~.CreateTagRequest], @@ -968,7 +1000,8 @@ def list_tags( ) -> Callable[[datacatalog.ListTagsRequest], datacatalog.ListTagsResponse]: r"""Return a callable for the list tags method over gRPC. - Lists the tags on an [Entry][google.cloud.datacatalog.v1.Entry]. + Lists tags assigned to an + [Entry][google.cloud.datacatalog.v1.Entry]. Returns: Callable[[~.ListTagsRequest], @@ -994,21 +1027,24 @@ def set_iam_policy( ) -> Callable[[iam_policy_pb2.SetIamPolicyRequest], policy_pb2.Policy]: r"""Return a callable for the set iam policy method over gRPC. - Sets the access control policy for a resource. Replaces any - existing policy. Supported resources are: + Sets an access control policy for a resource. Replaces any + existing policy. - - Tag templates. - - Entries. - - Entry groups. Note, this method cannot be used to manage - policies for BigQuery, Pub/Sub and any external Google Cloud - Platform resources synced to Data Catalog. + Supported resources are: + + - Tag templates + - Entry groups - Callers must have following Google IAM permission + Note: This method sets policies only within Data Catalog and + can't be used to manage policies in BigQuery, Pub/Sub, Dataproc + Metastore, and any external Google Cloud Platform resources + synced with the Data Catalog. + + To call this method, you must have the following Google IAM + permissions: - ``datacatalog.tagTemplates.setIamPolicy`` to set policies on tag templates. - - ``datacatalog.entries.setIamPolicy`` to set policies on - entries. - ``datacatalog.entryGroups.setIamPolicy`` to set policies on entry groups. @@ -1036,25 +1072,28 @@ def get_iam_policy( ) -> Callable[[iam_policy_pb2.GetIamPolicyRequest], policy_pb2.Policy]: r"""Return a callable for the get iam policy method over gRPC. - Gets the access control policy for a resource. A ``NOT_FOUND`` - error is returned if the resource does not exist. An empty - policy is returned if the resource exists but does not have a - policy set on it. + Gets the access control policy for a resource. + + May return: + + - A\ ``NOT_FOUND`` error if the resource doesn't exist or you + don't have the permission to view it. + - An empty policy if the resource exists but doesn't have a set + policy. Supported resources are: - - Tag templates. - - Entries. - - Entry groups. Note, this method cannot be used to manage - policies for BigQuery, Pub/Sub and any external Google Cloud - Platform resources synced to Data Catalog. + - Tag templates + - Entry groups + + Note: This method doesn't get policies from Google Cloud + Platform resources ingested into Data Catalog. - Callers must have following Google IAM permission + To call this method, you must have the following Google IAM + permissions: - ``datacatalog.tagTemplates.getIamPolicy`` to get policies on tag templates. - - ``datacatalog.entries.getIamPolicy`` to get policies on - entries. - ``datacatalog.entryGroups.getIamPolicy`` to get policies on entry groups. @@ -1085,20 +1124,20 @@ def test_iam_permissions( ]: r"""Return a callable for the test iam permissions method over gRPC. - Returns the caller's permissions on a resource. If the resource - does not exist, an empty set of permissions is returned (We - don't return a ``NOT_FOUND`` error). - + Gets your permissions on a resource. + Returns an empty set of permissions if the resource + doesn't exist. Supported resources are: - - Tag templates. - - Entries. - - Entry groups. Note, this method cannot be used to manage - policies for BigQuery, Pub/Sub and any external Google Cloud - Platform resources synced to Data Catalog. + - Tag templates + - Entry groups - A caller is not required to have Google IAM permission to make - this request. + Note: This method gets policies only within Data Catalog + and can't be used to get policies from BigQuery, + Pub/Sub, Dataproc Metastore, and any external Google + Cloud Platform resources ingested into Data Catalog. + No Google IAM permissions are required to call this + method. Returns: Callable[[~.TestIamPermissionsRequest], diff --git a/google/cloud/datacatalog_v1/services/data_catalog/transports/grpc_asyncio.py b/google/cloud/datacatalog_v1/services/data_catalog/transports/grpc_asyncio.py index c76ba94b..befa37be 100644 --- a/google/cloud/datacatalog_v1/services/data_catalog/transports/grpc_asyncio.py +++ b/google/cloud/datacatalog_v1/services/data_catalog/transports/grpc_asyncio.py @@ -37,8 +37,8 @@ class DataCatalogGrpcAsyncIOTransport(DataCatalogTransport): """gRPC AsyncIO backend transport for DataCatalog. - Data Catalog API service allows clients to discover, - understand, and manage their data. + Data Catalog API service allows you to discover, understand, + and manage your data. This class defines the same methods as the primary client, so the primary client can load the underlying transport implementation @@ -241,23 +241,22 @@ def search_catalog( ]: r"""Return a callable for the search catalog method over gRPC. - Searches Data Catalog for multiple resources like entries, tags - that match a query. + Searches Data Catalog for multiple resources like entries and + tags that match a query. - This is a custom method - (https://cloud.google.com/apis/design/custom_methods) and does - not return the complete resource, only the resource identifier - and high level fields. Clients can subsequently call ``Get`` - methods. + This is a [Custom Method] + (https://cloud.google.com/apis/design/custom_methods) that + doesn't return all information on a resource, only its ID and + high level fields. To get more information, you can subsequently + call specific get methods. - Note that Data Catalog search queries do not guarantee full - recall. Query results that match your query may not be returned, - even in subsequent result pages. Also note that results returned - (and not returned) can vary across repeated search queries. + Note: Data Catalog search queries don't guarantee full recall. + Results that match your query might not be returned, even in + subsequent result pages. Additionally, returned (and not + returned) results can vary if you repeat search queries. - See `Data Catalog Search - Syntax `__ - for more information. + For more information, see [Data Catalog search syntax] + (https://cloud.google.com/data-catalog/docs/how-to/search-reference). Returns: Callable[[~.SearchCatalogRequest], @@ -285,27 +284,36 @@ def create_entry_group( ]: r"""Return a callable for the create entry group method over gRPC. - Creates an EntryGroup. + Creates an entry group. An entry group contains logically related entries together with - Cloud Identity and Access Management policies that specify the - users who can create, edit, and view entries within the entry - group. + `Cloud Identity and Access + Management `__ policies. These + policies specify users who can create, edit, and view entries + within entry groups. + + Data Catalog automatically creates entry groups with names that + start with the ``@`` symbol for the following resources: + + - BigQuery entries (``@bigquery``) + - Pub/Sub topics (``@pubsub``) + - Dataproc Metastore services + (``@dataproc_metastore_{SERVICE_NAME_HASH}``) + + You can create your own entry groups for Cloud Storage fileset + entries and custom entries together with the corresponding IAM + policies. User-created entry groups can't contain the ``@`` + symbol, it is reserved for automatically created groups. - Data Catalog automatically creates an entry group for BigQuery - entries ("@bigquery") and Pub/Sub topics ("@pubsub"). Users - create their own entry group to contain Cloud Storage fileset - entries or custom type entries, and the IAM policies associated - with those entries. Entry groups, like entries, can be searched. + Entry groups, like entries, can be searched. A maximum of 10,000 entry groups may be created per organization across all locations. - Users should enable the Data Catalog API in the project - identified by the ``parent`` parameter (see [Data Catalog - Resource Project] - (https://cloud.google.com/data-catalog/docs/concepts/resource-project) - for more information). + You must enable the Data Catalog API in the project identified + by the ``parent`` parameter. For more information, see `Data + Catalog resource + project `__. Returns: Callable[[~.CreateEntryGroupRequest], @@ -333,7 +341,7 @@ def get_entry_group( ]: r"""Return a callable for the get entry group method over gRPC. - Gets an EntryGroup. + Gets an entry group. Returns: Callable[[~.GetEntryGroupRequest], @@ -361,11 +369,12 @@ def update_entry_group( ]: r"""Return a callable for the update entry group method over gRPC. - Updates an EntryGroup. The user should enable the Data Catalog - API in the project identified by the ``entry_group.name`` - parameter (see [Data Catalog Resource Project] - (https://cloud.google.com/data-catalog/docs/concepts/resource-project) - for more information). + Updates an entry group. + + You must enable the Data Catalog API in the project identified + by the ``entry_group.name`` parameter. For more information, see + `Data Catalog resource + project `__. Returns: Callable[[~.UpdateEntryGroupRequest], @@ -391,12 +400,12 @@ def delete_entry_group( ) -> Callable[[datacatalog.DeleteEntryGroupRequest], Awaitable[empty_pb2.Empty]]: r"""Return a callable for the delete entry group method over gRPC. - Deletes an EntryGroup. Only entry groups that do not contain - entries can be deleted. Users should enable the Data Catalog API - in the project identified by the ``name`` parameter (see [Data - Catalog Resource Project] - (https://cloud.google.com/data-catalog/docs/concepts/resource-project) - for more information). + Deletes an entry group. + + You must enable the Data Catalog API in the project identified + by the ``name`` parameter. For more information, see `Data + Catalog resource + project `__. Returns: Callable[[~.DeleteEntryGroupRequest], @@ -451,16 +460,19 @@ def create_entry( ) -> Callable[[datacatalog.CreateEntryRequest], Awaitable[datacatalog.Entry]]: r"""Return a callable for the create entry method over gRPC. - Creates an entry. Only entries of types 'FILESET', 'CLUSTER', - 'DATA_STREAM' or with a user-specified type can be created. + Creates an entry. - Users should enable the Data Catalog API in the project - identified by the ``parent`` parameter (see [Data Catalog - Resource Project] - (https://cloud.google.com/data-catalog/docs/concepts/resource-project) - for more information). + You can create entries only with 'FILESET', 'CLUSTER', + 'DATA_STREAM', or custom types. Data Catalog automatically + creates entries with other types during metadata ingestion from + integrated systems. - A maximum of 100,000 entries may be created per entry group. + You must enable the Data Catalog API in the project identified + by the ``parent`` parameter. For more information, see `Data + Catalog resource + project `__. + + An entry group can have a maximum of 100,000 entries. Returns: Callable[[~.CreateEntryRequest], @@ -486,11 +498,12 @@ def update_entry( ) -> Callable[[datacatalog.UpdateEntryRequest], Awaitable[datacatalog.Entry]]: r"""Return a callable for the update entry method over gRPC. - Updates an existing entry. Users should enable the Data Catalog - API in the project identified by the ``entry.name`` parameter - (see [Data Catalog Resource Project] - (https://cloud.google.com/data-catalog/docs/concepts/resource-project) - for more information). + Updates an existing entry. + + You must enable the Data Catalog API in the project identified + by the ``entry.name`` parameter. For more information, see `Data + Catalog resource + project `__. Returns: Callable[[~.UpdateEntryRequest], @@ -516,13 +529,16 @@ def delete_entry( ) -> Callable[[datacatalog.DeleteEntryRequest], Awaitable[empty_pb2.Empty]]: r"""Return a callable for the delete entry method over gRPC. - Deletes an existing entry. Only entries created through + Deletes an existing entry. + + You can delete only the entries created by the [CreateEntry][google.cloud.datacatalog.v1.DataCatalog.CreateEntry] - method can be deleted. Users should enable the Data Catalog API - in the project identified by the ``name`` parameter (see [Data - Catalog Resource Project] - (https://cloud.google.com/data-catalog/docs/concepts/resource-project) - for more information). + method. + + You must enable the Data Catalog API in the project identified + by the ``name`` parameter. For more information, see `Data + Catalog resource + project `__. Returns: Callable[[~.DeleteEntryRequest], @@ -574,10 +590,9 @@ def lookup_entry( ) -> Callable[[datacatalog.LookupEntryRequest], Awaitable[datacatalog.Entry]]: r"""Return a callable for the lookup entry method over gRPC. - Get an entry by target resource name. This method - allows clients to use the resource name from the source - Google Cloud Platform service to get the Data Catalog - Entry. + Gets an entry by its target resource name. + The resource name comes from the source Google Cloud + Platform service. Returns: Callable[[~.LookupEntryRequest], @@ -631,11 +646,12 @@ def create_tag_template( ) -> Callable[[datacatalog.CreateTagTemplateRequest], Awaitable[tags.TagTemplate]]: r"""Return a callable for the create tag template method over gRPC. - Creates a tag template. The user should enable the Data Catalog - API in the project identified by the ``parent`` parameter (see - `Data Catalog Resource - Project `__ - for more information). + Creates a tag template. + + You must enable the Data Catalog API in the project identified + by the ``parent`` parameter. For more information, see [Data + Catalog resource project] + (https://cloud.google.com/data-catalog/docs/concepts/resource-project). Returns: Callable[[~.CreateTagTemplateRequest], @@ -687,15 +703,16 @@ def update_tag_template( ) -> Callable[[datacatalog.UpdateTagTemplateRequest], Awaitable[tags.TagTemplate]]: r"""Return a callable for the update tag template method over gRPC. - Updates a tag template. This method cannot be used to update the - fields of a template. The tag template fields are represented as - separate resources and should be updated using their own - create/update/delete methods. Users should enable the Data - Catalog API in the project identified by the - ``tag_template.name`` parameter (see [Data Catalog Resource - Project] - (https://cloud.google.com/data-catalog/docs/concepts/resource-project) - for more information). + Updates a tag template. + + You can't update template fields with this method. These fields + are separate resources with their own create, update, and delete + methods. + + You must enable the Data Catalog API in the project identified + by the ``tag_template.name`` parameter. For more information, + see `Data Catalog resource + project `__. Returns: Callable[[~.UpdateTagTemplateRequest], @@ -721,11 +738,12 @@ def delete_tag_template( ) -> Callable[[datacatalog.DeleteTagTemplateRequest], Awaitable[empty_pb2.Empty]]: r"""Return a callable for the delete tag template method over gRPC. - Deletes a tag template and all tags using the template. Users - should enable the Data Catalog API in the project identified by - the ``name`` parameter (see [Data Catalog Resource Project] - (https://cloud.google.com/data-catalog/docs/concepts/resource-project) - for more information). + Deletes a tag template and all tags that use it. + + You must enable the Data Catalog API in the project identified + by the ``name`` parameter. For more information, see `Data + Catalog resource + project `__. Returns: Callable[[~.DeleteTagTemplateRequest], @@ -753,11 +771,12 @@ def create_tag_template_field( ]: r"""Return a callable for the create tag template field method over gRPC. - Creates a field in a tag template. The user should enable the - Data Catalog API in the project identified by the ``parent`` - parameter (see `Data Catalog Resource - Project `__ - for more information). + Creates a field in a tag template. + + You must enable the Data Catalog API in the project identified + by the ``parent`` parameter. For more information, see `Data + Catalog resource + project `__. Returns: Callable[[~.CreateTagTemplateFieldRequest], @@ -785,12 +804,14 @@ def update_tag_template_field( ]: r"""Return a callable for the update tag template field method over gRPC. - Updates a field in a tag template. This method cannot be used to - update the field type. Users should enable the Data Catalog API - in the project identified by the ``name`` parameter (see [Data - Catalog Resource Project] - (https://cloud.google.com/data-catalog/docs/concepts/resource-project) - for more information). + Updates a field in a tag template. + + You can't update the field type with this method. + + You must enable the Data Catalog API in the project identified + by the ``name`` parameter. For more information, see `Data + Catalog resource + project `__. Returns: Callable[[~.UpdateTagTemplateFieldRequest], @@ -818,11 +839,12 @@ def rename_tag_template_field( ]: r"""Return a callable for the rename tag template field method over gRPC. - Renames a field in a tag template. The user should enable the - Data Catalog API in the project identified by the ``name`` - parameter (see `Data Catalog Resource - Project `__ - for more information). + Renames a field in a tag template. + + You must enable the Data Catalog API in the project identified + by the ``name`` parameter. For more information, see [Data + Catalog resource project] + (https://cloud.google.com/data-catalog/docs/concepts/resource-project). Returns: Callable[[~.RenameTagTemplateFieldRequest], @@ -852,8 +874,8 @@ def rename_tag_template_field_enum_value( r"""Return a callable for the rename tag template field enum value method over gRPC. - Renames an enum value in a tag template. The enum - values have to be unique within one enum field. + Renames an enum value in a tag template. + Within a single enum field, enum values must be unique. Returns: Callable[[~.RenameTagTemplateFieldEnumValueRequest], @@ -883,12 +905,13 @@ def delete_tag_template_field( ]: r"""Return a callable for the delete tag template field method over gRPC. - Deletes a field in a tag template and all uses of that field. - Users should enable the Data Catalog API in the project - identified by the ``name`` parameter (see [Data Catalog Resource - Project] - (https://cloud.google.com/data-catalog/docs/concepts/resource-project) - for more information). + Deletes a field in a tag template and all uses of this field + from the tags based on this template. + + You must enable the Data Catalog API in the project identified + by the ``name`` parameter. For more information, see `Data + Catalog resource + project `__. Returns: Callable[[~.DeleteTagTemplateFieldRequest], @@ -914,12 +937,21 @@ def create_tag( ) -> Callable[[datacatalog.CreateTagRequest], Awaitable[tags.Tag]]: r"""Return a callable for the create tag method over gRPC. - Creates a tag on an [Entry][google.cloud.datacatalog.v1.Entry]. + Creates a tag and assigns it to: + + - An [Entry][google.cloud.datacatalog.v1.Entry] if the method + name is + ``projects.locations.entryGroups.entries.tags.create``. + - Or [EntryGroup][google.cloud.datacatalog.v1.EntryGroup]if the + method name is + ``projects.locations.entryGroups.tags.create``. + Note: The project identified by the ``parent`` parameter for the - `tag `__ - and the `tag - template `__ - used to create the tag must be from the same organization. + [tag] + (https://cloud.google.com/data-catalog/docs/reference/rest/v1/projects.locations.entryGroups.entries.tags/create#path-parameters) + and the [tag template] + (https://cloud.google.com/data-catalog/docs/reference/rest/v1/projects.locations.tagTemplates/create#path-parameters) + used to create the tag must be in the same organization. Returns: Callable[[~.CreateTagRequest], @@ -999,7 +1031,8 @@ def list_tags( ]: r"""Return a callable for the list tags method over gRPC. - Lists the tags on an [Entry][google.cloud.datacatalog.v1.Entry]. + Lists tags assigned to an + [Entry][google.cloud.datacatalog.v1.Entry]. Returns: Callable[[~.ListTagsRequest], @@ -1025,21 +1058,24 @@ def set_iam_policy( ) -> Callable[[iam_policy_pb2.SetIamPolicyRequest], Awaitable[policy_pb2.Policy]]: r"""Return a callable for the set iam policy method over gRPC. - Sets the access control policy for a resource. Replaces any - existing policy. Supported resources are: + Sets an access control policy for a resource. Replaces any + existing policy. - - Tag templates. - - Entries. - - Entry groups. Note, this method cannot be used to manage - policies for BigQuery, Pub/Sub and any external Google Cloud - Platform resources synced to Data Catalog. + Supported resources are: + + - Tag templates + - Entry groups - Callers must have following Google IAM permission + Note: This method sets policies only within Data Catalog and + can't be used to manage policies in BigQuery, Pub/Sub, Dataproc + Metastore, and any external Google Cloud Platform resources + synced with the Data Catalog. + + To call this method, you must have the following Google IAM + permissions: - ``datacatalog.tagTemplates.setIamPolicy`` to set policies on tag templates. - - ``datacatalog.entries.setIamPolicy`` to set policies on - entries. - ``datacatalog.entryGroups.setIamPolicy`` to set policies on entry groups. @@ -1067,25 +1103,28 @@ def get_iam_policy( ) -> Callable[[iam_policy_pb2.GetIamPolicyRequest], Awaitable[policy_pb2.Policy]]: r"""Return a callable for the get iam policy method over gRPC. - Gets the access control policy for a resource. A ``NOT_FOUND`` - error is returned if the resource does not exist. An empty - policy is returned if the resource exists but does not have a - policy set on it. + Gets the access control policy for a resource. + + May return: + + - A\ ``NOT_FOUND`` error if the resource doesn't exist or you + don't have the permission to view it. + - An empty policy if the resource exists but doesn't have a set + policy. Supported resources are: - - Tag templates. - - Entries. - - Entry groups. Note, this method cannot be used to manage - policies for BigQuery, Pub/Sub and any external Google Cloud - Platform resources synced to Data Catalog. + - Tag templates + - Entry groups + + Note: This method doesn't get policies from Google Cloud + Platform resources ingested into Data Catalog. - Callers must have following Google IAM permission + To call this method, you must have the following Google IAM + permissions: - ``datacatalog.tagTemplates.getIamPolicy`` to get policies on tag templates. - - ``datacatalog.entries.getIamPolicy`` to get policies on - entries. - ``datacatalog.entryGroups.getIamPolicy`` to get policies on entry groups. @@ -1116,20 +1155,20 @@ def test_iam_permissions( ]: r"""Return a callable for the test iam permissions method over gRPC. - Returns the caller's permissions on a resource. If the resource - does not exist, an empty set of permissions is returned (We - don't return a ``NOT_FOUND`` error). - + Gets your permissions on a resource. + Returns an empty set of permissions if the resource + doesn't exist. Supported resources are: - - Tag templates. - - Entries. - - Entry groups. Note, this method cannot be used to manage - policies for BigQuery, Pub/Sub and any external Google Cloud - Platform resources synced to Data Catalog. + - Tag templates + - Entry groups - A caller is not required to have Google IAM permission to make - this request. + Note: This method gets policies only within Data Catalog + and can't be used to get policies from BigQuery, + Pub/Sub, Dataproc Metastore, and any external Google + Cloud Platform resources ingested into Data Catalog. + No Google IAM permissions are required to call this + method. Returns: Callable[[~.TestIamPermissionsRequest], diff --git a/google/cloud/datacatalog_v1/services/policy_tag_manager/async_client.py b/google/cloud/datacatalog_v1/services/policy_tag_manager/async_client.py index e57f8ecb..a2d82bb7 100644 --- a/google/cloud/datacatalog_v1/services/policy_tag_manager/async_client.py +++ b/google/cloud/datacatalog_v1/services/policy_tag_manager/async_client.py @@ -37,7 +37,7 @@ class PolicyTagManagerAsyncClient: - """Policy Tag Manager API service allows clients to manage their + """Policy Tag Manager API service allows you to manage your policy tags and taxonomies. Policy tags are used to tag BigQuery columns and apply @@ -182,9 +182,9 @@ async def create_taxonomy( timeout: float = None, metadata: Sequence[Tuple[str, str]] = (), ) -> policytagmanager.Taxonomy: - r"""Creates a taxonomy in a specified project. The - taxonomy is initially empty, i.e., does not contain - policy tags. + r"""Creates a taxonomy in a specified project. + The taxonomy is initially empty, that is, it doesn't + contain policy tags. Args: request (:class:`google.cloud.datacatalog_v1.types.CreateTaxonomyRequest`): @@ -199,7 +199,7 @@ async def create_taxonomy( on the ``request`` instance; if ``request`` is provided, this should not be set. taxonomy (:class:`google.cloud.datacatalog_v1.types.Taxonomy`): - The taxonomy to be created. + The taxonomy to create. This corresponds to the ``taxonomy`` field on the ``request`` instance; if ``request`` is provided, this should not be set. @@ -212,13 +212,14 @@ async def create_taxonomy( Returns: google.cloud.datacatalog_v1.types.Taxonomy: A taxonomy is a collection of hierarchical policy tags that classify data - along a common axis. For instance a "data - sensitivity" taxonomy could contain the following - policy tags: + along a common axis. + + For example, a "data sensitivity" taxonomy might + contain the following policy tags: :literal:`\` + PII + Account number + Age + SSN + Zipcode + Financials + Revenue`\ \` - A "data origin" taxonomy could contain the following + A "data origin" taxonomy might contain the following policy tags: :literal:`\` + User data + Employee data + Partner data + Public data`\ \` @@ -272,9 +273,9 @@ async def delete_taxonomy( timeout: float = None, metadata: Sequence[Tuple[str, str]] = (), ) -> None: - r"""Deletes a taxonomy. This method will also delete all - policy tags in this taxonomy, their associated policies, - and the policy tags references from BigQuery columns. + r"""Deletes a taxonomy, including all policy tags in this + taxonomy, their associated policies, and the policy tags + references from BigQuery columns. Args: request (:class:`google.cloud.datacatalog_v1.types.DeleteTaxonomyRequest`): @@ -282,8 +283,9 @@ async def delete_taxonomy( [DeleteTaxonomy][google.cloud.datacatalog.v1.PolicyTagManager.DeleteTaxonomy]. name (:class:`str`): Required. Resource name of the - taxonomy to be deleted. All policy tags - in this taxonomy will also be deleted. + taxonomy to delete. + Note: All policy tags in this taxonomy + are also deleted. This corresponds to the ``name`` field on the ``request`` instance; if ``request`` is provided, this @@ -339,17 +341,17 @@ async def update_taxonomy( timeout: float = None, metadata: Sequence[Tuple[str, str]] = (), ) -> policytagmanager.Taxonomy: - r"""Updates a taxonomy. This method can update the - taxonomy's display name, description, and activated - policy types. + r"""Updates a taxonomy, including its display name, + description, and activated policy types. Args: request (:class:`google.cloud.datacatalog_v1.types.UpdateTaxonomyRequest`): The request object. Request message for [UpdateTaxonomy][google.cloud.datacatalog.v1.PolicyTagManager.UpdateTaxonomy]. taxonomy (:class:`google.cloud.datacatalog_v1.types.Taxonomy`): - The taxonomy to update. Only description, display_name, - and activated policy types can be updated. + The taxonomy to update. You can + update only its description, display + name, and activated policy types. This corresponds to the ``taxonomy`` field on the ``request`` instance; if ``request`` is provided, this @@ -363,13 +365,14 @@ async def update_taxonomy( Returns: google.cloud.datacatalog_v1.types.Taxonomy: A taxonomy is a collection of hierarchical policy tags that classify data - along a common axis. For instance a "data - sensitivity" taxonomy could contain the following - policy tags: + along a common axis. + + For example, a "data sensitivity" taxonomy might + contain the following policy tags: :literal:`\` + PII + Account number + Age + SSN + Zipcode + Financials + Revenue`\ \` - A "data origin" taxonomy could contain the following + A "data origin" taxonomy might contain the following policy tags: :literal:`\` + User data + Employee data + Partner data + Public data`\ \` @@ -424,7 +427,7 @@ async def list_taxonomies( metadata: Sequence[Tuple[str, str]] = (), ) -> pagers.ListTaxonomiesAsyncPager: r"""Lists all taxonomies in a project in a particular - location that the caller has permission to view. + location that you have a permission to view. Args: request (:class:`google.cloud.datacatalog_v1.types.ListTaxonomiesRequest`): @@ -512,7 +515,7 @@ async def get_taxonomy( [GetTaxonomy][google.cloud.datacatalog.v1.PolicyTagManager.GetTaxonomy]. name (:class:`str`): Required. Resource name of the - requested taxonomy. + taxonomy to get. This corresponds to the ``name`` field on the ``request`` instance; if ``request`` is provided, this @@ -526,13 +529,14 @@ async def get_taxonomy( Returns: google.cloud.datacatalog_v1.types.Taxonomy: A taxonomy is a collection of hierarchical policy tags that classify data - along a common axis. For instance a "data - sensitivity" taxonomy could contain the following - policy tags: + along a common axis. + + For example, a "data sensitivity" taxonomy might + contain the following policy tags: :literal:`\` + PII + Account number + Age + SSN + Zipcode + Financials + Revenue`\ \` - A "data origin" taxonomy could contain the following + A "data origin" taxonomy might contain the following policy tags: :literal:`\` + User data + Employee data + Partner data + Public data`\ \` @@ -594,13 +598,13 @@ async def create_policy_tag( parent (:class:`str`): Required. Resource name of the taxonomy that the policy tag will belong - to. + to.

This corresponds to the ``parent`` field on the ``request`` instance; if ``request`` is provided, this should not be set. policy_tag (:class:`google.cloud.datacatalog_v1.types.PolicyTag`): - The policy tag to be created. + The policy tag to create. This corresponds to the ``policy_tag`` field on the ``request`` instance; if ``request`` is provided, this should not be set. @@ -612,14 +616,15 @@ async def create_policy_tag( Returns: google.cloud.datacatalog_v1.types.PolicyTag: - Denotes one policy tag in a taxonomy (e.g. ssn). Policy tags can be defined - in a hierarchy. For example, consider the following - hierarchy: + Denotes one policy tag in a taxonomy, for example, SSN. + + Policy tags can be defined in a hierarchy. For + example: :literal:`\` + Geolocation + LatLong + City + ZipCode`\ \` - Policy tag "Geolocation" contains 3 child policy - tags: "LatLong", "City", and "ZipCode". + Where the "Geolocation" policy tag contains three + children. """ # Create or coerce a protobuf request object. @@ -670,13 +675,12 @@ async def delete_policy_tag( timeout: float = None, metadata: Sequence[Tuple[str, str]] = (), ) -> None: - r"""Deletes a policy tag. This method also deletes: + r"""Deletes a policy tag together with the following: - - all of its descendant policy tags, if any - - the policies associated with the policy tag and its - descendants - - references from BigQuery table schema of the policy tag and - its descendants. + - All of its descendant policy tags, if any + - Policies associated with the policy tag and its descendants + - References from BigQuery table schema of the policy tag and + its descendants Args: request (:class:`google.cloud.datacatalog_v1.types.DeletePolicyTagRequest`): @@ -684,8 +688,9 @@ async def delete_policy_tag( [DeletePolicyTag][google.cloud.datacatalog.v1.PolicyTagManager.DeletePolicyTag]. name (:class:`str`): Required. Resource name of the policy - tag to be deleted. All of its descendant - policy tags will also be deleted. + tag to delete. + Note: All of its descendant policy tags + are also deleted. This corresponds to the ``name`` field on the ``request`` instance; if ``request`` is provided, this @@ -741,18 +746,17 @@ async def update_policy_tag( timeout: float = None, metadata: Sequence[Tuple[str, str]] = (), ) -> policytagmanager.PolicyTag: - r"""Updates a policy tag. This method can update the - policy tag's display name, description, and parent - policy tag. + r"""Updates a policy tag, including its display + name, description, and parent policy tag. Args: request (:class:`google.cloud.datacatalog_v1.types.UpdatePolicyTagRequest`): The request object. Request message for [UpdatePolicyTag][google.cloud.datacatalog.v1.PolicyTagManager.UpdatePolicyTag]. policy_tag (:class:`google.cloud.datacatalog_v1.types.PolicyTag`): - The policy tag to update. Only the description, - display_name, and parent_policy_tag fields can be - updated. + The policy tag to update. You can + update only its description, display + name, and parent policy tag fields. This corresponds to the ``policy_tag`` field on the ``request`` instance; if ``request`` is provided, this @@ -765,14 +769,15 @@ async def update_policy_tag( Returns: google.cloud.datacatalog_v1.types.PolicyTag: - Denotes one policy tag in a taxonomy (e.g. ssn). Policy tags can be defined - in a hierarchy. For example, consider the following - hierarchy: + Denotes one policy tag in a taxonomy, for example, SSN. + + Policy tags can be defined in a hierarchy. For + example: :literal:`\` + Geolocation + LatLong + City + ZipCode`\ \` - Policy tag "Geolocation" contains 3 child policy - tags: "LatLong", "City", and "ZipCode". + Where the "Geolocation" policy tag contains three + children. """ # Create or coerce a protobuf request object. @@ -910,8 +915,8 @@ async def get_policy_tag( The request object. Request message for [GetPolicyTag][google.cloud.datacatalog.v1.PolicyTagManager.GetPolicyTag]. name (:class:`str`): - Required. Resource name of the - requested policy tag. + Required. Resource name of the policy + tag. This corresponds to the ``name`` field on the ``request`` instance; if ``request`` is provided, this @@ -924,14 +929,15 @@ async def get_policy_tag( Returns: google.cloud.datacatalog_v1.types.PolicyTag: - Denotes one policy tag in a taxonomy (e.g. ssn). Policy tags can be defined - in a hierarchy. For example, consider the following - hierarchy: + Denotes one policy tag in a taxonomy, for example, SSN. + + Policy tags can be defined in a hierarchy. For + example: :literal:`\` + Geolocation + LatLong + City + ZipCode`\ \` - Policy tag "Geolocation" contains 3 child policy - tags: "LatLong", "City", and "ZipCode". + Where the "Geolocation" policy tag contains three + children. """ # Create or coerce a protobuf request object. @@ -1189,8 +1195,8 @@ async def test_iam_permissions( timeout: float = None, metadata: Sequence[Tuple[str, str]] = (), ) -> iam_policy_pb2.TestIamPermissionsResponse: - r"""Returns the permissions that a caller has on a - specified policy tag or taxonomy. + r"""Returns your permissions on a specified policy tag or + taxonomy. Args: request (:class:`google.iam.v1.iam_policy_pb2.TestIamPermissionsRequest`): diff --git a/google/cloud/datacatalog_v1/services/policy_tag_manager/client.py b/google/cloud/datacatalog_v1/services/policy_tag_manager/client.py index 3af5da93..2e1d9faf 100644 --- a/google/cloud/datacatalog_v1/services/policy_tag_manager/client.py +++ b/google/cloud/datacatalog_v1/services/policy_tag_manager/client.py @@ -74,7 +74,7 @@ def get_transport_class(cls, label: str = None,) -> Type[PolicyTagManagerTranspo class PolicyTagManagerClient(metaclass=PolicyTagManagerClientMeta): - """Policy Tag Manager API service allows clients to manage their + """Policy Tag Manager API service allows you to manage your policy tags and taxonomies. Policy tags are used to tag BigQuery columns and apply @@ -390,9 +390,9 @@ def create_taxonomy( timeout: float = None, metadata: Sequence[Tuple[str, str]] = (), ) -> policytagmanager.Taxonomy: - r"""Creates a taxonomy in a specified project. The - taxonomy is initially empty, i.e., does not contain - policy tags. + r"""Creates a taxonomy in a specified project. + The taxonomy is initially empty, that is, it doesn't + contain policy tags. Args: request (google.cloud.datacatalog_v1.types.CreateTaxonomyRequest): @@ -407,7 +407,7 @@ def create_taxonomy( on the ``request`` instance; if ``request`` is provided, this should not be set. taxonomy (google.cloud.datacatalog_v1.types.Taxonomy): - The taxonomy to be created. + The taxonomy to create. This corresponds to the ``taxonomy`` field on the ``request`` instance; if ``request`` is provided, this should not be set. @@ -420,13 +420,14 @@ def create_taxonomy( Returns: google.cloud.datacatalog_v1.types.Taxonomy: A taxonomy is a collection of hierarchical policy tags that classify data - along a common axis. For instance a "data - sensitivity" taxonomy could contain the following - policy tags: + along a common axis. + + For example, a "data sensitivity" taxonomy might + contain the following policy tags: :literal:`\` + PII + Account number + Age + SSN + Zipcode + Financials + Revenue`\ \` - A "data origin" taxonomy could contain the following + A "data origin" taxonomy might contain the following policy tags: :literal:`\` + User data + Employee data + Partner data + Public data`\ \` @@ -480,9 +481,9 @@ def delete_taxonomy( timeout: float = None, metadata: Sequence[Tuple[str, str]] = (), ) -> None: - r"""Deletes a taxonomy. This method will also delete all - policy tags in this taxonomy, their associated policies, - and the policy tags references from BigQuery columns. + r"""Deletes a taxonomy, including all policy tags in this + taxonomy, their associated policies, and the policy tags + references from BigQuery columns. Args: request (google.cloud.datacatalog_v1.types.DeleteTaxonomyRequest): @@ -490,8 +491,9 @@ def delete_taxonomy( [DeleteTaxonomy][google.cloud.datacatalog.v1.PolicyTagManager.DeleteTaxonomy]. name (str): Required. Resource name of the - taxonomy to be deleted. All policy tags - in this taxonomy will also be deleted. + taxonomy to delete. + Note: All policy tags in this taxonomy + are also deleted. This corresponds to the ``name`` field on the ``request`` instance; if ``request`` is provided, this @@ -547,17 +549,17 @@ def update_taxonomy( timeout: float = None, metadata: Sequence[Tuple[str, str]] = (), ) -> policytagmanager.Taxonomy: - r"""Updates a taxonomy. This method can update the - taxonomy's display name, description, and activated - policy types. + r"""Updates a taxonomy, including its display name, + description, and activated policy types. Args: request (google.cloud.datacatalog_v1.types.UpdateTaxonomyRequest): The request object. Request message for [UpdateTaxonomy][google.cloud.datacatalog.v1.PolicyTagManager.UpdateTaxonomy]. taxonomy (google.cloud.datacatalog_v1.types.Taxonomy): - The taxonomy to update. Only description, display_name, - and activated policy types can be updated. + The taxonomy to update. You can + update only its description, display + name, and activated policy types. This corresponds to the ``taxonomy`` field on the ``request`` instance; if ``request`` is provided, this @@ -571,13 +573,14 @@ def update_taxonomy( Returns: google.cloud.datacatalog_v1.types.Taxonomy: A taxonomy is a collection of hierarchical policy tags that classify data - along a common axis. For instance a "data - sensitivity" taxonomy could contain the following - policy tags: + along a common axis. + + For example, a "data sensitivity" taxonomy might + contain the following policy tags: :literal:`\` + PII + Account number + Age + SSN + Zipcode + Financials + Revenue`\ \` - A "data origin" taxonomy could contain the following + A "data origin" taxonomy might contain the following policy tags: :literal:`\` + User data + Employee data + Partner data + Public data`\ \` @@ -632,7 +635,7 @@ def list_taxonomies( metadata: Sequence[Tuple[str, str]] = (), ) -> pagers.ListTaxonomiesPager: r"""Lists all taxonomies in a project in a particular - location that the caller has permission to view. + location that you have a permission to view. Args: request (google.cloud.datacatalog_v1.types.ListTaxonomiesRequest): @@ -720,7 +723,7 @@ def get_taxonomy( [GetTaxonomy][google.cloud.datacatalog.v1.PolicyTagManager.GetTaxonomy]. name (str): Required. Resource name of the - requested taxonomy. + taxonomy to get. This corresponds to the ``name`` field on the ``request`` instance; if ``request`` is provided, this @@ -734,13 +737,14 @@ def get_taxonomy( Returns: google.cloud.datacatalog_v1.types.Taxonomy: A taxonomy is a collection of hierarchical policy tags that classify data - along a common axis. For instance a "data - sensitivity" taxonomy could contain the following - policy tags: + along a common axis. + + For example, a "data sensitivity" taxonomy might + contain the following policy tags: :literal:`\` + PII + Account number + Age + SSN + Zipcode + Financials + Revenue`\ \` - A "data origin" taxonomy could contain the following + A "data origin" taxonomy might contain the following policy tags: :literal:`\` + User data + Employee data + Partner data + Public data`\ \` @@ -802,13 +806,13 @@ def create_policy_tag( parent (str): Required. Resource name of the taxonomy that the policy tag will belong - to. + to.

This corresponds to the ``parent`` field on the ``request`` instance; if ``request`` is provided, this should not be set. policy_tag (google.cloud.datacatalog_v1.types.PolicyTag): - The policy tag to be created. + The policy tag to create. This corresponds to the ``policy_tag`` field on the ``request`` instance; if ``request`` is provided, this should not be set. @@ -820,14 +824,15 @@ def create_policy_tag( Returns: google.cloud.datacatalog_v1.types.PolicyTag: - Denotes one policy tag in a taxonomy (e.g. ssn). Policy tags can be defined - in a hierarchy. For example, consider the following - hierarchy: + Denotes one policy tag in a taxonomy, for example, SSN. + + Policy tags can be defined in a hierarchy. For + example: :literal:`\` + Geolocation + LatLong + City + ZipCode`\ \` - Policy tag "Geolocation" contains 3 child policy - tags: "LatLong", "City", and "ZipCode". + Where the "Geolocation" policy tag contains three + children. """ # Create or coerce a protobuf request object. @@ -878,13 +883,12 @@ def delete_policy_tag( timeout: float = None, metadata: Sequence[Tuple[str, str]] = (), ) -> None: - r"""Deletes a policy tag. This method also deletes: + r"""Deletes a policy tag together with the following: - - all of its descendant policy tags, if any - - the policies associated with the policy tag and its - descendants - - references from BigQuery table schema of the policy tag and - its descendants. + - All of its descendant policy tags, if any + - Policies associated with the policy tag and its descendants + - References from BigQuery table schema of the policy tag and + its descendants Args: request (google.cloud.datacatalog_v1.types.DeletePolicyTagRequest): @@ -892,8 +896,9 @@ def delete_policy_tag( [DeletePolicyTag][google.cloud.datacatalog.v1.PolicyTagManager.DeletePolicyTag]. name (str): Required. Resource name of the policy - tag to be deleted. All of its descendant - policy tags will also be deleted. + tag to delete. + Note: All of its descendant policy tags + are also deleted. This corresponds to the ``name`` field on the ``request`` instance; if ``request`` is provided, this @@ -949,18 +954,17 @@ def update_policy_tag( timeout: float = None, metadata: Sequence[Tuple[str, str]] = (), ) -> policytagmanager.PolicyTag: - r"""Updates a policy tag. This method can update the - policy tag's display name, description, and parent - policy tag. + r"""Updates a policy tag, including its display + name, description, and parent policy tag. Args: request (google.cloud.datacatalog_v1.types.UpdatePolicyTagRequest): The request object. Request message for [UpdatePolicyTag][google.cloud.datacatalog.v1.PolicyTagManager.UpdatePolicyTag]. policy_tag (google.cloud.datacatalog_v1.types.PolicyTag): - The policy tag to update. Only the description, - display_name, and parent_policy_tag fields can be - updated. + The policy tag to update. You can + update only its description, display + name, and parent policy tag fields. This corresponds to the ``policy_tag`` field on the ``request`` instance; if ``request`` is provided, this @@ -973,14 +977,15 @@ def update_policy_tag( Returns: google.cloud.datacatalog_v1.types.PolicyTag: - Denotes one policy tag in a taxonomy (e.g. ssn). Policy tags can be defined - in a hierarchy. For example, consider the following - hierarchy: + Denotes one policy tag in a taxonomy, for example, SSN. + + Policy tags can be defined in a hierarchy. For + example: :literal:`\` + Geolocation + LatLong + City + ZipCode`\ \` - Policy tag "Geolocation" contains 3 child policy - tags: "LatLong", "City", and "ZipCode". + Where the "Geolocation" policy tag contains three + children. """ # Create or coerce a protobuf request object. @@ -1118,8 +1123,8 @@ def get_policy_tag( The request object. Request message for [GetPolicyTag][google.cloud.datacatalog.v1.PolicyTagManager.GetPolicyTag]. name (str): - Required. Resource name of the - requested policy tag. + Required. Resource name of the policy + tag. This corresponds to the ``name`` field on the ``request`` instance; if ``request`` is provided, this @@ -1132,14 +1137,15 @@ def get_policy_tag( Returns: google.cloud.datacatalog_v1.types.PolicyTag: - Denotes one policy tag in a taxonomy (e.g. ssn). Policy tags can be defined - in a hierarchy. For example, consider the following - hierarchy: + Denotes one policy tag in a taxonomy, for example, SSN. + + Policy tags can be defined in a hierarchy. For + example: :literal:`\` + Geolocation + LatLong + City + ZipCode`\ \` - Policy tag "Geolocation" contains 3 child policy - tags: "LatLong", "City", and "ZipCode". + Where the "Geolocation" policy tag contains three + children. """ # Create or coerce a protobuf request object. @@ -1395,8 +1401,8 @@ def test_iam_permissions( timeout: float = None, metadata: Sequence[Tuple[str, str]] = (), ) -> iam_policy_pb2.TestIamPermissionsResponse: - r"""Returns the permissions that a caller has on a - specified policy tag or taxonomy. + r"""Returns your permissions on a specified policy tag or + taxonomy. Args: request (google.iam.v1.iam_policy_pb2.TestIamPermissionsRequest): diff --git a/google/cloud/datacatalog_v1/services/policy_tag_manager/transports/grpc.py b/google/cloud/datacatalog_v1/services/policy_tag_manager/transports/grpc.py index c2455a1f..521d5fb6 100644 --- a/google/cloud/datacatalog_v1/services/policy_tag_manager/transports/grpc.py +++ b/google/cloud/datacatalog_v1/services/policy_tag_manager/transports/grpc.py @@ -34,7 +34,7 @@ class PolicyTagManagerGrpcTransport(PolicyTagManagerTransport): """gRPC backend transport for PolicyTagManager. - Policy Tag Manager API service allows clients to manage their + Policy Tag Manager API service allows you to manage your policy tags and taxonomies. Policy tags are used to tag BigQuery columns and apply @@ -239,9 +239,9 @@ def create_taxonomy( ) -> Callable[[policytagmanager.CreateTaxonomyRequest], policytagmanager.Taxonomy]: r"""Return a callable for the create taxonomy method over gRPC. - Creates a taxonomy in a specified project. The - taxonomy is initially empty, i.e., does not contain - policy tags. + Creates a taxonomy in a specified project. + The taxonomy is initially empty, that is, it doesn't + contain policy tags. Returns: Callable[[~.CreateTaxonomyRequest], @@ -267,9 +267,9 @@ def delete_taxonomy( ) -> Callable[[policytagmanager.DeleteTaxonomyRequest], empty_pb2.Empty]: r"""Return a callable for the delete taxonomy method over gRPC. - Deletes a taxonomy. This method will also delete all - policy tags in this taxonomy, their associated policies, - and the policy tags references from BigQuery columns. + Deletes a taxonomy, including all policy tags in this + taxonomy, their associated policies, and the policy tags + references from BigQuery columns. Returns: Callable[[~.DeleteTaxonomyRequest], @@ -295,9 +295,8 @@ def update_taxonomy( ) -> Callable[[policytagmanager.UpdateTaxonomyRequest], policytagmanager.Taxonomy]: r"""Return a callable for the update taxonomy method over gRPC. - Updates a taxonomy. This method can update the - taxonomy's display name, description, and activated - policy types. + Updates a taxonomy, including its display name, + description, and activated policy types. Returns: Callable[[~.UpdateTaxonomyRequest], @@ -327,7 +326,7 @@ def list_taxonomies( r"""Return a callable for the list taxonomies method over gRPC. Lists all taxonomies in a project in a particular - location that the caller has permission to view. + location that you have a permission to view. Returns: Callable[[~.ListTaxonomiesRequest], @@ -407,13 +406,12 @@ def delete_policy_tag( ) -> Callable[[policytagmanager.DeletePolicyTagRequest], empty_pb2.Empty]: r"""Return a callable for the delete policy tag method over gRPC. - Deletes a policy tag. This method also deletes: + Deletes a policy tag together with the following: - - all of its descendant policy tags, if any - - the policies associated with the policy tag and its - descendants - - references from BigQuery table schema of the policy tag and - its descendants. + - All of its descendant policy tags, if any + - Policies associated with the policy tag and its descendants + - References from BigQuery table schema of the policy tag and + its descendants Returns: Callable[[~.DeletePolicyTagRequest], @@ -441,9 +439,8 @@ def update_policy_tag( ]: r"""Return a callable for the update policy tag method over gRPC. - Updates a policy tag. This method can update the - policy tag's display name, description, and parent - policy tag. + Updates a policy tag, including its display + name, description, and parent policy tag. Returns: Callable[[~.UpdatePolicyTagRequest], @@ -579,8 +576,8 @@ def test_iam_permissions( ]: r"""Return a callable for the test iam permissions method over gRPC. - Returns the permissions that a caller has on a - specified policy tag or taxonomy. + Returns your permissions on a specified policy tag or + taxonomy. Returns: Callable[[~.TestIamPermissionsRequest], diff --git a/google/cloud/datacatalog_v1/services/policy_tag_manager/transports/grpc_asyncio.py b/google/cloud/datacatalog_v1/services/policy_tag_manager/transports/grpc_asyncio.py index 3c379dd4..902b2432 100644 --- a/google/cloud/datacatalog_v1/services/policy_tag_manager/transports/grpc_asyncio.py +++ b/google/cloud/datacatalog_v1/services/policy_tag_manager/transports/grpc_asyncio.py @@ -36,7 +36,7 @@ class PolicyTagManagerGrpcAsyncIOTransport(PolicyTagManagerTransport): """gRPC AsyncIO backend transport for PolicyTagManager. - Policy Tag Manager API service allows clients to manage their + Policy Tag Manager API service allows you to manage your policy tags and taxonomies. Policy tags are used to tag BigQuery columns and apply @@ -244,9 +244,9 @@ def create_taxonomy( ]: r"""Return a callable for the create taxonomy method over gRPC. - Creates a taxonomy in a specified project. The - taxonomy is initially empty, i.e., does not contain - policy tags. + Creates a taxonomy in a specified project. + The taxonomy is initially empty, that is, it doesn't + contain policy tags. Returns: Callable[[~.CreateTaxonomyRequest], @@ -272,9 +272,9 @@ def delete_taxonomy( ) -> Callable[[policytagmanager.DeleteTaxonomyRequest], Awaitable[empty_pb2.Empty]]: r"""Return a callable for the delete taxonomy method over gRPC. - Deletes a taxonomy. This method will also delete all - policy tags in this taxonomy, their associated policies, - and the policy tags references from BigQuery columns. + Deletes a taxonomy, including all policy tags in this + taxonomy, their associated policies, and the policy tags + references from BigQuery columns. Returns: Callable[[~.DeleteTaxonomyRequest], @@ -302,9 +302,8 @@ def update_taxonomy( ]: r"""Return a callable for the update taxonomy method over gRPC. - Updates a taxonomy. This method can update the - taxonomy's display name, description, and activated - policy types. + Updates a taxonomy, including its display name, + description, and activated policy types. Returns: Callable[[~.UpdateTaxonomyRequest], @@ -334,7 +333,7 @@ def list_taxonomies( r"""Return a callable for the list taxonomies method over gRPC. Lists all taxonomies in a project in a particular - location that the caller has permission to view. + location that you have a permission to view. Returns: Callable[[~.ListTaxonomiesRequest], @@ -418,13 +417,12 @@ def delete_policy_tag( ]: r"""Return a callable for the delete policy tag method over gRPC. - Deletes a policy tag. This method also deletes: + Deletes a policy tag together with the following: - - all of its descendant policy tags, if any - - the policies associated with the policy tag and its - descendants - - references from BigQuery table schema of the policy tag and - its descendants. + - All of its descendant policy tags, if any + - Policies associated with the policy tag and its descendants + - References from BigQuery table schema of the policy tag and + its descendants Returns: Callable[[~.DeletePolicyTagRequest], @@ -452,9 +450,8 @@ def update_policy_tag( ]: r"""Return a callable for the update policy tag method over gRPC. - Updates a policy tag. This method can update the - policy tag's display name, description, and parent - policy tag. + Updates a policy tag, including its display + name, description, and parent policy tag. Returns: Callable[[~.UpdatePolicyTagRequest], @@ -592,8 +589,8 @@ def test_iam_permissions( ]: r"""Return a callable for the test iam permissions method over gRPC. - Returns the permissions that a caller has on a - specified policy tag or taxonomy. + Returns your permissions on a specified policy tag or + taxonomy. Returns: Callable[[~.TestIamPermissionsRequest], diff --git a/google/cloud/datacatalog_v1/services/policy_tag_manager_serialization/async_client.py b/google/cloud/datacatalog_v1/services/policy_tag_manager_serialization/async_client.py index 99f190e8..951e1086 100644 --- a/google/cloud/datacatalog_v1/services/policy_tag_manager_serialization/async_client.py +++ b/google/cloud/datacatalog_v1/services/policy_tag_manager_serialization/async_client.py @@ -28,15 +28,17 @@ from google.cloud.datacatalog_v1.types import policytagmanager from google.cloud.datacatalog_v1.types import policytagmanagerserialization +from google.cloud.datacatalog_v1.types import timestamps from .transports.base import PolicyTagManagerSerializationTransport, DEFAULT_CLIENT_INFO from .transports.grpc_asyncio import PolicyTagManagerSerializationGrpcAsyncIOTransport from .client import PolicyTagManagerSerializationClient class PolicyTagManagerSerializationAsyncClient: - """Policy Tag Manager serialization API service allows clients - to manipulate their policy tags and taxonomies in serialized - format, where taxonomy is a hierarchical group of policy tags. + """Policy Tag Manager Serialization API service allows you to + manipulate your policy tags and taxonomies in a serialized + format. + Taxonomy is a hierarchical group of policy tags. """ _client: PolicyTagManagerSerializationClient @@ -173,6 +175,77 @@ def __init__( client_info=client_info, ) + async def replace_taxonomy( + self, + request: policytagmanagerserialization.ReplaceTaxonomyRequest = None, + *, + retry: retries.Retry = gapic_v1.method.DEFAULT, + timeout: float = None, + metadata: Sequence[Tuple[str, str]] = (), + ) -> policytagmanager.Taxonomy: + r"""Replaces (updates) a taxonomy and all its policy tags. + + The taxonomy and its entire hierarchy of policy tags must be + represented literally by ``SerializedTaxonomy`` and the nested + ``SerializedPolicyTag`` messages. + + This operation automatically does the following: + + - Deletes the existing policy tags that are missing from the + ``SerializedPolicyTag``. + - Creates policy tags that don't have resource names. They are + considered new. + - Updates policy tags with valid resources names accordingly. + + Args: + request (:class:`google.cloud.datacatalog_v1.types.ReplaceTaxonomyRequest`): + The request object. Request message for + [ReplaceTaxonomy][google.cloud.datacatalog.v1.PolicyTagManagerSerialization.ReplaceTaxonomy]. + retry (google.api_core.retry.Retry): Designation of what errors, if any, + should be retried. + timeout (float): The timeout for this request. + metadata (Sequence[Tuple[str, str]]): Strings which should be + sent along with the request as metadata. + + Returns: + google.cloud.datacatalog_v1.types.Taxonomy: + A taxonomy is a collection of hierarchical policy tags that classify data + along a common axis. + + For example, a "data sensitivity" taxonomy might + contain the following policy tags: + + :literal:`\` + PII + Account number + Age + SSN + Zipcode + Financials + Revenue`\ \` + + A "data origin" taxonomy might contain the following + policy tags: + + :literal:`\` + User data + Employee data + Partner data + Public data`\ \` + + """ + # Create or coerce a protobuf request object. + request = policytagmanagerserialization.ReplaceTaxonomyRequest(request) + + # Wrap the RPC method; this adds retry and timeout information, + # and friendly error handling. + rpc = gapic_v1.method_async.wrap_method( + self._client._transport.replace_taxonomy, + default_timeout=None, + client_info=DEFAULT_CLIENT_INFO, + ) + + # Certain fields should be provided within the metadata header; + # add these here. + metadata = tuple(metadata) + ( + gapic_v1.routing_header.to_grpc_metadata((("name", request.name),)), + ) + + # Send the request. + response = await rpc(request, retry=retry, timeout=timeout, metadata=metadata,) + + # Done; return the response. + return response + async def import_taxonomies( self, request: policytagmanagerserialization.ImportTaxonomiesRequest = None, @@ -182,16 +255,13 @@ async def import_taxonomies( metadata: Sequence[Tuple[str, str]] = (), ) -> policytagmanagerserialization.ImportTaxonomiesResponse: r"""Creates new taxonomies (including their policy tags) - by importing from inlined source or cross-regional - source. New taxonomies will be created in a given parent - project. - - If using the cross-regional source, a new taxonomy is - created by copying from a source in another region. + in a given project by importing from inlined or cross- + regional sources. + For a cross-regional source, new taxonomies are created + by copying from a source in another region. - If using the inlined source, this method provides a way - to bulk create taxonomies and policy tags using nested - proto structure. + For an inlined source, taxonomies and policy tags are + created in bulk using nested protocol buffer structures. Args: request (:class:`google.cloud.datacatalog_v1.types.ImportTaxonomiesRequest`): @@ -240,13 +310,13 @@ async def export_taxonomies( timeout: float = None, metadata: Sequence[Tuple[str, str]] = (), ) -> policytagmanagerserialization.ExportTaxonomiesResponse: - r"""Exports taxonomies as the requested type and returns - the taxonomies including their policy tags. The - requested taxonomies must belong to one project. + r"""Exports taxonomies in the requested type and returns them, + including their policy tags. The requested taxonomies must + belong to the same project. - SerializedTaxonomy protos with nested policy tags that - are generated by this method can be used as input for - future ImportTaxonomies calls. + This method generates ``SerializedTaxonomy`` protocol buffers + with nested policy tags that can be used as input for + ``ImportTaxonomies`` calls. Args: request (:class:`google.cloud.datacatalog_v1.types.ExportTaxonomiesRequest`): diff --git a/google/cloud/datacatalog_v1/services/policy_tag_manager_serialization/client.py b/google/cloud/datacatalog_v1/services/policy_tag_manager_serialization/client.py index 37b72a56..382221e7 100644 --- a/google/cloud/datacatalog_v1/services/policy_tag_manager_serialization/client.py +++ b/google/cloud/datacatalog_v1/services/policy_tag_manager_serialization/client.py @@ -32,6 +32,7 @@ from google.cloud.datacatalog_v1.types import policytagmanager from google.cloud.datacatalog_v1.types import policytagmanagerserialization +from google.cloud.datacatalog_v1.types import timestamps from .transports.base import PolicyTagManagerSerializationTransport, DEFAULT_CLIENT_INFO from .transports.grpc import PolicyTagManagerSerializationGrpcTransport from .transports.grpc_asyncio import PolicyTagManagerSerializationGrpcAsyncIOTransport @@ -77,9 +78,10 @@ def get_transport_class( class PolicyTagManagerSerializationClient( metaclass=PolicyTagManagerSerializationClientMeta ): - """Policy Tag Manager serialization API service allows clients - to manipulate their policy tags and taxonomies in serialized - format, where taxonomy is a hierarchical group of policy tags. + """Policy Tag Manager Serialization API service allows you to + manipulate your policy tags and taxonomies in a serialized + format. + Taxonomy is a hierarchical group of policy tags. """ @staticmethod @@ -359,6 +361,80 @@ def __init__( ), ) + def replace_taxonomy( + self, + request: policytagmanagerserialization.ReplaceTaxonomyRequest = None, + *, + retry: retries.Retry = gapic_v1.method.DEFAULT, + timeout: float = None, + metadata: Sequence[Tuple[str, str]] = (), + ) -> policytagmanager.Taxonomy: + r"""Replaces (updates) a taxonomy and all its policy tags. + + The taxonomy and its entire hierarchy of policy tags must be + represented literally by ``SerializedTaxonomy`` and the nested + ``SerializedPolicyTag`` messages. + + This operation automatically does the following: + + - Deletes the existing policy tags that are missing from the + ``SerializedPolicyTag``. + - Creates policy tags that don't have resource names. They are + considered new. + - Updates policy tags with valid resources names accordingly. + + Args: + request (google.cloud.datacatalog_v1.types.ReplaceTaxonomyRequest): + The request object. Request message for + [ReplaceTaxonomy][google.cloud.datacatalog.v1.PolicyTagManagerSerialization.ReplaceTaxonomy]. + retry (google.api_core.retry.Retry): Designation of what errors, if any, + should be retried. + timeout (float): The timeout for this request. + metadata (Sequence[Tuple[str, str]]): Strings which should be + sent along with the request as metadata. + + Returns: + google.cloud.datacatalog_v1.types.Taxonomy: + A taxonomy is a collection of hierarchical policy tags that classify data + along a common axis. + + For example, a "data sensitivity" taxonomy might + contain the following policy tags: + + :literal:`\` + PII + Account number + Age + SSN + Zipcode + Financials + Revenue`\ \` + + A "data origin" taxonomy might contain the following + policy tags: + + :literal:`\` + User data + Employee data + Partner data + Public data`\ \` + + """ + # Create or coerce a protobuf request object. + # Minor optimization to avoid making a copy if the user passes + # in a policytagmanagerserialization.ReplaceTaxonomyRequest. + # There's no risk of modifying the input as we've already verified + # there are no flattened fields. + if not isinstance( + request, policytagmanagerserialization.ReplaceTaxonomyRequest + ): + request = policytagmanagerserialization.ReplaceTaxonomyRequest(request) + + # Wrap the RPC method; this adds retry and timeout information, + # and friendly error handling. + rpc = self._transport._wrapped_methods[self._transport.replace_taxonomy] + + # Certain fields should be provided within the metadata header; + # add these here. + metadata = tuple(metadata) + ( + gapic_v1.routing_header.to_grpc_metadata((("name", request.name),)), + ) + + # Send the request. + response = rpc(request, retry=retry, timeout=timeout, metadata=metadata,) + + # Done; return the response. + return response + def import_taxonomies( self, request: policytagmanagerserialization.ImportTaxonomiesRequest = None, @@ -368,16 +444,13 @@ def import_taxonomies( metadata: Sequence[Tuple[str, str]] = (), ) -> policytagmanagerserialization.ImportTaxonomiesResponse: r"""Creates new taxonomies (including their policy tags) - by importing from inlined source or cross-regional - source. New taxonomies will be created in a given parent - project. - - If using the cross-regional source, a new taxonomy is - created by copying from a source in another region. + in a given project by importing from inlined or cross- + regional sources. + For a cross-regional source, new taxonomies are created + by copying from a source in another region. - If using the inlined source, this method provides a way - to bulk create taxonomies and policy tags using nested - proto structure. + For an inlined source, taxonomies and policy tags are + created in bulk using nested protocol buffer structures. Args: request (google.cloud.datacatalog_v1.types.ImportTaxonomiesRequest): @@ -429,13 +502,13 @@ def export_taxonomies( timeout: float = None, metadata: Sequence[Tuple[str, str]] = (), ) -> policytagmanagerserialization.ExportTaxonomiesResponse: - r"""Exports taxonomies as the requested type and returns - the taxonomies including their policy tags. The - requested taxonomies must belong to one project. + r"""Exports taxonomies in the requested type and returns them, + including their policy tags. The requested taxonomies must + belong to the same project. - SerializedTaxonomy protos with nested policy tags that - are generated by this method can be used as input for - future ImportTaxonomies calls. + This method generates ``SerializedTaxonomy`` protocol buffers + with nested policy tags that can be used as input for + ``ImportTaxonomies`` calls. Args: request (google.cloud.datacatalog_v1.types.ExportTaxonomiesRequest): diff --git a/google/cloud/datacatalog_v1/services/policy_tag_manager_serialization/transports/base.py b/google/cloud/datacatalog_v1/services/policy_tag_manager_serialization/transports/base.py index 753c3b8e..199f0b95 100644 --- a/google/cloud/datacatalog_v1/services/policy_tag_manager_serialization/transports/base.py +++ b/google/cloud/datacatalog_v1/services/policy_tag_manager_serialization/transports/base.py @@ -26,6 +26,7 @@ from google.auth import credentials as ga_credentials # type: ignore from google.oauth2 import service_account # type: ignore +from google.cloud.datacatalog_v1.types import policytagmanager from google.cloud.datacatalog_v1.types import policytagmanagerserialization try: @@ -154,6 +155,9 @@ def _get_scopes_kwargs( def _prep_wrapped_messages(self, client_info): # Precompute the wrapped methods. self._wrapped_methods = { + self.replace_taxonomy: gapic_v1.method.wrap_method( + self.replace_taxonomy, default_timeout=None, client_info=client_info, + ), self.import_taxonomies: gapic_v1.method.wrap_method( self.import_taxonomies, default_timeout=None, client_info=client_info, ), @@ -162,6 +166,15 @@ def _prep_wrapped_messages(self, client_info): ), } + @property + def replace_taxonomy( + self, + ) -> Callable[ + [policytagmanagerserialization.ReplaceTaxonomyRequest], + Union[policytagmanager.Taxonomy, Awaitable[policytagmanager.Taxonomy]], + ]: + raise NotImplementedError() + @property def import_taxonomies( self, diff --git a/google/cloud/datacatalog_v1/services/policy_tag_manager_serialization/transports/grpc.py b/google/cloud/datacatalog_v1/services/policy_tag_manager_serialization/transports/grpc.py index d2b556d7..f88e0c6d 100644 --- a/google/cloud/datacatalog_v1/services/policy_tag_manager_serialization/transports/grpc.py +++ b/google/cloud/datacatalog_v1/services/policy_tag_manager_serialization/transports/grpc.py @@ -24,6 +24,7 @@ import grpc # type: ignore +from google.cloud.datacatalog_v1.types import policytagmanager from google.cloud.datacatalog_v1.types import policytagmanagerserialization from .base import PolicyTagManagerSerializationTransport, DEFAULT_CLIENT_INFO @@ -33,9 +34,10 @@ class PolicyTagManagerSerializationGrpcTransport( ): """gRPC backend transport for PolicyTagManagerSerialization. - Policy Tag Manager serialization API service allows clients - to manipulate their policy tags and taxonomies in serialized - format, where taxonomy is a hierarchical group of policy tags. + Policy Tag Manager Serialization API service allows you to + manipulate your policy tags and taxonomies in a serialized + format. + Taxonomy is a hierarchical group of policy tags. This class defines the same methods as the primary client, so the primary client can load the underlying transport implementation @@ -229,6 +231,47 @@ def grpc_channel(self) -> grpc.Channel: """ return self._grpc_channel + @property + def replace_taxonomy( + self, + ) -> Callable[ + [policytagmanagerserialization.ReplaceTaxonomyRequest], + policytagmanager.Taxonomy, + ]: + r"""Return a callable for the replace taxonomy method over gRPC. + + Replaces (updates) a taxonomy and all its policy tags. + + The taxonomy and its entire hierarchy of policy tags must be + represented literally by ``SerializedTaxonomy`` and the nested + ``SerializedPolicyTag`` messages. + + This operation automatically does the following: + + - Deletes the existing policy tags that are missing from the + ``SerializedPolicyTag``. + - Creates policy tags that don't have resource names. They are + considered new. + - Updates policy tags with valid resources names accordingly. + + Returns: + Callable[[~.ReplaceTaxonomyRequest], + ~.Taxonomy]: + A function that, when called, will call the underlying RPC + on the server. + """ + # Generate a "stub function" on-the-fly which will actually make + # the request. + # gRPC handles serialization and deserialization, so we just need + # to pass in the functions for each. + if "replace_taxonomy" not in self._stubs: + self._stubs["replace_taxonomy"] = self.grpc_channel.unary_unary( + "/google.cloud.datacatalog.v1.PolicyTagManagerSerialization/ReplaceTaxonomy", + request_serializer=policytagmanagerserialization.ReplaceTaxonomyRequest.serialize, + response_deserializer=policytagmanager.Taxonomy.deserialize, + ) + return self._stubs["replace_taxonomy"] + @property def import_taxonomies( self, @@ -239,16 +282,13 @@ def import_taxonomies( r"""Return a callable for the import taxonomies method over gRPC. Creates new taxonomies (including their policy tags) - by importing from inlined source or cross-regional - source. New taxonomies will be created in a given parent - project. - - If using the cross-regional source, a new taxonomy is - created by copying from a source in another region. + in a given project by importing from inlined or cross- + regional sources. + For a cross-regional source, new taxonomies are created + by copying from a source in another region. - If using the inlined source, this method provides a way - to bulk create taxonomies and policy tags using nested - proto structure. + For an inlined source, taxonomies and policy tags are + created in bulk using nested protocol buffer structures. Returns: Callable[[~.ImportTaxonomiesRequest], @@ -277,13 +317,13 @@ def export_taxonomies( ]: r"""Return a callable for the export taxonomies method over gRPC. - Exports taxonomies as the requested type and returns - the taxonomies including their policy tags. The - requested taxonomies must belong to one project. + Exports taxonomies in the requested type and returns them, + including their policy tags. The requested taxonomies must + belong to the same project. - SerializedTaxonomy protos with nested policy tags that - are generated by this method can be used as input for - future ImportTaxonomies calls. + This method generates ``SerializedTaxonomy`` protocol buffers + with nested policy tags that can be used as input for + ``ImportTaxonomies`` calls. Returns: Callable[[~.ExportTaxonomiesRequest], diff --git a/google/cloud/datacatalog_v1/services/policy_tag_manager_serialization/transports/grpc_asyncio.py b/google/cloud/datacatalog_v1/services/policy_tag_manager_serialization/transports/grpc_asyncio.py index 39b42954..f04d2483 100644 --- a/google/cloud/datacatalog_v1/services/policy_tag_manager_serialization/transports/grpc_asyncio.py +++ b/google/cloud/datacatalog_v1/services/policy_tag_manager_serialization/transports/grpc_asyncio.py @@ -25,6 +25,7 @@ import grpc # type: ignore from grpc.experimental import aio # type: ignore +from google.cloud.datacatalog_v1.types import policytagmanager from google.cloud.datacatalog_v1.types import policytagmanagerserialization from .base import PolicyTagManagerSerializationTransport, DEFAULT_CLIENT_INFO from .grpc import PolicyTagManagerSerializationGrpcTransport @@ -35,9 +36,10 @@ class PolicyTagManagerSerializationGrpcAsyncIOTransport( ): """gRPC AsyncIO backend transport for PolicyTagManagerSerialization. - Policy Tag Manager serialization API service allows clients - to manipulate their policy tags and taxonomies in serialized - format, where taxonomy is a hierarchical group of policy tags. + Policy Tag Manager Serialization API service allows you to + manipulate your policy tags and taxonomies in a serialized + format. + Taxonomy is a hierarchical group of policy tags. This class defines the same methods as the primary client, so the primary client can load the underlying transport implementation @@ -232,6 +234,47 @@ def grpc_channel(self) -> aio.Channel: # Return the channel from cache. return self._grpc_channel + @property + def replace_taxonomy( + self, + ) -> Callable[ + [policytagmanagerserialization.ReplaceTaxonomyRequest], + Awaitable[policytagmanager.Taxonomy], + ]: + r"""Return a callable for the replace taxonomy method over gRPC. + + Replaces (updates) a taxonomy and all its policy tags. + + The taxonomy and its entire hierarchy of policy tags must be + represented literally by ``SerializedTaxonomy`` and the nested + ``SerializedPolicyTag`` messages. + + This operation automatically does the following: + + - Deletes the existing policy tags that are missing from the + ``SerializedPolicyTag``. + - Creates policy tags that don't have resource names. They are + considered new. + - Updates policy tags with valid resources names accordingly. + + Returns: + Callable[[~.ReplaceTaxonomyRequest], + Awaitable[~.Taxonomy]]: + A function that, when called, will call the underlying RPC + on the server. + """ + # Generate a "stub function" on-the-fly which will actually make + # the request. + # gRPC handles serialization and deserialization, so we just need + # to pass in the functions for each. + if "replace_taxonomy" not in self._stubs: + self._stubs["replace_taxonomy"] = self.grpc_channel.unary_unary( + "/google.cloud.datacatalog.v1.PolicyTagManagerSerialization/ReplaceTaxonomy", + request_serializer=policytagmanagerserialization.ReplaceTaxonomyRequest.serialize, + response_deserializer=policytagmanager.Taxonomy.deserialize, + ) + return self._stubs["replace_taxonomy"] + @property def import_taxonomies( self, @@ -242,16 +285,13 @@ def import_taxonomies( r"""Return a callable for the import taxonomies method over gRPC. Creates new taxonomies (including their policy tags) - by importing from inlined source or cross-regional - source. New taxonomies will be created in a given parent - project. - - If using the cross-regional source, a new taxonomy is - created by copying from a source in another region. + in a given project by importing from inlined or cross- + regional sources. + For a cross-regional source, new taxonomies are created + by copying from a source in another region. - If using the inlined source, this method provides a way - to bulk create taxonomies and policy tags using nested - proto structure. + For an inlined source, taxonomies and policy tags are + created in bulk using nested protocol buffer structures. Returns: Callable[[~.ImportTaxonomiesRequest], @@ -280,13 +320,13 @@ def export_taxonomies( ]: r"""Return a callable for the export taxonomies method over gRPC. - Exports taxonomies as the requested type and returns - the taxonomies including their policy tags. The - requested taxonomies must belong to one project. + Exports taxonomies in the requested type and returns them, + including their policy tags. The requested taxonomies must + belong to the same project. - SerializedTaxonomy protos with nested policy tags that - are generated by this method can be used as input for - future ImportTaxonomies calls. + This method generates ``SerializedTaxonomy`` protocol buffers + with nested policy tags that can be used as input for + ``ImportTaxonomies`` calls. Returns: Callable[[~.ExportTaxonomiesRequest], diff --git a/google/cloud/datacatalog_v1/types/__init__.py b/google/cloud/datacatalog_v1/types/__init__.py index ef3be71a..79dd1780 100644 --- a/google/cloud/datacatalog_v1/types/__init__.py +++ b/google/cloud/datacatalog_v1/types/__init__.py @@ -13,6 +13,11 @@ # See the License for the specific language governing permissions and # limitations under the License. # +from .bigquery import ( + BigQueryConnectionSpec, + BigQueryRoutineSpec, + CloudSqlBigQueryConnectionSpec, +) from .data_source import DataSource from .datacatalog import ( CreateEntryGroupRequest, @@ -21,6 +26,7 @@ CreateTagTemplateFieldRequest, CreateTagTemplateRequest, DatabaseTableSpec, + DataSourceConnectionSpec, DeleteEntryGroupRequest, DeleteEntryRequest, DeleteTagRequest, @@ -40,6 +46,7 @@ LookupEntryRequest, RenameTagTemplateFieldEnumValueRequest, RenameTagTemplateFieldRequest, + RoutineSpec, SearchCatalogRequest, SearchCatalogResponse, UpdateEntryGroupRequest, @@ -76,6 +83,7 @@ ImportTaxonomiesRequest, ImportTaxonomiesResponse, InlineSource, + ReplaceTaxonomyRequest, SerializedPolicyTag, SerializedTaxonomy, ) @@ -102,8 +110,15 @@ TagTemplateField, ) from .timestamps import SystemTimestamps +from .usage import ( + UsageSignal, + UsageStats, +) __all__ = ( + "BigQueryConnectionSpec", + "BigQueryRoutineSpec", + "CloudSqlBigQueryConnectionSpec", "IntegratedSystem", "DataSource", "CreateEntryGroupRequest", @@ -112,6 +127,7 @@ "CreateTagTemplateFieldRequest", "CreateTagTemplateRequest", "DatabaseTableSpec", + "DataSourceConnectionSpec", "DeleteEntryGroupRequest", "DeleteEntryRequest", "DeleteTagRequest", @@ -131,6 +147,7 @@ "LookupEntryRequest", "RenameTagTemplateFieldEnumValueRequest", "RenameTagTemplateFieldRequest", + "RoutineSpec", "SearchCatalogRequest", "SearchCatalogResponse", "UpdateEntryGroupRequest", @@ -161,6 +178,7 @@ "ImportTaxonomiesRequest", "ImportTaxonomiesResponse", "InlineSource", + "ReplaceTaxonomyRequest", "SerializedPolicyTag", "SerializedTaxonomy", "ColumnSchema", @@ -178,4 +196,6 @@ "TagTemplate", "TagTemplateField", "SystemTimestamps", + "UsageSignal", + "UsageStats", ) diff --git a/google/cloud/datacatalog_v1/types/bigquery.py b/google/cloud/datacatalog_v1/types/bigquery.py new file mode 100644 index 00000000..84820400 --- /dev/null +++ b/google/cloud/datacatalog_v1/types/bigquery.py @@ -0,0 +1,92 @@ +# -*- coding: utf-8 -*- +# Copyright 2020 Google LLC +# +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. +# +import proto # type: ignore + + +__protobuf__ = proto.module( + package="google.cloud.datacatalog.v1", + manifest={ + "BigQueryConnectionSpec", + "CloudSqlBigQueryConnectionSpec", + "BigQueryRoutineSpec", + }, +) + + +class BigQueryConnectionSpec(proto.Message): + r"""Specification for the BigQuery connection. + Attributes: + connection_type (google.cloud.datacatalog_v1.types.BigQueryConnectionSpec.ConnectionType): + The type of the BigQuery connection. + cloud_sql (google.cloud.datacatalog_v1.types.CloudSqlBigQueryConnectionSpec): + Specification for the BigQuery connection to + a Cloud SQL instance. + has_credential (bool): + True if there are credentials attached to the + BigQuery connection; false otherwise. + """ + + class ConnectionType(proto.Enum): + r"""The type of the BigQuery connection.""" + CONNECTION_TYPE_UNSPECIFIED = 0 + CLOUD_SQL = 1 + + connection_type = proto.Field(proto.ENUM, number=1, enum=ConnectionType,) + cloud_sql = proto.Field( + proto.MESSAGE, + number=2, + oneof="connection_spec", + message="CloudSqlBigQueryConnectionSpec", + ) + has_credential = proto.Field(proto.BOOL, number=3,) + + +class CloudSqlBigQueryConnectionSpec(proto.Message): + r"""Specification for the BigQuery connection to a Cloud SQL + instance. + + Attributes: + instance_id (str): + Cloud SQL instance ID in the format of + ``project:location:instance``. + database (str): + Database name. + type_ (google.cloud.datacatalog_v1.types.CloudSqlBigQueryConnectionSpec.DatabaseType): + Type of the Cloud SQL database. + """ + + class DatabaseType(proto.Enum): + r"""Supported Cloud SQL database types.""" + DATABASE_TYPE_UNSPECIFIED = 0 + POSTGRES = 1 + MYSQL = 2 + + instance_id = proto.Field(proto.STRING, number=1,) + database = proto.Field(proto.STRING, number=2,) + type_ = proto.Field(proto.ENUM, number=3, enum=DatabaseType,) + + +class BigQueryRoutineSpec(proto.Message): + r"""Fields specific for BigQuery routines. + Attributes: + imported_libraries (Sequence[str]): + Paths of the imported libraries. + """ + + imported_libraries = proto.RepeatedField(proto.STRING, number=1,) + + +__all__ = tuple(sorted(__protobuf__.manifest)) diff --git a/google/cloud/datacatalog_v1/types/common.py b/google/cloud/datacatalog_v1/types/common.py index 9bc6ad34..f9dcee7e 100644 --- a/google/cloud/datacatalog_v1/types/common.py +++ b/google/cloud/datacatalog_v1/types/common.py @@ -22,8 +22,8 @@ class IntegratedSystem(proto.Enum): - r"""This enum describes all the possible systems that Data - Catalog integrates with. + r"""This enum lists all the systems that Data Catalog integrates + with. """ INTEGRATED_SYSTEM_UNSPECIFIED = 0 BIGQUERY = 1 diff --git a/google/cloud/datacatalog_v1/types/data_source.py b/google/cloud/datacatalog_v1/types/data_source.py index 6ddc6fcc..54ce88d6 100644 --- a/google/cloud/datacatalog_v1/types/data_source.py +++ b/google/cloud/datacatalog_v1/types/data_source.py @@ -22,18 +22,19 @@ class DataSource(proto.Message): - r"""Describes the physical location of an entry. + r"""Physical location of an entry. Attributes: service (google.cloud.datacatalog_v1.types.DataSource.Service): - Service in which the data is physically - stored. + Service that physically stores the data. resource (str): - Full name of the resource as defined by the service, e.g. - //bigquery.googleapis.com/projects/{project_id}/locations/{location}/datasets/{dataset_id}/tables/{table_id} + Full name of a resource as defined by the service. For + example: + + ``//bigquery.googleapis.com/projects/{PROJECT_ID}/locations/{LOCATION}/datasets/{DATASET_ID}/tables/{TABLE_ID}`` """ class Service(proto.Enum): - r"""Service name where the data is stored.""" + r"""Name of a service that stores the data.""" SERVICE_UNSPECIFIED = 0 CLOUD_STORAGE = 1 BIGQUERY = 2 diff --git a/google/cloud/datacatalog_v1/types/datacatalog.py b/google/cloud/datacatalog_v1/types/datacatalog.py index 2437039d..3e678f58 100644 --- a/google/cloud/datacatalog_v1/types/datacatalog.py +++ b/google/cloud/datacatalog_v1/types/datacatalog.py @@ -15,6 +15,7 @@ # import proto # type: ignore +from google.cloud.datacatalog_v1.types import bigquery from google.cloud.datacatalog_v1.types import common from google.cloud.datacatalog_v1.types import data_source as gcd_data_source from google.cloud.datacatalog_v1.types import gcs_fileset_spec as gcd_gcs_fileset_spec @@ -23,6 +24,7 @@ from google.cloud.datacatalog_v1.types import table_spec from google.cloud.datacatalog_v1.types import tags as gcd_tags from google.cloud.datacatalog_v1.types import timestamps +from google.cloud.datacatalog_v1.types import usage from google.protobuf import field_mask_pb2 # type: ignore @@ -45,6 +47,8 @@ "LookupEntryRequest", "Entry", "DatabaseTableSpec", + "DataSourceConnectionSpec", + "RoutineSpec", "EntryGroup", "CreateTagTemplateRequest", "GetTagTemplateRequest", @@ -67,16 +71,18 @@ class EntryType(proto.Enum): - r"""Entry resources in Data Catalog can be of different types e.g. a - BigQuery Table entry is of type ``TABLE``. This enum describes all - the possible types Data Catalog contains. + r"""The enum field that lists all the types of entry resources in Data + Catalog. For example, a BigQuery table entry has the ``TABLE`` type. """ ENTRY_TYPE_UNSPECIFIED = 0 TABLE = 2 MODEL = 5 DATA_STREAM = 3 FILESET = 4 + CLUSTER = 6 DATABASE = 7 + DATA_SOURCE_CONNECTION = 8 + ROUTINE = 9 SERVICE = 14 @@ -86,46 +92,54 @@ class SearchCatalogRequest(proto.Message): Attributes: scope (google.cloud.datacatalog_v1.types.SearchCatalogRequest.Scope): - Required. The scope of this search request. A ``scope`` that - has empty ``include_org_ids``, ``include_project_ids`` AND - false ``include_gcp_public_datasets`` is considered invalid. - Data Catalog will return an error in such a case. + Required. The scope of this search request. + + The ``scope`` is invalid if ``include_org_ids``, + ``include_project_ids`` are empty AND + ``include_gcp_public_datasets`` is set to ``false``. In this + case, the request returns an error. query (str): - Optional. The query string in search query syntax. An empty - query string will result in all data assets (in the - specified scope) that the user has access to. + Optional. The query string with a minimum of 3 characters + and specific syntax. For more information, see `Data Catalog + search + syntax `__. - Query strings can be simple as "x" or more qualified as: + An empty query string returns all data assets (in the + specified scope) that you have access to. - - name:x - - column:x - - description:y + A query string can be a simple ``xyz`` or qualified by + predicates: - Note: Query tokens need to have a minimum of 3 characters - for substring matching to work correctly. See `Data Catalog - Search - Syntax `__ - for more information. + - ``name:x`` + - ``column:y`` + - ``description:z`` page_size (int): - Number of results in the search page. If <=0 then defaults - to 10. Max limit for page_size is 1000. Throws an invalid - argument for page_size > 1000. + Number of results to return in a single + search page. + Can't be negative or 0, defaults to 10 in this + case. The maximum number is 1000. If exceeded, + throws an "invalid argument" exception. page_token (str): - Optional. Pagination token returned in an earlier - [SearchCatalogResponse.next_page_token][google.cloud.datacatalog.v1.SearchCatalogResponse.next_page_token], - which indicates that this is a continuation of a prior + Optional. Pagination token that, if specified, returns the + next page of search results. If empty, returns the first + page. + + This token is returned in the + [SearchCatalogResponse.next_page_token][google.cloud.datacatalog.v1.SearchCatalogResponse.next_page_token] + field of the response to a previous [SearchCatalogRequest][google.cloud.datacatalog.v1.DataCatalog.SearchCatalog] - call, and that the system should return the next page of - data. If empty, the first page is returned. + call. order_by (str): - Specifies the ordering of results, currently supported - case-sensitive choices are: + Specifies the order of results. + + Currently supported case-sensitive values are: - - ``relevance``, only supports descending - - ``last_modified_timestamp [asc|desc]``, defaults to - descending if not specified + - ``relevance`` that can only be descending + - ``last_modified_timestamp [asc|desc]`` with descending + (``desc``) as default - If not specified, defaults to ``relevance`` descending. + If this parameter is omitted, it defaults to the descending + ``relevance``. """ class Scope(proto.Message): @@ -134,40 +148,53 @@ class Scope(proto.Message): Attributes: include_org_ids (Sequence[str]): - The list of organization IDs to search - within. To find your organization ID, follow - instructions in - https://cloud.google.com/resource- - manager/docs/creating-managing-organization. + The list of organization IDs to search within. + + To find your organization ID, follow the steps from + [Creating and managing organizations] + (/resource-manager/docs/creating-managing-organization). include_project_ids (Sequence[str]): - The list of project IDs to search within. To - learn more about the distinction between project - names/IDs/numbers, go to - https://cloud.google.com/docs/overview/#projects. + The list of project IDs to search within. + + For more information on the distinction between project + names, IDs, and numbers, see + `Projects `__. include_gcp_public_datasets (bool): If ``true``, include Google Cloud Platform (GCP) public - datasets in the search results. Info on GCP public datasets - is available at https://cloud.google.com/public-datasets/. - By default, GCP public datasets are excluded. + datasets in search results. By default, they are excluded. + + See `Google Cloud Public Datasets `__ for + more information. restricted_locations (Sequence[str]): - Optional. The list of locations to search within. - - 1. If empty, search will be performed in all locations; - 2. If any of the locations are NOT `supported - regions `__, - error will be returned; - 3. Otherwise, search only the given locations for matching - results. Typical usage is to leave this field empty. When - a location is unreachable as returned in the - ``SearchCatalogResponse.unreachable`` field, users can - repeat the search request with this parameter set to get - additional information on the error. + Optional. The list of locations to search within. If empty, + all locations are searched. + + Returns an error if any location in the list isn't one of + the `Supported + regions `__. + + If a location is unreachable, its name is returned in the + ``SearchCatalogResponse.unreachable`` field. To get + additional information on the error, repeat the search + request and set the location name as the value of this + parameter. + include_public_tag_templates (bool): + Optional. If ``true``, include [public tag + templates][google.cloud.datacatalog.v1.TagTemplate.is_publicly_readable] + in the search results. By default, they are included only if + you have explicit permissions on them to view them. For + example, if you are the owner. + + Other scope fields, for example, ``include_org_ids``, still + restrict the returned public tag templates and at least one + of them is required. """ include_org_ids = proto.RepeatedField(proto.STRING, number=2,) include_project_ids = proto.RepeatedField(proto.STRING, number=3,) include_gcp_public_datasets = proto.Field(proto.BOOL, number=7,) restricted_locations = proto.RepeatedField(proto.STRING, number=16,) + include_public_tag_templates = proto.Field(proto.BOOL, number=19,) scope = proto.Field(proto.MESSAGE, number=6, message=Scope,) query = proto.Field(proto.STRING, number=1,) @@ -184,14 +211,17 @@ class SearchCatalogResponse(proto.Message): results (Sequence[google.cloud.datacatalog_v1.types.SearchCatalogResult]): Search results. next_page_token (str): - The token that can be used to retrieve the - next page of results. + Pagination token that can be used in + subsequent calls to retrieve the next page of + results. unreachable (Sequence[str]): - Unreachable locations. Search result does not include data - from those locations. Users can get additional information - on the error by repeating the search request with a more - restrictive parameter -- setting the value for - ``SearchDataCatalogRequest.scope.restricted_locations``. + Unreachable locations. Search results don't include data + from those locations. + + To get additional information on an error, repeat the search + request and restrict it to specific locations by setting the + ``SearchCatalogRequest.scope.restricted_locations`` + parameter. """ @property @@ -211,13 +241,11 @@ class CreateEntryGroupRequest(proto.Message): Attributes: parent (str): - Required. The name of the project this entry group belongs - to. Example: - - ``projects/{project_id}/locations/{location}`` - - Note: The entry group itself and its child resources might - not be stored in the location specified in its name. + Required. The names of the project and + location that the new entry group belongs to. + Note: The entry group itself and its child + resources might not be stored in the location + specified in its name. entry_group_id (str): Required. The ID of the entry group to create. @@ -225,8 +253,7 @@ class CreateEntryGroupRequest(proto.Message): underscores (_), and must start with a letter or underscore. The maximum size is 64 bytes when encoded in UTF-8. entry_group (google.cloud.datacatalog_v1.types.EntryGroup): - The entry group to create. Defaults to an - empty entry group. + The entry group to create. Defaults to empty. """ parent = proto.Field(proto.STRING, number=1,) @@ -240,8 +267,8 @@ class UpdateEntryGroupRequest(proto.Message): Attributes: entry_group (google.cloud.datacatalog_v1.types.EntryGroup): - Required. The updated entry group. "name" - field must be set. + Required. Updates for the entry group. The ``name`` field + must be set. update_mask (google.protobuf.field_mask_pb2.FieldMask): Names of fields whose values to overwrite on an entry group. @@ -263,10 +290,9 @@ class GetEntryGroupRequest(proto.Message): Attributes: name (str): - Required. The name of the entry group. For example, - ``projects/{project_id}/locations/{location}/entryGroups/{entry_group_id}``. + Required. The name of the entry group to get. read_mask (google.protobuf.field_mask_pb2.FieldMask): - The fields to return. If not set or empty, + The fields to return. If empty or omitted, all fields are returned. """ @@ -280,8 +306,8 @@ class DeleteEntryGroupRequest(proto.Message): Attributes: name (str): - Required. The name of the entry group. For example, - ``projects/{project_id}/locations/{location}/entryGroups/{entry_group_id}``. + Required. The name of the entry group to + delete. force (bool): Optional. If true, deletes all entries in the entry group. @@ -297,17 +323,18 @@ class ListEntryGroupsRequest(proto.Message): Attributes: parent (str): - Required. The name of the location that contains the entry - groups, which can be provided in URL format. Example: - - - projects/{project_id}/locations/{location} + Required. The name of the location that + contains the entry groups to list. + Can be provided as a URL. page_size (int): - Optional. The maximum number of items to return. Default is - 10. Max limit is 1000. Throws an invalid argument for - ``page_size > 1000``. + Optional. The maximum number of items to return. + + Default is 10. Maximum limit is 1000. Throws an invalid + argument if ``page_size`` is greater than 1000. page_token (str): - Optional. Token that specifies which page is - requested. If empty, the first page is returned. + Optional. Pagination token that specifies the + next page to return. If empty, returns the first + page. """ parent = proto.Field(proto.STRING, number=1,) @@ -321,11 +348,11 @@ class ListEntryGroupsResponse(proto.Message): Attributes: entry_groups (Sequence[google.cloud.datacatalog_v1.types.EntryGroup]): - EntryGroup details. + Entry group details. next_page_token (str): - Token to retrieve the next page of results. - It is set to empty if no items remain in - results. + Pagination token to specify in the next call + to retrieve the next page of results. Empty if + there are no more items. """ @property @@ -342,13 +369,11 @@ class CreateEntryRequest(proto.Message): Attributes: parent (str): - Required. The name of the entry group this entry belongs to. - Example: - - ``projects/{project_id}/locations/{location}/entryGroups/{entry_group_id}`` - - Note: The entry itself and its child resources might not be - stored in the location specified in its name. + Required. The name of the entry group this + entry belongs to. + Note: The entry itself and its child resources + might not be stored in the location specified in + its name. entry_id (str): Required. The ID of the entry to create. @@ -370,8 +395,8 @@ class UpdateEntryRequest(proto.Message): Attributes: entry (google.cloud.datacatalog_v1.types.Entry): - Required. The updated entry. The "name" field - must be set. + Required. Updates for the entry. The ``name`` field must be + set. update_mask (google.protobuf.field_mask_pb2.FieldMask): Names of fields whose values to overwrite on an entry. @@ -379,29 +404,29 @@ class UpdateEntryRequest(proto.Message): are overwritten. If such fields are non-required and omitted in the request body, their values are emptied. - The following fields are modifiable: + You can modify only the fields listed below. - - For entries with type ``DATA_STREAM``: + For entries with type ``DATA_STREAM``: - - ``schema`` + - ``schema`` - - For entries with type ``FILESET``: + For entries with type ``FILESET``: - - ``schema`` - - ``display_name`` - - ``description`` - - ``gcs_fileset_spec`` - - ``gcs_fileset_spec.file_patterns`` + - ``schema`` + - ``display_name`` + - ``description`` + - ``gcs_fileset_spec`` + - ``gcs_fileset_spec.file_patterns`` - - For entries with ``user_specified_type``: + For entries with ``user_specified_type``: - - ``schema`` - - ``display_name`` - - ``description`` - - ``user_specified_type`` - - ``user_specified_system`` - - ``linked_resource`` - - ``source_system_timestamps`` + - ``schema`` + - ``display_name`` + - ``description`` + - ``user_specified_type`` + - ``user_specified_system`` + - ``linked_resource`` + - ``source_system_timestamps`` """ entry = proto.Field(proto.MESSAGE, number=1, message="Entry",) @@ -416,9 +441,7 @@ class DeleteEntryRequest(proto.Message): Attributes: name (str): - Required. The name of the entry. Example: - - - projects/{project_id}/locations/{location}/entryGroups/{entry_group_id}/entries/{entry_id} + Required. The name of the entry to delete. """ name = proto.Field(proto.STRING, number=1,) @@ -430,9 +453,7 @@ class GetEntryRequest(proto.Message): Attributes: name (str): - Required. The name of the entry. Example: - - - projects/{project_id}/locations/{location}/entryGroups/{entry_group_id}/entries/{entry_id} + Required. The name of the entry to get. """ name = proto.Field(proto.STRING, number=1,) @@ -445,28 +466,28 @@ class LookupEntryRequest(proto.Message): Attributes: linked_resource (str): The full name of the Google Cloud Platform resource the Data - Catalog entry represents. See: - https://cloud.google.com/apis/design/resource_names#full_resource_name. - Full names are case-sensitive. + Catalog entry represents. For more information, see [Full + Resource Name] + (https://cloud.google.com/apis/design/resource_names#full_resource_name). - Examples: + Full names are case-sensitive. For example: - - //bigquery.googleapis.com/projects/projectId/datasets/datasetId/tables/tableId - - //pubsub.googleapis.com/projects/projectId/topics/topicId + - ``//bigquery.googleapis.com/projects/{PROJECT_ID}/datasets/{DATASET_ID}/tables/{TABLE_ID}`` + - ``//pubsub.googleapis.com/projects/{PROJECT_ID}/topics/{TOPIC_ID}`` sql_resource (str): The SQL name of the entry. SQL names are case-sensitive. Examples: - - ``pubsub.project_id.topic_id`` - - :literal:`pubsub.project_id.`topic.id.with.dots\`` - - ``bigquery.table.project_id.dataset_id.table_id`` - - ``bigquery.dataset.project_id.dataset_id`` - - ``datacatalog.entry.project_id.location_id.entry_group_id.entry_id`` + - ``pubsub.topic.{PROJECT_ID}.{TOPIC_ID}`` + - ``pubsub.topic.{PROJECT_ID}.``\ \`\ ``{TOPIC.ID.SEPARATED.WITH.DOTS}``\ \` + - ``bigquery.table.{PROJECT_ID}.{DATASET_ID}.{TABLE_ID}`` + - ``bigquery.dataset.{PROJECT_ID}.{DATASET_ID}`` + - ``datacatalog.entry.{PROJECT_ID}.{LOCATION_ID}.{ENTRY_GROUP_ID}.{ENTRY_ID}`` - ``*_id``\ s should satisfy the standard SQL rules for - identifiers. - https://cloud.google.com/bigquery/docs/reference/standard-sql/lexical. + Identifiers (``*_ID``) should comply with the [Lexical + structure in Standard SQL] + (https://cloud.google.com/bigquery/docs/reference/standard-sql/lexical). fully_qualified_name (str): Fully qualified name (FQN) of the resource. @@ -482,7 +503,7 @@ class LookupEntryRequest(proto.Message): Example for a DPMS table: - ``dataproc_metastore:project_id.location_id.instance_id.database_id.table_id`` + ``dataproc_metastore:{PROJECT_ID}.{LOCATION_ID}.{INSTANCE_ID}.{DATABASE_ID}.{TABLE_ID}`` """ linked_resource = proto.Field(proto.STRING, number=1, oneof="target_name",) @@ -491,37 +512,35 @@ class LookupEntryRequest(proto.Message): class Entry(proto.Message): - r"""Entry Metadata. A Data Catalog Entry resource represents another - resource in Google Cloud Platform (such as a BigQuery dataset or a - Pub/Sub topic) or outside of Google Cloud Platform. Clients can use - the ``linked_resource`` field in the Entry resource to refer to the - original resource ID of the source system. + r"""Entry metadata. A Data Catalog entry represents another resource in + Google Cloud Platform (such as a BigQuery dataset or a Pub/Sub + topic) or outside of it. You can use the ``linked_resource`` field + in the entry resource to refer to the original resource ID of the + source system. - An Entry resource contains resource details, such as its schema. An - Entry can also be used to attach flexible metadata, such as a - [Tag][google.cloud.datacatalog.v1.Tag]. + An entry resource contains resource details, for example, its + schema. Additionally, you can attach flexible metadata to an entry + in the form of a [Tag][google.cloud.datacatalog.v1.Tag]. Attributes: name (str): - Output only. The resource name of an entry in URL format. - Example: - - ``projects/{project_id}/locations/{location}/entryGroups/{entry_group_id}/entries/{entry_id}`` - - Note: The entry itself and its child resources might not be - stored in the location specified in its name. + Output only. The resource name of an entry in + URL format. + Note: The entry itself and its child resources + might not be stored in the location specified in + its name. linked_resource (str): The resource this metadata entry refers to. For Google Cloud Platform resources, ``linked_resource`` is - the `full name of the - resource `__. + the [Full Resource Name] + (https://cloud.google.com/apis/design/resource_names#full_resource_name). For example, the ``linked_resource`` for a table resource from BigQuery is: - ``//bigquery.googleapis.com/projects/{projectId}/datasets/{datasetId}/tables/{tableId}`` + ``//bigquery.googleapis.com/projects/{PROJECT_ID}/datasets/{DATASET_ID}/tables/{TABLE_ID}`` - Output only when entry is one of the types in the + Output only when the entry is one of the types in the ``EntryType`` enum. For entries with a ``user_specified_type``, this field is @@ -550,50 +569,69 @@ class Entry(proto.Message): Example for a DPMS table: - ``dataproc_metastore:project_id.location_id.instance_id.database_id.table_id`` + ``dataproc_metastore:{PROJECT_ID}.{LOCATION_ID}.{INSTANCE_ID}.{DATABASE_ID}.{TABLE_ID}`` type_ (google.cloud.datacatalog_v1.types.EntryType): - The type of the entry. - Only used for Entries with types in the - EntryType enum. - user_specified_type (str): - Entry type if it does not fit any of the input-allowed - values listed in ``EntryType`` enum above. When creating an - entry, users should check the enum values first, if nothing - matches the entry to be created, then provide a custom - value, for example "my_special_type". - ``user_specified_type`` strings must begin with a letter or - underscore and can only contain letters, numbers, and - underscores; are case insensitive; must be at least 1 - character and at most 64 characters long. - - Currently, only FILESET enum value is allowed. All other - entries created through Data Catalog must use + The type of the entry. Only used for entries with types + listed in the ``EntryType`` enum. + + Currently, only ``FILESET`` enum value is allowed. All other + entries created in Data Catalog must use the ``user_specified_type``. + user_specified_type (str): + Custom entry type that doesn't match any of the values + allowed for input and listed in the ``EntryType`` enum. + + When creating an entry, first check the type values in the + enum. If there are no appropriate types for the new entry, + provide a custom value, for example, ``my_special_type``. + + The ``user_specified_type`` string has the following + limitations: + + - Is case insensitive. + - Must begin with a letter or underscore. + - Can only contain letters, numbers, and underscores. + - Must be at least 1 character and at most 64 characters + long. integrated_system (google.cloud.datacatalog_v1.types.IntegratedSystem): - Output only. This field indicates the entry's - source system that Data Catalog integrates with, - such as BigQuery or Pub/Sub. + Output only. Indicates the entry's source + system that Data Catalog integrates with, such + as BigQuery, Pub/Sub, or Dataproc Metastore. user_specified_system (str): - This field indicates the entry's source system that Data - Catalog does not integrate with. ``user_specified_system`` - strings must begin with a letter or underscore and can only - contain letters, numbers, and underscores; are case - insensitive; must be at least 1 character and at most 64 - characters long. + Indicates the entry's source system that Data Catalog + doesn't automatically integrate with. + + The ``user_specified_system`` string has the following + limitations: + + - Is case insensitive. + - Must begin with a letter or underscore. + - Can only contain letters, numbers, and underscores. + - Must be at least 1 character and at most 64 characters + long. gcs_fileset_spec (google.cloud.datacatalog_v1.types.GcsFilesetSpec): - Specification that applies to a Cloud Storage - fileset. This is only valid on entries of type - FILESET. + Specification that applies to a Cloud Storage fileset. Valid + only for entries with the ``FILESET`` type. bigquery_table_spec (google.cloud.datacatalog_v1.types.BigQueryTableSpec): - Specification that applies to a BigQuery table. This is only - valid on entries of type ``TABLE``. + Specification that applies to a BigQuery table. Valid only + for entries with the ``TABLE`` type. bigquery_date_sharded_spec (google.cloud.datacatalog_v1.types.BigQueryDateShardedSpec): - Specification for a group of BigQuery tables with name - pattern ``[prefix]YYYYMMDD``. Context: - https://cloud.google.com/bigquery/docs/partitioned-tables#partitioning_versus_sharding. + Specification for a group of BigQuery tables with the + ``[prefix]YYYYMMDD`` name pattern. + + For more information, see [Introduction to partitioned + tables] + (https://cloud.google.com/bigquery/docs/partitioned-tables#partitioning_versus_sharding). database_table_spec (google.cloud.datacatalog_v1.types.DatabaseTableSpec): - Specification that applies to a table resource. Only valid - for entries of ``TABLE`` type. + Specification that applies to a table resource. Valid only + for entries with the ``TABLE`` type. + data_source_connection_spec (google.cloud.datacatalog_v1.types.DataSourceConnectionSpec): + Specification that applies to a data source connection. + Valid only for entries with the ``DATA_SOURCE_CONNECTION`` + type. + routine_spec (google.cloud.datacatalog_v1.types.RoutineSpec): + Specification that applies to a user-defined function or + procedure. Valid only for entries with the ``ROUTINE`` type. display_name (str): Display name of an entry. @@ -615,10 +653,21 @@ class Entry(proto.Message): Schema of the entry. An entry might not have any schema attached to it. source_system_timestamps (google.cloud.datacatalog_v1.types.SystemTimestamps): - Timestamps about the underlying resource, not about this - Data Catalog entry. Output only when Entry is of type in the - EntryType enum. For entries with user_specified_type, this - field is optional and defaults to an empty timestamp. + Timestamps from the underlying resource, not from the Data + Catalog entry. + + Output only when the entry has a type listed in the + ``EntryType`` enum. For entries with + ``user_specified_type``, this field is optional and defaults + to an empty timestamp. + usage_signal (google.cloud.datacatalog_v1.types.UsageSignal): + Output only. Resource usage statistics. + labels (Sequence[google.cloud.datacatalog_v1.types.Entry.LabelsEntry]): + Cloud labels attached to the entry. + In Data Catalog, you can create and modify + labels attached only to custom entries. Synced + entries have unmodifiable labels that come from + the source system. data_source (google.cloud.datacatalog_v1.types.DataSource): Output only. Physical location of the entry. """ @@ -653,20 +702,28 @@ class Entry(proto.Message): database_table_spec = proto.Field( proto.MESSAGE, number=24, oneof="spec", message="DatabaseTableSpec", ) + data_source_connection_spec = proto.Field( + proto.MESSAGE, number=27, oneof="spec", message="DataSourceConnectionSpec", + ) + routine_spec = proto.Field( + proto.MESSAGE, number=28, oneof="spec", message="RoutineSpec", + ) display_name = proto.Field(proto.STRING, number=3,) description = proto.Field(proto.STRING, number=4,) schema = proto.Field(proto.MESSAGE, number=5, message=gcd_schema.Schema,) source_system_timestamps = proto.Field( proto.MESSAGE, number=7, message=timestamps.SystemTimestamps, ) + usage_signal = proto.Field(proto.MESSAGE, number=13, message=usage.UsageSignal,) + labels = proto.MapField(proto.STRING, proto.STRING, number=14,) data_source = proto.Field( proto.MESSAGE, number=20, message=gcd_data_source.DataSource, ) class DatabaseTableSpec(proto.Message): - r"""Specification that applies to a table resource. Only valid for - entries of ``TABLE`` type. + r"""Specification that applies to a table resource. Valid only for + entries with the ``TABLE`` type. Attributes: type_ (google.cloud.datacatalog_v1.types.DatabaseTableSpec.TableType): @@ -682,31 +739,115 @@ class TableType(proto.Enum): type_ = proto.Field(proto.ENUM, number=1, enum=TableType,) -class EntryGroup(proto.Message): - r"""EntryGroup Metadata. An EntryGroup resource represents a logical - grouping of zero or more Data Catalog - [Entry][google.cloud.datacatalog.v1.Entry] resources. +class DataSourceConnectionSpec(proto.Message): + r"""Specification that applies to a data source connection. Valid only + for entries with the ``DATA_SOURCE_CONNECTION`` type. Attributes: - name (str): - The resource name of the entry group in URL format. Example: + bigquery_connection_spec (google.cloud.datacatalog_v1.types.BigQueryConnectionSpec): + Fields specific to BigQuery connections. + """ + + bigquery_connection_spec = proto.Field( + proto.MESSAGE, number=1, message=bigquery.BigQueryConnectionSpec, + ) + + +class RoutineSpec(proto.Message): + r"""Specification that applies to a routine. Valid only for entries with + the ``ROUTINE`` type. + + Attributes: + routine_type (google.cloud.datacatalog_v1.types.RoutineSpec.RoutineType): + The type of the routine. + language (str): + The language the routine is written in. The exact value + depends on the source system. For BigQuery routines, + possible values are: + + - ``SQL`` + - ``JAVASCRIPT`` + routine_arguments (Sequence[google.cloud.datacatalog_v1.types.RoutineSpec.Argument]): + Arguments of the routine. + return_type (str): + Return type of the argument. The exact value + depends on the source system and the language. + definition_body (str): + The body of the routine. + bigquery_routine_spec (google.cloud.datacatalog_v1.types.BigQueryRoutineSpec): + Fields specific for BigQuery routines. + """ + + class RoutineType(proto.Enum): + r"""The fine-grained type of the routine.""" + ROUTINE_TYPE_UNSPECIFIED = 0 + SCALAR_FUNCTION = 1 + PROCEDURE = 2 + + class Argument(proto.Message): + r"""Input or output argument of a function or stored procedure. + Attributes: + name (str): + The name of the argument. A return argument + of a function might not have a name. + mode (google.cloud.datacatalog_v1.types.RoutineSpec.Argument.Mode): + Specifies whether the argument is input or + output. + type_ (str): + Type of the argument. The exact value depends + on the source system and the language. + """ + + class Mode(proto.Enum): + r"""The input or output mode of the argument.""" + MODE_UNSPECIFIED = 0 + IN = 1 + OUT = 2 + INOUT = 3 + + name = proto.Field(proto.STRING, number=1,) + mode = proto.Field(proto.ENUM, number=2, enum="RoutineSpec.Argument.Mode",) + type_ = proto.Field(proto.STRING, number=3,) + + routine_type = proto.Field(proto.ENUM, number=1, enum=RoutineType,) + language = proto.Field(proto.STRING, number=2,) + routine_arguments = proto.RepeatedField(proto.MESSAGE, number=3, message=Argument,) + return_type = proto.Field(proto.STRING, number=4,) + definition_body = proto.Field(proto.STRING, number=5,) + bigquery_routine_spec = proto.Field( + proto.MESSAGE, + number=6, + oneof="system_spec", + message=bigquery.BigQueryRoutineSpec, + ) + + +class EntryGroup(proto.Message): + r"""Entry group metadata. - ``projects/{project_id}/locations/{location}/entryGroups/{entry_group_id}`` + An ``EntryGroup`` resource represents a logical grouping of zero or + more Data Catalog [Entry][google.cloud.datacatalog.v1.Entry] + resources. - Note: The entry group itself and its child resources might - not be stored in the location specified in its name. + Attributes: + name (str): + The resource name of the entry group in URL + format. + Note: The entry group itself and its child + resources might not be stored in the location + specified in its name. display_name (str): A short name to identify the entry group, for example, "analytics data - jan 2011". Default value is an empty string. description (str): - Entry group description, which can consist of + Entry group description. Can consist of several sentences or paragraphs that describe - entry group contents. Default value is an empty - string. + the entry group contents. Default value is an + empty string. data_catalog_timestamps (google.cloud.datacatalog_v1.types.SystemTimestamps): - Output only. Timestamps about this - EntryGroup. Default value is empty timestamps. + Output only. Timestamps of the entry group. + Default value is empty. """ name = proto.Field(proto.STRING, number=1,) @@ -725,10 +866,6 @@ class CreateTagTemplateRequest(proto.Message): parent (str): Required. The name of the project and the template location `region `__. - - Example: - - - projects/{project_id}/locations/us-central1 tag_template_id (str): Required. The ID of the tag template to create. @@ -751,9 +888,8 @@ class GetTagTemplateRequest(proto.Message): Attributes: name (str): - Required. The name of the tag template. Example: - - - projects/{project_id}/locations/{location}/tagTemplates/{tag_template_id} + Required. The name of the tag template to + get. """ name = proto.Field(proto.STRING, number=1,) @@ -765,16 +901,15 @@ class UpdateTagTemplateRequest(proto.Message): Attributes: tag_template (google.cloud.datacatalog_v1.types.TagTemplate): - Required. The template to update. The "name" - field must be set. + Required. The template to update. The ``name`` field must be + set. update_mask (google.protobuf.field_mask_pb2.FieldMask): Names of fields whose values to overwrite on a tag template. Currently, only ``display_name`` can be overwritten. - In general, if this parameter is absent or empty, all - modifiable fields are overwritten. If such fields are - non-required and omitted in the request body, their values - are emptied. + If this parameter is absent or empty, all modifiable fields + are overwritten. If such fields are non-required and omitted + in the request body, their values are emptied. """ tag_template = proto.Field(proto.MESSAGE, number=1, message=gcd_tags.TagTemplate,) @@ -789,14 +924,12 @@ class DeleteTagTemplateRequest(proto.Message): Attributes: name (str): - Required. The name of the tag template to delete. Example: - - - projects/{project_id}/locations/{location}/tagTemplates/{tag_template_id} + Required. The name of the tag template to + delete. force (bool): - Required. Currently, this field must always be set to - ``true``. This confirms the deletion of any possible tags - using this template. ``force = false`` will be supported in - the future. + Required. If true, deletes all tags that use this template. + + Currently, ``true`` is the only supported value. """ name = proto.Field(proto.STRING, number=1,) @@ -809,14 +942,13 @@ class CreateTagRequest(proto.Message): Attributes: parent (str): - Required. The name of the resource to attach this tag to. - Tags can be attached to entries. An entry can have up to - 1000 attached tags. Example: - - ``projects/{project_id}/locations/{location}/entryGroups/{entry_group_id}/entries/{entry_id}`` + Required. The name of the resource to attach + this tag to. + Tags can be attached to entries or entry groups. + An entry can have up to 1000 attached tags. - Note: The tag and its child resources might not be stored in - the location specified in its name. + Note: The tag and its child resources might not + be stored in the location specified in its name. tag (google.cloud.datacatalog_v1.types.Tag): Required. The tag to create. """ @@ -856,9 +988,7 @@ class DeleteTagRequest(proto.Message): Attributes: name (str): - Required. The name of the tag to delete. Example: - - - projects/{project_id}/locations/{location}/entryGroups/{entry_group_id}/entries/{entry_id}/tags/{tag_id} + Required. The name of the tag to delete. """ name = proto.Field(proto.STRING, number=1,) @@ -872,10 +1002,6 @@ class CreateTagTemplateFieldRequest(proto.Message): parent (str): Required. The name of the project and the template location `region `__. - - Example: - - - projects/{project_id}/locations/us-central1/tagTemplates/{tag_template_id} tag_template_field_id (str): Required. The ID of the tag template field to create. @@ -904,9 +1030,7 @@ class UpdateTagTemplateFieldRequest(proto.Message): Attributes: name (str): - Required. The name of the tag template field. Example: - - - projects/{project_id}/locations/{location}/tagTemplates/{tag_template_id}/fields/{tag_template_field_id} + Required. The name of the tag template field. tag_template_field (google.cloud.datacatalog_v1.types.TagTemplateField): Required. The template to update. update_mask (google.protobuf.field_mask_pb2.FieldMask): @@ -945,9 +1069,7 @@ class RenameTagTemplateFieldRequest(proto.Message): Attributes: name (str): - Required. The name of the tag template. Example: - - - projects/{project_id}/locations/{location}/tagTemplates/{tag_template_id}/fields/{tag_template_field_id} + Required. The name of the tag template. new_tag_template_field_id (str): Required. The new ID of this tag template field. For example, ``my_new_field``. @@ -963,9 +1085,7 @@ class RenameTagTemplateFieldEnumValueRequest(proto.Message): Attributes: name (str): - Required. The name of the enum field value. Example: - - - projects/{project_id}/locations/{location}/tagTemplates/{tag_template_id}/fields/{tag_template_field_id}/enumValues/{enum_value_display_name} + Required. The name of the enum field value. new_enum_value_display_name (str): Required. The new display name of the enum value. For example, ``my_new_enum_value``. @@ -981,15 +1101,13 @@ class DeleteTagTemplateFieldRequest(proto.Message): Attributes: name (str): - Required. The name of the tag template field to delete. - Example: - - - projects/{project_id}/locations/{location}/tagTemplates/{tag_template_id}/fields/{tag_template_field_id} + Required. The name of the tag template field + to delete. force (bool): - Required. Currently, this field must always be set to - ``true``. This confirms the deletion of this field from any - tags using this field. ``force = false`` will be supported - in the future. + Required. If true, deletes this field from any tags that use + it. + + Currently, ``true`` is the only supported value. """ name = proto.Field(proto.STRING, number=1,) @@ -1003,20 +1121,18 @@ class ListTagsRequest(proto.Message): Attributes: parent (str): Required. The name of the Data Catalog resource to list the - tags of. The resource could be an - [Entry][google.cloud.datacatalog.v1.Entry] or an - [EntryGroup][google.cloud.datacatalog.v1.EntryGroup]. + tags of. - Examples: - - - projects/{project_id}/locations/{location}/entryGroups/{entry_group_id} - - projects/{project_id}/locations/{location}/entryGroups/{entry_group_id}/entries/{entry_id} + The resource can be an + [Entry][google.cloud.datacatalog.v1.Entry] or an + [EntryGroup][google.cloud.datacatalog.v1.EntryGroup] + (without ``/entries/{entries}`` at the end). page_size (int): The maximum number of tags to return. Default - is 10. Max limit is 1000. + is 10. Maximum limit is 1000. page_token (str): - Token that specifies which page is requested. - If empty, the first page is returned. + Pagination token that specifies the next page + to return. If empty, the first page is returned. """ parent = proto.Field(proto.STRING, number=1,) @@ -1032,9 +1148,8 @@ class ListTagsResponse(proto.Message): tags (Sequence[google.cloud.datacatalog_v1.types.Tag]): [Tag][google.cloud.datacatalog.v1.Tag] details. next_page_token (str): - Token to retrieve the next page of results. - It is set to empty if no items remain in - results. + Pagination token of the next results page. + Empty if there are no more items in results. """ @property @@ -1051,22 +1166,23 @@ class ListEntriesRequest(proto.Message): Attributes: parent (str): - Required. The name of the entry group that contains the - entries, which can be provided in URL format. Example: - - - projects/{project_id}/locations/{location}/entryGroups/{entry_group_id} + Required. The name of the entry group that + contains the entries to list. + Can be provided in URL format. page_size (int): - The maximum number of items to return. Default is 10. Max - limit is 1000. Throws an invalid argument for - ``page_size > 1000``. + The maximum number of items to return. Default is 10. + Maximum limit is 1000. Throws an invalid argument if + ``page_size`` is more than 1000. page_token (str): - Token that specifies which page is requested. - If empty, the first page is returned. + Pagination token that specifies the next page + to return. If empty, the first page is returned. read_mask (google.protobuf.field_mask_pb2.FieldMask): - The fields to return for each Entry. If not set or empty, - all fields are returned. For example, setting read_mask to - contain only one path "name" will cause ListEntries to - return a list of Entries with only "name" field. + The fields to return for each entry. If empty or omitted, + all fields are returned. + + For example, to return a list of entries with only the + ``name`` field, set ``read_mask`` to only one path with the + ``name`` value. """ parent = proto.Field(proto.STRING, number=1,) @@ -1083,9 +1199,8 @@ class ListEntriesResponse(proto.Message): entries (Sequence[google.cloud.datacatalog_v1.types.Entry]): Entry details. next_page_token (str): - Token to retrieve the next page of results. - It is set to empty if no items remain in - results. + Pagination token of the next results page. + Empty if there are no more items in results. """ @property diff --git a/google/cloud/datacatalog_v1/types/gcs_fileset_spec.py b/google/cloud/datacatalog_v1/types/gcs_fileset_spec.py index 37b54c53..576becf4 100644 --- a/google/cloud/datacatalog_v1/types/gcs_fileset_spec.py +++ b/google/cloud/datacatalog_v1/types/gcs_fileset_spec.py @@ -28,17 +28,19 @@ class GcsFilesetSpec(proto.Message): Attributes: file_patterns (Sequence[str]): Required. Patterns to identify a set of files in Google - Cloud Storage. See `Cloud Storage - documentation `__ - for more information. Note that bucket wildcards are - currently not supported. + Cloud Storage. - Examples of valid file_patterns: + For more information, see [Wildcard Names] + (https://cloud.google.com/storage/docs/gsutil/addlhelp/WildcardNames). - - ``gs://bucket_name/dir/*``: matches all files within - ``bucket_name/dir`` directory. + Note: Currently, bucket wildcards are not supported. + + Examples of valid ``file_patterns``: + + - ``gs://bucket_name/dir/*``: matches all files in + ``bucket_name/dir`` directory - ``gs://bucket_name/dir/**``: matches all files in - ``bucket_name/dir`` spanning all subdirectories. + ``bucket_name/dir`` and all subdirectories - ``gs://bucket_name/file*``: matches files prefixed by ``file`` in ``bucket_name`` - ``gs://bucket_name/??.txt``: matches files with two @@ -50,15 +52,15 @@ class GcsFilesetSpec(proto.Message): contain ``a``, ``b``, ... or ``m`` followed by ``.txt`` in ``bucket_name`` - ``gs://bucket_name/a/*/b``: matches all files in - ``bucket_name`` that match ``a/*/b`` pattern, such as + ``bucket_name`` that match the ``a/*/b`` pattern, such as ``a/c/b``, ``a/d/b`` - ``gs://another_bucket/a.txt``: matches ``gs://another_bucket/a.txt`` - You can combine wildcards to provide more powerful matches, + You can combine wildcards to match complex sets of files, for example: - - ``gs://bucket_name/[a-m]??.j*g`` + ``gs://bucket_name/[a-m]??.j*g`` sample_gcs_file_specs (Sequence[google.cloud.datacatalog_v1.types.GcsFileSpec]): Output only. Sample files contained in this fileset, not all files contained in this fileset @@ -72,16 +74,16 @@ class GcsFilesetSpec(proto.Message): class GcsFileSpec(proto.Message): - r"""Specifications of a single file in Cloud Storage. + r"""Specification of a single file in Cloud Storage. Attributes: file_path (str): - Required. The full file path. Example: + Required. Full file path. Example: ``gs://bucket_name/a/b.txt``. gcs_timestamps (google.cloud.datacatalog_v1.types.SystemTimestamps): - Output only. Timestamps about the Cloud - Storage file. + Output only. Creation, modification, and + expiration timestamps of a Cloud Storage file. size_bytes (int): - Output only. The size of the file, in bytes. + Output only. File size in bytes. """ file_path = proto.Field(proto.STRING, number=1,) diff --git a/google/cloud/datacatalog_v1/types/policytagmanager.py b/google/cloud/datacatalog_v1/types/policytagmanager.py index 1aa3cba9..623a0af2 100644 --- a/google/cloud/datacatalog_v1/types/policytagmanager.py +++ b/google/cloud/datacatalog_v1/types/policytagmanager.py @@ -42,8 +42,10 @@ class Taxonomy(proto.Message): r"""A taxonomy is a collection of hierarchical policy tags that classify - data along a common axis. For instance a "data sensitivity" taxonomy - could contain the following policy tags: + data along a common axis. + + For example, a "data sensitivity" taxonomy might contain the + following policy tags: :: @@ -55,7 +57,7 @@ class Taxonomy(proto.Message): + Financials + Revenue - A "data origin" taxonomy could contain the following policy tags: + A "data origin" taxonomy might contain the following policy tags: :: @@ -66,29 +68,29 @@ class Taxonomy(proto.Message): Attributes: name (str): - Output only. Resource name of this taxonomy in format: - "projects/{project_number}/locations/{location_id}/taxonomies/{taxonomy_id}". - Note that taxonomy_id's are unique and generated by Policy - Tag Manager. + Output only. Resource name of this taxonomy + in URL format. + Note: Policy tag manager generates unique + taxonomy IDs. display_name (str): Required. User-defined name of this taxonomy. - It must: contain only unicode letters, numbers, - underscores, dashes and spaces; not start or end - with spaces; and be at most 200 bytes long when - encoded in UTF-8. + The name can't start or end with spaces, must + contain only Unicode letters, numbers, + underscores, dashes, and spaces, and be at most + 200 bytes long when encoded in UTF-8. description (str): - Optional. Description of this taxonomy. It - must: contain only unicode characters, tabs, - newlines, carriage returns and page breaks; and - be at most 2000 bytes long when encoded in - UTF-8. If not set, defaults to an empty - description. + Optional. Description of this taxonomy. If + not set, defaults to empty. + The description must contain only Unicode + characters, tabs, newlines, carriage returns, + and page breaks, and be at most 2000 bytes long + when encoded in UTF-8. policy_tag_count (int): - Output only. Number of policy tags contained - in this taxonomy. + Output only. Number of policy tags in this + taxonomy. taxonomy_timestamps (google.cloud.datacatalog_v1.types.SystemTimestamps): - Output only. Timestamps about this taxonomy. Only - create_time and update_time are used. + Output only. Creation and modification + timestamps of this taxonomy. activated_policy_types (Sequence[google.cloud.datacatalog_v1.types.Taxonomy.PolicyType]): Optional. A list of policy types that are activated for this taxonomy. If not set, @@ -111,9 +113,9 @@ class PolicyType(proto.Enum): class PolicyTag(proto.Message): - r"""Denotes one policy tag in a taxonomy (e.g. ssn). Policy tags can be - defined in a hierarchy. For example, consider the following - hierarchy: + r"""Denotes one policy tag in a taxonomy, for example, SSN. + + Policy tags can be defined in a hierarchy. For example: :: @@ -122,38 +124,37 @@ class PolicyTag(proto.Message): + City + ZipCode - Policy tag "Geolocation" contains 3 child policy tags: "LatLong", - "City", and "ZipCode". + Where the "Geolocation" policy tag contains three children. Attributes: name (str): - Output only. Resource name of this policy tag in format: - "projects/{project_number}/locations/{location_id}/taxonomies/{taxonomy_id}/policyTags/{policy_tag_id}". - Both taxonomy_ids and policy_tag_ids are unique and - generated by Policy Tag Manager. + Output only. Resource name of this policy tag + in the URL format. + The policy tag manager generates unique taxonomy + IDs and policy tag IDs.

display_name (str): Required. User-defined name of this policy - tag. It must: be unique within the parent - taxonomy; contain only unicode letters, numbers, - underscores, dashes and spaces; not start or end - with spaces; and be at most 200 bytes long when - encoded in UTF-8. + tag. + The name can't start or end with spaces and must + be unique within the parent taxonomy, contain + only Unicode letters, numbers, underscores, + dashes and spaces, and be at most 200 bytes long + when encoded in UTF-8. description (str): - Description of this policy tag. It must: - contain only unicode characters, tabs, newlines, - carriage returns and page breaks; and be at most - 2000 bytes long when encoded in UTF-8. If not - set, defaults to an empty description. If not - set, defaults to an empty description. + Description of this policy tag. If not set, + defaults to empty. + The description must contain only Unicode + characters, tabs, newlines, carriage returns and + page breaks, and be at most 2000 bytes long when + encoded in UTF-8. parent_policy_tag (str): Resource name of this policy tag's parent - policy tag (e.g. for the "LatLong" policy tag in - the example above, this field contains the - resource name of the "Geolocation" policy tag). - If empty, it means this policy tag is a top - level policy tag (e.g. this field is empty for - the "Geolocation" policy tag in the example - above). If not set, defaults to an empty string. + policy tag. If empty, this is a top level tag. + If not set, defaults to an empty string. + For example, for the "LatLong" policy tag in the + example above, this field contains the resource + name of the "Geolocation" policy tag, and, for + "Geolocation", this field is empty. child_policy_tags (Sequence[str]): Output only. Resource names of child policy tags of this policy tag. @@ -175,7 +176,7 @@ class CreateTaxonomyRequest(proto.Message): Required. Resource name of the project that the taxonomy will belong to. taxonomy (google.cloud.datacatalog_v1.types.Taxonomy): - The taxonomy to be created. + The taxonomy to create. """ parent = proto.Field(proto.STRING, number=1,) @@ -188,9 +189,10 @@ class DeleteTaxonomyRequest(proto.Message): Attributes: name (str): - Required. Resource name of the taxonomy to be - deleted. All policy tags in this taxonomy will - also be deleted. + Required. Resource name of the taxonomy to + delete. + Note: All policy tags in this taxonomy are also + deleted. """ name = proto.Field(proto.STRING, number=1,) @@ -202,14 +204,15 @@ class UpdateTaxonomyRequest(proto.Message): Attributes: taxonomy (google.cloud.datacatalog_v1.types.Taxonomy): - The taxonomy to update. Only description, display_name, and - activated policy types can be updated. + The taxonomy to update. You can update only + its description, display name, and activated + policy types. update_mask (google.protobuf.field_mask_pb2.FieldMask): - The update mask applies to the resource. For the - ``FieldMask`` definition, see - https://developers.google.com/protocol-buffers/docs/reference/google.protobuf#fieldmask - If not set, defaults to all of the fields that are allowed - to update. + Specifies fields to update. If not set, defaults to all + fields you can update. + + For more information, see [FieldMask] + (https://developers.google.com/protocol-buffers/docs/reference/google.protobuf#fieldmask). """ taxonomy = proto.Field(proto.MESSAGE, number=1, message="Taxonomy",) @@ -228,11 +231,13 @@ class ListTaxonomiesRequest(proto.Message): list the taxonomies of. page_size (int): The maximum number of items to return. Must - be a value between 1 and 1000. If not set, - defaults to 50. + be a value between 1 and 1000 inclusively. If + not set, defaults to 50. page_token (str): - The next_page_token value returned from a previous list - request, if any. If not set, defaults to an empty string. + The pagination token of the next results + page. If not set, the first page is returned. + The token is returned in the response to a + previous list request. """ parent = proto.Field(proto.STRING, number=1,) @@ -248,9 +253,8 @@ class ListTaxonomiesResponse(proto.Message): taxonomies (Sequence[google.cloud.datacatalog_v1.types.Taxonomy]): Taxonomies that the project contains. next_page_token (str): - Token used to retrieve the next page of - results, or empty if there are no more results - in the list. + Pagination token of the next results page. + Empty if there are no more results in the list. """ @property @@ -267,8 +271,8 @@ class GetTaxonomyRequest(proto.Message): Attributes: name (str): - Required. Resource name of the requested - taxonomy. + Required. Resource name of the taxonomy to + get. """ name = proto.Field(proto.STRING, number=1,) @@ -281,9 +285,9 @@ class CreatePolicyTagRequest(proto.Message): Attributes: parent (str): Required. Resource name of the taxonomy that - the policy tag will belong to. + the policy tag will belong to.

policy_tag (google.cloud.datacatalog_v1.types.PolicyTag): - The policy tag to be created. + The policy tag to create. """ parent = proto.Field(proto.STRING, number=1,) @@ -297,8 +301,9 @@ class DeletePolicyTagRequest(proto.Message): Attributes: name (str): Required. Resource name of the policy tag to - be deleted. All of its descendant policy tags - will also be deleted. + delete. + Note: All of its descendant policy tags are also + deleted. """ name = proto.Field(proto.STRING, number=1,) @@ -310,18 +315,16 @@ class UpdatePolicyTagRequest(proto.Message): Attributes: policy_tag (google.cloud.datacatalog_v1.types.PolicyTag): - The policy tag to update. Only the description, - display_name, and parent_policy_tag fields can be updated. + The policy tag to update. You can update only + its description, display name, and parent policy + tag fields. update_mask (google.protobuf.field_mask_pb2.FieldMask): - The update mask applies to the resource. Only display_name, - description and parent_policy_tag can be updated and thus - can be listed in the mask. If update_mask is not provided, - all allowed fields (i.e. display_name, description and - parent) will be updated. For more information including the - ``FieldMask`` definition, see - https://developers.google.com/protocol-buffers/docs/reference/google.protobuf#fieldmask - If not set, defaults to all of the fields that are allowed - to update. + Specifies the fields to update. + + You can update only display name, description, and parent + policy tag. If not set, defaults to all updatable fields. + For more information, see [FieldMask] + (https://developers.google.com/protocol-buffers/docs/reference/google.protobuf#fieldmask). """ policy_tag = proto.Field(proto.MESSAGE, number=1, message="PolicyTag",) @@ -340,11 +343,14 @@ class ListPolicyTagsRequest(proto.Message): list the policy tags of. page_size (int): The maximum number of items to return. Must - be a value between 1 and 1000. If not set, - defaults to 50. + be a value between 1 and 1000 inclusively. + If not set, defaults to 50. page_token (str): - The next_page_token value returned from a previous List - request, if any. If not set, defaults to an empty string. + The pagination token of the next results + page. If not set, returns the first page. + + The token is returned in the response to a + previous list request. """ parent = proto.Field(proto.STRING, number=1,) @@ -358,12 +364,10 @@ class ListPolicyTagsResponse(proto.Message): Attributes: policy_tags (Sequence[google.cloud.datacatalog_v1.types.PolicyTag]): - The policy tags that are in the requested - taxonomy. + The policy tags that belong to the taxonomy. next_page_token (str): - Token used to retrieve the next page of - results, or empty if there are no more results - in the list. + Pagination token of the next results page. + Empty if there are no more results in the list. """ @property @@ -380,8 +384,7 @@ class GetPolicyTagRequest(proto.Message): Attributes: name (str): - Required. Resource name of the requested - policy tag. + Required. Resource name of the policy tag. """ name = proto.Field(proto.STRING, number=1,) diff --git a/google/cloud/datacatalog_v1/types/policytagmanagerserialization.py b/google/cloud/datacatalog_v1/types/policytagmanagerserialization.py index 17d84604..7f75d6d0 100644 --- a/google/cloud/datacatalog_v1/types/policytagmanagerserialization.py +++ b/google/cloud/datacatalog_v1/types/policytagmanagerserialization.py @@ -23,6 +23,7 @@ manifest={ "SerializedTaxonomy", "SerializedPolicyTag", + "ReplaceTaxonomyRequest", "ImportTaxonomiesRequest", "InlineSource", "CrossRegionalSource", @@ -34,8 +35,8 @@ class SerializedTaxonomy(proto.Message): - r"""Message representing a taxonomy, including its policy tags in - hierarchy, as a nested proto. Used for taxonomy replacement, + r"""A nested protocol buffer that represents a taxonomy and the + hierarchy of its policy tags. Used for taxonomy replacement, import, and export. Attributes: @@ -65,22 +66,21 @@ class SerializedTaxonomy(proto.Message): class SerializedPolicyTag(proto.Message): - r"""Message representing one policy tag, including all its - descendant policy tags, as a nested proto. + r"""A nested protocol buffer that represents a policy tag and all + its descendants. Attributes: policy_tag (str): Resource name of the policy tag. - This field will be ignored when calling - ImportTaxonomies. + + This field is ignored when calling ``ImportTaxonomies``. display_name (str): Required. Display name of the policy tag. At most 200 bytes when encoded in UTF-8. description (str): - Description of the serialized policy tag. The - length of the description is limited to 2000 - bytes when encoded in UTF-8. If not set, - defaults to an empty description. + Description of the serialized policy tag. At + most 2000 bytes when encoded in UTF-8. If not + set, defaults to an empty description. child_policy_tags (Sequence[google.cloud.datacatalog_v1.types.SerializedPolicyTag]): Children of the policy tag, if any. """ @@ -93,6 +93,25 @@ class SerializedPolicyTag(proto.Message): ) +class ReplaceTaxonomyRequest(proto.Message): + r"""Request message for + [ReplaceTaxonomy][google.cloud.datacatalog.v1.PolicyTagManagerSerialization.ReplaceTaxonomy]. + + Attributes: + name (str): + Required. Resource name of the taxonomy to + update. + serialized_taxonomy (google.cloud.datacatalog_v1.types.SerializedTaxonomy): + Required. Taxonomy to update along with its + child policy tags. + """ + + name = proto.Field(proto.STRING, number=1,) + serialized_taxonomy = proto.Field( + proto.MESSAGE, number=2, message="SerializedTaxonomy", + ) + + class ImportTaxonomiesRequest(proto.Message): r"""Request message for [ImportTaxonomies][google.cloud.datacatalog.v1.PolicyTagManagerSerialization.ImportTaxonomies]. @@ -102,10 +121,9 @@ class ImportTaxonomiesRequest(proto.Message): Required. Resource name of project that the imported taxonomies will belong to. inline_source (google.cloud.datacatalog_v1.types.InlineSource): - Inline source used for taxonomies import. + Inline source taxonomy to import. cross_regional_source (google.cloud.datacatalog_v1.types.CrossRegionalSource): - Cross-regional source taxonomy to be - imported. + Cross-regional source taxonomy to import. """ parent = proto.Field(proto.STRING, number=1,) @@ -121,7 +139,7 @@ class InlineSource(proto.Message): r"""Inline source containing taxonomies to import. Attributes: taxonomies (Sequence[google.cloud.datacatalog_v1.types.SerializedTaxonomy]): - Required. Taxonomies to be imported. + Required. Taxonomies to import. """ taxonomies = proto.RepeatedField( @@ -136,7 +154,7 @@ class CrossRegionalSource(proto.Message): Attributes: taxonomy (str): Required. The resource name of the source - taxonomy to be imported. + taxonomy to import. """ taxonomy = proto.Field(proto.STRING, number=1,) @@ -148,7 +166,7 @@ class ImportTaxonomiesResponse(proto.Message): Attributes: taxonomies (Sequence[google.cloud.datacatalog_v1.types.Taxonomy]): - Taxonomies that were imported. + Imported taxonomies. """ taxonomies = proto.RepeatedField( @@ -166,11 +184,10 @@ class ExportTaxonomiesRequest(proto.Message): the exported taxonomies belong to. taxonomies (Sequence[str]): Required. Resource names of the taxonomies to - be exported. + export. serialized_taxonomies (bool): - Export taxonomies as serialized taxonomies, - which contain all the policy tags as nested - protos. + Serialized export taxonomies that contain all + the policy tags as nested protocol buffers. """ parent = proto.Field(proto.STRING, number=1,) @@ -185,7 +202,7 @@ class ExportTaxonomiesResponse(proto.Message): Attributes: taxonomies (Sequence[google.cloud.datacatalog_v1.types.SerializedTaxonomy]): List of taxonomies and policy tags as nested - protos. + protocol buffers. """ taxonomies = proto.RepeatedField( diff --git a/google/cloud/datacatalog_v1/types/schema.py b/google/cloud/datacatalog_v1/types/schema.py index 2c1756b4..ba1def89 100644 --- a/google/cloud/datacatalog_v1/types/schema.py +++ b/google/cloud/datacatalog_v1/types/schema.py @@ -22,7 +22,9 @@ class Schema(proto.Message): - r"""Represents a schema (e.g. BigQuery, GoogleSQL, Avro schema). + r"""Represents a schema, for example, a BigQuery, GoogleSQL, or + Avro schema. + Attributes: columns (Sequence[google.cloud.datacatalog_v1.types.ColumnSchema]): The unified GoogleSQL-like schema of columns. @@ -35,8 +37,8 @@ class Schema(proto.Message): class ColumnSchema(proto.Message): - r"""Representation of a column within a schema. Columns could be - nested inside other columns. + r"""A column within a schema. Columns can be nested inside + other columns. Attributes: column (str): @@ -53,8 +55,8 @@ class ColumnSchema(proto.Message): The description must be a UTF-8 string with the maximum size of 2000 bytes. mode (str): - Optional. A column's mode indicates if values in this column - are required, nullable, or repeated. + Optional. A column's mode indicates whether values in this + column are required, nullable, or repeated. Only ``NULLABLE``, ``REQUIRED``, and ``REPEATED`` values are supported. Default mode is ``NULLABLE``. diff --git a/google/cloud/datacatalog_v1/types/search.py b/google/cloud/datacatalog_v1/types/search.py index 52c63d71..c4423e3e 100644 --- a/google/cloud/datacatalog_v1/types/search.py +++ b/google/cloud/datacatalog_v1/types/search.py @@ -26,9 +26,7 @@ class SearchResultType(proto.Enum): - r"""The different types of resources that can be returned in - search. - """ + r"""The resource types that can be returned in search results.""" SEARCH_RESULT_TYPE_UNSPECIFIED = 0 ENTRY = 1 TAG_TEMPLATE = 2 @@ -36,54 +34,66 @@ class SearchResultType(proto.Enum): class SearchCatalogResult(proto.Message): - r"""A result that appears in the response of a search request. + r"""Result in the response to a search request. Each result captures details of one entry that matches the search. Attributes: search_result_type (google.cloud.datacatalog_v1.types.SearchResultType): - Type of the search result. This field can be - used to determine which Get method to call to - fetch the full resource. + Type of the search result. + You can use this field to determine which get + method to call to fetch the full resource. search_result_subtype (str): - Sub-type of the search result. This is a dot-delimited - description of the resource's full type, and is the same as - the value callers would provide in the "type" search facet. + Sub-type of the search result. + + A dot-delimited full type of the resource. The same type you + specify in the ``type`` search predicate. + Examples: ``entry.table``, ``entry.dataStream``, ``tagTemplate``. relative_resource_name (str): - The relative resource name of the resource in URL format. + The relative name of the resource in URL format. + Examples: - - ``projects/{project_id}/locations/{location_id}/entryGroups/{entry_group_id}/entries/{entry_id}`` - - ``projects/{project_id}/tagTemplates/{tag_template_id}`` + - ``projects/{PROJECT_ID}/locations/{LOCATION_ID}/entryGroups/{ENTRY_GROUP_ID}/entries/{ENTRY_ID}`` + - ``projects/{PROJECT_ID}/tagTemplates/{TAG_TEMPLATE_ID}`` linked_resource (str): - The full name of the cloud resource the entry belongs to. - See: - https://cloud.google.com/apis/design/resource_names#full_resource_name. + The full name of the Google Cloud resource the entry belongs + to. + + For more information, see [Full Resource Name] + (/apis/design/resource_names#full_resource_name). + Example: - - ``//bigquery.googleapis.com/projects/projectId/datasets/datasetId/tables/tableId`` + ``//bigquery.googleapis.com/projects/PROJECT_ID/datasets/DATASET_ID/tables/TABLE_ID`` modify_time (google.protobuf.timestamp_pb2.Timestamp): - Last-modified timestamp of the entry from the - managing system. + The last modification timestamp of the entry + in the source system. integrated_system (google.cloud.datacatalog_v1.types.IntegratedSystem): - Output only. This field indicates the entry's - source system that Data Catalog integrates with, - such as BigQuery or Cloud Pub/Sub. + Output only. The source system that Data + Catalog automatically integrates with, such as + BigQuery, Cloud Pub/Sub, or Dataproc Metastore. user_specified_system (str): - This field indicates the entry's source - system that Data Catalog does not integrate - with. + Custom source system that you can manually + integrate Data Catalog with. fully_qualified_name (str): - Fully Qualified Name of the resource. There are two main - forms of FQNs: {system}:{project}.{dot-separated path to - resource} for non-regionalized resources - {system}:{project}.{location id}.{dot-separated path to - resource} for regionalized resources Examples: - - - dataproc_metastore:projectId.locationId.instanceId.databaseId.tableId - - bigquery:table.project_id.dataset_id.table_id + Fully qualified name (FQN) of the resource. + + FQNs take two forms: + + - For non-regionalized resources: + + ``{SYSTEM}:{PROJECT}.{PATH_TO_RESOURCE_SEPARATED_WITH_DOTS}`` + + - For regionalized resources: + + ``{SYSTEM}:{PROJECT}.{LOCATION_ID}.{PATH_TO_RESOURCE_SEPARATED_WITH_DOTS}`` + + Example for a DPMS table: + + ``dataproc_metastore:PROJECT_ID.LOCATION_ID.INSTANCE_ID.DATABASE_ID.TABLE_ID`` """ search_result_type = proto.Field(proto.ENUM, number=1, enum="SearchResultType",) diff --git a/google/cloud/datacatalog_v1/types/table_spec.py b/google/cloud/datacatalog_v1/types/table_spec.py index aed2af12..8b71c03f 100644 --- a/google/cloud/datacatalog_v1/types/table_spec.py +++ b/google/cloud/datacatalog_v1/types/table_spec.py @@ -42,11 +42,11 @@ class BigQueryTableSpec(proto.Message): table_source_type (google.cloud.datacatalog_v1.types.TableSourceType): Output only. The table source type. view_spec (google.cloud.datacatalog_v1.types.ViewSpec): - Table view specification. This field should only be - populated if ``table_source_type`` is ``BIGQUERY_VIEW``. + Table view specification. Populated only if the + ``table_source_type`` is ``BIGQUERY_VIEW``. table_spec (google.cloud.datacatalog_v1.types.TableSpec): - Spec of a BigQuery table. This field should only be - populated if ``table_source_type`` is ``BIGQUERY_TABLE``. + Specification of a BigQuery table. Populated only if the + ``table_source_type`` is ``BIGQUERY_TABLE``. """ table_source_type = proto.Field(proto.ENUM, number=1, enum="TableSourceType",) @@ -70,14 +70,16 @@ class ViewSpec(proto.Message): class TableSpec(proto.Message): - r"""Normal BigQuery table spec. + r"""Normal BigQuery table specification. Attributes: grouped_entry (str): - Output only. If the table is a dated shard, i.e., with name - pattern ``[prefix]YYYYMMDD``, ``grouped_entry`` is the Data - Catalog resource name of the date sharded grouped entry, for - example, - ``projects/{project_id}/locations/{location}/entrygroups/{entry_group_id}/entries/{entry_id}``. + Output only. If the table is date-sharded, that is, it + matches the ``[prefix]YYYYMMDD`` name pattern, this field is + the Data Catalog resource name of the date-sharded grouped + entry. For example: + + ``projects/{PROJECT_ID}/locations/{LOCATION}/entrygroups/{ENTRY_GROUP_ID}/entries/{ENTRY_ID}``. + Otherwise, ``grouped_entry`` is empty. """ @@ -85,20 +87,24 @@ class TableSpec(proto.Message): class BigQueryDateShardedSpec(proto.Message): - r"""Spec for a group of BigQuery tables with name pattern - ``[prefix]YYYYMMDD``. Context: - https://cloud.google.com/bigquery/docs/partitioned-tables#partitioning_versus_sharding + r"""Specification for a group of BigQuery tables with the + ``[prefix]YYYYMMDD`` name pattern. + + For more information, see [Introduction to partitioned tables] + (https://cloud.google.com/bigquery/docs/partitioned-tables#partitioning_versus_sharding). Attributes: dataset (str): Output only. The Data Catalog resource name of the dataset - entry the current table belongs to, for example, - ``projects/{project_id}/locations/{location}/entrygroups/{entry_group_id}/entries/{entry_id}``. + entry the current table belongs to. For example: + + ``projects/{PROJECT_ID}/locations/{LOCATION}/entrygroups/{ENTRY_GROUP_ID}/entries/{ENTRY_ID}``. table_prefix (str): - Output only. The table name prefix of the shards. The name - of any given shard is ``[table_prefix]YYYYMMDD``, for - example, for shard ``MyTable20180101``, the ``table_prefix`` - is ``MyTable``. + Output only. The table name prefix of the shards. + + The name of any given shard is ``[table_prefix]YYYYMMDD``. + For example, for the ``MyTable20180101`` shard, the + ``table_prefix`` is ``MyTable``. shard_count (int): Output only. Total number of shards. """ diff --git a/google/cloud/datacatalog_v1/types/tags.py b/google/cloud/datacatalog_v1/types/tags.py index 8b4fdae5..a7a4dcd1 100644 --- a/google/cloud/datacatalog_v1/types/tags.py +++ b/google/cloud/datacatalog_v1/types/tags.py @@ -25,8 +25,9 @@ class Tag(proto.Message): - r"""Tags are used to attach custom metadata to Data Catalog resources. - Tags conform to the specifications within their tag template. + r"""Tags contain custom metadata and are attached to Data Catalog + resources. Tags conform with the specification of their tag + template. See `Data Catalog IAM `__ for @@ -34,19 +35,15 @@ class Tag(proto.Message): Attributes: name (str): - The resource name of the tag in URL format. Example: - - ``projects/{project_id}/locations/{location}/entrygroups/{entry_group_id}/entries/{entry_id}/tags/{tag_id}`` - - where ``tag_id`` is a system-generated identifier. - - Note: The tag itself might not be stored in the location - specified in its name. + The resource name of the tag in URL format + where tag ID is a system-generated identifier. + Note: The tag itself might not be stored in the + location specified in its name. template (str): - Required. The resource name of the tag template that this - tag uses. Example: + Required. The resource name of the tag template this tag + uses. Example: - ``projects/{project_id}/locations/{location}/tagTemplates/{tag_template_id}`` + ``projects/{PROJECT_ID}/locations/{LOCATION}/tagTemplates/{TAG_TEMPLATE_ID}`` This field cannot be modified after creation. template_display_name (str): @@ -54,17 +51,18 @@ class Tag(proto.Message): template. column (str): Resources like entry can have schemas associated with them. - This scope allows users to attach tags to an individual - column based on that schema. + This scope allows you to attach tags to an individual column + based on that schema. To attach a tag to a nested column, separate column names with a dot (``.``). Example: ``column.nested_column``. fields (Sequence[google.cloud.datacatalog_v1.types.Tag.FieldsEntry]): - Required. This maps the ID of a tag field to - the value of and additional information about - that field. Valid field IDs are defined by the - tag's template. A tag must have at least 1 field - and at most 500 fields. + Required. Maps the ID of a tag field to its + value and additional information about that + field. + Tag template defines valid field IDs. A tag + must have at least 1 field and at most 500 + fields. """ name = proto.Field(proto.STRING, number=1,) @@ -75,41 +73,46 @@ class Tag(proto.Message): class TagField(proto.Message): - r"""Contains the value and supporting information for a field within a + r"""Contains the value and additional information on a field within a [Tag][google.cloud.datacatalog.v1.Tag]. Attributes: display_name (str): Output only. The display name of this field. double_value (float): - Holds the value for a tag field with double - type. + The value of a tag field with a double type. string_value (str): - Holds the value for a tag field with string - type. The maximum length is 2000 UTF-8 - characters. + The value of a tag field with a string type. + The maximum length is 2000 UTF-8 characters. bool_value (bool): - Holds the value for a tag field with boolean - type. + The value of a tag field with a boolean type. timestamp_value (google.protobuf.timestamp_pb2.Timestamp): - Holds the value for a tag field with - timestamp type. + The value of a tag field with a timestamp + type. enum_value (google.cloud.datacatalog_v1.types.TagField.EnumValue): - Holds the value for a tag field with enum - type. This value must be one of the allowed - values in the definition of this enum. + The value of a tag field with an enum type. + This value must be one of the allowed values + listed in this enum. + richtext_value (str): + The value of a tag field with a rich text + type. + The maximum length is 10 MiB as this value holds + HTML descriptions including encoded images. The + maximum length of the text without images is 100 + KiB. order (int): Output only. The order of this field with respect to other - fields in this tag. It can be set in + fields in this tag. Can be set by [Tag][google.cloud.datacatalog.v1.TagTemplateField.order]. + For example, a higher value can indicate a more important field. The value can be negative. Multiple fields can have - the same order, and field orders within a tag do not have to + the same order, and field orders within a tag don't have to be sequential. """ class EnumValue(proto.Message): - r"""Holds an enum value. + r"""An enum value. Attributes: display_name (str): The display name of the enum value. @@ -125,50 +128,87 @@ class EnumValue(proto.Message): proto.MESSAGE, number=5, oneof="kind", message=timestamp_pb2.Timestamp, ) enum_value = proto.Field(proto.MESSAGE, number=6, oneof="kind", message=EnumValue,) + richtext_value = proto.Field(proto.STRING, number=8, oneof="kind",) order = proto.Field(proto.INT32, number=7,) class TagTemplate(proto.Message): - r"""A tag template defines a tag, which can have one or more typed - fields. The template is used to create and attach the tag to GCP - resources. `Tag template - roles `__ - provide permissions to create, edit, and use the template. See, for - example, the `TagTemplate - User `__ - role, which includes permission to use the tag template to tag + r"""A tag template defines a tag that can have one or more typed fields. + + The template is used to create tags that are attached to GCP + resources. [Tag template roles] + (https://cloud.google.com/iam/docs/understanding-roles#data-catalog-roles) + provide permissions to create, edit, and use the template. For + example, see the [TagTemplate User] + (https://cloud.google.com/data-catalog/docs/how-to/template-user) + role that includes a permission to use the tag template to tag resources. Attributes: name (str): - The resource name of the tag template in URL format. - Example: - - ``projects/{project_id}/locations/{location}/tagTemplates/{tag_template_id}`` - - Note: The tag template itself and its child resources might - not be stored in the location specified in its name. + The resource name of the tag template in URL + format. + Note: The tag template itself and its child + resources might not be stored in the location + specified in its name. display_name (str): Display name for this template. Defaults to an empty string. The name must contain only Unicode letters, numbers (0-9), underscores (_), dashes (-), spaces ( ), and can't start or end with spaces. The maximum length is 200 characters. + is_publicly_readable (bool): + Indicates whether this is a public tag template. + + Every user has view access to a *public* tag template by + default. This means that: + + - Every user can use this tag template to tag an entry. + - If an entry is tagged using the tag template, the tag is + always shown in the response to ``ListTags`` called on + the entry. + - To get the template using the GetTagTemplate method, you + need view access either on the project or the + organization the tag template resides in but no other + permission is needed. + - Operations on the tag template other than viewing (for + example, editing IAM policies) follow standard IAM + structures. + + Tags created with a public tag template are referred to as + public tags. + + You can search for a public tag by value with a simple + search query instead of using a ``tag:`` predicate. + + Public tag templates may not appear in search results + depending on scope, see: + [include_public_tag_templates][google.cloud.datacatalog.v1.SearchCatalogRequest.Scope.include_public_tag_templates] + + Note: If an `IAM domain + restriction `__ + is configured in the tag template's location, the public + access will not be enabled but the simple search for tag + values will still work. fields (Sequence[google.cloud.datacatalog_v1.types.TagTemplate.FieldsEntry]): Required. Map of tag template field IDs to the settings for the field. This map is an exhaustive list of the allowed - fields. This map must contain at least one field and at most + fields. The map must contain at least one field and at most 500 fields. - The keys to this map are tag template field IDs. Field IDs - can contain letters (both uppercase and lowercase), numbers - (0-9) and underscores (_). Field IDs must be at least 1 - character long and at most 64 characters long. Field IDs - must start with a letter or underscore. + The keys to this map are tag template field IDs. The IDs + have the following limitations: + + - Can contain uppercase and lowercase letters, numbers + (0-9) and underscores (_). + - Must be at least 1 character and at most 64 characters + long. + - Must start with a letter or underscore. """ name = proto.Field(proto.STRING, number=1,) display_name = proto.Field(proto.STRING, number=2,) + is_publicly_readable = proto.Field(proto.BOOL, number=5,) fields = proto.MapField( proto.STRING, proto.MESSAGE, number=3, message="TagTemplateField", ) @@ -181,9 +221,9 @@ class TagTemplateField(proto.Message): Output only. The resource name of the tag template field in URL format. Example: - ``projects/{project_id}/locations/{location}/tagTemplates/{tag_template}/fields/{field}`` + ``projects/{PROJECT_ID}/locations/{LOCATION}/tagTemplates/{TAG_TEMPLATE}/fields/{FIELD}`` - Note: The ``TagTemplateField`` itself might not be stored in + Note: The tag template field itself might not be stored in the location specified in its name. The name must contain only letters (a-z, A-Z), numbers @@ -200,18 +240,20 @@ class TagTemplateField(proto.Message): Required. The type of value this tag field can contain. is_required (bool): - Whether this is a required field. Defaults to + If true, this field is required. Defaults to false. description (str): The description for this field. Defaults to an empty string. order (int): The order of this field with respect to other - fields in this tag template. For example, a - higher value can indicate a more important - field. The value can be negative. Multiple - fields can have the same order, and field orders - within a tag do not have to be sequential. + fields in this tag template. + + For example, a higher value can indicate a more + important field. The value can be negative. + Multiple fields can have the same order and + field orders within a tag don't have to be + sequential. """ name = proto.Field(proto.STRING, number=6,) @@ -226,10 +268,10 @@ class FieldType(proto.Message): r""" Attributes: primitive_type (google.cloud.datacatalog_v1.types.FieldType.PrimitiveType): - Represents primitive types - string, bool + Primitive types, such as string, boolean, etc. enum_type (google.cloud.datacatalog_v1.types.FieldType.EnumType): - Represents an enum type. + An enum type. """ class PrimitiveType(proto.Enum): @@ -239,6 +281,7 @@ class PrimitiveType(proto.Enum): STRING = 2 BOOL = 3 TIMESTAMP = 4 + RICHTEXT = 5 class EnumType(proto.Message): r""" @@ -252,9 +295,9 @@ class EnumType(proto.Message): set. The order of items in this set is preserved. This field can - be used to create, remove and reorder enum values. To rename - enum values, use the ``RenameTagTemplateFieldEnumValue`` - method. + be used to create, remove, and reorder enum values. To + rename enum values, use the + ``RenameTagTemplateFieldEnumValue`` method. """ class EnumValue(proto.Message): diff --git a/google/cloud/datacatalog_v1/types/timestamps.py b/google/cloud/datacatalog_v1/types/timestamps.py index 9c27d676..1501a311 100644 --- a/google/cloud/datacatalog_v1/types/timestamps.py +++ b/google/cloud/datacatalog_v1/types/timestamps.py @@ -24,20 +24,24 @@ class SystemTimestamps(proto.Message): - r"""Timestamps about this resource according to a particular + r"""Timestamps associated with this resource in a particular system. Attributes: create_time (google.protobuf.timestamp_pb2.Timestamp): - The creation time of the resource within the + Creation timestamp of the resource within the given system. update_time (google.protobuf.timestamp_pb2.Timestamp): - The last-modified time of the resource within - the given system. + Timestamp of the last modification of the + resource or its metadata within a given system. + Note: Depending on the source system, not every + modification updates this timestamp. + For example, BigQuery timestamps every metadata + modification but not data or permission changes. expire_time (google.protobuf.timestamp_pb2.Timestamp): - Output only. The expiration time of the - resource within the given system. Currently only - apllicable to BigQuery resources. + Output only. Expiration timestamp of the + resource within the given system. + Currently only applicable to BigQuery resources. """ create_time = proto.Field(proto.MESSAGE, number=1, message=timestamp_pb2.Timestamp,) diff --git a/google/cloud/datacatalog_v1/types/usage.py b/google/cloud/datacatalog_v1/types/usage.py new file mode 100644 index 00000000..ee389f88 --- /dev/null +++ b/google/cloud/datacatalog_v1/types/usage.py @@ -0,0 +1,80 @@ +# -*- coding: utf-8 -*- +# Copyright 2020 Google LLC +# +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. +# +import proto # type: ignore + +from google.protobuf import timestamp_pb2 # type: ignore + + +__protobuf__ = proto.module( + package="google.cloud.datacatalog.v1", manifest={"UsageStats", "UsageSignal",}, +) + + +class UsageStats(proto.Message): + r"""Detailed statistics on the entry's usage. + + Usage statistics have the following limitations: + + - Only BigQuery tables have them. + - They only include BigQuery query jobs. + - They might be underestimated because wildcard table references + are not yet counted. For more information, see [Querying multiple + tables using a wildcard table] + (https://cloud.google.com/bigquery/docs/querying-wildcard-tables) + + Attributes: + total_completions (float): + The number of successful uses of the + underlying entry. + total_failures (float): + The number of failed attempts to use the + underlying entry. + total_cancellations (float): + The number of cancelled attempts to use the + underlying entry. + total_execution_time_for_completions_millis (float): + Total time spent only on successful uses, in + milliseconds. + """ + + total_completions = proto.Field(proto.FLOAT, number=1,) + total_failures = proto.Field(proto.FLOAT, number=2,) + total_cancellations = proto.Field(proto.FLOAT, number=3,) + total_execution_time_for_completions_millis = proto.Field(proto.FLOAT, number=4,) + + +class UsageSignal(proto.Message): + r"""The set of all usage signals that Data Catalog stores. + Note: Usually, these signals are updated daily. In rare cases, + an update may fail but will be performed again on the next day. + + Attributes: + update_time (google.protobuf.timestamp_pb2.Timestamp): + The end timestamp of the duration of usage + statistics. + usage_within_time_range (Sequence[google.cloud.datacatalog_v1.types.UsageSignal.UsageWithinTimeRangeEntry]): + Usage statistics over each of the predefined time ranges. + + Supported time ranges are ``{"24H", "7D", "30D"}``. + """ + + update_time = proto.Field(proto.MESSAGE, number=1, message=timestamp_pb2.Timestamp,) + usage_within_time_range = proto.MapField( + proto.STRING, proto.MESSAGE, number=2, message="UsageStats", + ) + + +__all__ = tuple(sorted(__protobuf__.manifest)) diff --git a/scripts/fixup_datacatalog_v1_keywords.py b/scripts/fixup_datacatalog_v1_keywords.py index 38e83db3..2307fbfb 100644 --- a/scripts/fixup_datacatalog_v1_keywords.py +++ b/scripts/fixup_datacatalog_v1_keywords.py @@ -69,6 +69,7 @@ class datacatalogCallTransformer(cst.CSTTransformer): 'lookup_entry': ('linked_resource', 'sql_resource', 'fully_qualified_name', ), 'rename_tag_template_field': ('name', 'new_tag_template_field_id', ), 'rename_tag_template_field_enum_value': ('name', 'new_enum_value_display_name', ), + 'replace_taxonomy': ('name', 'serialized_taxonomy', ), 'search_catalog': ('scope', 'query', 'page_size', 'page_token', 'order_by', ), 'set_iam_policy': ('resource', 'policy', ), 'test_iam_permissions': ('resource', 'permissions', ), diff --git a/tests/unit/gapic/datacatalog_v1/test_data_catalog.py b/tests/unit/gapic/datacatalog_v1/test_data_catalog.py index e65c0b33..61bf032c 100644 --- a/tests/unit/gapic/datacatalog_v1/test_data_catalog.py +++ b/tests/unit/gapic/datacatalog_v1/test_data_catalog.py @@ -38,6 +38,7 @@ from google.cloud.datacatalog_v1.services.data_catalog.transports.base import ( _GOOGLE_AUTH_VERSION, ) +from google.cloud.datacatalog_v1.types import bigquery from google.cloud.datacatalog_v1.types import common from google.cloud.datacatalog_v1.types import data_source from google.cloud.datacatalog_v1.types import datacatalog @@ -47,6 +48,7 @@ from google.cloud.datacatalog_v1.types import table_spec from google.cloud.datacatalog_v1.types import tags from google.cloud.datacatalog_v1.types import timestamps +from google.cloud.datacatalog_v1.types import usage from google.iam.v1 import iam_policy_pb2 # type: ignore from google.iam.v1 import options_pb2 # type: ignore from google.iam.v1 import policy_pb2 # type: ignore @@ -3412,7 +3414,9 @@ def test_create_tag_template( ) as call: # Designate an appropriate return value for the call. call.return_value = tags.TagTemplate( - name="name_value", display_name="display_name_value", + name="name_value", + display_name="display_name_value", + is_publicly_readable=True, ) response = client.create_tag_template(request) @@ -3425,6 +3429,7 @@ def test_create_tag_template( assert isinstance(response, tags.TagTemplate) assert response.name == "name_value" assert response.display_name == "display_name_value" + assert response.is_publicly_readable is True def test_create_tag_template_from_dict(): @@ -3466,7 +3471,11 @@ async def test_create_tag_template_async( ) as call: # Designate an appropriate return value for the call. call.return_value = grpc_helpers_async.FakeUnaryUnaryCall( - tags.TagTemplate(name="name_value", display_name="display_name_value",) + tags.TagTemplate( + name="name_value", + display_name="display_name_value", + is_publicly_readable=True, + ) ) response = await client.create_tag_template(request) @@ -3479,6 +3488,7 @@ async def test_create_tag_template_async( assert isinstance(response, tags.TagTemplate) assert response.name == "name_value" assert response.display_name == "display_name_value" + assert response.is_publicly_readable is True @pytest.mark.asyncio @@ -3638,7 +3648,9 @@ def test_get_tag_template( with mock.patch.object(type(client.transport.get_tag_template), "__call__") as call: # Designate an appropriate return value for the call. call.return_value = tags.TagTemplate( - name="name_value", display_name="display_name_value", + name="name_value", + display_name="display_name_value", + is_publicly_readable=True, ) response = client.get_tag_template(request) @@ -3651,6 +3663,7 @@ def test_get_tag_template( assert isinstance(response, tags.TagTemplate) assert response.name == "name_value" assert response.display_name == "display_name_value" + assert response.is_publicly_readable is True def test_get_tag_template_from_dict(): @@ -3688,7 +3701,11 @@ async def test_get_tag_template_async( with mock.patch.object(type(client.transport.get_tag_template), "__call__") as call: # Designate an appropriate return value for the call. call.return_value = grpc_helpers_async.FakeUnaryUnaryCall( - tags.TagTemplate(name="name_value", display_name="display_name_value",) + tags.TagTemplate( + name="name_value", + display_name="display_name_value", + is_publicly_readable=True, + ) ) response = await client.get_tag_template(request) @@ -3701,6 +3718,7 @@ async def test_get_tag_template_async( assert isinstance(response, tags.TagTemplate) assert response.name == "name_value" assert response.display_name == "display_name_value" + assert response.is_publicly_readable is True @pytest.mark.asyncio @@ -3836,7 +3854,9 @@ def test_update_tag_template( ) as call: # Designate an appropriate return value for the call. call.return_value = tags.TagTemplate( - name="name_value", display_name="display_name_value", + name="name_value", + display_name="display_name_value", + is_publicly_readable=True, ) response = client.update_tag_template(request) @@ -3849,6 +3869,7 @@ def test_update_tag_template( assert isinstance(response, tags.TagTemplate) assert response.name == "name_value" assert response.display_name == "display_name_value" + assert response.is_publicly_readable is True def test_update_tag_template_from_dict(): @@ -3890,7 +3911,11 @@ async def test_update_tag_template_async( ) as call: # Designate an appropriate return value for the call. call.return_value = grpc_helpers_async.FakeUnaryUnaryCall( - tags.TagTemplate(name="name_value", display_name="display_name_value",) + tags.TagTemplate( + name="name_value", + display_name="display_name_value", + is_publicly_readable=True, + ) ) response = await client.update_tag_template(request) @@ -3903,6 +3928,7 @@ async def test_update_tag_template_async( assert isinstance(response, tags.TagTemplate) assert response.name == "name_value" assert response.display_name == "display_name_value" + assert response.is_publicly_readable is True @pytest.mark.asyncio diff --git a/tests/unit/gapic/datacatalog_v1/test_policy_tag_manager_serialization.py b/tests/unit/gapic/datacatalog_v1/test_policy_tag_manager_serialization.py index 8a0e69a0..58660995 100644 --- a/tests/unit/gapic/datacatalog_v1/test_policy_tag_manager_serialization.py +++ b/tests/unit/gapic/datacatalog_v1/test_policy_tag_manager_serialization.py @@ -45,6 +45,7 @@ ) from google.cloud.datacatalog_v1.types import policytagmanager from google.cloud.datacatalog_v1.types import policytagmanagerserialization +from google.cloud.datacatalog_v1.types import timestamps from google.oauth2 import service_account import google.auth @@ -537,6 +538,172 @@ def test_policy_tag_manager_serialization_client_client_options_from_dict(): ) +def test_replace_taxonomy( + transport: str = "grpc", + request_type=policytagmanagerserialization.ReplaceTaxonomyRequest, +): + client = PolicyTagManagerSerializationClient( + credentials=ga_credentials.AnonymousCredentials(), transport=transport, + ) + + # Everything is optional in proto3 as far as the runtime is concerned, + # and we are mocking out the actual API, so just send an empty request. + request = request_type() + + # Mock the actual call within the gRPC stub, and fake the request. + with mock.patch.object(type(client.transport.replace_taxonomy), "__call__") as call: + # Designate an appropriate return value for the call. + call.return_value = policytagmanager.Taxonomy( + name="name_value", + display_name="display_name_value", + description="description_value", + policy_tag_count=1715, + activated_policy_types=[ + policytagmanager.Taxonomy.PolicyType.FINE_GRAINED_ACCESS_CONTROL + ], + ) + response = client.replace_taxonomy(request) + + # Establish that the underlying gRPC stub method was called. + assert len(call.mock_calls) == 1 + _, args, _ = call.mock_calls[0] + assert args[0] == policytagmanagerserialization.ReplaceTaxonomyRequest() + + # Establish that the response is the type that we expect. + assert isinstance(response, policytagmanager.Taxonomy) + assert response.name == "name_value" + assert response.display_name == "display_name_value" + assert response.description == "description_value" + assert response.policy_tag_count == 1715 + assert response.activated_policy_types == [ + policytagmanager.Taxonomy.PolicyType.FINE_GRAINED_ACCESS_CONTROL + ] + + +def test_replace_taxonomy_from_dict(): + test_replace_taxonomy(request_type=dict) + + +def test_replace_taxonomy_empty_call(): + # This test is a coverage failsafe to make sure that totally empty calls, + # i.e. request == None and no flattened fields passed, work. + client = PolicyTagManagerSerializationClient( + credentials=ga_credentials.AnonymousCredentials(), transport="grpc", + ) + + # Mock the actual call within the gRPC stub, and fake the request. + with mock.patch.object(type(client.transport.replace_taxonomy), "__call__") as call: + client.replace_taxonomy() + call.assert_called() + _, args, _ = call.mock_calls[0] + assert args[0] == policytagmanagerserialization.ReplaceTaxonomyRequest() + + +@pytest.mark.asyncio +async def test_replace_taxonomy_async( + transport: str = "grpc_asyncio", + request_type=policytagmanagerserialization.ReplaceTaxonomyRequest, +): + client = PolicyTagManagerSerializationAsyncClient( + credentials=ga_credentials.AnonymousCredentials(), transport=transport, + ) + + # Everything is optional in proto3 as far as the runtime is concerned, + # and we are mocking out the actual API, so just send an empty request. + request = request_type() + + # Mock the actual call within the gRPC stub, and fake the request. + with mock.patch.object(type(client.transport.replace_taxonomy), "__call__") as call: + # Designate an appropriate return value for the call. + call.return_value = grpc_helpers_async.FakeUnaryUnaryCall( + policytagmanager.Taxonomy( + name="name_value", + display_name="display_name_value", + description="description_value", + policy_tag_count=1715, + activated_policy_types=[ + policytagmanager.Taxonomy.PolicyType.FINE_GRAINED_ACCESS_CONTROL + ], + ) + ) + response = await client.replace_taxonomy(request) + + # Establish that the underlying gRPC stub method was called. + assert len(call.mock_calls) + _, args, _ = call.mock_calls[0] + assert args[0] == policytagmanagerserialization.ReplaceTaxonomyRequest() + + # Establish that the response is the type that we expect. + assert isinstance(response, policytagmanager.Taxonomy) + assert response.name == "name_value" + assert response.display_name == "display_name_value" + assert response.description == "description_value" + assert response.policy_tag_count == 1715 + assert response.activated_policy_types == [ + policytagmanager.Taxonomy.PolicyType.FINE_GRAINED_ACCESS_CONTROL + ] + + +@pytest.mark.asyncio +async def test_replace_taxonomy_async_from_dict(): + await test_replace_taxonomy_async(request_type=dict) + + +def test_replace_taxonomy_field_headers(): + client = PolicyTagManagerSerializationClient( + credentials=ga_credentials.AnonymousCredentials(), + ) + + # Any value that is part of the HTTP/1.1 URI should be sent as + # a field header. Set these to a non-empty value. + request = policytagmanagerserialization.ReplaceTaxonomyRequest() + + request.name = "name/value" + + # Mock the actual call within the gRPC stub, and fake the request. + with mock.patch.object(type(client.transport.replace_taxonomy), "__call__") as call: + call.return_value = policytagmanager.Taxonomy() + client.replace_taxonomy(request) + + # Establish that the underlying gRPC stub method was called. + assert len(call.mock_calls) == 1 + _, args, _ = call.mock_calls[0] + assert args[0] == request + + # Establish that the field header was sent. + _, _, kw = call.mock_calls[0] + assert ("x-goog-request-params", "name=name/value",) in kw["metadata"] + + +@pytest.mark.asyncio +async def test_replace_taxonomy_field_headers_async(): + client = PolicyTagManagerSerializationAsyncClient( + credentials=ga_credentials.AnonymousCredentials(), + ) + + # Any value that is part of the HTTP/1.1 URI should be sent as + # a field header. Set these to a non-empty value. + request = policytagmanagerserialization.ReplaceTaxonomyRequest() + + request.name = "name/value" + + # Mock the actual call within the gRPC stub, and fake the request. + with mock.patch.object(type(client.transport.replace_taxonomy), "__call__") as call: + call.return_value = grpc_helpers_async.FakeUnaryUnaryCall( + policytagmanager.Taxonomy() + ) + await client.replace_taxonomy(request) + + # Establish that the underlying gRPC stub method was called. + assert len(call.mock_calls) + _, args, _ = call.mock_calls[0] + assert args[0] == request + + # Establish that the field header was sent. + _, _, kw = call.mock_calls[0] + assert ("x-goog-request-params", "name=name/value",) in kw["metadata"] + + def test_import_taxonomies( transport: str = "grpc", request_type=policytagmanagerserialization.ImportTaxonomiesRequest, @@ -930,6 +1097,7 @@ def test_policy_tag_manager_serialization_base_transport(): # Every method on the transport should just blindly # raise NotImplementedError. methods = ( + "replace_taxonomy", "import_taxonomies", "export_taxonomies", )