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

戻り値

固定リンクがコピーされました

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" }です。

*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と、外部APIのURLの、より多くの文字に一致する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アドレス制限を設定している場合、このJavaScript APIを使って同一ドメインの別アプリに対しkintone REST APIを実行するには、kintoneのIPアドレスを許可してください。
    IPアドレスの詳細は、次のページを参照してください。
    cybozu.comが使用するドメインとIPアドレス (External link)
    ただし、外部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です。上限を超えるとエラーになります。
    • レスポンスボディは文字列のみ対応しています。画像などのバイナリデータは取得できません。
  • 自己証明書を使ったサーバーとの通信はできません。