当前位置:   article > 正文

boto3用法

boto3

aws是Amazon Web Service的简写,它包括众多服务,其中最有名的两个是EC2和S3。
S3是Simple Storage Service的简写,它是一种对象存储的实现。

安装和配置

安装boto3和awscli:pip install boto3 awscli
配置aws:aws configure

根据提示输入access_key_id, secret_access_keyregion
其中access_key_id, secret_access_key的默认存储位置为:~/.aws/credentials

  1. [default]
  2. aws_access_key_id = YOUR_ACCESS_KEY
  3. aws_secret_access_key = YOUR_SECRET_KEY

region的存储位置为~/.aws/config:

  1. [default]
  2. region=us-east-1

快速开始

如下代码,首先创建一个s3服务,然后查看全部Bucket,最后上传一个文件。

  1. import boto3
  2. # Let's use Amazon S3
  3. s3 = boto3.resource('s3')
  4. # Print out bucket names
  5. for bucket in s3.buckets.all():
  6. print(bucket.name)
  7. # Upload a new file
  8. data = open('test.jpg', 'rb')
  9. s3.Bucket('my-bucket').put_object(Key='test.jpg', Body=data)

Code Examples

使用Bucket

创建bucket

如下函数封装boto3的create_bucket(),如果创建Bucket成功,返回True,否则返回False。

  1. import logging
  2. import boto3
  3. from botocore.exceptions import ClientError
  4. def create_bucket(bucket_name):
  5. s3 = boto3.client('s3')
  6. try
  7. s3.create_bucket(Bucket=bucket_name)
  8. except ClientError as e:
  9. logging.error(e)
  10. return False
  11. return True

列出bucket

  1. s3 = boto3.client('s3')
  2. response = s3.list_buckets()
  3. print('Existing buckets:')
  4. for bucket in response['Buckets']:
  5. print(f'{bucket["Name"]}')

上传文件

基本用法

s3提供了两种文件上传方式:upload_file()upload_fileobj()upload_file()会把一个大文件拆分成若干个chunk并行上传,因此upload_file()传输速率较快,它适用于上传内容已经确定的文件。upload_fileobj()可用于单线程上传一个二进制流。
upload_file()例子:

  1. import logging
  2. import boto3
  3. from botocore.exceptions import ClientError
  4. def upload_file(file_name, bucket, object_name=None):
  5. """Upload a file to an S3 bucket
  6. :param file_name: File to upload
  7. :param bucket: Bucket to upload to
  8. :param object_name: S3 object name. If not specified then file_name is used
  9. :return: True if file was uploaded, else False
  10. """
  11. # If S3 object_name was not specified, use file_name
  12. if object_name is None:
  13. object_name = file_name
  14. # Upload the file
  15. s3_client = boto3.client('s3')
  16. try:
  17. response = s3_client.upload_file(file_name, bucket, object_name)
  18. except ClientError as e:
  19. logging.error(e)
  20. return False
  21. return True

upload_fileobj()例子:

  1. s3 = boto3.client('s3')
  2. with open("FILE_NAME", "rb") as f:
  3. s3.upload_fileobj(f, "BUCKET_NAME", "OBJECT_NAME")

upload_fileobj()的文件参数只能是rb模式打开的文件。

Client、Bucket、Object三个类型都提供了upload_file()upload_fileobj()两个函数,每个类型提供的同一函数功能都是等价的,并无优劣之分,可以随意调用三个对象的上传文件函数。

ExtraArgs

ExtraArgs提供了上传文件的其它参数,这些参数可用于控制上传文件的读写权限、meta信息等。S3Transfer是一个非常重要的对象,它定义了传输过程中的许多参数,在
boto3.s3.transfer.S3Transfer.ALLOWED_UPLOAD_ARGS中,定义了ExtraArgs可用的参数列表。

  1. s3.upload_file(
  2. 'FILE_NAME', 'BUCKET_NAME', 'OBJECT_NAME',
  3. ExtraArgs={'Metadata': {'mykey': 'myvalue'}}
  4. )
  5. s3.upload_file(
  6. 'FILE_NAME', 'BUCKET_NAME', 'OBJECT_NAME',
  7. ExtraArgs={'ACL': 'public-read'}
  8. )
  9. s3.upload_file(
  10. 'FILE_NAME', 'BUCKET_NAME', 'OBJECT_NAME',
  11. ExtraArgs={
  12. 'GrantRead': 'uri="http://acs.amazonaws.com/groups/global/AllUsers"',
  13. 'GrantFullControl': 'id="01234567890abcdefg"',
  14. }
  15. )

上传过程的回调函数

