コンテンツにスキップ

添付ファイルのアップロード



POST /api/v1/attachment/upload

概要

ワークスペースの添付ファイルをアップロードし、添付ファイル識別子を返します。これは後続の Issue またはインシデントコメントの関連付けに使用します。この API はファイルをアップロードするだけで、コメントを自動作成しません。

呼び出し前の準備と使用手順

  1. 添付するローカルファイルと、添付ファイルアップロード権限を持つワークスペース API Key を準備します。リクエストは multipart/form-data 形式で、フィールド名は files です。
  2. アップロード成功後、content.attachmentUuid を保存し、Issue 返信を作成 のリクエスト配列 attachmentUuids にこの識別子を設定します。アップロード自体ではコメントは追加されません。
  3. 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 と errorCode ft.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 つアップロードします。

フィードバック

このページは役に立ちましたか?