View a markdown version of this page

GetObject (SOAP API) - Amazon Simple Storage Service
元素傳回的元素存取控制SOAP 區塊和可繼續下載

本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。

GetObject (SOAP API)

注意

Amazon S3 的 SOAP API 不適用於新客戶，並且將於 2025 年 8 月 31 日接近生命週期結束 (EOL)。我們建議您使用 REST API 或 AWS SDKs。

GetObject 操作會傳回物件的目前版本。如果您嘗試GetObject使用具有刪除標記作為其目前版本的物件，S3 會傳回 404 錯誤。您無法使用 SOAP API 擷取物件的指定版本。若要這樣做，請使用 REST API。如需詳細資訊，請參閱版本控制。如需更多選項，請使用 GetObjectExtended (SOAP API)操作。

注意

虛擬託管樣式要求不支援值為「soap」的物件金鑰名稱。對於使用「soap」的物件金鑰名稱值，必須改用路徑樣式 URL。

範例

此範例會從「引號」儲存貯體取得「Nelson」物件。

Sample Request

<GetObject xmlns="https://doc.s3.amazonaws.com/2006-03-01">
  <Bucket>quotes</Bucket>
  <Key>Nelson</Key>
  <GetMetadata>true</GetMetadata>
  <GetData>true</GetData>
  <InlineData>true</InlineData>
  <AWSAccessKeyId>AKIAIOSFODNN7EXAMPLE</AWSAccessKeyId>
  <Timestamp>2006-03-01T12:00:00.183Z</Timestamp>
  <Signature>Iuyz3d3P0aTou39dzbqaEXAMPLE=</Signature>
</GetObject>

Sample Response

<GetObjectResponse xmlns="https://s3.amazonaws.com/doc/2006-03-01">
  <GetObjectResponse>
    <Status>
      <Code>200</Code>
      <Description>OK</Description>
    </Status>
    <Metadata>
      <Name>Content-Type</Name>
      <Value>text/plain</Value>
    </Metadata>
    <Metadata>
      <Name>family</Name>
      <Value>Muntz</Value>
    </Metadata>
    <Data>aGEtaGE=</Data>
    <LastModified>2006-01-01T12:00:00.000Z</LastModified>
    <ETag>&quot;828ef3fdfa96f00ad9f27c383fc9ac7f&quot;</ETag>
  </GetObjectResponse>
</GetObjectResponse>

元素

  • 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

  • 對於失敗GET的操作，您可以設計應用程式來下載剩餘部分，而不是整個檔案。如需詳細資訊，請參閱REST GET 錯誤復原

範圍 GETs

對於某些用戶端，您可能想要將大型下載分成較小的下載。若要將 GET 分成較小的單位，請使用範圍。

您必須先判斷 GET 的大小，才能將 GET 分成較小的單位。例如，以下請求會取得 bigfile 物件的大小。

<ListBucket xmlns="https://doc.s3.amazonaws.com/2006-03-01">
  <Bucket>bigbucket</Bucket>
  <Prefix>bigfile</Prefix>
  <MaxKeys>1</MaxKeys>
  <AWSAccessKeyId>AKIAIOSFODNN7EXAMPLE</AWSAccessKeyId>
  <Timestamp>2006-03-01T12:00:00.183Z</Timestamp>
  <Signature>Iuyz3d3P0aTou39dzbqaEXAMPLE=</Signature>
</ListBucket>

Amazon S3 傳回下列回應。

<ListBucketResult xmlns="https://s3.amazonaws.com/doc/2006-03-01">
  <Name>quotes</Name>
  <Prefix>N</Prefix>
  <MaxKeys>1</MaxKeys>
  <IsTruncated>false</IsTruncated>
  <Contents>
    <Key>bigfile</Key>
    <LastModified>2006-01-01T12:00:00.000Z</LastModified>
    <ETag>&quot;828ef3fdfa96f00ad9f27c383fc9ac7f&quot;</ETag>
    <Size>2023276</Size>
    <StorageClass>STANDARD</StorageClass>
    <Owner>
      <ID>bcaf1ffd86f41161ca5fb16fd081034f</ID>
      <DisplayName>bigfile</DisplayName>
     </Owner>
  </Contents>
</ListBucketResult>

以下是從 Bigfile 物件下載第一個 MB 的請求。

<GetObject xmlns="https://doc.s3.amazonaws.com/2006-03-01">
  <Bucket>bigbucket</Bucket>
  <Key>bigfile</Key>
  <GetMetadata>true</GetMetadata>
  <GetData>true</GetData>
  <InlineData>true</InlineData>
  <ByteRangeStart>0</ByteRangeStart>
  <ByteRangeEnd>1048576</ByteRangeEnd>
  <AWSAccessKeyId>AKIAIOSFODNN7EXAMPLE</AWSAccessKeyId>
  <Timestamp>2006-03-01T12:00:00.183Z</Timestamp>
  <Signature>Iuyz3d3P0aTou39dzbqaEXAMPLE=</Signature>