一边上传一边打印上传进度可以通过实现Callback回调来实现。

  1. s3.upload_file(
  2. 'FILE_NAME', 'BUCKET_NAME', 'OBJECT_NAME',
  3. Callback=ProgressPercentage('FILE_NAME')
  4. )

ProgressPercentage

  1. import os
  2. import sys
  3. import threading
  4. class ProgressPercentage(object):
  5. def __init__(self, filename):
  6. self._filename = filename
  7. self._size = float(os.path.getsize(filename))
  8. self._seen_so_far = 0
  9. self._lock = threading.Lock()
  10. def __call__(self, bytes_amount):
  11. # To simplify, assume this is hooked up to a single filename
  12. with self._lock:
  13. self._seen_so_far += bytes_amount
  14. percentage = (self._seen_so_far / self._size) * 100
  15. sys.stdout.write(
  16. "\r%s %s / %s (%.2f%%)" % (
  17. self._filename, self._seen_so_far, self._size,
  18. percentage))
  19. sys.stdout.flush()
'
运行

下载文件

下载文件和上传文件几乎是完全对称的,Client、Bucket、Object三个对象提供了download_file()download_fileobj()download_file()是并行的,download_file_obj()是串行的,这两个函数同样提供了ExtraArgs和Callback参数。boto3.s3.transfer.S3Transfer.ALLOWED_DOWNLOAD_ARGS描述了下载过程的ExtraArgs的可用参数。

  1. import boto3
  2. s3 = boto3.client('s3')
  3. s3.download_file('BUCKET_NAME', 'OBJECT_NAME', 'FILE_NAME')
  4. with open('FILE_NAME', 'wb') as f:
  5. s3.download_fileobj('BUCKET_NAME', 'OBJECT_NAME', f)

传输配置

在上传文件、下载文件、复制文件过程中,AWS SDK会自动管理重试等网络配置。默认的网络配置可适用于大多数情况,只有特殊情境下才需要修改传输配置。
传输配置封装在 boto3.s3.transfer.TransferConfig对象中,upload_file()等函数都有一个Config参数接受一个TransferConfig对象。

修改multipart阈值

当使用upload_file()上传一个大文件时,如果文件大小超过了multipart_threshold,那么会启动多线程上传。

  1. import boto3
  2. from boto3.s3.transfer import TransferConfig
  3. # Set the desired multipart threshold value (5GB)
  4. GB = 1024 ** 3
  5. config = TransferConfig(multipart_threshold=5*GB)
  6. # Perform the transfer
  7. s3 = boto3.client('s3')
  8. s3.upload_file('FILE_NAME', 'BUCKET_NAME', 'OBJECT_NAME', Config=config)

设置并发数

对于upload_file()download_file()默认启用多线程下载,为了减少网络占用或者增加网络占用,可以通过传输配置来控制。

  1. # To consume less downstream bandwidth, decrease the maximum concurrency
  2. config = TransferConfig(max_concurrency=5)
  3. # Download an S3 object
  4. s3 = boto3.client('s3')
  5. s3.download_file('BUCKET_NAME', 'OBJECT_NAME', 'FILE_NAME', Config=config)

设置并发的实现方式

在boto3中,并发是通过多线程来实现的。如果不使用线程就没法实现并发,max_concurrency参数会被忽略掉。

  1. # Disable thread use/transfer concurrency
  2. config = TransferConfig(use_threads=False)
  3. s3 = boto3.client('s3')
  4. s3.download_file('BUCKET_NAME', 'OBJECT_NAME', 'FILE_NAME', Config=config)

将一个Bucket作为一个静态服务

获取一个桶的静态服务配置

  1. import boto3
  2. # Retrieve the website configuration
  3. s3 = boto3.client('s3')
  4. result = s3.get_bucket_website('BUCKET_NAME')

设置一个桶的静态服务配置

  1. # Define the website configuration
  2. website_configuration = {
  3. 'ErrorDocument': {'Key': 'error.html'},
  4. 'IndexDocument': {'Suffix': 'index.html'},
  5. }
  6. # Set the website configuration
  7. s3 = boto3.client('s3')
  8. s3.put_bucket_website('BUCKET_NAME', website_configuration)

删除一个桶的网站配置

  1. # Delete the website configuration
  2. s3 = boto3.client('s3')
  3. s3.delete_bucket_website('BUCKET_NAME')

获取一个Bucket的权限列表

  1. import boto3
  2. # Retrieve a bucket's ACL
  3. s3 = boto3.client('s3')
  4. result = s3.get_bucket_acl(Bucket='my-bucket')
  5. print(result)

presigned URL

