コンテンツにスキップ

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



POST /api/v1/attachment/upload

概要

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

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

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

フィードバック

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