Add 'list_hmac_keys' / 'create_hmac_key' methods to client. (#8043)

tseaver · tseaver · commit a36ceb796d8b · 2019-07-09T11:57:34.000-04:00
Toward #7851.
diff --git a/storage/google/cloud/storage/client.py b/storage/google/cloud/storage/client.py
@@ -26,6 +26,7 @@
 from google.cloud.storage.batch import Batch
 from google.cloud.storage.bucket import Bucket
 from google.cloud.storage.blob import Blob
+from google.cloud.storage.hmac_key import HMACKeyMetadata
 
 
 _marker = object()
@@ -561,6 +562,66 @@ def list_buckets(
             extra_params=extra_params,
         )
 
+    def create_hmac_key(self, service_account_email):
+        """Create an HMAC key for a service account.
+
+        :type service_account_email: str
+        :param service_account_email: e-mail address of the service account
+
+        :rtype:
+            Tuple[:class:`~google.cloud.storage.hmac_key.HMACKeyMetadata`, str]
+        :returns: metadata for the created key, plus the bytes of the key's secret, which is an 40-character base64-encoded string.
+        """
+        path = "/projects/%s/hmacKeys".format(self.project)
+        qs_params = {"serviceAccountEmail": service_account_email}
+        api_response = self._connection.api_request(
+            method="POST", path=path, query_params=qs_params
+        )
+        metadata = HMACKeyMetadata(self)
+        metadata._properties = api_response["metadata"]
+        secret = api_response["secret"]
+        return metadata, secret
+
+    def list_hmac_keys(
+        self, max_results=None, service_account_email=None, show_deleted_keys=None
+    ):
+        """List HMAC keys for a project.
+
+        :type max_results: int
+        :param max_results:
+            (Optional) max number of keys to return in a given page.
+
+        :type service_account_email: str
+        :param service_account_email:
+            (Optional) limit keys to those created by the given service account.
+
+        :type show_deleted_keys: bool
+        :param show_deleted_keys:
+            (Optional) included deleted keys in the list. Default is to
+            exclude them.
+
+        :rtype:
+            Tuple[:class:`~google.cloud.storage.hmac_key.HMACKeyMetadata`, str]
+        :returns: metadata for the created key, plus the bytes of the key's secret, which is an 40-character base64-encoded string.
+        """
+        path = "/projects/%s/hmacKeys".format(self.project)
+        extra_params = {}
+
+        if service_account_email is not None:
+            extra_params["serviceAccountEmail"] = service_account_email
+
+        if show_deleted_keys is not None:
+            extra_params["showDeletedKeys"] = show_deleted_keys
+
+        return page_iterator.HTTPIterator(
+            client=self,
+            api_request=self._connection.api_request,
+            path=path,
+            item_to_value=_item_to_hmac_key_metadata,
+            max_results=max_results,
+            extra_params=extra_params,
+        )
+
 
 def _item_to_bucket(iterator, item):
     """Convert a JSON bucket to the native object.
@@ -578,3 +639,20 @@ def _item_to_bucket(iterator, item):
     bucket = Bucket(iterator.client, name)
     bucket._set_properties(item)
     return bucket
+
+
+def _item_to_hmac_key_metadata(iterator, item):
+    """Convert a JSON key metadata resource to the native object.
+
+    :type iterator: :class:`~google.api_core.page_iterator.Iterator`
+    :param iterator: The iterator that has retrieved the item.
+
+    :type item: dict
+    :param item: An item to be converted to a key metadata instance.
+
+    :rtype: :class:`~google.cloud.storage.hmac_key.HMACKeyMetadata`
+    :returns: The next key metadata instance in the page.
+    """
+    metadata = HMACKeyMetadata(iterator.client)
+    metadata._properties = item
+    return metadata
diff --git a/storage/tests/unit/test_client.py b/storage/tests/unit/test_client.py
@@ -874,7 +874,7 @@ def test_list_buckets_all_arguments(self):
         uri_parts = urlparse(requested_url)
         self.assertEqual(parse_qs(uri_parts.query), expected_query)
 
-    def test_page_empty_response(self):
+    def test_list_buckets_page_empty_response(self):
         from google.api_core import page_iterator
 
         project = "PROJECT"
@@ -885,7 +885,7 @@ def test_page_empty_response(self):
         iterator._page = page
         self.assertEqual(list(page), [])
 
-    def test_page_non_empty_response(self):
+    def test_list_buckets_page_non_empty_response(self):
         import six
         from google.cloud.storage.bucket import Bucket
 
@@ -908,3 +908,138 @@ def dummy_response():
         self.assertEqual(page.remaining, 0)
         self.assertIsInstance(bucket, Bucket)
         self.assertEqual(bucket.name, blob_name)
+
+    def test_create_hmac_key(self):
+        import datetime
+        from pytz import UTC
+        from six.moves.urllib.parse import urlencode
+        from google.cloud.storage.hmac_key import HMACKeyMetadata
+
+        PROJECT = "PROJECT"
+        ACCESS_ID = "ACCESS-ID"
+        CREDENTIALS = _make_credentials()
+        EMAIL = "storage-user-123@example.com"
+        SECRET = "a" * 40
+        now = datetime.datetime.utcnow().replace(tzinfo=UTC)
+        now_stamp = "{}Z".format(now.isoformat())
+        RESOURCE = {
+            "kind": "storage#hmacKey",
+            "metadata": {
+                "accessId": ACCESS_ID,
+                "etag": "ETAG",
+                "id": "projects/{}/hmacKeys/{}".format(PROJECT, ACCESS_ID),
+                "project": PROJECT,
+                "state": "ACTIVE",
+                "serviceAccountEmail": EMAIL,
+                "timeCreated": now_stamp,
+                "updated": now_stamp,
+            },
+            "secret": SECRET,
+        }
+
+        client = self._make_one(project=PROJECT, credentials=CREDENTIALS)
+        http = _make_requests_session([_make_json_response(RESOURCE)])
+        client._http_internal = http
+
+        metadata, secret = client.create_hmac_key(service_account_email=EMAIL)
+
+        self.assertIsInstance(metadata, HMACKeyMetadata)
+        self.assertIs(metadata._client, client)
+        self.assertEqual(metadata._properties, RESOURCE["metadata"])
+        self.assertEqual(secret, RESOURCE["secret"])
+
+        URI = "/".join(
+            [
+                client._connection.API_BASE_URL,
+                "storage",
+                client._connection.API_VERSION,
+                "projects/%s/hmacKeys",
+            ]
+        )
+        QS_PARAMS = {"serviceAccountEmail": EMAIL}
+        FULL_URI = "{}?{}".format(URI, urlencode(QS_PARAMS))
+        http.request.assert_called_once_with(
+            method="POST", url=FULL_URI, data=None, headers=mock.ANY
+        )
+
+    def test_list_hmac_keys_defaults_empty(self):
+        PROJECT = "PROJECT"
+        CREDENTIALS = _make_credentials()
+        client = self._make_one(project=PROJECT, credentials=CREDENTIALS)
+
+        http = _make_requests_session([_make_json_response({})])
+        client._http_internal = http
+
+        metadatas = list(client.list_hmac_keys())
+
+        self.assertEqual(len(metadatas), 0)
+
+        URI = "/".join(
+            [
+                client._connection.API_BASE_URL,
+                "storage",
+                client._connection.API_VERSION,
+                "projects/%s/hmacKeys",
+            ]
+        )
+        http.request.assert_called_once_with(
+            method="GET", url=URI, data=None, headers=mock.ANY
+        )
+
+    def test_list_hmac_keys_explicit_non_empty(self):
+        from six.moves.urllib.parse import urlencode
+        from google.cloud.storage.hmac_key import HMACKeyMetadata
+
+        PROJECT = "PROJECT"
+        MAX_RESULTS = 3
+        EMAIL = "storage-user-123@example.com"
+        ACCESS_ID = "ACCESS-ID"
+        CREDENTIALS = _make_credentials()
+        client = self._make_one(project=PROJECT, credentials=CREDENTIALS)
+
+        response = {
+            "kind": "storage#hmacKeysMetadata",
+            "items": [
+                {
+                    "kind": "storage#hmacKeyMetadata",
+                    "accessId": ACCESS_ID,
+                    "serviceAccountEmail": EMAIL,
+                }
+            ],
+        }
+
+        http = _make_requests_session([_make_json_response(response)])
+        client._http_internal = http
+
+        metadatas = list(
+            client.list_hmac_keys(
+                max_results=MAX_RESULTS,
+                service_account_email=EMAIL,
+                show_deleted_keys=True,
+            )
+        )
+
+        self.assertEqual(len(metadatas), len(response["items"]))
+
+        for metadata, resource in zip(metadatas, response["items"]):
+            self.assertIsInstance(metadata, HMACKeyMetadata)
+            self.assertIs(metadata._client, client)
+            self.assertEqual(metadata._properties, resource)
+
+        URI = "/".join(
+            [
+                client._connection.API_BASE_URL,
+                "storage",
+                client._connection.API_VERSION,
+                "projects/%s/hmacKeys",
+            ]
+        )
+        QS_PARAMS = {
+            "maxResults": MAX_RESULTS,
+            "serviceAccountEmail": EMAIL,
+            "showDeletedKeys": True,
+        }
+        FULL_URI = "{}?{}".format(URI, urlencode(QS_PARAMS))
+        http.request.assert_called_once_with(
+            method="GET", url=FULL_URI, data=None, headers=mock.ANY
+        )
