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.
|