85 lines
2.4 KiB
ReStructuredText
85 lines
2.4 KiB
ReStructuredText
|
.. _guide_quickstart:
|
||
|
|
||
|
Quickstart
|
||
|
==========
|
||
|
Getting started with Boto 3 is easy, but requires a few steps.
|
||
|
|
||
|
Installation
|
||
|
------------
|
||
|
Install the latest Boto 3 release via :command:`pip`::
|
||
|
|
||
|
pip install boto3
|
||
|
|
||
|
You may also install a specific version::
|
||
|
|
||
|
pip install boto3==1.0.0
|
||
|
|
||
|
.. note::
|
||
|
|
||
|
The latest development version can always be found on
|
||
|
`GitHub <https://github.com/boto/boto3>`_.
|
||
|
|
||
|
Configuration
|
||
|
-------------
|
||
|
Before you can begin using Boto 3, you should set up authentication
|
||
|
credentials. Credentials for your AWS account can be found in the
|
||
|
`IAM Console <https://console.aws.amazon.com/iam/home>`_. You can
|
||
|
create or use an existing user. Go to manage access keys and
|
||
|
generate a new set of keys.
|
||
|
|
||
|
If you have the `AWS CLI <http://aws.amazon.com/cli/>`_
|
||
|
installed, then you can use it to configure your credentials file::
|
||
|
|
||
|
aws configure
|
||
|
|
||
|
Alternatively, you can create the credential file yourself. By default,
|
||
|
its location is at ``~/.aws/credentials``::
|
||
|
|
||
|
[default]
|
||
|
aws_access_key_id = YOUR_ACCESS_KEY
|
||
|
aws_secret_access_key = YOUR_SECRET_KEY
|
||
|
|
||
|
You may also want to set a default region. This can be done in the
|
||
|
configuration file. By default, its location is at ``~/.aws/config``::
|
||
|
|
||
|
[default]
|
||
|
region=us-east-1
|
||
|
|
||
|
Alternatively, you can pass a ``region_name`` when creating clients
|
||
|
and resources.
|
||
|
|
||
|
This sets up credentials for the default profile as well as a default
|
||
|
region to use when creating connections. See
|
||
|
:ref:`guide_configuration` for in-depth configuration sources and
|
||
|
options.
|
||
|
|
||
|
Using Boto 3
|
||
|
------------
|
||
|
To use Boto 3, you must first import it and tell it what service you are
|
||
|
going to use::
|
||
|
|
||
|
import boto3
|
||
|
|
||
|
# Let's use Amazon S3
|
||
|
s3 = boto3.resource('s3')
|
||
|
|
||
|
Now that you have an ``s3`` resource, you can make requests and process
|
||
|
responses from the service. The following uses the ``buckets`` collection
|
||
|
to print out all bucket names::
|
||
|
|
||
|
# Print out bucket names
|
||
|
for bucket in s3.buckets.all():
|
||
|
print(bucket.name)
|
||
|
|
||
|
It's also easy to upload and download binary data. For example, the
|
||
|
following uploads a new file to S3. It assumes that the bucket ``my-bucket``
|
||
|
already exists::
|
||
|
|
||
|
# Upload a new file
|
||
|
data = open('test.jpg', 'rb')
|
||
|
s3.Bucket('my-bucket').put_object(Key='test.jpg', Body=data)
|
||
|
|
||
|
:ref:`guide_resources` and :ref:`guide_collections` will be covered in more
|
||
|
detail in the following sections, so don't worry if you do not completely
|
||
|
understand the examples.
|