添付ファイルアップロード¶
POST /api/v1/attachment/upload
概要¶
ワークスペースの添付ファイルをアップロードし、添付ファイル識別子を返します。これは後続の Issue またはインシデントコメントの関連付けに使用します。本インターフェースはファイルをアップロードするだけで、コメントを自動作成しません。
呼び出し前の準備と使用手順¶
- 添付するローカルファイルと、添付ファイルのアップロード権限を持つワークスペースの API Key を準備します。リクエストは multipart/form-data 形式で、フィールド名は files です。
- アップロード成功後、content.attachmentUuid を保存し、インシデントコメントを追加のリクエスト配列 attachmentUUIDs にその識別子を設定します。アップロード自体ではコメントは追加されません。
- 1 回につき 1 ファイルのみをアップロードし、最大 50 MiB です。リクエストがタイムアウトした場合は、まず添付ファイルが生成されているかを確認してから、再送するかどうかを判断してください。
リクエストヘッダー¶
| パラメータ名 | 型 | 必須 | 説明 |
|---|---|---|---|
| DF-API-KEY | string | Y | AK 識別子、AK uuid 例: <DF-API-KEY>取得または入力方法: 対象ワークスペースの API Key 管理で、本インターフェースの権限を持つ 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 ファイルのみをアップロードします。- ファイル part にはファイル名を含める必要があります。例:
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 を返し、errorCodeはft.ParameterValidationFailedです。ファイル拡張子、サイズ、数量が要件を満たさない場合も拒否されます。
成功レスポンスの content フィールド:
| フィールド | 型 | 説明 |
|---|---|---|
| fileName | string | アップロード時の元のファイル名 |
| attachmentUuid | string | 添付ファイル識別子。後続のインターフェースで添付ファイルを関連付けるために使用します。フィールド名の大文字と小文字に注意してください |
| 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 | 添付ファイル識別子。インシデントコメント追加リクエストの 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 つアップロードしてください。 |