Debian Codegraph @

docs/source/guide/s3-presigned-urls.rst

raw
1 .. Copyright 2010-2019 Amazon.com, Inc. or its affiliates. All Rights Reserved.
2
3 This work is licensed under a Creative Commons Attribution-NonCommercial-ShareAlike 4.0
4 International License (the "License"). You may not use this file except in compliance with the
5 License. A copy of the License is located at http://creativecommons.org/licenses/by-nc-sa/4.0/.
6
7 This file is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND,
8 either express or implied. See the License for the specific language governing permissions and
9 limitations under the License.
10
11
12 ##############
13 Presigned URLs
14 ##############
15
16 A user who does not have AWS credentials or permission to access an S3 object
17 can be granted temporary access by using a presigned URL.
18
19 A presigned URL is generated by an AWS user who has access to the object. The
20 generated URL is then given to the unauthorized user. The presigned URL can be
21 entered in a browser or used by a program or HTML webpage. The credentials
22 used by the presigned URL are those of the AWS user who generated the URL.
23
24 A presigned URL remains valid for a limited period of time which is specified
25 when the URL is generated.
26
27 .. code-block:: python
28
29 import logging
30 import boto3
31 from botocore.exceptions import ClientError
32
33
34 def create_presigned_url(bucket_name, object_name, expiration=3600):
35 """Generate a presigned URL to share an S3 object
36
37 :param bucket_name: string
38 :param object_name: string
39 :param expiration: Time in seconds for the presigned URL to remain valid
40 :return: Presigned URL as string. If error, returns None.
41 """
42
43 # Generate a presigned URL for the S3 object
44 s3_client = boto3.client('s3')
45 try:
46 response = s3_client.generate_presigned_url(
47 'get_object',
48 Params={'Bucket': bucket_name, 'Key': object_name},
49 ExpiresIn=expiration,
50 )
51 except ClientError as e:
52 logging.error(e)
53 return None
54
55 # The response contains the presigned URL
56 return response
57
58 The user can download the S3 object by entering the presigned URL in a browser.
59 A program or HTML page can download the S3 object by using the presigned URL
60 as part of an HTTP GET request.
61
62 The following code demonstrates using the Python ``requests`` package to
63 perform a GET request.
64
65 .. code-block:: python
66
67 import requests # To install: pip install requests
68
69 url = create_presigned_url('amzn-s3-demo-bucket', 'OBJECT_NAME')
70 if url is not None:
71 response = requests.get(url)
72
73
74 Using presigned URLs to perform other S3 operations
75 ===================================================
76
77 The main purpose of presigned URLs is to grant a user temporary access to an
78 S3 object. However, presigned URLs can be used to grant permission to perform
79 additional operations on S3 buckets and objects.
80
81 The ``create_presigned_url_expanded`` method shown below generates a presigned
82 URL to perform a specified S3 operation. The method accepts the name of the S3
83 ``Client`` method to perform, such as 'list_buckets' or 'get_bucket_location.'
84 The parameters to pass to the method are specified in the
85 ``method_parameters`` dictionary argument. The HTTP method to use (GET, PUT,
86 etc.) can be specified, but the AWS SDK for Python will automatically select
87 the appropriate method so this argument is not normally required.
88
89 .. code-block:: python
90
91 import logging
92 import boto3
93 from botocore.exceptions import ClientError
94
95
96 def create_presigned_url_expanded(
97 client_method_name, method_parameters=None, expiration=3600, http_method=None
98 ):
99 """Generate a presigned URL to invoke an S3.Client method
100
101 Not all the client methods provided in the AWS Python SDK are supported.
102
103 :param client_method_name: Name of the S3.Client method, e.g., 'list_buckets'
104 :param method_parameters: Dictionary of parameters to send to the method
105 :param expiration: Time in seconds for the presigned URL to remain valid
106 :param http_method: HTTP method to use (GET, etc.)
107 :return: Presigned URL as string. If error, returns None.
108 """
109
110 # Generate a presigned URL for the S3 client method
111 s3_client = boto3.client('s3')
112 try:
113 response = s3_client.generate_presigned_url(
114 ClientMethod=client_method_name,
115 Params=method_parameters,
116 ExpiresIn=expiration,
117 HttpMethod=http_method,
118 )
119 except ClientError as e:
120 logging.error(e)
121 return None
122
123 # The response contains the presigned URL
124 return response
125
126
127 Generating a presigned URL to upload a file
128 ===========================================
129
130 A user who does not have AWS credentials to upload a file can use a
131 presigned URL to perform the upload. The upload operation makes an HTTP POST
132 request and requires additional parameters to be sent as part of the request.
133
134 .. code-block:: python
135
136 import logging
137 import boto3
138 from botocore.exceptions import ClientError
139
140
141 def create_presigned_post(
142 bucket_name, object_name, fields=None, conditions=None, expiration=3600
143 ):
144 """Generate a presigned URL S3 POST request to upload a file
145
146 :param bucket_name: string
147 :param object_name: string
148 :param fields: Dictionary of prefilled form fields
149 :param conditions: List of conditions to include in the policy
150 :param expiration: Time in seconds for the presigned URL to remain valid
151 :return: Dictionary with the following keys:
152 url: URL to post to
153 fields: Dictionary of form fields and values to submit with the POST
154 :return: None if error.
155 """
156
157 # Generate a presigned S3 POST URL
158 s3_client = boto3.client('s3')
159 try:
160 response = s3_client.generate_presigned_post(
161 bucket_name,
162 object_name,
163 Fields=fields,
164 Conditions=conditions,
165 ExpiresIn=expiration,
166 )
167 except ClientError as e:
168 logging.error(e)
169 return None
170
171 # The response contains the presigned URL and required fields
172 return response
173
174 The generated presigned URL includes both a URL and additional fields that
175 must be passed as part of the subsequent HTTP POST request.
176
177 The following code demonstrates how to use the ``requests`` package with a
178 presigned POST URL to perform a POST request to upload a file to S3.
179
180 .. code-block:: python
181
182 import requests # To install: pip install requests
183
184 # Generate a presigned S3 POST URL
185 object_name = 'OBJECT_NAME'
186 response = create_presigned_post('amzn-s3-demo-bucket', object_name)
187 if response is None:
188 exit(1)
189
190 # Demonstrate how another Python program can use the presigned URL to upload a file
191 with open(object_name, 'rb') as f:
192 files = {'file': (object_name, f)}
193 http_response = requests.post(response['url'], data=response['fields'], files=files)
194 # If successful, returns HTTP status code 204
195 logging.info(f'File upload HTTP status code: {http_response.status_code}')
196
197 The presigned POST URL and fields values can also be used in an HTML page.
198
199 .. code-block:: html
200
201 <html>
202 <head>
203 <meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
204 </head>
205 <body>
206 <!-- Copy the 'url' value returned by S3Client.generate_presigned_post() -->
207 <form action="URL_VALUE" method="post" enctype="multipart/form-data">
208 <!-- Copy the 'fields' key:values returned by S3Client.generate_presigned_post() -->
209 <input type="hidden" name="key" value="VALUE" />
210 <input type="hidden" name="AWSAccessKeyId" value="VALUE" />
211 <input type="hidden" name="policy" value="VALUE" />
212 <input type="hidden" name="signature" value="VALUE" />
213 File:
214 <input type="file" name="file" /> <br />
215 <input type="submit" name="submit" value="Upload to Amazon S3" />
216 </form>
217 </body>
218 </html>