Skip to content

Commit

Permalink
Add documentation for bucket notification APIs.
Browse files Browse the repository at this point in the history
  • Loading branch information
@donatello
donatello committed Sep 14, 2016
1 parent ba899ef commit 4e96068
Showing 1 changed file with 218 additions and 3 deletions.
221 changes: 218 additions & 3 deletions docs/API.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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`](#get_bucket_notification) | |
| [`remove_all_bucket_notifications`](#remove_all_bucket_notifications) | |

## 1. Constructor

Expand Down Expand Up @@ -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``. |

Expand Down Expand Up @@ -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__
Expand Down Expand Up @@ -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. |

Expand All @@ -319,6 +322,218 @@ 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 |
|:---|:---|:---|
|``Policy`` | _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)

Fetch the notifications 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:

``` python
{
'TopicConfigurations': [
{
'Id': 'string',
'Arn': 'string',
'Events': [
'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': {
'Key': {
'FilterRules': [
{
'Name': 'prefix'|'suffix',
'Value': 'string'
},
]
}
}
},
],
'QueueConfigurations': [
{
'Id': 'string',
'Arn': 'string',
'Events': [
'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': {
'Key': {
'FilterRules': [
{
'Name': 'prefix'|'suffix',
'Value': 'string'
},
]
}
}
},
],
'CloudFunctionConfigurations': [
{
'Id': 'string',
'Arn': 'string',
'Events': [
'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': {
'Key': {
'FilterRules': [
{
'Name': 'prefix'|'suffix',
'Value': 'string'
},
]
}
}
},
]
}

```

Three types of notifications are supported - AWS SNS, AWS SQS and AWS Lambda.

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)
Expand Down

0 comments on commit 4e96068

Please sign in to comment.