# GetObject（SOAP API）
**注意**
Amazon S3 的 SOAP API 不适用于新客户，并将于 2025 年 8 月 31 日接近使用寿命终止（EOL）。我们建议您使用 REST API 或 Amazon SDK。
`GetObject` 操作返回对象的当前版本。如果您尝试对以删除标记作为其当前版本的对象执行 `GetObject`，S3 将返回 404 错误。您不能使用 SOAP API 来检索对象的指定版本。要执行这一操作，请使用 REST API。有关更多信息，请参阅[版本控制](https://docs.amazonaws.cn/AmazonS3/latest/userguide/Versioning.html)。有关更多选项，请使用 [GetObjectExtended（SOAP API）](SOAPGetObjectExtended.md)操作。
**注意**
对于[虚拟托管类型请求](https://docs.amazonaws.cn/AmazonS3/latest/userguide/VirtualHosting.html#virtual-hosted-style-access)，不支持值为“soap”的对象键名称。对于使用“soap”的对象键名称值，必须改用[路径类型 URL](https://docs.amazonaws.cn//AmazonS3/latest/userguide/VirtualHosting.html#path-style-access)。
**Example**
本示例从“quotes”存储桶获取“Nelson”对象。
`Sample Request`
```
1.
2. quotes
3. Nelson
4. true
5. true
6. true
7. AKIAIOSFODNN7EXAMPLE
8. 2006-03-01T12:00:00.183Z
9. Iuyz3d3P0aTou39dzbqaEXAMPLE=
10.
```
`Sample Response`
```
1.
2.
3.
4. 200
5. OK
6.
7.
8. Content-Type
9. text/plain
10.
11.
12. family
13. Muntz
14.
15. aGEtaGE=
16. 2006-01-01T12:00:00.000Z
17. "828ef3fdfa96f00ad9f27c383fc9ac7f"
18.
19.
```
## 元素
+ `Bucket:` 要从中检索对象的存储桶。
+ `Key:` 用于标识对象的键。
+ `GetMetadata:` 如果为 true，则元数据将随对象一起返回。
+ `GetData:` 如果为 true，则返回对象数据。
+ `InlineData:` 如果为 true，则以 base 64 编码的数据将作为响应的 SOAP 正文的一部分返回。如果为 false，则数据作为 SOAP 附件返回。InlineData 选项不适合用于大型对象。系统将此操作限制为处理 1 MB 或更小的数据。如果生成的 Data 参数编码后的大小超过 1 MB，则设置了 InlineData 标志的 GetObject 请求将失败并显示 `InlineDataTooLargeError` 状态代码。要下载大型对象，请考虑在不设置 InlineData 标志的情况下调用 GetObject，或者改用 REST API。
## 返回的元素
+ `Metadata:` 随对象一起存储的名称-值对元数据。
+ `Data:` 如果请求中 InlineData 为 true，则它包含以 base 64 编码的对象数据。
+ `LastModified:` 在 Amazon S3 中存储对象的时间。
+ `ETag:` 对象的实体标签。这是对象的哈希值，可用于执行有条件获取。ETag 仅反映对于对象内容的更改，而不反映对其元数据的更改。
## 访问控制
仅当被授予对象的 `READ` 访问权限后，您才能读取该对象。
## SOAP 分块下载和可恢复下载
为了提供 `GET` 灵活性，Amazon S3 支持分块下载和可恢复下载。
从以下各项中进行选择：
+ 对于大型对象下载，您可能希望将其分成较小的分块。有关更多信息，请参阅 [Range GET](#SOAPRangeGETs)。
+ 对于失败的 `GET` 操作，您可以将应用程序设计为下载剩余内容而不是整个文件。有关更多信息，请参阅 [REST GET 错误恢复](#SOAPGETErrorRecovery)。
### Range GET
对于某些客户端，您可能希望将大型下载分解为若干较小的下载。要将 GET 分解成较小的单位，请使用 Range。
在将 GET 分解为较小的单位之前，必须确定其大小。例如，以下请求获取大文件对象的大小。
```
1.
2. bigbucket
3. bigfile
4. 1
5. AKIAIOSFODNN7EXAMPLE
6. 2006-03-01T12:00:00.183Z
7. Iuyz3d3P0aTou39dzbqaEXAMPLE=
8.
```
Amazon S3 返回以下响应。
```
1.
2. quotes
3. N
4. 1
5. false
6.
7. bigfile
8. 2006-01-01T12:00:00.000Z
9. "828ef3fdfa96f00ad9f27c383fc9ac7f"
10. 2023276
11. STANDARD
12.
13. bcaf1ffd86f41161ca5fb16fd081034f
14. bigfile
15.
16.
17.
```
以下是从大文件对象下载第一个兆字节的请求。
```
1.
2. bigbucket
3. bigfile
4. true
5. true
6. true
7. 0
8. 1048576
9. AKIAIOSFODNN7EXAMPLE
10. 2006-03-01T12:00:00.183Z
11. Iuyz3d3P0aTou39dzbqaEXAMPLE=
12.
```
Amazon S3 返回文件的第一个兆字节和文件的 Etag。
```
1.
2.
3.
4. 200
5. OK
6.
7.
8. Content-Type
9. text/plain
10.
11.
12. family
13. Muntz
14.
15. --first megabyte of bigfile--
16. 2006-01-01T12:00:00.000Z
17. "828ef3fdfa96f00ad9f27c383fc9ac7f"
18.
19.
```
要确保文件在下载前面的部分后不会更改，请指定 IfMatch 元素。尽管 IfMatch 元素不是必需的，但对于可能发生变化的内容，建议使用该元素。
以下是使用 IfMatch 请求标头获取文件剩余部分的请求。
```
1.
2. bigbucket
3. bigfile
4. true
5. true
6. true
7. 10485761
8. 2023276
9. "828ef3fdfa96f00ad9f27c383fc9ac7f"
10. AKIAIOSFODNN7EXAMPLE
11. 2006-03-01T12:00:00.183Z
12. Iuyz3d3P0aTou39dzbqaEXAMPLE=
13.
```
Amazon S3 将返回以下响应和文件的剩余部分。
```
1.
2.
3.
4. 200
5. OK
6.
7.
8. Content-Type
9. text/plain
10.
11.
12. family
13. >Muntz
14.
15. --remainder of bigfile--
16. 2006-01-01T12:00:00.000Z
17. "828ef3fdfa96f00ad9f27c383fc9ac7f"
18.
19.
```
### 受版本控制的 GetObject
以下请求返回存储桶中对象的指定版本。
```
1.
2. quotes
3. Nelson
4. true
5. true
6. true
7. AKIAIOSFODNN7EXAMPLE
8. 2006-03-01T12:00:00.183Z
9. Iuyz3d3P0aTou39dzbqaEXAMPLE=
10.
```
示例响应
```
1.
2.
3.
4. 200
5. OK
6.
7.
8. Content-Type
9. text/plain
10.
11.
12. family
13. Muntz
14.
15. aGEtaGE=
16. 2006-01-01T12:00:00.000Z
17. "828ef3fdfa96f00ad9f27c383fc9ac7f"
18.
19.
```
### REST GET 错误恢复
如果对象 GET 失败，则可以通过指定要下载的范围来获取文件的剩余部分。为此，必须使用 `ListBucket` 获取对象的大小，并对文件的剩余部分执行 Range `GET`。有关更多信息，请参阅 [GetObjectExtended（SOAP API）](SOAPGetObjectExtended.md)。
### 相关资源
[针对对象的操作（SOAP API）](SOAPObjectsOps.md)