分享一个Object

  1. import logging
  2. import boto3
  3. from botocore.exceptions import ClientError
  4. def create_presigned_url(bucket_name, object_name, expiration=3600):
  5. """Generate a presigned URL to share an S3 object
  6. :param bucket_name: string
  7. :param object_name: string
  8. :param expiration: Time in seconds for the presigned URL to remain valid
  9. :return: Presigned URL as string. If error, returns None.
  10. """
  11. # Generate a presigned URL for the S3 object
  12. s3_client = boto3.client('s3')
  13. try:
  14. response = s3_client.generate_presigned_url('get_object',
  15. Params={'Bucket': bucket_name,
  16. 'Key': object_name},
  17. ExpiresIn=expiration)
  18. except ClientError as e:
  19. logging.error(e)
  20. return None
  21. # The response contains the presigned URL
  22. return response

直接使用GET请求这个URL:

  1. import requests # To install: pip install requests
  2. url = create_presigned_url('BUCKET_NAME', 'OBJECT_NAME')
  3. if url is not None:
  4. response = requests.get(url)

其它技巧

桶策略

IAP:Identity&Access Policy

查询一个桶的权限

  1. import boto3
  2. # Retrieve the policy of the specified bucket
  3. s3 = boto3.client('s3')
  4. result = s3.get_bucket_policy('BUCKET_NAME')
  5. print(result['Policy'])

设置一个桶策略

  1. import json
  2. # Create a bucket policy
  3. bucket_name = 'BUCKET_NAME'
  4. bucket_policy = {
  5. 'Version': '2012-10-17',
  6. 'Statement': [{
  7. 'Sid': 'AddPerm',
  8. 'Effect': 'Allow',
  9. 'Principal': '*',
  10. 'Action': ['s3:GetObject'],
  11. 'Resource': f'arn:aws:s3:::{bucket_name}/*'
  12. }]
  13. }
  14. # Convert the policy from JSON dict to string
  15. bucket_policy = json.dumps(bucket_policy)
  16. # Set the new policy
  17. s3 = boto3.client('s3')
  18. s3.put_bucket_policy(bucket_name, Policy=bucket_policy)

删除桶策略

  1. # Delete a bucket's policy
  2. s3 = boto3.client('s3')
  3. s3.delete_bucket_policy('BUCKET_NAME')

重要包介绍

boto3根包

boto3根包提供了两类API:全局设置、重要入口类。
全局设置包括:

  • boto3.set_stream_logger(name='boto3', level=10, format_string=None)设置日志级别
  • boto3.setup_default_session(**kwargs)设置默认session

重要入口类包括:

  • boto3.resource(*args, **kwargs):最终会调用session包下的resource函数boto3.session.Session.resource()
  • boto3.client(*args, **kwargs):最终会调用session包下的resource函数boto3.session.Session.client()

collection包

boto3中的许多事物最终都可以看做一个集合,例如所有的Bucket构成一个集合,一个目录下的全部Object构成一个集合。collection包指的是boto3.resources.collection
collection包主要提供两个入口类:CollectionManagerResourceCollection。这两个类几乎具有完全一样的方法:

  • all():获取全部对象的迭代器
  • filter():过滤对象
  • limit(count):只读取count个对象
  • page_size(count)和pages()用于分页

resource包

boto3.resource包下内容较多,它包括请求和回复的格式等类型。
https://boto3.amazonaws.com/v1/documentation/api/latest/reference/core/resources.html

session包

boto3.session包只包含一个Session类,这个类是整个boto库的入口类。一个Session对象相当于一个包含了各种基础配置的对象(如aws_access_key_id、aws_secret_access_key等),利用此对象可以获取到Client、Resource等对象。
利用Session可以获取一些全局信息

  • get_available_partitions():获取可用分区列表
  • get_available_regions():获取可用region列表
  • available_profiles:获取可用的配置文件目录
  • get_available_regions(service_name, partition_name='aws', allow_non_regional=False):获取可用分区
  • get_available_resources():获取可用资源列表,也就是可以用sess.resource(service_name)函数获取的服务列表
  • get_awailable_services():获取可用服务列表,也就是可以用sess.client(service_name)函数获取的服务列表
  • get_credentials():和此session有关的秘钥,使用botocore.credential.Credential对象存储。

利用Session可以构建最重要的两个入口类:

  1. resource(service_name, region_name=None, api_version=None, use_ssl=True, verify=None, endpoint_url=None, aws_access_key_id=None, aws_secret_access_key=None, aws_session_token=None, config=None)
  2. client(service_name, region_name=None, api_version=None, use_ssl=True, verify=None, endpoint_url=None, aws_access_key_id=None, aws_secret_access_key=None, aws_session_token=None, config=None)

