def commit(self,
project_id,
mode,
mutations,
transaction=None,
options=None):
"""
Commits a transaction, optionally creating, deleting or modifying some
entities.
Example:
>>> from google.cloud.gapic.datastore.v1 import datastore_client
>>> from google.cloud.gapic.datastore.v1 import enums
>>> client = datastore_client.DatastoreClient()
>>> project_id = ''
>>> mode = enums.CommitRequest.Mode.MODE_UNSPECIFIED
>>> mutations = []
>>> response = client.commit(project_id, mode, mutations)
Args:
project_id (string): The ID of the project against which to make the request.
mode (enum :class:`google.cloud.gapic.datastore.v1.enums.CommitRequest.Mode`): The type of commit to perform. Defaults to ``TRANSACTIONAL``.
mutations (list[:class:`google.cloud.proto.datastore.v1.datastore_pb2.Mutation`]): The mutations to perform.
When mode is ``TRANSACTIONAL``, mutations affecting a single entity are
applied in order. The following sequences of mutations affecting a single
entity are not permitted in a single ``Commit`` request:
- ``insert`` followed by ``insert``
- ``update`` followed by ``insert``
- ``upsert`` followed by ``insert``
- ``delete`` followed by ``update``
When mode is ``NON_TRANSACTIONAL``, no two mutations may affect a single
entity.
transaction (bytes): The identifier of the transaction associated with the commit. A
transaction identifier is returned by a call to
``Datastore.BeginTransaction``.
options (:class:`google.gax.CallOptions`): Overrides the default
settings for this call, e.g, timeout, retries etc.
Returns:
A :class:`google.cloud.proto.datastore.v1.datastore_pb2.CommitResponse` instance.
Raises:
:exc:`google.gax.errors.GaxError` if the RPC is aborted.
:exc:`ValueError` if the parameters are invalid.
"""
# Sanity check: We have some fields which are mutually exclusive;
# raise ValueError if more than one is sent.
oneof.check_oneof(
transaction=transaction, )
# Create the request object.
request = datastore_pb2.CommitRequest(
project_id=project_id,
mode=mode,
mutations=mutations,
transaction=transaction)
return self._commit(request, options)
def get_document(self,
name,
mask=None,
transaction=None,
read_time=None,
options=None):
"""
Gets a single document.
Example:
>>> from google.cloud import firestore_v1beta1
>>>
>>> client = firestore_v1beta1.FirestoreClient()
>>>
>>> name = client.any_path_path('[PROJECT]', '[DATABASE]', '[DOCUMENT]', '[ANY_PATH]')
>>>
>>> response = client.get_document(name)
Args:
name (str): The resource name of the Document to get. In the format:
``projects/{project_id}/databases/{database_id}/documents/{document_path}``.
mask (Union[dict, ~google.cloud.firestore_v1beta1.types.DocumentMask]): The fields to return. If not set, returns all fields.
If the document has a field that is not present in this mask, that field
will not be returned in the response.
If a dict is provided, it must be of the same form as the protobuf
message :class:`~google.cloud.firestore_v1beta1.types.DocumentMask`
transaction (bytes): Reads the document in a transaction.
read_time (Union[dict, ~google.cloud.firestore_v1beta1.types.Timestamp]): Reads the version of the document at the given time.
This may not be older than 60 seconds.
If a dict is provided, it must be of the same form as the protobuf
message :class:`~google.cloud.firestore_v1beta1.types.Timestamp`
options (~google.gax.CallOptions): Overrides the default
settings for this call, e.g, timeout, retries etc.
Returns:
A :class:`~google.cloud.firestore_v1beta1.types.Document` instance.
Raises:
:exc:`google.gax.errors.GaxError` if the RPC is aborted.
:exc:`ValueError` if the parameters are invalid.
"""
# Sanity check: We have some fields which are mutually exclusive;
# raise ValueError if more than one is sent.
oneof.check_oneof(
transaction=transaction,
read_time=read_time,
)
request = firestore_pb2.GetDocumentRequest(name=name,
mask=mask,
transaction=transaction,
read_time=read_time)
return self._get_document(request, options)
def run_query(self,
project_id,
partition_id,
read_options,
query=None,
gql_query=None,
options=None):
"""
Queries for entities.
Example:
>>> from google.cloud.gapic.datastore.v1 import datastore_client
>>> from google.cloud.proto.datastore.v1 import datastore_pb2
>>> from google.cloud.proto.datastore.v1 import entity_pb2
>>> api = datastore_client.DatastoreClient()
>>> project_id = ''
>>> partition_id = entity_pb2.PartitionId()
>>> read_options = datastore_pb2.ReadOptions()
>>> response = api.run_query(project_id, partition_id, read_options)
Args:
project_id (string): The ID of the project against which to make the request.
partition_id (:class:`google.cloud.proto.datastore.v1.entity_pb2.PartitionId`): Entities are partitioned into subsets, identified by a partition ID.
Queries are scoped to a single partition.
This partition ID is normalized with the standard default context
partition ID.
read_options (:class:`google.cloud.proto.datastore.v1.datastore_pb2.ReadOptions`): The options for this query.
query (:class:`google.cloud.proto.datastore.v1.query_pb2.Query`): The query to run.
gql_query (:class:`google.cloud.proto.datastore.v1.query_pb2.GqlQuery`): The GQL query to run.
options (:class:`google.gax.CallOptions`): Overrides the default
settings for this call, e.g, timeout, retries etc.
Returns:
A :class:`google.cloud.proto.datastore.v1.datastore_pb2.RunQueryResponse` instance.
Raises:
:exc:`google.gax.errors.GaxError` if the RPC is aborted.
:exc:`ValueError` if the parameters are invalid.
"""
# Sanity check: We have some fields which are mutually exclusive;
# raise ValueError if more than one is sent.
oneof.check_oneof(
query=query,
gql_query=gql_query,
)
# Create the request object.
request = datastore_pb2.RunQueryRequest(project_id=project_id,
partition_id=partition_id,
read_options=read_options,
query=query,
gql_query=gql_query)
return self._run_query(request, options)
def seek(self, subscription, time=None, snapshot=None, options=None):
"""
Seeks an existing subscription to a point in time or to a given snapshot,
whichever is provided in the request.
Example:
>>> from google.cloud.gapic.pubsub.v1 import subscriber_client
>>> client = subscriber_client.SubscriberClient()
>>> subscription = client.subscription_path('[PROJECT]', '[SUBSCRIPTION]')
>>> response = client.seek(subscription)
Args:
subscription (string): The subscription to affect.
time (:class:`google.protobuf.timestamp_pb2.Timestamp`): The time to seek to.
Messages retained in the subscription that were published before this
time are marked as acknowledged, and messages retained in the
subscription that were published after this time are marked as
unacknowledged. Note that this operation affects only those messages
retained in the subscription (configured by the combination of
``message_retention_duration`` and ``retain_acked_messages``). For example,
if ``time`` corresponds to a point before the message retention
window (or to a point before the system's notion of the subscription
creation time), only retained messages will be marked as unacknowledged,
and already-expunged messages will not be restored.
snapshot (string): The snapshot to seek to. The snapshot's topic must be the same as that of
the provided subscription.
Format is ``projects/{project}/snapshots/{snap}``.
options (:class:`google.gax.CallOptions`): Overrides the default
settings for this call, e.g, timeout, retries etc.
Returns:
A :class:`google.cloud.proto.pubsub.v1.pubsub_pb2.SeekResponse` instance.
Raises:
:exc:`google.gax.errors.GaxError` if the RPC is aborted.
:exc:`ValueError` if the parameters are invalid.
"""
# Sanity check: We have some fields which are mutually exclusive;
# raise ValueError if more than one is sent.
oneof.check_oneof(
time=time,
snapshot=snapshot,
)
# Create the request object.
request = pubsub_pb2.SeekRequest(subscription=subscription,
time=time,
snapshot=snapshot)
return self._seek(request, options)
def seek(self, subscription, time=None, snapshot=None, options=None):
"""
Seeks an existing subscription to a point in time or to a given snapshot,
whichever is provided in the request.
Example:
>>> from google.cloud.gapic.pubsub.v1 import subscriber_client
>>> client = subscriber_client.SubscriberClient()
>>> subscription = client.subscription_path('[PROJECT]', '[SUBSCRIPTION]')
>>> response = client.seek(subscription)
Args:
subscription (string): The subscription to affect.
time (:class:`google.protobuf.timestamp_pb2.Timestamp`): The time to seek to.
Messages retained in the subscription that were published before this
time are marked as acknowledged, and messages retained in the
subscription that were published after this time are marked as
unacknowledged. Note that this operation affects only those messages
retained in the subscription (configured by the combination of
``message_retention_duration`` and ``retain_acked_messages``). For example,
if ``time`` corresponds to a point before the message retention
window (or to a point before the system's notion of the subscription
creation time), only retained messages will be marked as unacknowledged,
and already-expunged messages will not be restored.
snapshot (string): The snapshot to seek to. The snapshot's topic must be the same as that of
the provided subscription.
Format is ``projects/{project}/snapshots/{snap}``.
options (:class:`google.gax.CallOptions`): Overrides the default
settings for this call, e.g, timeout, retries etc.
Returns:
A :class:`google.cloud.proto.pubsub.v1.pubsub_pb2.SeekResponse` instance.
Raises:
:exc:`google.gax.errors.GaxError` if the RPC is aborted.
:exc:`ValueError` if the parameters are invalid.
"""
# Sanity check: We have some fields which are mutually exclusive;
# raise ValueError if more than one is sent.
oneof.check_oneof(
time=time,
snapshot=snapshot, )
# Create the request object.
request = pubsub_pb2.SeekRequest(
subscription=subscription, time=time, snapshot=snapshot)
return self._seek(request, options)
def test_check_failures(self):
with self.assertRaises(ValueError):
oneof.check_oneof(foo='bar', spam='eggs')
with self.assertRaises(ValueError):
oneof.check_oneof(foo='bar', baz='bacon', spam='eggs')
with self.assertRaises(ValueError):
oneof.check_oneof(foo='bar', spam=0, eggs=None)
def run_query(self,
parent,
structured_query=None,
transaction=None,
new_transaction=None,
read_time=None,
options=None):
"""
Runs a query.
Example:
>>> from google.cloud import firestore_v1beta1
>>>
>>> client = firestore_v1beta1.FirestoreClient()
>>>
>>> parent = client.any_path_path('[PROJECT]', '[DATABASE]', '[DOCUMENT]', '[ANY_PATH]')
>>>
>>> for element in client.run_query(parent):
... # process element
... pass
Args:
parent (str): The parent resource name. In the format:
``projects/{project_id}/databases/{database_id}/documents`` or
``projects/{project_id}/databases/{database_id}/documents/{document_path}``.
For example:
``projects/my-project/databases/my-database/documents`` or
``projects/my-project/databases/my-database/documents/chatrooms/my-chatroom``
structured_query (Union[dict, ~google.cloud.firestore_v1beta1.types.StructuredQuery]): A structured query.
If a dict is provided, it must be of the same form as the protobuf
message :class:`~google.cloud.firestore_v1beta1.types.StructuredQuery`
transaction (bytes): Reads documents in a transaction.
new_transaction (Union[dict, ~google.cloud.firestore_v1beta1.types.TransactionOptions]): Starts a new transaction and reads the documents.
Defaults to a read-only transaction.
The new transaction ID will be returned as the first response in the
stream.
If a dict is provided, it must be of the same form as the protobuf
message :class:`~google.cloud.firestore_v1beta1.types.TransactionOptions`
read_time (Union[dict, ~google.cloud.firestore_v1beta1.types.Timestamp]): Reads documents as they were at the given time.
This may not be older than 60 seconds.
If a dict is provided, it must be of the same form as the protobuf
message :class:`~google.cloud.firestore_v1beta1.types.Timestamp`
options (~google.gax.CallOptions): Overrides the default
settings for this call, e.g, timeout, retries etc.
Returns:
Iterable[~google.cloud.firestore_v1beta1.types.RunQueryResponse].
Raises:
:exc:`google.gax.errors.GaxError` if the RPC is aborted.
:exc:`ValueError` if the parameters are invalid.
"""
# Sanity check: We have some fields which are mutually exclusive;
# raise ValueError if more than one is sent.
oneof.check_oneof(structured_query=structured_query, )
# Sanity check: We have some fields which are mutually exclusive;
# raise ValueError if more than one is sent.
oneof.check_oneof(
transaction=transaction,
new_transaction=new_transaction,
read_time=read_time,
)
request = firestore_pb2.RunQueryRequest(
parent=parent,
structured_query=structured_query,
transaction=transaction,
new_transaction=new_transaction,
read_time=read_time)
return self._run_query(request, options)
def batch_get_documents(self,
database,
documents,
mask=None,
transaction=None,
new_transaction=None,
read_time=None,
options=None):
"""
Gets multiple documents.
Documents returned by this method are not guaranteed to be returned in the
same order that they were requested.
Example:
>>> from google.cloud import firestore_v1beta1
>>>
>>> client = firestore_v1beta1.FirestoreClient()
>>>
>>> database = client.database_root_path('[PROJECT]', '[DATABASE]')
>>> documents = []
>>>
>>> for element in client.batch_get_documents(database, documents):
... # process element
... pass
Args:
database (str): The database name. In the format:
``projects/{project_id}/databases/{database_id}``.
documents (list[str]): The names of the documents to retrieve. In the format:
``projects/{project_id}/databases/{database_id}/documents/{document_path}``.
The request will fail if any of the document is not a child resource of the
given ``database``. Duplicate names will be elided.
mask (Union[dict, ~google.cloud.firestore_v1beta1.types.DocumentMask]): The fields to return. If not set, returns all fields.
If a document has a field that is not present in this mask, that field will
not be returned in the response.
If a dict is provided, it must be of the same form as the protobuf
message :class:`~google.cloud.firestore_v1beta1.types.DocumentMask`
transaction (bytes): Reads documents in a transaction.
new_transaction (Union[dict, ~google.cloud.firestore_v1beta1.types.TransactionOptions]): Starts a new transaction and reads the documents.
Defaults to a read-only transaction.
The new transaction ID will be returned as the first response in the
stream.
If a dict is provided, it must be of the same form as the protobuf
message :class:`~google.cloud.firestore_v1beta1.types.TransactionOptions`
read_time (Union[dict, ~google.cloud.firestore_v1beta1.types.Timestamp]): Reads documents as they were at the given time.
This may not be older than 60 seconds.
If a dict is provided, it must be of the same form as the protobuf
message :class:`~google.cloud.firestore_v1beta1.types.Timestamp`
options (~google.gax.CallOptions): Overrides the default
settings for this call, e.g, timeout, retries etc.
Returns:
Iterable[~google.cloud.firestore_v1beta1.types.BatchGetDocumentsResponse].
Raises:
:exc:`google.gax.errors.GaxError` if the RPC is aborted.
:exc:`ValueError` if the parameters are invalid.
"""
# Sanity check: We have some fields which are mutually exclusive;
# raise ValueError if more than one is sent.
oneof.check_oneof(
transaction=transaction,
new_transaction=new_transaction,
read_time=read_time,
)
request = firestore_pb2.BatchGetDocumentsRequest(
database=database,
documents=documents,
mask=mask,
transaction=transaction,
new_transaction=new_transaction,
read_time=read_time)
return self._batch_get_documents(request, options)
def list_documents(self,
parent,
collection_id,
page_size=None,
order_by=None,
mask=None,
transaction=None,
read_time=None,
show_missing=None,
options=None):
"""
Lists documents.
Example:
>>> from google.cloud import firestore_v1beta1
>>> from google.gax import CallOptions, INITIAL_PAGE
>>>
>>> client = firestore_v1beta1.FirestoreClient()
>>>
>>> parent = client.any_path_path('[PROJECT]', '[DATABASE]', '[DOCUMENT]', '[ANY_PATH]')
>>> collection_id = ''
>>>
>>>
>>> # Iterate over all results
>>> for element in client.list_documents(parent, collection_id):
... # process element
... pass
>>>
>>> # Or iterate over results one page at a time
>>> for page in client.list_documents(parent, collection_id, options=CallOptions(page_token=INITIAL_PAGE)):
... for element in page:
... # process element
... pass
Args:
parent (str): The parent resource name. In the format:
``projects/{project_id}/databases/{database_id}/documents`` or
``projects/{project_id}/databases/{database_id}/documents/{document_path}``.
For example:
``projects/my-project/databases/my-database/documents`` or
``projects/my-project/databases/my-database/documents/chatrooms/my-chatroom``
collection_id (str): The collection ID, relative to ``parent``, to list. For example: ``chatrooms``
or ``messages``.
page_size (int): The maximum number of resources contained in the
underlying API response. If page streaming is performed per-
resource, this parameter does not affect the return value. If page
streaming is performed per-page, this determines the maximum number
of resources in a page.
order_by (str): The order to sort results by. For example: ``priority desc, name``.
mask (Union[dict, ~google.cloud.firestore_v1beta1.types.DocumentMask]): The fields to return. If not set, returns all fields.
If a document has a field that is not present in this mask, that field
will not be returned in the response.
If a dict is provided, it must be of the same form as the protobuf
message :class:`~google.cloud.firestore_v1beta1.types.DocumentMask`
transaction (bytes): Reads documents in a transaction.
read_time (Union[dict, ~google.cloud.firestore_v1beta1.types.Timestamp]): Reads documents as they were at the given time.
This may not be older than 60 seconds.
If a dict is provided, it must be of the same form as the protobuf
message :class:`~google.cloud.firestore_v1beta1.types.Timestamp`
show_missing (bool): If the list should show missing documents. A missing document is a
document that does not exist but has sub-documents. These documents will
be returned with a key but will not have fields, ``Document.create_time``,
or ``Document.update_time`` set.
Requests with ``show_missing`` may not specify ``where`` or
``order_by``.
options (~google.gax.CallOptions): Overrides the default
settings for this call, e.g, timeout, retries etc.
Returns:
A :class:`~google.gax.PageIterator` instance. By default, this
is an iterable of :class:`~google.cloud.firestore_v1beta1.types.Document` instances.
This object can also be configured to iterate over the pages
of the response through the `options` parameter.
Raises:
:exc:`google.gax.errors.GaxError` if the RPC is aborted.
:exc:`ValueError` if the parameters are invalid.
"""
# Sanity check: We have some fields which are mutually exclusive;
# raise ValueError if more than one is sent.
oneof.check_oneof(
transaction=transaction,
read_time=read_time,
)
request = firestore_pb2.ListDocumentsRequest(
parent=parent,
collection_id=collection_id,
page_size=page_size,
order_by=order_by,
mask=mask,
transaction=transaction,
read_time=read_time,
show_missing=show_missing)
return self._list_documents(request, options)
def commit(self,
session,
mutations,
transaction_id=None,
single_use_transaction=None,
options=None):
"""
Commits a transaction. The request includes the mutations to be
applied to rows in the database.
``Commit`` might return an ``ABORTED`` error. This can occur at any time;
commonly, the cause is conflicts with concurrent
transactions. However, it can also happen for a variety of other
reasons. If ``Commit`` returns ``ABORTED``, the caller should re-attempt
the transaction from the beginning, re-using the same session.
Example:
>>> from google.cloud import spanner_v1
>>>
>>> client = spanner_v1.SpannerClient()
>>>
>>> session = client.session_path('[PROJECT]', '[INSTANCE]', '[DATABASE]', '[SESSION]')
>>> mutations = []
>>>
>>> response = client.commit(session, mutations)
Args:
session (str): Required. The session in which the transaction to be committed is running.
mutations (list[Union[dict, ~google.cloud.spanner_v1.types.Mutation]]): The mutations to be executed when this transaction commits. All
mutations are applied atomically, in the order they appear in
this list.
If a dict is provided, it must be of the same form as the protobuf
message :class:`~google.cloud.spanner_v1.types.Mutation`
transaction_id (bytes): Commit a previously-started transaction.
single_use_transaction (Union[dict, ~google.cloud.spanner_v1.types.TransactionOptions]): Execute mutations in a temporary transaction. Note that unlike
commit of a previously-started transaction, commit with a
temporary transaction is non-idempotent. That is, if the
``CommitRequest`` is sent to Cloud Spanner more than once (for
instance, due to retries in the application, or in the
transport library), it is possible that the mutations are
executed more than once. If this is undesirable, use
``BeginTransaction`` and
``Commit`` instead.
If a dict is provided, it must be of the same form as the protobuf
message :class:`~google.cloud.spanner_v1.types.TransactionOptions`
options (~google.gax.CallOptions): Overrides the default
settings for this call, e.g, timeout, retries etc.
Returns:
A :class:`~google.cloud.spanner_v1.types.CommitResponse` instance.
Raises:
:exc:`google.gax.errors.GaxError` if the RPC is aborted.
:exc:`ValueError` if the parameters are invalid.
"""
# Sanity check: We have some fields which are mutually exclusive;
# raise ValueError if more than one is sent.
oneof.check_oneof(
transaction_id=transaction_id,
single_use_transaction=single_use_transaction, )
request = spanner_pb2.CommitRequest(
session=session,
mutations=mutations,
transaction_id=transaction_id,
single_use_transaction=single_use_transaction)
return self._commit(request, options)
def test_check_ok(self):
self.assertIsNone(oneof.check_oneof())
self.assertIsNone(oneof.check_oneof(foo='bar'))
self.assertIsNone(oneof.check_oneof(foo='bar', baz=None))
self.assertIsNone(oneof.check_oneof(foo=None, baz='bacon'))
self.assertIsNone(oneof.check_oneof(foo='bar', spam=None, eggs=None))
def list_groups(self,
name,
children_of_group=None,
ancestors_of_group=None,
descendants_of_group=None,
page_size=0,
options=None):
"""
Lists the existing groups.
Example:
>>> from google.cloud.gapic.monitoring.v3 import group_service_client
>>> from google.gax import CallOptions, INITIAL_PAGE
>>> api = group_service_client.GroupServiceClient()
>>> name = api.project_path('[PROJECT]')
>>>
>>> # Iterate over all results
>>> for element in api.list_groups(name):
>>> # process element
>>> pass
>>>
>>> # Or iterate over results one page at a time
>>> for page in api.list_groups(name, options=CallOptions(page_token=INITIAL_PAGE)):
>>> for element in page:
>>> # process element
>>> pass
Args:
name (string): The project whose groups are to be listed. The format is
``\"projects/{project_id_or_number}\"``.
children_of_group (string): A group name: ``\"projects/{project_id_or_number}/groups/{group_id}\"``.
Returns groups whose ``parentName`` field contains the group
name. If no groups have this parent, the results are empty.
ancestors_of_group (string): A group name: ``\"projects/{project_id_or_number}/groups/{group_id}\"``.
Returns groups that are ancestors of the specified group.
The groups are returned in order, starting with the immediate parent and
ending with the most distant ancestor. If the specified group has no
immediate parent, the results are empty.
descendants_of_group (string): A group name: ``\"projects/{project_id_or_number}/groups/{group_id}\"``.
Returns the descendants of the specified group. This is a superset of
the results returned by the ``childrenOfGroup`` filter, and includes
children-of-children, and so forth.
page_size (int): The maximum number of resources contained in the
underlying API response. If page streaming is performed per-
resource, this parameter does not affect the return value. If page
streaming is performed per-page, this determines the maximum number
of resources in a page.
options (:class:`google.gax.CallOptions`): Overrides the default
settings for this call, e.g, timeout, retries etc.
Returns:
A :class:`google.gax.PageIterator` instance. By default, this
is an iterable of :class:`google.cloud.proto.monitoring.v3.group_pb2.Group` instances.
This object can also be configured to iterate over the pages
of the response through the `CallOptions` parameter.
Raises:
:exc:`google.gax.errors.GaxError` if the RPC is aborted.
:exc:`ValueError` if the parameters are invalid.
"""
# Sanity check: We have some fields which are mutually exclusive;
# raise ValueError if more than one is sent.
oneof.check_oneof(
children_of_group=children_of_group,
ancestors_of_group=ancestors_of_group,
descendants_of_group=descendants_of_group,
)
# Create the request object.
request = group_service_pb2.ListGroupsRequest(
name=name,
children_of_group=children_of_group,
ancestors_of_group=ancestors_of_group,
descendants_of_group=descendants_of_group,
page_size=page_size)
return self._list_groups(request, options)