Questetra BPM Suite の外からケースを開始する（事前アップロード編）

ファイルを事前にアップロードしてからケースを開始する

curl 編と Python 編では、ファイル型のデータ項目に値を渡すために、ファイル本体を他のパラメータと一緒に multipart/form-data 形式で送信しました。メッセージ開始イベント (HTTP) には、もう一つの方法があります。先にファイルだけをアップロードして ID を受け取り、その ID をケース開始のリクエストで送る「事前アップロード」です。今回はこの手順を curl と Python で紹介します。

事前アップロードはメッセージ開始イベント (HTTP) で利用できます。受信タスク (HTTP) では利用できません。

事前アップロードが必要になるのは、添付するファイルの合計が大きい場合です。メッセージ開始イベント (HTTP) が受け付ける multipart/form-data 形式のリクエストは、ファイルを含めたリクエスト全体で 100 MB までです。ファイル本体を他のパラメータと一緒に送る方法ではこの上限を超えられませんが、事前アップロードなら、ファイルを分けてアップロードすることで合計 100 MB を超えるファイルを添付できます。

ワークフローアプリは curl 編と同じものを使用します。もし作成していない場合は、準備編と curl 編の「さまざまなデータを送信する > アプリの設定」を参照しながら、アプリを作成・リリースしておいてください。

手順の概要

事前アップロードでは、2 回の HTTP リクエストを送信します。

ファイルをアップロードする：/File/upload に API キーとファイルを multipart/form-data 形式で送信します。応答としてファイルごとの ID が返ります。
ケースを開始する：/start に、ファイル型のパラメータの値として 1. で受け取った ID を、他のパラメータと一緒に送信します。

リクエスト	URL	Content-Type
ファイルのアップロード	`https://example.questetra.net/System/Event/MessageStart/{processModelInfoId}/{nodeNumber}/File/upload`	multipart/form-data
ケースの開始	`https://example.questetra.net/System/Event/MessageStart/{processModelInfoId}/{nodeNumber}/start`	application/x-www-form-urlencoded

{processModelInfoId} と {nodeNumber} は、ケース開始の URL と同じ値です。

curl でケースを開始する

1. ファイルをアップロードする

curl https://example.questetra.net/System/Event/MessageStart/{processModelInfoId}/{nodeNumber}/File/upload ^
  -F "key={API キー}" ^
  -F "files=@ques-kun-01.png" ^
  -F "files=@ques-kun-02.png"

ファイルを渡すパラメータ名は、データ項目のフィールド名ではなく files で固定です。複数のファイルをアップロードするときは、files を繰り返します。API キーは、ケース開始と同じ key パラメータで渡します。

アップロードに成功すると、次のような JSON が返ります。

{
  "files": [
    {
      "id": "12345:AbCdEfGhIjKlMnOp",
      "name": "ques-kun-01.png",
      "contentType": "image/png",
>      "length": 34567,
      "lengthText": "33.8 KB",
      "image": true,
      "inline": false,
      "malwareScanStatus": "NO_THREATS_FOUND"
>    },
    {
      "id": "12346:QrStUvWxYzAbCdEf",
      "name": "ques-kun-02.png",
      "contentType": "image/png",
      "length": 45678,
      "lengthText": "44.7 KB",
      "image": true,
      "inline": false,
      "malwareScanStatus": "NO_THREATS_FOUND"
    }
  ]
}

ケース開始で使うのは files[].id の値です。ファイルの番号とアクセストークンをコロンでつないだ文字列になっているので、そのまま次のリクエストに渡します。

2. ケースを開始する

curl https://example.questetra.net/System/Event/MessageStart/{processModelInfoId}/{nodeNumber}/start ^
  --data-urlencode "key={API キー}" ^
  --data-urlencode "title=テスト" ^
  --data-urlencode "q_str=ケース開始テストです" ^
  --data-urlencode "q_file=12345:AbCdEfGhIjKlMnOp" ^
  --data-urlencode "q_file=12346:QrStUvWxYzAbCdEf"

ファイル型のパラメータ q_file に、アップロードで受け取った ID を渡します。複数のファイルを添付するときは、curl 編でファイル本体を送ったときと同じく、同じパラメータ名で繰り返します。ファイル本体を送信しないので、curl 編でファイル型のデータ項目を送るときに必要とした -F オプションではなく、--data-urlencode オプションで送信できます。

ケース開始のリクエストは、application/x-www-form-urlencoded 形式で送信してください。multipart/form-data 形式で送ると、ID は受け付けられず、ファイルが添付されないままケースが開始されます。

Python でケースを開始する

Python 編と同じく Requests パッケージを使用します。アップロードの応答から ID を取り出し、ケース開始のパラメータに追加します。

import requests

# API エンドポイント
base_url = 'https://example.questetra.net/System/Event/MessageStart/{processModelInfoId}/{nodeNumber}'
api_key = '{APIキー}'

# 1. ファイルをアップロードする
files = [ # パラメータ名は files で固定
    ('files', ('ques-kun-01.png', open('./ques-kun-01.png', 'rb'), 'image/png')),
    ('files', ('ques-kun-02.png', open('./ques-kun-02.png', 'rb'), 'image/png')),
]
r = requests.post(f'{base_url}/File/upload', data={'key': api_key}, files=files)
r.raise_for_status()
file_ids = [f['id'] for f in r.json()['files']] # ID のリスト

# 2. ケースを開始する
params = [ # 同じパラメータ名を繰り返すため、辞書ではなくタプルのリストにする
    ('key', api_key),
    ('title', 'テスト'),
    ('q_str', 'ケース開始テストです'),
]
params += [('q_file', file_id) for file_id in file_ids]
r = requests.post(f'{base_url}/start', data=params) # files を渡さないので application/x-www-form-urlencoded で送信される
r.raise_for_status()
print(f'Status Code: {r.status_code}')
print(r.text)

Python 編で説明したとおり、Requests は files を渡さなければ application/x-www-form-urlencoded 形式で送信します。ケース開始のリクエストでは files を渡さず、ID を data に含めてください。

事前アップロードの注意点

1 回のアップロードで送れるのは 100 MB までです。 ケース開始のリクエストと同じ上限です。合計がこれを超えるときは、複数回に分けてアップロードしてください。
ID が保証されるのは 1 時間です。 アップロードしてから 1 時間以内にケース開始に使ってください。
ID は 1 回だけ使えます。 ケースの開始に使われた ID は、それ以降は無効になります。同じファイルを別のケースに添付するときは、もう一度アップロードしてください。ケース開始が入力エラーになった場合は ID は使われていないので、同じ ID でもう一度ケースを開始できます。