boto3.s3.transfer

boto3.s3.transfer包下包含两个类:TransferConfig和S3Transfer。TransferConfig对象可作为upload_file()的Config参数的取值;S3Transfer对象实现了upload_file()download_file(),实际上Client、Bucket、Object等类最终都会调用这两个函数,S3Transfer还提供了两个常量表示上传下载时可接受的参数:ALLOWED_DOWNLOAD_ARGS和ALLOWED_UPLOAD_ARGS。

  1. class boto3.s3.transfer.TransferConfig(multipart_threshold=8388608, max_concurrency=10, multipart_chunksize=8388608, num_download_attempts=5, max_io_queue=100, io_chunksize=262144, use_threads=True)
  2. class boto3.s3.transfer.S3Transfer(client=None, config=None, osutil=None, manager=None)
  3. ALLOWED_DOWNLOAD_ARGS = ['VersionId', 'SSECustomerAlgorithm', 'SSECustomerKey', 'SSECustomerKeyMD5', 'RequestPayer']
  4. ALLOWED_UPLOAD_ARGS = ['ACL', 'CacheControl', 'ContentDisposition', 'ContentEncoding', 'ContentLanguage', 'ContentType', 'Expires', 'GrantFullControl', 'GrantRead', 'GrantReadACP', 'GrantWriteACP', 'Metadata', 'RequestPayer', 'ServerSideEncryption', 'StorageClass', 'SSECustomerAlgorithm', 'SSECustomerKey', 'SSECustomerKeyMD5', 'SSEKMSKeyId', 'WebsiteRedirectLocation']
  5. download_file(bucket, key, filename, extra_args=None, callback=None)
  6. upload_file(filename, bucket, key, callback=None, extra_args=None)[source]

用户指南

boto3官网教程中的用户指南描述了boto3中的各个实体,是最终的文档。
https://boto3.amazonaws.com/v1/documentation/api/latest/guide/index.html

boto3提供了两个级别的接口来访问AWS服务:High Level的Resource级别的接口,Low Level的Client接口。
Client级别的接口返回Dictionary来表示查询到的资源信息,Resource级别的接口对Client级别的接口进行了面向对象的封装,接口的返回值大部分都是Resource对象(如果返回值是某个Resource的信息的话),我们可以对返回的对象再进行操作(比如删除,修改等)。

Resource

Resource对象是AWS服务的面向对象封装,它提供了比Client更抽象、更高级的封装。
每个Resource对象都包含若干属性和方法,这些属性和方法可以分为以下几大类别: identifiers, attributes, actions, references, sub-resources, 和 collections。
Resource对象可以被分为两类:

  • 服务对象(Service Resource):例如 sqs, s3, ec2
  • 独立对象(Indivisual Resource):例如sqs.Queue 、 s3.Bucket

服务对象和独立对象的区别在于:服务对象没有identifiers和attributes之类的属性和方法。

Collection

Collection对象和Django中的QuerySets非常像。

Client

Client对象提供了最底层的AWS服务封装,这些服务操作和AWS服务定义是一一对应的。实际上,Client类型的代码是由JSON形式的服务说明文件直接生成的。

Paginator分页

有些请求返回的对象太多,所以不能一次性全部返回,只能使用迭代的方式进行访问。
https://boto3.amazonaws.com/v1/documentation/api/latest/guide/paginators.html

Configuration

boto3会依次查找如下位置的配置,直到找到配置为止(也就是如下配置优先级递减):

  • boto.client()方法中的参数
  • 创建session时传递的参数
  • 环境变量
  • Shared credential file (~/.aws/credentials)
  • AWS config file (~/.aws/config)
  • Assume Role provider
  • Boto2 config file (/etc/boto.cfg and ~/.boto)
  • Instance metadata service on an Amazon EC2 instance that has an IAM role configured.

https://boto3.amazonaws.com/v1/documentation/api/latest/guide/configuration.html#configuration

使用技巧

content-range随机读取,相当于C语言中的fseek:https://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html#sec14.16

https://boto3.amazonaws.com/v1/documentation/api/latest/index.html

S3 API

转载于:https://www.cnblogs.com/weiyinfu/p/10993205.html

声明:本文内容由网友自发贡献,不代表【wpsshop博客】立场,版权归原作者所有,本站不承担相应法律责任。如您发现有侵权的内容,请联系我们。转载请注明出处:https://www.wpsshop.cn/w/神奇cpp/article/detail/917894
推荐阅读
相关标签
  

闽ICP备14008679号