プラグインから外部サービスのAPIを実行します。
このAPIを利用すると、クロスドメイン制約を回避して、外部APIにリクエストを送信できます。

認証情報など秘匿する情報を付与して外部APIを実行する場合は、APIを実行する前に、必要な情報をあらかじめプラグインに保存します。
プラグインに情報を保存、取得する方法は、次のページを参照してください。

• 外部APIの実行に必要な情報をプラグインへ保存する
• 外部APIの実行に必要な情報を取得する

PC／モバイル

kintone.plugin.app.proxy(pluginId, url, method, headers, data, successCallback, failureCallback)

successCallbackを指定した場合、戻り値はありません。
引数のsuccessCallbackを省略した場合は、kintone.Promiseオブジェクトが返ります。
kintone.Promiseオブジェクト

PC

• レコード一覧画面
• レコード詳細画面
• レコード追加画面
• レコード編集画面
• レコード印刷画面
• グラフの画面

モバイル

• レコード一覧画面
• レコード詳細画面
• レコード追加画面
• レコード編集画面
• グラフの画面

コールバックを使った記述方法

1
2
3
4
5
6
7

kintone.plugin.app.proxy('mjjfipoklghomcgafnajfibfgllhpocm', 'https://api.example.com', 'GET', {}, {}, (body, status, headers) => {
  // success
  console.log(status, JSON.parse(body), headers);
}, (error) => {
  // error
  console.log(error);
});

kintone.Promiseオブジェクトを使った記述方法

1

await kintone.plugin.app.proxy('mjjfipoklghomcgafnajfibfgllhpocm', 'https://api.example.com', 'GET', {}, {});

保存した情報がリクエストに加わる条件

• このAPIを使ったリクエストでは、次の条件をすべて満たすときに、プラグインへ保存した情報がリクエストに追加されます。

  • アプリが同一
  • プラグインが同一
  • HTTPメソッドが同一
  • 実行するAPIのURLが前方一致する ^*1
    URLの大文字と小文字は区別されます。

• プラグインに複数の設定を保存した場合は、APIの実行時に指定したURLと、より多くの文字が一致するURLを指定している設定が優先されます。
  たとえば、外部APIの実行に必要な情報をプラグインへ保存するAPIで、次のようなURLやリクエストヘッダーを指定したとします。
  外部APIの実行に必要な情報をプラグインへ保存するAPI

  • 設定その1
    • URL：https://api.example.com/
    • ヘッダー：{ "Content-Type": "application/x-www-form-urlencoded" }
  • 設定その2
    • URL：https://api.example.com/foo/
    • ヘッダー：{ "Content-Type": "application/json" }

  次の値を指定して、このAPIを実行します。

  • URL：https://api.example.com/foo/operate.json
  • ヘッダー：{}

  このとき、APIの実行時に送信されるリクエストのヘッダーは、{ "Content-Type": "application/json" }です。

外部APIを実行するときに送信されるリクエストヘッダー

外部APIを実行するときに指定されるリクエストヘッダーは、このAPIで指定されたリクエストヘッダーに、次の条件を満たした設定情報のリクエストヘッダーを付加したものです。
保存した情報がリクエストに加わる条件

たとえば、それぞれのAPIのリクエストヘッダーを次のように指定したとします。

• 外部APIの実行に必要な情報をプラグインへ保存するAPI

  1 2 3

  { "k1": "v1" }

• プラグインから外部APIを実行するAPI（このAPI）

  1 2 3

  { "k2": "v2" }

この場合、次のリクエストヘッダーが実際に送信されます。

1
2
3
4

{
  "k1": "v1",
  "k2": "v2"
}

外部APIを実行するときに送信されるリクエストボディ

HTTPメソッドがPOST／PUTの場合

このAPIで指定したリクエストボディに、次の条件を満たした設定情報のデータを付加したものとなります。
保存した情報がリクエストに加わる条件
これは、リクエストヘッダーと同じです。
ただし、このAPIで指定されたリクエストボディの型がオブジェクトの場合のみ、設定情報のデータを付加し、文字列の場合は付加しません。

HTTPメソッドがGET／DELETEの場合

