GetObject（SOAP API）

注意

Amazon S3 的 SOAP API 不适用于新客户，并将于 2025 年 8 月 31 日接近使用寿命终止（EOL）。我们建议您使用 REST API 或 Amazon SDK。

GetObject 操作返回对象的当前版本。如果您尝试对以删除标记作为其当前版本的对象执行 GetObject，S3 将返回 404 错误。您不能使用 SOAP API 来检索对象的指定版本。要执行这一操作，请使用 REST API。有关更多信息，请参阅版本控制。有关更多选项，请使用 GetObjectExtended（SOAP API）操作。

注意

对于虚拟托管类型请求，不支持值为“soap”的对象键名称。对于使用“soap”的对象键名称值，必须改用路径类型 URL。

例

本示例从“quotes”存储桶获取“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，则以 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。
对于失败的 GET 操作，您可以将应用程序设计为下载剩余内容而不是整个文件。有关更多信息，请参阅 REST GET 错误恢复。

Range GET

对于某些客户端，您可能希望将大型下载分解为若干较小的下载。要将 GET 分解成较小的单位，请使用 Range。

在将 GET 分解为较小的单位之前，必须确定其大小。例如，以下请求获取大文件对象的大小。


<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>

以下是从大文件对象下载第一个兆字节的请求。


<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 返回文件的第一个兆字节和文件的 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 获取对象的大小，并对文件的剩余部分执行 Range GET。有关更多信息，请参阅 GetObjectExtended（SOAP API）。