# `Aliyun.Oss.Bucket`

Bucket operations - basic operations.

Other operations can be found in:

- `Aliyun.Oss.Bucket.WORM`
- `Aliyun.Oss.Bucket.ACL`
- `Aliyun.Oss.Bucket.Lifecycle`
- `Aliyun.Oss.Bucket.Versioning`
- `Aliyun.Oss.Bucket.Replication`
- `Aliyun.Oss.Bucket.Policy`
- `Aliyun.Oss.Bucket.Inventory`
- `Aliyun.Oss.Bucket.Logging`
- `Aliyun.Oss.Bucket.Website`
- `Aliyun.Oss.Bucket.Referer`
- `Aliyun.Oss.Bucket.Tags`
- `Aliyun.Oss.Bucket.Encryption`
- `Aliyun.Oss.Bucket.RequestPayment`
- `Aliyun.Oss.Bucket.CORS`

# `delete_bucket`

```elixir
@spec delete_bucket(Aliyun.Oss.Config.t(), String.t(), keyword()) ::
  {:error, Exception.t()} | {:ok, Aliyun.Oss.Client.Response.t()}
```

DeleteBucket - deletes a bucket.

## Options

- `:headers` - Defaults to `%{}`

## Examples

    iex> Aliyun.Oss.Bucket.delete_bucket(config, "some-bucket")
    {:ok,
    %Aliyun.Oss.Client.Response{
      data: "",
      headers: %{
        "connection" => ["keep-alive"],
        "content-length" => ["0"],
        "date" => ["Fri, 11 Jan 2019 05:26:36 GMT"],
        "server" => ["AliyunOSS"],
        "x-oss-request-id" => ["5C38290C41F2DE32412A3A88"],
        "x-oss-server-time" => ["230"]
      }
    }}
    iex> Aliyun.Oss.Bucket.delete_bucket(config, "unknown-bucket")
    {:error,
    %Aliyun.Oss.Client.Error{
      status: 404,
      code: "NoSuchBucket",
      message: "The specified bucket does not exist.",
      details: %{
        "BucketName" => "unknown-bucket",
        "Code" => "NoSuchBucket",
        "EC" => "0015-00000101",
        "HostId" => "unknown-bucket.oss-cn-shenzhen.aliyuncs.com",
        "Message" => "The specified bucket does not exist.",
        "RecommendDoc" => "https://api.aliyun.com/troubleshoot?q=0015-00000101",
        "RequestId" => "5C3000000000000000000000"
      }
    }}

# `get_bucket`

```elixir
@spec get_bucket(Aliyun.Oss.Config.t(), String.t(), keyword()) ::
  {:error, Exception.t()} | {:ok, Aliyun.Oss.Client.Response.t()}
```

GetBucket (ListObjects) - lists the information about all objects in a bucket.

## Options

- `:query_params` - Defaults to `%{}`
- `:headers` - Defaults to `%{}`

## Examples

    iex> Aliyun.Oss.Bucket.get_bucket(config, "some-bucket", query_params: %{"prefix" => "foo/"})
    {:ok, %Aliyun.Oss.Client.Response{
        data: %{
          "ListBucketResult" => %{
            "Contents" => [
              %{
                "ETag" => ""D410293F000B000D00D"",
                "key" => "foo/bar",
                "LastModified" => "2018-09-12T02:59:41.000Z",
                "Owner" => %{"DislayName" => "11111111", "ID" => "11111111"},
                "Size" => "12345",
                "StorageClass" => "IA",
                "Type" => "Normal"
              },
              ...
            ],
            "Delimiter" => nil,
            "IsTruncated" => true,
            "Marker" => nil,
            "MaxKeys" => 100,
            "Name" => "some-bucket",
            "NextMarker" => "XXXXX",
            "Prefix" => "foo/"
          }
        },
        headers: %{
          "connection" => ["keep-alive"],
          ...
        }
      }
    }

    iex> Aliyun.Oss.Bucket.get_bucket(config, "unknown-bucket")
    {:error,
      %Aliyun.Oss.Client.Error{
        status: 404,
        code: "NoSuchBucket",
        message: "The specified bucket does not exist.",
        details: %{
          "BucketName" => "unknown-bucket",
          "Code" => "NoSuchBucket",
          "EC" => "0015-00000101",
          "HostId" => "unknown-bucket.oss-cn-shenzhen.aliyuncs.com",
          "Message" => "The specified bucket does not exist.",
          "RecommendDoc" => "https://api.aliyun.com/troubleshoot?q=0015-00000101",
          "RequestId" => "5BFF89955E29FF66F10B9763"
        }
      }
    }

# `get_bucket_info`

```elixir
@spec get_bucket_info(Aliyun.Oss.Config.t(), String.t()) ::
  {:error, Exception.t()} | {:ok, Aliyun.Oss.Client.Response.t()}
```

GetBucketInfo - gets the information about a bucket.

## Examples

    iex> Aliyun.Oss.Bucket.get_bucket_info(config, "some-bucket")
    {:ok, %Aliyun.Oss.Client.Response{
      data: %{
        "BucketInfo" => %{
          "Bucket" => %{
            "AccessControlList" => %{"Grant" => "private"},
            "AccessMonitor" => "Disabled",
            "BlockPublicAccess" => "false",
            "BucketPolicy" => %{"LogBucket" => nil, "LogPrefix" => nil},
            "Comment" => nil,
            "CreationDate" => "2018-08-29T01:52:03.000Z",
            "CrossRegionReplication" => "Disabled",
            "DataRedundancyType" => "LRS",
            "ExtranetEndpoint" => "oss-cn-shenzhen.aliyuncs.com",
            "IntranetEndpoint" => "oss-cn-shenzhen-internal.aliyuncs.com",
            "Location" => "oss-cn-shenzhen",
            "Name" => "some-bucket",
            "Owner" => %{
              "DisplayName" => "11111111",
              "ID" => "11111111"
            },
            "ResourceGroupId" => "rg-acfmvqvnke6otqi",
            "ResourcePoolConfig" => nil,
            "ServerSideEncryptionRule" => %{"SSEAlgorithm" => "None"},
            "StorageClass" => "IA",
            "TransferAcceleration" => "Disabled",
            "Versioning" => "Suspended"
          }
        }
      },
      headers: %{
        "connection" => ["keep-alive"],
        ...
      }
    }

# `get_bucket_location`

```elixir
@spec get_bucket_location(Aliyun.Oss.Config.t(), String.t()) ::
  {:error, Exception.t()} | {:ok, Aliyun.Oss.Client.Response.t()}
```

GetBucketLocation - views the location information of a bucket.

## Examples

    iex> Aliyun.Oss.Bucket.get_bucket_location(config, "some-bucket")
    {:ok, %Aliyun.Oss.Client.Response{
        data: %{"LocationConstraint" => "oss-cn-shenzhen"},
        headers: %{
          "connection" => ["keep-alive"],
          ...
        }
      }
    }

# `get_bucket_stat`

```elixir
@spec get_bucket_stat(Aliyun.Oss.Config.t(), String.t()) ::
  {:error, Exception.t()} | {:ok, Aliyun.Oss.Client.Response.t()}
```

GetBucketStat - views the storage and objects count information of a bucket.

## Examples

    iex> Aliyun.Oss.Bucket.get_bucket_stat(config, "some-bucket")
    {:ok, %Aliyun.Oss.Client.Response{
        data: %{
          "ArchiveObjectCount" => "0",
          "ArchiveRealStorage" => "0",
          "ArchiveStorage" => "0",
          "ColdArchiveObjectCount" => "0",
          "ColdArchiveRealStorage" => "0",
          "ColdArchiveStorage" => "0",
          "DeepColdArchiveObjectCount" => "0",
          "DeepColdArchiveRealStorage" => "0",
          "DeepColdArchiveStorage" => "0",
          "DeleteMarkerCount" => "303",
          "InfrequentAccessObjectCount" => "0",
          "InfrequentAccessRealStorage" => "0",
          "InfrequentAccessStorage" => "0",
          "LastModifiedTime" => "1751610223",
          "LiveChannelCount" => "2",
          "MultipartPartCount" => "0",
          "MultipartUploadCount" => "0",
          "ObjectCount" => "19",
          "StandardObjectCount" => "19",
          "StandardStorage" => "3166616",
          "Storage" => "3166616"
        },
        headers: %{
          "connection" => ["keep-alive"],
          ...
        }
      }
    }

# `list_buckets`

# `list_objects`

```elixir
@spec list_objects(Aliyun.Oss.Config.t(), String.t(), keyword()) ::
  {:error, Exception.t()} | {:ok, Aliyun.Oss.Client.Response.t()}
```

GetBucketV2 (ListObjectsV2) - lists the information about all objects in a bucket.

## Options

- `:query_params` - Defaults to `%{}`
- `:headers` - Defaults to `%{}`

## Examples

    iex> Aliyun.Oss.Bucket.list_objects(config, "some-bucket", query_params: %{"prefix" => "foo/"})
    {:ok, %Aliyun.Oss.Client.Response{
        data: %{
          "ListBucketResult" => %{
            "Contents" => [
              %{
                "ETag" => ""D410293F000B000D00D"",
                "key" => "foo/bar",
                "LastModified" => "2018-09-12T02:59:41.000Z",
                "Owner" => %{"DislayName" => "11111111", "ID" => "11111111"},
                "Size" => "12345",
                "StorageClass" => "IA",
                "Type" => "Normal"
              },
              ...
            ],
            "Delimiter" => nil,
            "IsTruncated" => true,
            "Marker" => nil,
            "KeyCount" => 100,
            "MaxKeys" => 100,
            "Name" => "some-bucket",
            "NextContinuationToken" => "XXXXX",
            "Prefix" => "foo/"
          }
        },
        headers: %{
          "connection" => ["keep-alive"],
          ...
        }
      }
    }

    iex> Aliyun.Oss.Bucket.list_objects(config, "unknown-bucket")
    {:error,
      %Aliyun.Oss.Client.Error{
        status: 404,
        code: "NoSuchBucket",
        message: "The specified bucket does not exist.",
        details: %{
          "BucketName" => "unknown-bucket",
          "Code" => "NoSuchBucket",
          "EC" => "0015-00000101",
          "HostId" => "unknown-bucket.oss-cn-shenzhen.aliyuncs.com",
          "Message" => "The specified bucket does not exist.",
          "RecommendDoc" => "https://api.aliyun.com/troubleshoot?q=0015-00000101",
          "RequestId" => "5BFF89955E29FF66F10B9763"
        }
      }
    }

# `put_bucket`

```elixir
@spec put_bucket(Aliyun.Oss.Config.t(), String.t(), String.t(), keyword()) ::
  {:error, Exception.t()} | {:ok, Aliyun.Oss.Client.Response.t()}
```

PutBucket - creates a bucket.

## Options

- `:headers` - Defaults to `%{}`

## Examples

    iex> body = ~S{
    <?xml version="1.0" encoding="UTF-8"?>
    <CreateBucketConfiguration>
      <StorageClass>Standard</StorageClass>
    </CreateBucketConfiguration>
    }
    iex> Aliyun.Oss.Bucket.put_bucket(config, "new-bucket", body, headers: %{"x-oss-acl" => "private"})
    {:ok,
    %Aliyun.Oss.Client.Response{
      data: "",
      headers: %{
        "connection" => ["keep-alive"],
        "content-length" => ["0"],
        "date" => ["Fri, 11 Jan 2019 04:35:39 GMT"],
        "location" => ["/new-bucket"],
        "server" => ["AliyunOSS"],
        "x-oss-request-id" => ["5C381D000000000000000000"],
        "x-oss-server-time" => ["438"]
      }
    }}
    iex> Aliyun.Oss.Bucket.put_bucket(config, "new-bucket", body, headers: %{"x-oss-acl" => "invalid-permission"}) # get error
    {:error,
    %Aliyun.Oss.Client.Error{
      status: 400,
      code: "InvalidArgument",
      message: "no such bucket access control exists",
      details: %{
        "ArgumentName" => "x-oss-acl",
        "ArgumentValue" => "invalid-permission",
        "Code" => "InvalidArgument",
        "EC" => "0015-00000204",
        "HostId" => "new-bucket.oss-cn-shenzhen.aliyuncs.com",
        "Message" => "no such bucket access control exists",
        "RecommendDoc" => "https://api.aliyun.com/troubleshoot?q=0015-00000204",
        "RequestId" => "5C3000000000000000000000"
      }
    }}

---

*Consult [api-reference.md](api-reference.md) for complete listing*