# `LibOss.Core.Bucket`
[🔗](https://github.com/tt67wq/lib-oss/blob/main/lib/lib_oss/core/bucket.ex#L1)

存储桶操作模块

负责：
- 基础操作：put_bucket, delete_bucket
- 对象列表：get_bucket, list_object_v2
- 存储桶信息：get_bucket_info, get_bucket_location, get_bucket_stat

# `err_t`

```elixir
@type err_t() :: {:error, LibOss.Exception.t()}
```

# `bucket_exists?`

```elixir
@spec bucket_exists?(module(), LibOss.Typespecs.bucket()) :: boolean()
```

检查存储桶是否存在

## 参数
- name: Agent进程名称
- bucket: 存储桶名称

## 返回值
- boolean()

## 示例
    iex> LibOss.Core.Bucket.bucket_exists?(MyOss, "my-bucket")
    true

# `delete_bucket`

```elixir
@spec delete_bucket(module(), LibOss.Typespecs.bucket()) :: :ok | err_t()
```

删除存储桶

## 参数
- name: Agent进程名称
- bucket: 存储桶名称

## 返回值
- :ok | {:error, Exception.t()}

注意：只能删除空的存储桶

## 示例
    iex> LibOss.Core.Bucket.delete_bucket(MyOss, "my-bucket")
    :ok

## 相关文档
https://help.aliyun.com/document_detail/31947.html

# `get_bucket`

```elixir
@spec get_bucket(module(), LibOss.Typespecs.bucket(), LibOss.Typespecs.params()) ::
  {:ok, map()} | err_t()
```

列出存储桶中的对象（v1 API）

## 参数
- name: Agent进程名称
- bucket: 存储桶名称
- query_params: 查询参数

## 查询参数
- prefix: 对象名前缀
- marker: 起始对象名
- max-keys: 最大返回数量
- delimiter: 分隔符

## 返回值
- `{:ok, map()} | {:error, Exception.t()}`

## 示例
    iex> LibOss.Core.Bucket.get_bucket(MyOss, "my-bucket", %{"prefix" => "photos/"})
    {:ok, %{objects: [...], is_truncated: false}}

## 相关文档
https://help.aliyun.com/document_detail/31948.html

# `get_bucket_info`

```elixir
@spec get_bucket_info(module(), LibOss.Typespecs.bucket()) :: {:ok, map()} | err_t()
```

获取存储桶信息

## 参数
- name: Agent进程名称
- bucket: 存储桶名称

## 返回值
- `{:ok, map()} | {:error, Exception.t()}`

返回的map包含：
- name: 存储桶名称
- location: 数据中心
- creation_date: 创建时间
- storage_class: 存储类型
- owner: 所有者信息

## 示例
    iex> LibOss.Core.Bucket.get_bucket_info(MyOss, "my-bucket")
    {:ok, %{
      name: "my-bucket",
      location: "oss-cn-hangzhou",
      creation_date: "2023-01-01T00:00:00.000Z",
      storage_class: "Standard"
    }}

## 相关文档
https://help.aliyun.com/document_detail/31968.html

# `get_bucket_location`

```elixir
@spec get_bucket_location(module(), LibOss.Typespecs.bucket()) ::
  {:ok, String.t()} | err_t()
```

获取存储桶位置信息

## 参数
- name: Agent进程名称
- bucket: 存储桶名称

## 返回值
- `{:ok, String.t()} | {:error, Exception.t()}`

## 示例
    iex> LibOss.Core.Bucket.get_bucket_location(MyOss, "my-bucket")
    {:ok, "oss-cn-hangzhou"}

## 相关文档
https://help.aliyun.com/document_detail/31967.html

# `get_bucket_stat`

```elixir
@spec get_bucket_stat(module(), LibOss.Typespecs.bucket()) :: {:ok, map()} | err_t()
```

获取存储桶统计信息

## 参数
- name: Agent进程名称
- bucket: 存储桶名称

## 返回值
- `{:ok, map()} | {:error, Exception.t()}`

返回的map包含：
- storage: 存储量统计
- object_count: 对象数量统计
- multipart_upload_count: 分片上传任务数量

## 示例
    iex> LibOss.Core.Bucket.get_bucket_stat(MyOss, "my-bucket")
    {:ok, %{
      storage: 1024000,
      object_count: 100,
      multipart_upload_count: 5
    }}

## 相关文档
https://help.aliyun.com/document_detail/426056.html

# `get_object_count`

```elixir
@spec get_object_count(module(), LibOss.Typespecs.bucket(), String.t()) ::
  {:ok, non_neg_integer()} | err_t()
```

获取存储桶中对象的总数（近似值）

## 参数
- name: Agent进程名称
- bucket: 存储桶名称
- prefix: 对象名前缀（可选）

## 返回值
- `{:ok, non_neg_integer()} | {:error, Exception.t()}`

注意：这是一个近似值，通过分页获取所有对象计算得出

## 示例
    iex> LibOss.Core.Bucket.get_object_count(MyOss, "my-bucket")
    {:ok, 1500}

# `list_object_v2`

```elixir
@spec list_object_v2(module(), LibOss.Typespecs.bucket(), LibOss.Typespecs.params()) ::
  {:ok, map()} | err_t()
```

列出存储桶中的对象（v2 API）

## 参数
- name: Agent进程名称
- bucket: 存储桶名称
- query_params: 查询参数

## 查询参数
- prefix: 对象名前缀
- continuation-token: 继续标记
- max-keys: 最大返回数量
- start-after: 起始对象名
- delimiter: 分隔符

## 返回值
- `{:ok, map()} | {:error, Exception.t()}`

## 示例
    iex> LibOss.Core.Bucket.list_object_v2(MyOss, "my-bucket", %{"prefix" => "photos/"})
    {:ok, %{objects: [...], is_truncated: false}}

## 相关文档
https://help.aliyun.com/document_detail/187544.html

# `put_bucket`

```elixir
@spec put_bucket(
  module(),
  LibOss.Typespecs.bucket(),
  String.t(),
  String.t(),
  LibOss.Typespecs.headers()
) :: :ok | err_t()
```

创建存储桶

## 参数
- name: Agent进程名称
- bucket: 存储桶名称
- storage_class: 存储类型（可选，默认"Standard"）
- data_redundancy_type: 数据冗余类型（可选，默认"LRS"）
- headers: 可选的HTTP请求头

## 存储类型
- "Standard": 标准存储
- "IA": 低频访问存储
- "Archive": 归档存储
- "ColdArchive": 冷归档存储

## 数据冗余类型
- "LRS": 本地冗余存储
- "ZRS": 同城冗余存储

## 返回值
- :ok | {:error, Exception.t()}

## 示例
    iex> LibOss.Core.Bucket.put_bucket(MyOss, "my-bucket")
    :ok

    iex> LibOss.Core.Bucket.put_bucket(MyOss, "my-bucket", "IA", "ZRS")
    :ok

## 相关文档
https://help.aliyun.com/document_detail/31946.html

# `valid_redundancy_types`

```elixir
@spec valid_redundancy_types() :: [String.t()]
```

获取有效的数据冗余类型列表

## 返回值
- [String.t()]

# `valid_storage_classes`

```elixir
@spec valid_storage_classes() :: [String.t()]
```

获取有效的存储类型列表

## 返回值
- [String.t()]

# `validate_redundancy_type`

```elixir
@spec validate_redundancy_type(String.t()) :: :ok | err_t()
```

验证数据冗余类型是否有效

## 参数
- redundancy_type: 数据冗余类型

## 返回值
- :ok | {:error, Exception.t()}

# `validate_storage_class`

```elixir
@spec validate_storage_class(String.t()) :: :ok | err_t()
```

验证存储类型是否有效

## 参数
- storage_class: 存储类型

## 返回值
- :ok | {:error, Exception.t()}

---

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