</GetObject>

Amazon S3 會傳回檔案的第一個 MB 和檔案的 Etag。

<GetObjectResponse xmlns="http://s3.amazonaws.com/doc/2006-03-01">
  <GetObjectResponse>
    <Status>
      <Code>200</Code>
      <Description>OK</Description>
    </Status>
    <Metadata>
      <Name>Content-Type</Name>
      <Value>text/plain</Value>
    </Metadata>
    <Metadata>
      <Name>family</Name>
      <Value>Muntz</Value>
    </Metadata>
    <Data>--first megabyte of bigfile--</Data>
    <LastModified>2006-01-01T12:00:00.000Z</LastModified>
    <ETag>"828ef3fdfa96f00ad9f27c383fc9ac7f"</ETag>
  </GetObjectResponse>
</GetObjectResponse>

若要確保檔案自上一個部分下載後沒有變更，請指定 IfMatch 元素。雖然不需要 IfMatch 元素，但建議用於可能變更的內容。

以下是使用 IfMatch 請求標頭取得檔案其餘部分的請求。

<GetObject xmlns="https://doc.s3.amazonaws.com/2006-03-01">
  <Bucket>bigbucket</Bucket>
  <Key>bigfile</Key>
  <GetMetadata>true</GetMetadata>
  <GetData>true</GetData>
  <InlineData>true</InlineData>
  <ByteRangeStart>10485761</ByteRangeStart>
  <ByteRangeEnd>2023276</ByteRangeEnd>
  <IfMatch>"828ef3fdfa96f00ad9f27c383fc9ac7f"</IfMatch>
  <AWSAccessKeyId>AKIAIOSFODNN7EXAMPLE</AWSAccessKeyId>
  <Timestamp>2006-03-01T12:00:00.183Z</Timestamp>
  <Signature>Iuyz3d3P0aTou39dzbqaEXAMPLE=</Signature>
</GetObject>

Amazon S3 會傳回下列回應和檔案的其餘部分。

<GetObjectResponse xmlns="http://s3.amazonaws.com/doc/2006-03-01">
  <GetObjectResponse>
    <Status>
      <Code>200</Code>
      <Description>OK</Description>
    </Status>
    <Metadata>
      <Name>Content-Type</Name>
      <Value>text/plain</Value>
    </Metadata>
    <Metadata>
      <Name>family</Name>
      <Value>>Muntz</Value>
    </Metadata>
    <Data>--remainder of bigfile--</Data>
    <LastModified>2006-01-01T12:00:00.000Z</LastModified>
    <ETag>"828ef3fdfa96f00ad9f27c383fc9ac7f"</ETag>
  </GetObjectResponse>
</GetObjectResponse>

版本化 GetObject

下列請求會傳回儲存貯體中指定版本的物件。

<GetObject xmlns="https://doc.s3.amazonaws.com/2006-03-01">
<Bucket>quotes</Bucket>
<Key>Nelson</Key>
<GetMetadata>true</GetMetadata>
<GetData>true</GetData>
<InlineData>true</InlineData>
<AWSAccessKeyId>AKIAIOSFODNN7EXAMPLE</AWSAccessKeyId>
<Timestamp>2006-03-01T12:00:00.183Z</Timestamp>
<Signature>Iuyz3d3P0aTou39dzbqaEXAMPLE=</Signature>
</GetObject>

回應範例

<GetObjectResponse xmlns="https://s3.amazonaws.com/doc/2006-03-01">
<GetObjectResponse>
<Status>
<Code>200</Code>
<Description>OK</Description>
</Status>
<Metadata>
<Name>Content-Type</Name>
<Value>text/plain</Value>
</Metadata>
<Metadata>
<Name>family</Name>
<Value>Muntz</Value>
</Metadata>
<Data>aGEtaGE=</Data>
<LastModified>2006-01-01T12:00:00.000Z</LastModified>
<ETag>&quot;828ef3fdfa96f00ad9f27c383fc9ac7f&quot;</ETag>
</GetObjectResponse>
</GetObjectResponse>

REST GET 錯誤復原

如果物件 GET 失敗，您可以透過指定要下載的範圍來取得其餘的檔案。若要這樣做，您必須使用 取得物件的大小，ListBucket並在其餘檔案GET上執行範圍。如需詳細資訊，請參閱GetObjectExtended (SOAP API)。

相關資源

物件上的操作 (SOAP API)