Services or capabilities described in Amazon Web Services documentation might vary by Region. To see the differences applicable to the China Regions, see Getting Started with Amazon Web Services in China (PDF).

This documentation is for Version 1 of the Amazon CLI only. For documentation related to Version 2 of the Amazon CLI, see the Version 2 User Guide.

Using API-Level (s3api) commands in the Amazon CLI

The API-level commands (contained in the s3api command set) provide direct access to the Amazon Simple Storage Service (Amazon S3) APIs, and enable some operations that are not exposed in the high-level s3 commands. These commands are the equivalent of the other Amazon services that provide API-level access to the services' functionality. For more information on the s3 commands, see Using high-level (s3) commands in the Amazon CLI

This topic provides examples that demonstrate how to use the lower-level commands that map to the Amazon S3 APIs. In addition, you can find examples for each S3 API command in the s3api section of the Amazon CLI reference guide.

Prerequisites

To run the s3api commands, you need to:

Apply a custom ACL

With high-level commands, you can use the --acl option to apply predefined access control lists (ACLs) to Amazon S3 objects. But you can't use that command to set bucket-wide ACLs. However, you can do this by using the put-bucket-acl API-level command.

The following example shows how to grant full control to two Amazon users (user1@example.com and user2@example.com) and read permission to everyone. The identifier for "everyone" comes from a special URI that you pass as a parameter.

$ aws s3api put-bucket-acl --bucket amzn-s3-demo-bucket --grant-full-control 'emailaddress="user1@example.com",emailaddress="user2@example.com"' --grant-read 'uri="http://acs.amazonaws.com.cn/groups/global/AllUsers"'

For details about how to construct the ACLs, see PUT Bucket acl in the Amazon Simple Storage Service API Reference. The s3api ACL commands in the CLI, such as put-bucket-acl, use the same shorthand argument notation.

Configure a logging policy

The API command put-bucket-logging configures a bucket logging policy.

In the following example, the Amazon user user@example.com is granted full control over the log files, and all users have read access to them. Notice that the put-bucket-acl command is also required to grant the Amazon S3 log delivery system (specified by a URI) the permissions needed to read and write the logs to the bucket.

$ aws s3api put-bucket-acl --bucket amzn-s3-demo-bucket --grant-read-acp 'URI="http://acs.amazonaws.com.cn/groups/s3/LogDelivery"' --grant-write 'URI="http://acs.amazonaws.com.cn/groups/s3/LogDelivery"'
$ aws s3api put-bucket-logging --bucket amzn-s3-demo-bucket --bucket-logging-status file://logging.json

The logging.json file in the previous command has the following content.

{
  "LoggingEnabled": {
    "TargetBucket": "amzn-s3-demo-bucket",
    "TargetPrefix": "amzn-s3-demo-bucketLogs/",
    "TargetGrants": [
      {
        "Grantee": {
          "Type": "AmazonCustomerByEmail",
          "EmailAddress": "user@example.com"
        },
        "Permission": "FULL_CONTROL"
      },
      {
        "Grantee": {
          "Type": "Group",
          "URI": "http://acs.amazonaws.com.cn/groups/global/AllUsers"
        },
        "Permission": "READ"
      }
    ]
  }
}

Resources

Amazon CLI reference:

Service reference: