krewData
APIリファレンス
概要

プロトコル

HTTPS

URI

https://api.krewdata.grapecity.com/trigger/v1/{実行単位ID}

フォーマット

JSON

文字コード

UTF-8

API一覧

API URI 説明
アクセストークン要求 https://api.krewdata.grapecity.com/trigger/v1/{実行単位ID}/token 実行単位の実行を要求するためのアクセストークンを要求します。
実行要求 https://api.krewdata.grapecity.com/trigger/v1/{実行単位ID}/run 実行単位の実行を要求します。
実行状況確認 https://api.krewdata.grapecity.com/trigger/v1/{実行単位ID}/status 実行単位の実行状況を確認します。
アクセストークン要求

実行単位の実行を要求するためのアクセストークンを要求します。

取得したアクセストークンには有効期限があります。有効期限が切れた場合は新しいアクセストークンを取得する必要があります。

HTTPメソッド

POST

URI

https://api.krewdata.grapecity.com/trigger/v1/{実行単位ID}/token

リクエストパラメータ

パラメータ名 指定する値 必須 説明
krewdataAppUrl 文字列 必須 実行を要求する実行単位が登録されているkrewData専用アプリのURLを指定します。
serialNumber 文字列 必須 Base64エンコードしたリアルタイム実行のシリアルナンバーを指定します。

リクエストの例

{
     "krewdataAppUrl": "https://yourdomain.cybozu.com/k/123",
     "serialNumber": "abcdef-jklmno-pqrstu-xyz123-456789"
}

レスポンス

リクエストが成功すると、レスポンスコード(code)、レスポンスステータス(status)、およびアクセストークン(accessToken)が返されます。アクセストークンは、実行要求API、実行状況確認APIのリクエストパラメータで使用します。

パラメータ名 値の種類 説明
code 数値 レスポンスコード。リクエストが成功した場合は200が返されます。
status 文字列 レスポンスステータス。リクエストが成功した場合は"OK"が返されます。
accessToken 文字列 アクセストークン

レスポンスの例

{
    "code": 200,
    "status": "OK",
    "accessToken": "abcdefg1234567"
}

エラーレスポンス

リクエストが失敗すると、レスポンスコード(code)、レスポンスステータス(status)、およびエラーメッセージ(description)が返されます。

レスポンスコード (code) レスポンスステータス (status) エラーメッセージ (description) 説明
400 Bad Request krewdataAppUrl data type is wrong, should be string type. krewdataAppUrlに文字列以外の値が指定されています。文字列を指定してください。
400 Bad Request krewdataAppUrl format is wrong, should be "https://yourdomain/k/appId(/)". krewdataAppUrlの指定した値のURL形式が誤っています。正しいURL形式で指定してください。
例)https://yourdomain.cybozu.com/k/123
400 Bad Request krewdataAppUrl is empty or krewdataAppUrl cannot be found. Pay attention to the spelling of "krewdataAppUrl". リクエストパラメータの必須項目(krewdataAppUrl)が指定されていないか値が空です。パラメータと値を指定してください。
400 Bad Request Request path is invalid. 要求したURLは無効です。有効なURLを指定してください。
400 Bad Request Request type (Webhook/API/RunBykrewSheet) is wrong. 要求した実行単位は実行方法がWebhookに設定されています。実行単位の実行方法を確認してください。
400 Bad Request serialNumber data type is wrong, should be string type. serialNumberに文字列以外の値が指定されています。文字列を指定してください。
400 Bad Request serialNumber is empty or serialNumber cannot be found. Pay attention to the spelling of "serialNumber". リクエストパラメータの必須項目(serialNumber)が指定されていないか値が空です。パラメータと値を指定してください。
400 Bad Request serialNumber is not a valid Base64 encoding value. serialNumberに指定した値がBase64エンコードされていません。Base64エンコードした値を指定してください。
400 Bad Request Specified krewdataAppUrl is invalid, should be "https://yourdomain.cybozu.com/k/{appId}". krewdataAppUrlに指定した値が誤っています。実行を要求する実行単位が登録されているkrewData専用アプリの正しいURLを指定してください。
例)https://yourdomain.cybozu.com/k/123
400 Bad Request Specified unit is invalid. 実行単位が無効です。krewDataプラグインのリアルタイム実行タブで以下を確認してください。
・アクセストークンを要求した実行単位が「有効」に設定されていること
・アクセストークンを要求した実行単位に有効なデータ編集フローが登録されていること
400 Bad Request Token request body schema is wrong. リクエストボディの形式が誤っています。正しい形式で指定してください。
401 Unauthorized Illegal License. serialNumberに指定したシリアルナンバーは無効です。有効なシリアルナンバーを指定してください。
429 Too Many Requests The rate limit for API calls has been exceeded. Specified unit has been disabled. 一定時間内の実行回数上限を超えるリクエストが実行され実行単位が無効に設定されました。

エラーレスポンスの例

{
    "code": 400,
    "status": "Bad Request",
    "description": "Request path is invalid."
}
実行要求

アクセストークンを使用し、実行単位の実行を要求します。

アクセストークンは実行要求APIで1回限り使用できます。再度、実行要求APIを呼び出す場合は、新しいアクセストークンを取得する必要があります。

HTTPメソッド

POST

URI

https://api.krewdata.grapecity.com/trigger/v1/{実行単位ID}/run

リクエストパラメータ

パラメータ名 指定する値 必須 説明
accessToken 文字列 必須 アクセストークン要求APIで取得した有効なアクセストークンを指定します。
アクセストークンは実行要求APIで1回限り使用できます。再度、実行要求APIを呼び出す場合は、新しいアクセストークンを取得する必要があります。
user 文字列 必須 実行単位の実行を要求するユーザーのkintoneログイン名を指定します。
ここで指定したkintoneログイン名は、実行ログの「実行ユーザー」として記録されます。
appId 数値又は文字列 必須 実行を要求する実行単位の「呼び出し元アプリ」のアプリIDを指定します。
record オブジェクト 省略可 実行単位のパラメータとして使用するレコード情報を指定します。

リクエストの例

{
    "accessToken": "abcdefg1234567",
    "user": "krewdata@example.com",
    "appId": "1234",
    "record":{
        "レコード番号":{
            "type":"RECORD_NUMBER",
            "value":"1"
        },
        "入荷日":{
            "type":"DATE",
            "value":"2020-11-01"
        },
        ...
    }
}

レスポンス

リクエストが成功すると、レスポンスコード(code)、レスポンスステータス(status)、およびタスクID(taskId)が返されます。

パラメータ名 値の種類 説明
code 数値 レスポンスコード。リクエストが成功した場合は200が返されます。
status 文字列 レスポンスステータス。リクエストが成功した場合は"OK"が返されます。
taskId 文字列 タスクID

レスポンスの例

{
    "code": 200,
    "status": "OK",
    "taskId": "hijklmn8901234"
}

エラーレスポンス

リクエストが失敗すると、レスポンスコード(code)、レスポンスステータス(status)、およびエラーメッセージ(description)が返されます。

レスポンスコード (code) レスポンスステータス (status) エラーメッセージ (description) 説明
400 Bad Request accessToken data type is wrong, should be string type. accessTokenに文字列以外の値が指定されています。文字列を指定してください。
400 Bad Request accessToken is empty or accessToken cannot be found. Pay attention to the spelling of "accessToken". リクエストパラメータの必須項目(accessToken)が指定されていないか値が空です。パラメータと値を指定してください。
400 Bad Request app (appId) is not call app of task specified. appIdで指定したアプリIDが、実行を要求する実行単位の「呼び出し元アプリ」のアプリIDと異なります。「呼び出し元アプリ」のアプリIDを指定してください。
400 Bad Request appId data type is wrong, should be string type. appIdに文字列以外の値が指定されています。文字列を指定してください。
400 Bad Request appId is empty or appId cannot be found. Pay attention to the spelling of "appId". リクエストパラメータの必須項目(appId)が指定されていないか値が空です。パラメータと値を指定してください。
400 Bad Request record data type is wrong, should be keep with Kintone record. recordパラメータにkintoneのレコード情報と異なる構造の値が指定されています。kintoneのレコード情報形式で指定してください。
400 Bad Request Request path is invalid. 要求したURLは無効です。有効なURLを指定してください。
400 Bad Request Request type (Webhook/API/RunBykrewSheet) is wrong. 要求した実行単位は実行方法がkrewSheet連携に設定されています。実行単位の実行方法を確認してください。
400 Bad Request Run request body schema is wrong. リクエストボディの形式が誤っています。正しい形式で指定してください。
400 Bad Request Specified token has been created for more than 10 minutes and cannot be used to run unit. 指定したアクセストークンは有効期限が切れています。アクセストークン要求APIで新しいアクセストークンを取得してください。
400 Bad Request Specified token has been used. 指定したアクセストークンは使用済みです。アクセストークン要求APIで新しいアクセストークンを取得してください。
400 Bad Request Specified token is invalid. accessTokenに指定した値が無効です。アクセストークン要求APIで取得した有効なアクセストークンを指定してください。
400 Bad Request user data type is wrong, should be string type. userに文字列以外の値が指定されています。文字列を指定してください。
400 Bad Request user is empty or user cannot be found. Pay attention to the spelling of "user". リクエストパラメータの必須項目(user)が指定されていないか値が空です。パラメータと値を指定してください。
409 Conflict Other User is running the execution unit.","taskId":{taskId} 他のユーザーが実行単位を実行中です。この実行単位は同時実行が許可されていません。

エラーレスポンスの例

{
    "code": 400,
    "status": "Bad Request",
    "description": "Specified token is invalid."
}
実行状況確認

実行単位の実行状況を確認します。

HTTPメソッド

POST

URI

https://api.krewdata.grapecity.com/trigger/v1/{実行単位ID}/status

リクエストパラメータ

パラメータ名 指定する値 必須 説明
accessToken 文字列 必須 アクセストークン要求APIで取得した有効なアクセストークンを指定します。
taskId 文字列 必須 実行要求APIで取得したタスクIDを指定します。

リクエストの例

{
    "accessToken": "abcdefg1234567",
    "taskId": "hijklmn8901234"
}

レスポンス

リクエストが成功すると、レスポンスコード(code)、レスポンスステータス(status)、実行単位の実行状況(taskStatus)、および実行単位に含まれるデータ編集フローの実行情報(flowInfo)が返されます。

パラメータ名 値の種類 説明
code 数値 レスポンスコード。リクエストが成功した場合は200が返されます。
status 文字列 レスポンスステータス。リクエストが成功した場合は"OK"が返されます。
taskStatus 文字列 実行単位の実行状況
  • Queuing:実行待機中
  • Running:実行中
  • Success:実行完了(成功)
  • Failure:実行完了(失敗)
errorCode 文字列 taskStatusがFailureだった場合のエラーコード
エラーコードの詳細は「エラーメッセージ」のデータ編集フロー実行時のエラーを参照してください。
errorMessage 文字列 taskStatusがFailureだった場合のエラーメッセージ
エラーメッセージの詳細は「エラーメッセージ」のデータ編集フロー実行時のエラーを参照してください。
flowInfo オブジェクト配列 実行単位に含まれるデータ編集フローの実行情報配列
flowInfo.flowExecUniqueKey 文字列 実行したデータ編集フローを一意に識別するキー値
flowInfo.flowName 文字列 データ編集フロー名
flowInfo.status 文字列 データ編集フローの実行状況
  • Queuing:実行待機中
  • Running:実行中
  • Success:実行完了(成功)
  • Failure:実行完了(失敗)
  • Cancel:実行中止
flowInfo.startTime 文字列 データ編集フローの実行開始日時
flowInfo.endTime 文字列 データ編集フローの実行終了日時

レスポンスの例

実行単位が実行中の場合はtaskStatusが"Running"で返されます。

{
    "code": 200,
    "status": "OK",
    "taskStatus": "Running",
    "flowInfo": [
        {
            flowExecUniqueKey: "12345678",
            flowName: "フロー1",
            status: "Running",
            startTime: "2020-12-01 09:00:00",
            endTime: ""
        },
        {
            flowExecUniqueKey: "90123456",
            flowName: "フロー2",
            status: "Queuing"
        }
    ]
}

実行単位の実行が成功した場合はtaskStatusが"Success"で返されます。

{
    "code": 200,
    "status": "OK",
    "taskStatus": "Success",
    "flowInfo": [
        {
            flowExecUniqueKey: "12345678",
            flowName: "フロー1",
            status: "Success",
            startTime: "2020-12-01 09:00:00",
            endTime: "2020-12-01 09:01:00"
        },
        {
            flowExecUniqueKey: "90123456",
            flowName: "フロー2",
            status: "Success",
            startTime: "2020-12-01 09:01:00",
            endTime: "2020-12-01 09:02:00"
        }
    ]
}

実行単位の実行が失敗した場合はtaskStatusが"Failure"で返されます。flowInfoオブジェクトには、各データ編集フローの実行結果情報が含まれます。

1番目のデータ編集フローの実行中にエラーが発生した場合:

{
    "code": 200,
    "status": "OK",
    "taskStatus": "Failure",
    "errorCode": "33",
    "errorMessage": "データ編集フローの設定が正しくありません。データ編集フローのエラーを修正してください。",
    "flowInfo": [
        {
            flowExecUniqueKey: "12345678",
            flowName: "フロー1",
            status: "Failure",
            startTime: "2020-12-01 09:00:00",
            endTime: "2020-12-01 09:01:00"
        },
        {
            flowExecUniqueKey: "90123456",
            flowName: "フロー2",
            status: "Cancel"
        }
    ]
}

実行単位の同時実行が許可されていない、タイムアウトなどの理由により、データ編集フローが実行されずにエラーとなった場合:

