WIP - Add documentation for bucket notification APIs.

minio · Sep 14, 2016 · c23d516 · c23d516
1 parent ba899ef
commit c23d516
Showing 1 changed file with 192 additions and 3 deletions.
diff --git a/docs/API.md b/docs/API.md
@@ -40,6 +40,9 @@ s3Client = Minio('s3.amazonaws.com',
 |[`list_incomplete_uploads`](#list_incomplete_uploads)   |  [`fput_object`](#fput_object) |   |
 | [`get_bucket_policy`](#get_bucket_policy) |[`fget_object`](#fget_object)  |  |
 | [`set_bucket_policy`](#set_bucket_policy) | [`get_partial_object`](#get_partial_object) |  |
+| [`get_bucket_notification`](#get_bucket_notification) |  |
+| [`set_bucket_notification`](#set_bucket_notification) |  |
+| [`remove_all_bucket_notifications`](#remove_all_bucket_notifications) |  |
 
 ## 1. Constructor
 
@@ -232,7 +235,7 @@ __Parameters__
 
 |Param   |Type   |Description   |
 |:---|:---|:---|
-|``bucketname``   | _string_|Name of the bucket.|
+|``bucket_name``   | _string_|Name of the bucket.|
 |``prefix``   |_string_ |The prefix of the incomplete objects uploaded should be listed. |
 |``recursive`` |_bool_ |``True`` indicates recursive style listing and ``False`` indicates directory style listing delimited by '/'. Optional default is ``False``.   |
 
@@ -270,7 +273,7 @@ __Parameters__
 
 |Param   |Type   |Description   |
 |:---|:---|:---|
-|``bucketname``   | _string_  |Name of the bucket.|
+|``bucket_name``   | _string_  |Name of the bucket.|
 |``prefix``   |_string_    |The prefix of objects to get current policy. |
 
 __Return Value__
@@ -302,7 +305,7 @@ __Parameters__
 
 |Param   |Type   |Description   |
 |:---|:---|:---|
-|``bucketname``   | _string_  |Name of the bucket.|
+|``bucket_name``   | _string_  |Name of the bucket.|
 |``prefix``   |_string_ |The prefix of objects to get current policy. |
 |``Policy``   | _minio.policy.Policy_   |Policy enum. Policy.READ_ONLY,Policy.WRITE_ONLY,Policy.READ_WRITE or Policy.NONE.   |
 
@@ -319,6 +322,192 @@ minioClient.set_bucket_policy('mybucket',
 
 ```
 
+<a name="get_bucket_notification"></a>
+### get_bucket_notification(bucket_name)
+
+Fetch the notifications configuration on a bucket.
+
+__Parameters__
+
+|Param   |Type   |Description   |
+|:---|:---|:---|
+|``bucket_name``   | _string_  |Name of the bucket.|
+
+__Return Value__
+
+|Param   |Type   |Description   |
+|:---|:---|:---|
+|``notification``   | _dict_   | If there is no notification configuration, an empty dictionary is returned. Otherwise it has the same structure as the argument to set_bucket_notification   |
+
+__Example__
+
+
+```py
+
+# Get the notifications configuration for a bucket.
+notification = minioClient.get_bucket_notification('mybucket')
+# If no notification is present on the bucket:
+# notification == {}
+
+```
+
+<a name="set_bucket_notification"></a>
+### set_bucket_notification(bucket_name, notification)
+
+Set notification configuration on a bucket.
+
+__Parameters__
+
+|Param   |Type   |Description   |
+|:---|:---|:---|
+|``bucket_name``   | _string_  |Name of the bucket.|
+|``notification``  | _dict_    |Non-empty dictionary with the structure specified below.|
+
+The `notification` argument has the following structure:
+
+* (dict) --
+  * __TopicConfigurations__ (list) -- Optional list of service
+    configuration items specifying AWS SNS Topics as the target of the
+    notification.
+  * __QueueConfigurations__ (list) -- Optional list of service
+    configuration items specifying AWS SQS Queues as the target of the
+    notification.
+  * __CloudFunctionconfigurations__ (list) -- Optional list of service
+    configuration items specifying AWS Lambda Cloud functions as the
+    target of the notification.
+
+At least one of the above items needs to be specified in the
+`notification` argument.
+
+The "service configuration item" alluded to above has the following structure:
+
+* (dict) --
+  * __Id__ (string) -- Optional Id for the configuration item. If not
+    specified, it is auto-generated by the server.
+  * __Arn__ (string) -- Specifies the particular Topic/Queue/Cloud
+    Function identifier.
+  * __Events__ (list) -- A non-empty list of event-type strings from:
+      _'s3:ReducedRedundancyLostObject'_
+      _'s3:ObjectCreated:*'_
+      _'s3:ObjectCreated:Put'_
+      _'s3:ObjectCreated:Post'_
+      _'s3:ObjectCreated:Copy'_
+      _'s3:ObjectCreated:CompleteMultipartUpload'_
+      _'s3:ObjectRemoved:*'_
+      _'s3:ObjectRemoved:Delete'_
+      _'s3:ObjectRemoved:DeleteMarkerCreated'_
+  * __Filter__ (dict) -- An optional dictionary container of object
+    key name based filter rules.
+    * __Key__ (dict) -- Dictionary container of object key name prefix
+      and suffix filtering rules.
+      * __FilterRules__ (list) -- A list of containers that specify
+        the criteria for the filter rule.
+        * (dict) -- A dictionary container of key value pairs that
+          specify a single filter rule.
+          * __Name__ (string) -- Object key name with value 'prefix'
+            or 'suffix'.
+          * __Value__ (string) -- Specify the value of the
+            prefix/suffix to which the rule applies.
+
+
+There is no return value. If there are errors from the target
+server/service, a `ResponseError` is thrown. If there are validation
+errors, `InvalidArgumentError` or `TypeError` may be thrown. The input
+configuration cannot be empty - to delete the notification
+configuration on a bucket, use the `remove_all_bucket_notifications()`
+API.
+
+__Example__
+
+
+```py
+
+notification = {
+    'QueueConfigurations': [
+        {
+            'Id': '1',
+            'Arn': 'arn1',
+            'Events': ['s3:ObjectCreated:PutObject'],
+            'Filter': {
+                'Key': {
+                    'FilterRules': [
+                        {
+                            'Name': 'prefix',
+                            'Value': 'abc'
+                        }
+                    ]
+                }
+            }
+        }
+    ],
+    'TopicConfigurations': [
+        {
+            'Arn': 'arn2',
+            'Events': ['s3:ObjectCreated:PostObject'],
+            'Filter': {
+                'Key': {
+                    'FilterRules': [
+                        {
+                            'Name': 'suffix',
+                            'Value': '.jpg'
+                        }
+                    ]
+                }
+            }
+        }
+    ],
+    'CloudFunctionConfigurations': [
+        {
+            'Arn': 'arn3',
+            'Events': ['s3:ObjectCreated:DeleteObject'],
+            'Filter': {
+                'Key': {
+                    'FilterRules': [
+                        {
+                            'Name': 'suffix',
+                            'Value': '.jpg'
+                        }
+                    ]
+                }
+            }
+        }
+    ]
+}
+
+try:
+    minioClient.set_bucket_notification('mybucket', notification)
+except ResponseError:
+    # handle error response from service.
+    pass
+except (ArgumentError, TypeError):
+    # should happen only during development. Fix the notification argument
+    pass
+```
+
+<a name="remove_all_bucket_notifications"></a>
+### remove_all_bucket_notifications(bucket_name)
+
+Remove all notifications configured on the bucket.
+
+__Parameters__
+
+|Param   |Type   |Description   |
+|:---|:---|:---|
+|``bucket_name``   | _string_  |Name of the bucket.|
+
+There is no returned value. A `ResponseError` exception is thrown if
+the operation did not complete successfully.
+
+__Example__
+
+
+```py
+
+# Get the notifications configuration for a bucket.
+minioClient.remove_all_bucket_notifications('mybucket')
+
+```
+
 ## 3. Object operations
 <a name="get_object"></a>
 ### get_object(bucket_name, object_name)