rgw/examples: adding info on boto3 extensions to docs

Signed-off-by: Yuval Lifshitz <yuvalif@yahoo.com>

diff --git a/doc/radosgw/s3/python.rst b/doc/radosgw/s3/python.rst
index a2c6a59d1d42bd5e5d44aeb301ce1e833d2db845..01777f75d74dcd43fae6fa6954ece919207c47b1 100644 (file)
--- a/doc/radosgw/s3/python.rst
+++ b/doc/radosgw/s3/python.rst
@@ -169,3 +169,18 @@ The output of this will look something like::
    http://objects.dreamhost.com/my-bucket-name/hello.txt
    http://objects.dreamhost.com/my-bucket-name/secret_plans.txt?Signature=XXXXXXXXXXXXXXXXXXXXXXXXXXX&Expires=1316027075&AWSAccessKeyId=XXXXXXXXXXXXXXXXXXX
 
+Using S3 API Extensions 
+-----------------------
+
+To use the boto3 client to tests the RadosGW extensions to the S3 API, the `extensions file`_ should be placed under: ``~/.aws/models/s3/2006-03-01/`` directory.
+For example, unordered list of objects could be fetched using:
+
+.. code-block:: python
+
+    print conn.list_objects(Bucket='my-new-bucket', AllowUnordered=True)
+
+
+Without the extensions file, in the above example, boto3 would complain that the ``AllowUnordered`` argument is invalid.
+
+
+.. _extensions file: https://github.com/ceph/ceph/blob/master/examples/examples/boto3/service-2.sdk-extras.json

diff --git a/examples/boto3/README.md b/examples/boto3/README.md
index fb73b32ccc8c569946ab4964e650899923fda245..2c285261d319f295b0ef66008d5f557b96dbd384 100644 (file)
--- a/examples/boto3/README.md
+++ b/examples/boto3/README.md
@@ -1,9 +1,27 @@
 # Introduction
-This directory contains examples on how to use boto3 to execrsize thew RadosGW extensions to the S3 API supported by AWS.
+This directory contains examples on how to use AWS CLI/boto3 to exercise the RadosGW extensions to the S3 API.
 
 # Users
-For the standard boto3 client to support these extensions, the: ``service-2.sdk-extras.json`` file should be placed under: ``~/.aws/models/s3/2006-03-01/`` directory.
+For the standard client to support these extensions, the: ``service-2.sdk-extras.json`` file should be placed under: ``~/.aws/models/s3/2006-03-01/`` directory.
 For more information see [here](https://github.com/boto/botocore/blob/develop/botocore/loaders.py#L33).
+## Python
+The [boto3 client](https://boto3.amazonaws.com/v1/documentation/api/latest/index.html) could be used with the extensions, code samples exists in this directory.
+## AWS CLI
+The standard [AWS CLI](https://docs.aws.amazon.com/cli/latest/) may also be used with these extensions. For example:
+- Unordered listing: 
+```
+aws --endpoint-url http://localhost:8000 s3api list-objects --bucket=mybucket --allow-unordered
+```
+- Bucket notifications with filtering extensions:
+```
+aws --region=default --endpoint-url http://localhost:8000 s3api put-bucket-notification-configuration --bucket mybucket --notification-configuration='{"TopicConfigurations": [{"Id": "notif1", "TopicArn": "arn:aws:sns:default::mytopic",  
+"Events": ["s3:ObjectCreated:*", "s3:ObjectRemoved:*"],  
+"Filter": {"Metadata": {"FilterRules": [{"Name": "x-amz-meta-foo", "Value": "bar"}, {"Name": "x-amz-meta-hello", "Value": "world"}]}, "Key": {"FilterRules": [{"Name": "regex", "Value": "([a-z]+)"}]}}}]}'
+ ```
+- Get configuration of a specific notification of a bucket:
+```
+aws --endpoint-url http://localhost:8000 s3api get-bucket-notification-configuration --bucket=mybucket --notification=notif1
+```
 
 # Developers
 Anyone developing an extension to the S3 API supported by AWS, please modify ``service-2.sdk-extras.json`` (all extensions should go into the same file), so that boto3 could be used to test the new API.