kintone API ドキュメント

プラグインから外部 API を実行する

目次

プラグインから外部 API を実行する

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

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

関数

PC／モバイル

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

引数

引数 型 必須 説明
pluginId 文字列 必須 API を実行するプラグインの プラグイン ID
url 文字列 必須 実行する API の URL
method 文字列 必須 API の実行に使用する HTTP メソッド
次のいずれかの値を指定します。
  • GET
  • POST
  • PUT
  • DELETE
headers オブジェクト 必須 リクエストヘッダー
実際のリクエストヘッダーには、headers に指定したパラメーターに加えて、 外部 API の実行に必要な情報をプラグインへ保存する API を使用してプラグインに保存したパラメーターも送信されます。
何も指定しない場合は {} を指定します。
data オブジェクトまたは文字列 必須 リクエストボディ
実際のリクエストボディには、data に指定したパラメーターに加えて、 外部 API の実行に必要な情報をプラグインへ保存する API を使用してプラグインに保存したデータも送信されます。
指定した値は、method が「POST」または「PUT」のときだけ利用されます。
「GET」または「DELETE」の場合には、URL のクエリ文字列としてパラメーターを指定してください。
successCallback 関数 省略可 リクエストが完了したあとに実行する関数
関数の引数には、次の3つの情報が渡されます。
  • 第 1 引数：レスポンスボディ（文字列）
  • 第 2 引数：ステータスコード（数値）
  • 第 3 引数：レスポンスヘッダー（オブジェクト）
省略した場合は kintone.Promise オブジェクト が返り、上記のレスポンスボディ、ステータスコード、レスポンスヘッダーが格納された配列で解決されます。
failureCallback 関数 省略可 リクエストが失敗した場合に実行する関数
関数の引数には、実行した API のレスポンスボディ（文字列）が渡されます。
省略した場合は kintone.Promise オブジェクト が返り、実行した API のレスポンスボディ（文字列）で棄却されます。

戻り値

successCallback を指定した場合、戻り値はありません。
引数の successCallback を省略した場合は、 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 やリクエストヘッダーを指定したとします。

    • 設定その 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" } です。

*1

たとえば、それぞれの関数で次の URL を指定した場合には、URL が前方一致するため、プラグインへ保存した情報がリクエストに加わります。

^

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

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

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

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

1
2
3
4

{
  "k1": "v1",
  "k2": "v2"
}
外部 API を実行するときに送信されるリクエストボディ
HTTP メソッドが POST／PUT の場合

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

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

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

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

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

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

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

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

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

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

1
2
3
4
5

{
  "k1": "v1",
  "k2": "v2-1",
  "k3": "v3"
}
設定情報とこの API で指定したリクエストヘッダーやリクエストボディのキーが重複する場合

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

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

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

1
2
3
4
5

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

注意事項

  • URL に存在しないサーバーを指定した場合、レスポンスはステータスコード「503」（DNS Cache Missing）のエラーとなります。
  • IP 制限をしている環境で接続元ドメイン内の別アプリへアクセスする場合は、 cybozu.com が使用するドメインとIPアドレス (External link) に記載されている IP アドレスを許可することでアクセスが可能になります。
    ただし、プラグインから外部 API を実行する API を利用して外部から自由にアクセス可能となるため、セキュリティの観点から推奨されません。
    接続元ドメインへのアクセスは kintone REST API リクエストを送信する API を利用してください。
  • HTTP メソッドに POST または PUT を指定した場合、「Content-Length」と「Transfer-Encoding」ヘッダーは、内部的に自動で付加されます。
    リクエストするときに明示的に指定すると、エラーが発生します。