添付ファイルのアップロード¶
POST /api/v1/attachment/upload
概要¶
ワークスペースの添付ファイルをアップロードし、添付ファイル識別子を返します。これは後続の Issue またはインシデントコメントの関連付けに使用します。この API はファイルをアップロードするだけで、コメントを自動作成しません。
呼び出し前の準備と使用手順¶
- 添付するローカルファイルと、添付ファイルアップロード権限を持つワークスペース API Key を準備します。リクエストは multipart/form-data 形式で、フィールド名は files です。
- アップロード成功後、content.attachmentUuid を保存し、Issue 返信を作成 のリクエスト配列 attachmentUuids にこの識別子を設定します。アップロード自体ではコメントは追加されません。
- 1 回につき 1 ファイルのみ、最大 50 MiB です。リクエストがタイムアウトした場合は、まず添付ファイルが生成されたか確認してから、再送するか判断してください。
リクエストヘッダー¶
| パラメータ名 | 型 | 必須 | 説明 |
|---|---|---|---|
| DF-API-KEY | string | Y | AK 識別子、AK uuid 例: <DF-API-KEY>取得または入力方法: 対象ワークスペースの API Key 管理で、この API の権限を持つ Key を作成または取得します。 |
ファイルパラメータ(multipart/form-data)¶
| パラメータ名 | 型 | 必須 | 説明 |
|---|---|---|---|
| files | file | Y | 添付ファイル 単一ファイルサイズ上限: 50M ファイル数上限: 1 許可されるファイル拡張子: ['txt', 'json', 'mp4', 'mov', 'png', 'jpg', 'pdf', 'xls', 'xlsx'] 例: @/path/to/image.png取得または入力方法: アップロードするローカルファイルのパスを入力します。curl では -F を使用し、パスの前に @ を付けます。 |
パラメータ補足¶
multipart/form-dataを使用して実際のファイルバイナリをアップロードします。ファイルフィールド名はfilesである必要があり、1 回につき 1 ファイルのみアップロードします。- ファイルパートにはファイル名を含める必要があります。例:
Content-Disposition: form-data; name="files"; filename="image.png"。 - リクエストヘッダーに
DF-API-KEYを指定します。curl の-Fまたは HTTP クライアントの multipart builder を使用して、Content-Type と boundary を自動生成します。 - 単一ファイルサイズは 50 MiB(50 × 1024 × 1024 バイト)以下です。許可されるファイル拡張子はファイルパラメータ表を参照してください。拡張子の検証では大文字と小文字を区別しません。
- Lark の
imageKeyはそのままファイルとしてアップロードできません。先に画像のバイナリを取得し、.pngまたは.jpg拡張子付きのファイル名でアップロードする必要があります。 filesファイルが欠落している場合、fileフィールドを誤用した場合、またはファイル名が指定されていない場合は、HTTP 406 とerrorCodeft.ParameterValidationFailedを返します。ファイル拡張子、サイズ、数が要件を満たさない場合も拒否されます。
成功時のレスポンスの content フィールド:
| フィールド | 型 | 説明 |
|---|---|---|
| fileName | string | アップロード時の元のファイル名 |
| attachmentUuid | string | 添付ファイル識別子。後続の API で添付ファイルを関連付けるために使用します。フィールド名の大文字と小文字に注意してください。 |
| fileSuffix | string | 元のファイル名の拡張子 |
リクエスト例¶
curl --request POST 'https://openapi.guance.com/api/v1/attachment/upload' \
--header 'DF-API-KEY: <DF-API-KEY>' \
--form 'files=@/path/to/image.png'
レスポンス¶
HTTP 200、application/json。アップロード成功時は添付ファイルのメタデータを返します。成功したアップロードを繰り返すと、新しい添付ファイル識別子が生成される場合があります。
| フィールド | 型 | 説明 |
|---|---|---|
| content.fileName | string | アップロード時の元のファイル名。 |
| content.attachmentUuid | string | 添付ファイル識別子。Issue 返信の作成リクエストの attachmentUuids 配列で使用します。 |
| content.fileSuffix | string | サーバー側で記録されたファイル拡張子。 |
{
"code": 200,
"content": {
"fileName": "image.png",
"attachmentUuid": "att_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
"fileSuffix": "png"
},
"errorCode": "",
"message": "",
"success": true,
"traceId": "TRACE_ID"
}
エラーレスポンス¶
認証、レート制限、および共通リクエストエラーについては、共通エラー定義 を参照してください。
| HTTP ステータス | errorCode | 発生条件 | メッセージまたはレスポンスの説明 | 対処方法 |
|---|---|---|---|---|
| 406 | ft.ParameterValidationFailed | files がない、フィールド名が誤っている、ファイル数が多すぎる、拡張子がサポートされていない、またはファイルが上限を超えている | メッセージには、不足しているフィールドや違反したルール(fileSuffix や limitSize など)が示されます。 | files フィールドで、サポートされている 50 MiB 以下のファイルを 1 つアップロードします。 |