このAPIで指定した外部APIのURLのクエリ文字列の末尾に、次の条件を満たした設定情報のデータをクエリ文字列として付加します。
保存した情報がリクエストに加わる条件
クエリ文字列の開始を表す?が含まれていない場合は、自動で付加されます。

たとえば、それぞれのAPIのリクエストボディやリクエストパラメーターを次のように指定したとします。

• 外部APIの実行に必要な情報をプラグインへ保存するAPI

  1 2 3

  { "k1": "v1" }

• プラグインから外部APIを実行するAPI（このAPI）
  url：「https://api.example.com?k=v」

この場合、次のURLにリクエストが送信されます。
https://api.example.com?k=v&k1=v1&k2=v2

複数の設定情報でキーが重複する場合

複数の設定情報が次の条件をどちらも満たす場合、外部APIのURLの一致した長さの長いものを優先します。

• 保存した情報がリクエストに加わる条件
• リクエストヘッダーのキーに重複する値がある。

HTTPメソッドがPOST／PUTの場合は、リクエストヘッダーに指定した値の型がオブジェクトの場合で、GET／DELETEの場合はクエリ文字列に適用されます。

たとえば、それぞれのAPIのリクエストヘッダーを次のように指定したとします。

• 外部APIの実行に必要な情報をプラグインへ保存するAPI

  1 2 3 4

  { "k1": "v1", "k2": "v2" }

• プラグインから外部APIを実行するAPI（このAPI）

  1 2 3 4

  { "k2": "v2-1", "k3": "v3" }

この場合、次のリクエストヘッダーが実際に送信されます。

1
2
3
4
5

{
  "k1": "v1",
  "k2": "v2-1",
  "k3": "v3"
}

設定情報とこのAPIで指定したリクエストヘッダーやリクエストボディのキーが重複する場合

設定されたリクエスト情報から採用したリクエストヘッダーのキーがこのAPIで指定するリクエストヘッダーにも含まれる場合、前者の値を優先します。
HTTPメソッドがPOST／PUTの場合のリクエストボディ（型がオブジェクトの場合のみ）も同様です。
GET／DELETEの場合は、キーの重複をチェックしません。

たとえば、それぞれのAPIのリクエストヘッダーを次のように指定したとします。

• 外部APIの実行に必要な情報をプラグインへ保存するAPI

  1 2 3 4

  { "k1": "v1", "k2": "v2" }

• プラグインから外部APIを実行するAPI（このAPI）

  1 2 3 4

  { "k2": "v2-1", "k3": "v3" }

この場合、次のリクエストヘッダーが実際に送信されます。

1
2
3
4
5

{
  "k1": "v1",
  "k2": "v2",
  "k3": "v3"
}

• 存在しないサーバーをurlに指定した場合、ステータスコード「503」（DNS Cache Missing）のエラーが返ります。
• IPアドレス制限を設定している場合、このJavaScript APIを使って同一ドメインの別アプリに対しkintone REST APIを実行するには、kintoneのIPアドレスを許可してください。
  IPアドレスの詳細は、次のページを参照してください。
  cybozu.comが使用するドメインとIPアドレス
  ただし、外部APIを実行するAPIを通じてすべてのkintone環境から自由にアクセスできるようになるため、セキュリティの観点から推奨していません。 同一ドメインに対するリクエストは、次のAPIを使用してください。
  kintone REST APIリクエストを送信するAPI
• このAPIを使って外部のAPIを実行しても、実行したAPI先で発行されるべきCookieは、自動で発行されません。
• HTTPメソッドにPOSTまたはPUTを指定した場合、「Content-Length」と「Transfer-Encoding」ヘッダーは自動で付加されます。
  リクエストするときに明示的に指定すると、エラーが発生します。

• 実行する外部APIのレスポンスに関する制限は、次のとおりです。
  • レスポンスヘッダーの上限は、100行で、1行あたりの最大長は8,180bytesです。
  • レスポンスボディの上限は10MBです。上限を超えるとエラーになります。
  • レスポンスボディは文字列のみ対応しています。画像などのバイナリデータは取得できません。
• 自己証明書を使ったサーバーとの通信はできません。