本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。
# GetObject (SOAP API)
**注意**
Amazon S3 的 SOAP API 不適用於新客戶，並且將於 2025 年 8 月 31 日接近生命週期結束 (EOL)。我們建議您使用 REST API 或 AWS SDKs。
`GetObject` 操作會傳回物件的目前版本。如果您嘗試`GetObject`使用具有刪除標記作為其目前版本的物件，S3 會傳回 404 錯誤。您無法使用 SOAP API 擷取物件的指定版本。若要這樣做，請使用 REST API。如需詳細資訊，請參閱[版本控制](https://docs.aws.amazon.com/AmazonS3/latest/userguide/Versioning.html)。如需更多選項，請使用 [GetObjectExtended (SOAP API)](SOAPGetObjectExtended.md)操作。
**注意**
[虛擬託管樣式要求](https://docs.aws.amazon.com/AmazonS3/latest/userguide/VirtualHosting.html#virtual-hosted-style-access)不支援值為「soap」的物件金鑰名稱。對於使用「soap」的物件金鑰名稱值，必須改用[路徑樣式 URL](https://docs.aws.amazon.com/AmazonS3/latest/userguide/VirtualHosting.html#path-style-access)。
**Example**
此範例會從「引號」儲存貯體取得「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，則會傳回以基底 64 編碼的資料，做為回應 SOAP 內文的一部分。如果為 false，則會將資料傳回為 SOAP 附件。InlineData 選項不適用於大型物件。系統會將此操作限制為使用 1MB 或更少的資料。如果產生的資料參數編碼超過 1MB，則具有 InlineData 旗標集的 GetObject 請求將使用`InlineDataTooLargeError`狀態碼失敗。若要下載大型物件，請考慮在未設定 InlineData 旗標的情況下呼叫 GetObject，或改用 REST API。
## 傳回的元素
+ `Metadata:` 與 物件一起存放的名稱值配對中繼資料。
+ `Data:` 如果 InlineData 在請求中為 true，則這包含基本 64 編碼的物件資料。
+ `LastModified:` 物件存放在 Amazon S3 中的時間。
+ `ETag:` 物件的實體標籤。這是物件的雜湊，可用於執行條件式取得。ETag 只會反映物件內容的變更，而不是其中繼資料。
## 存取控制
只有在您獲得物件的`READ`存取權時，才能讀取物件。
## SOAP 區塊和可繼續下載
為了提供`GET`彈性，Amazon S3 支援區塊和可繼續的下載。
從下列選取：
+ 對於大型物件下載，您可能想要將它們分成較小的區塊。如需詳細資訊，請參閱[範圍 GETs](#SOAPRangeGETs)
+ 對於失敗`GET`的操作，您可以設計應用程式來下載剩餘部分，而不是整個檔案。如需詳細資訊，請參閱[REST GET 錯誤復原](#SOAPGETErrorRecovery)
### 範圍 GETs
對於某些用戶端，您可能想要將大型下載分成較小的下載。若要將 GET 分成較小的單位，請使用範圍。
您必須先判斷 GET 的大小，才能將 GET 分成較小的單位。例如，以下請求會取得 bigfile 物件的大小。
```
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.
```
以下是從 Bigfile 物件下載第一個 MB 的請求。
```
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 會傳回檔案的第一個 MB 和檔案的 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`並在其餘檔案`GET`上執行範圍。如需詳細資訊，請參閱[GetObjectExtended (SOAP API)](SOAPGetObjectExtended.md)。
### 相關資源
[物件上的操作 (SOAP API)](SOAPObjectsOps.md)