apiプラグインで外部APIにファイルを送信できますか？

はい。apiプラグインのmethodにPOST、filesに一時ファイルを指定すると、multipart/form-dataで外部APIにファイルを送信します。

送信するファイルによって、次の2つの方法があります。

• Kurocoに保存したファイルを送信する
• Api::request_api_postで受け取ったファイルを中継する

files属性の指定方法

filesには、フォームのフィールド名をキーにした連想配列を指定します。各要素には、次の値を指定します。

キー	内容
path	送信する一時ファイルのパス（Kuroco一時フォルダからの相対パス）
name	送信時のファイル名

例えば、外部APIにフィールド名file_input_name、ファイル名image.pngとしてファイルを送信する場合は、filesを次の形式で指定します。

[
  "file_input_name" => [
    "path" => "rcms_get_file_XXXXXX",
    "name" => "image.png"
  ]
]

複数のファイルを送信する場合は、フィールド名ごとに要素を追加します。

queriesを指定すると、その値もファイルと同じリクエストでフォームの項目として送信されます。

Kurocoに保存したファイルを送信する

KurocoFilesなどに保存したファイルをget_fileで一時ファイルとして取得し、外部APIに送信します。get_fileのvarには、取得した一時ファイルのパスが格納されます。

{* 送信するファイルを一時ファイルとして取得する *}
{get_file path="/files/user/sample/image.png" var="tmp_path" status_var="get_file_result"}

{if $get_file_result}
    {* 外部APIの認証情報をシークレットから取得する *}
    {secret var="api_token" key="EXTERNAL_API_TOKEN"}

    {assign_array var="headers" values=""}
    {append var="headers" value="Authorization: Bearer `$api_token`"}

    {assign_array var="file" values=""}
    {assign var="file.path" value=$tmp_path}
    {assign var="file.name" value="image.png"}

    {assign_array var="files" values=""}
    {assign var="files.file_input_name" value=$file}

    {api
        endpoint="https://api.example.com/upload"
        method="POST"
        headers=$headers
        files=$files
        json_var="response"
        status_var="status"
        http_code_var="http_code"
        timeout=10
    }
{/if}

write_fileで作成した一時ファイルも、varに格納されたパスをpathに指定して同じように送信できます。

Api::request_api_postで受け取ったファイルを中継する

Api::request_api_postのエンドポイントで受け取ったファイルを、Kurocoに保存せずに外部APIへ送信します。エンドポイントとカスタム処理の作成方法は、カスタム処理と紐づいたAPIエンドポイントを作成するを参照してください。

例えば、次のようにApi::request_api_postのエンドポイントにファイルを送信した場合、

curl -X 'POST' 'https://your-site.g.kuroco.app/rcms-api/1/custom_file_upload' \
  -H 'Content-Type: multipart/form-data' \
  -F 'file_input_name=@image.png'

呼び出し先のカスタム処理では、受け取ったファイルが$filesに格納されます。$filesの各要素には、次の値が含まれます（このほかにtype・sizeなどの値も含まれます）。input_nameはリクエストのフィールド名です。

[
  [
    "path" => "request_api_postXXXXXX",
    "name" => "image.png",
    "input_name" => "file_input_name"
  ]
]

この$filesは、そのままapiプラグインのfilesに指定できます。外部APIにはinput_nameがフィールド名、nameがファイル名として送信されます。

{* Api::request_api_postの呼び出し先となるカスタム処理 *}
{secret var="api_token" key="EXTERNAL_API_TOKEN"}

{assign_array var="headers" values=""}
{append var="headers" value="Authorization: Bearer `$api_token`"}

{api
    endpoint="https://api.example.com/upload"
    method="POST"
    headers=$headers
    files=$files
    json_var="response"
    status_var="status"
    http_code_var="http_code"
    timeout=10
}

{if !$status}
    {append var="errors" value="ファイルを送信できませんでした。"}
{/if}

注意事項

• oauth_connectionを指定したapiプラグインではfilesを使用できません。外部APIの認証情報はシークレットに保存し、headersで指定します。secretプラグインを含むカスタム処理は、スーパーユーザーのみ保存できます。
• Files::uploadなどでアップロードした/files/temp/の一時ファイルは、get_fileで取得できないため、この方法では送信できません。
• カスタム処理を含むAPIリクエストは、PHPの実行時間30秒で打ち切られます。timeoutは30秒未満に設定してください。詳しくは実行時間の上限を参照してください。

関連ドキュメント

• Smarty プラグイン（api）
• カスタム処理と紐づいたAPIエンドポイントを作成する
• シークレット