{
    "code": 200,
    "status": "OK",
    "taskStatus": "Failure",
    "errorCode": "134",
    "errorMessage": "他のユーザーが実行単位を実行中です。この実行単位は同時実行が許可されていません。",
    "flowInfo": [
        {
            flowExecUniqueKey: "12345678",
            flowName: "フロー1",
            status: "Cancel"
        },
        {
            flowExecUniqueKey: "90123456",
            flowName: "フロー2",
            status: "Cancel"
        }
    ]
}

エラーレスポンス

リクエストが失敗すると、レスポンスコード(code)、レスポンスステータス(status)、およびエラーメッセージ(description)が返されます。

レスポンスコード (code) レスポンスステータス (status) エラーメッセージ (description) 説明
400 Bad Request accessToken data type is wrong, should be string type. accessTokenに文字列以外の値が指定されています。文字列を指定してください。
400 Bad Request accessToken is empty or accessToken cannot be found. Pay attention to the spelling of "accessToken". リクエストパラメータの必須項目(accessToken)が指定されていないか値が空です。パラメータと値を指定してください。
400 Bad Request Request path is invalid. 要求したURLは無効です。有効なURLを指定してください。
400 Bad Request Specified accessToken is invalid. accessTokenに指定した値が無効です。アクセストークン要求APIで取得した有効なアクセストークンを指定してください。
400 Bad Request Specified taskId is invalid. taskIdに指定した値が無効です。実行要求APIで取得した有効なタスクIDを指定してください。
400 Bad Request Status request body schema is wrong. リクエストボディの形式が誤っています。正しい形式で指定してください。
400 Bad Request taskId data type is wrong, should be string type. taskIdに文字列以外の値が指定されています。文字列を指定してください。
400 Bad Request taskId is empty or taskId cannot be found. Pay attention to the spelling of "taskId". リクエストパラメータの必須項目(taskId)が指定されていないか値が空です。パラメータと値を指定してください。

エラーレスポンスの例

{
    "code": 400,
    "status": "Bad Request",
    "description": "Specified taskId is invalid."
}
サンプルコード

アプリのレコード詳細画面に実行ボタンを配置し、ボタンクリック時に実行単位の実行を要求するサンプルコードを以下に示します。

このサンプルコードでは、レコード詳細画面のメニューの上側の空白部分に「実行」ボタンを配置します。

サンプルコード
コードのコピー
(function () {
  'use strict';
  kintone.events.on('app.record.detail.show', function (event) {
    var url = 'https://api.krewdata.grapecity.com/trigger/v1/abcdefghijklmn';
    var krewdataAppUrl = 'https://yourdomain.cybozu.com/k/123';
    var serialNumber = 'abcdef-jklmno-pqrstu-xyz123-456789';
    // 「実行」ボタンを配置
    if (document.getElementById('run_button') !== null) {
      return;
    }
    var runButton = document.createElement('button');
    runButton.id = 'run_button';
    runButton.innerText = '実行';
    runButton.onclick = async(butotnEvent) => {
      if (window.confirm('krewDataの実行単位を実行しますか?')) {
        // アクセストークンを要求する
        var tokenBody = {
          'krewdataAppUrl': krewdataAppUrl,
          'serialNumber': window.btoa(serialNumber)
        };
        var tokenResponse = await sendRequest('token', url, tokenBody);
        console.log(JSON.stringify(tokenResponse));
        // 実行単位の実行を要求する
        if (tokenResponse.code == 200) {
          var accessToken = tokenResponse.accessToken;
          var runBody = {
            'accessToken': accessToken,
            'user': kintone.getLoginUser().code,
            'appId': event.appId.toString(),
            'record': event.record
          };
          var runResponse = await sendRequest('run', url, runBody);
          console.log(JSON.stringify(runResponse));
          // 実行単位の実行状況を確認する
          if (runResponse.code == 200) {
            var taskId = runResponse.taskId;
            var statusBody = {
              'accessToken': accessToken,
              'taskId': taskId
            };
            var statusInterval = setInterval(async function () {
              var statusResponse = await sendRequest('status', url, statusBody);
              console.log(JSON.stringify(statusResponse));
              if (statusResponse.taskStatus == 'Success' || statusResponse.taskStatus == 'Failure') {
                clearInterval(statusInterval);
              }
            }, 5000); // 5sec
          }
        }
      }
    }
    kintone.app.record.getHeaderMenuSpaceElement().appendChild(runButton);
  });
})();
function sendRequest(api, url, body) {
  var _kintone = kintone;
  var uri = url + '/' + api;
  return new _kintone.Promise(function (resolve, reject) {
    _kintone.proxy(uri, 'POST', {
      'Content-Type': 'application/json;charset=UTF-8'
    }, body, function (body, status, headers) {
      resolve(JSON.parse(body));
    }, function (error) {
      reject(error);
    });
  });
}
関連トピック

 

 


Copyright © 2024 MESCIUS inc. All rights reserved.