# `LibOss.Api.Multipart`
[🔗](https://github.com/tt67wq/lib-oss/blob/main/lib/lib_oss/api/multipart.ex#L1)

OSS多部分上传相关API

提供多部分上传的初始化、上传分片、完成上传、中止上传等功能。

# `__using__`
*macro* 

创建宏，用于在客户端模块中导入所有多部分上传函数

# `abort_multipart_upload`

```elixir
@spec abort_multipart_upload(
  module(),
  LibOss.Typespecs.bucket(),
  LibOss.Typespecs.object(),
  LibOss.Typespecs.upload_id()
) :: :ok | {:error, LibOss.Exception.t()}
```

AbortMultipartUpload接口用于取消MultipartUpload事件并删除对应的Part数据。

Doc: https://help.aliyun.com/document_detail/31996.html

## Examples

    iex> abort_multipart_upload(bucket, "test.txt", "upload_id")
    :ok

# `complete_multipart_upload`

```elixir
@spec complete_multipart_upload(
  module(),
  LibOss.Typespecs.bucket(),
  LibOss.Typespecs.object(),
  LibOss.Typespecs.upload_id(),
  [{LibOss.Typespecs.part_num(), LibOss.Typespecs.etag()}],
  LibOss.Typespecs.headers()
) :: :ok | {:error, LibOss.Exception.t()}
```

所有数据Part都上传完成后，您必须调用CompleteMultipartUpload接口来完成整个文件的分片上传。

Doc: https://help.aliyun.com/document_detail/31995.html

## Examples

    iex> {:ok, etag1} = upload_part(bucket, "test.txt", "upload_id", 1, part1)
    iex> {:ok, etag2} = upload_part(bucket, "test.txt", "upload_id", 2, part2)
    iex> {:ok, etag3} = upload_part(bucket, "test.txt", "upload_id", 3, part3)
    iex> complete_multipart_upload(bucket, "test.txt", "upload_id", [{1, etag1}, {2, etag2}, {3, etag3}])
    :ok

# `init_multi_upload`

```elixir
@spec init_multi_upload(
  module(),
  LibOss.Typespecs.bucket(),
  LibOss.Typespecs.object(),
  LibOss.Typespecs.headers()
) :: {:ok, LibOss.Typespecs.upload_id()} | {:error, LibOss.Exception.t()}
```

使用Multipart Upload模式传输数据前，您必须先调用InitiateMultipartUpload接口来通知OSS初始化一个Multipart Upload事件。

Doc: https://help.aliyun.com/document_detail/31992.html

## Examples

    iex> init_multi_upload(bucket, "test.txt")
    {:ok, "upload_id"}

# `list_multipart_uploads`

```elixir
@spec list_multipart_uploads(
  module(),
  LibOss.Typespecs.bucket(),
  LibOss.Typespecs.params()
) ::
  {:ok, [LibOss.Typespecs.dict()]} | {:error, LibOss.Exception.t()}
```

调用ListMultipartUploads接口列举所有执行中的Multipart Upload事件，即已经初始化但还未完成（Complete）或者还未中止（Abort）的Multipart Upload事件。

Doc: https://help.aliyun.com/document_detail/31997.html

## Examples

    iex> list_multipart_uploads(bucket, %{"delimiter"=>"/", "max-uploads" => 10, "prefix"=>"test/"})
    {:ok,
     [
       %{
         "ETag" => ""1334928900AEB317206CC7EB950540EF-3"",
         "Key" => "test/multi-test.txt",
         "LastModified" => "2023-07-18T11:16:45.000Z",
         "Owner" => %{
           "DisplayName" => "1074124462684153",
           "ID" => "1074124462684153"
         },
         "Size" => "409608",
         "StorageClass" => "Standard",
         "Type" => "Multipart"
       },
       %{
         "ETag" => ""5EB63BBBE01EEED093CB22BB8F5ACDC3"",
         "Key" => "test/test.txt",
         "LastModified" => "2023-07-18T11:19:19.000Z",
         "Owner" => %{
           "DisplayName" => "1074124462684153",
           "ID" => "1074124462684153"
         },
         "Size" => "11",
         "StorageClass" => "Standard",
         "Type" => "Normal"
       }
     ]}

# `list_parts`

```elixir
@spec list_parts(
  module(),
  LibOss.Typespecs.bucket(),
  LibOss.Typespecs.object(),
  LibOss.Typespecs.upload_id(),
  LibOss.Typespecs.params()
) :: {:ok, [LibOss.Typespecs.dict()]} | {:error, LibOss.Exception.t()}
```

ListParts接口用于列举指定Upload ID所属的所有已经上传成功Part。

Doc: https://help.aliyun.com/document_detail/31998.html

## Examples

    iex> list_parts(bucket, "test.txt", "upload_id")
    {:ok,
     %{
      "ListPartsResult" => %{
        "Bucket" => "hope-data",
        "IsTruncated" => "false",
        "Key" => "test/multi-test.txt",
        "MaxParts" => "1000",
        "NextPartNumberMarker" => "3",
        "Part" => [
          %{
            "ETag" => ""3170FC594DACE56C506E0196B5DEA1D1"",
            "HashCrc64ecma" => "10873275732915280589",
            "LastModified" => "2023-07-19T02:58:16.000Z",
            "PartNumber" => "1",
            "Size" => "136536"
          },
          %{
            "ETag" => ""5539D60A05FD504B8210A662D7D15C1E"",
            "HashCrc64ecma" => "4592881501542342075",
            "LastModified" => "2023-07-19T02:58:17.000Z",
            "PartNumber" => "2",
            "Size" => "136536"
          },
          %{
            "ETag" => ""5C7D509F5744115EE3B2D55F4893FE3F"",
            "HashCrc64ecma" => "9048307046109329978",
            "LastModified" => "2023-07-19T02:58:17.000Z",
            "PartNumber" => "3",
            "Size" => "136536"
          }
        ],
        "PartNumberMarker" => "0",
        "StorageClass" => "Standard",
        "UploadId" => "39663F02E9384C87BFC9E9B0E8B1100E"
      }
    }}

# `upload_part`

```elixir
@spec upload_part(
  module(),
  LibOss.Typespecs.bucket(),
  LibOss.Typespecs.object(),
  LibOss.Typespecs.upload_id(),
  LibOss.Typespecs.part_num(),
  binary()
) :: {:ok, LibOss.Typespecs.etag()} | {:error, LibOss.Exception.t()}
```

初始化一个MultipartUpload后，调用UploadPart接口根据指定的Object名和uploadId来分块（Part）上传数据。

Doc: https://help.aliyun.com/document_detail/31993.html

## Examples

    iex> upload_part(bucket, "test.txt", "upload_id", 1, "hello world")
    {:ok, "etag"}

---

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