お知らせ：当社は、お客様により充実したサポート情報を迅速に提供するため、本ページのコンテンツは機械翻訳を用いて日本語に翻訳しています。正確かつ最新のサポート情報をご覧いただくには、本内容の英語版を参照してください。

早期アクセス

この機能はすべてのユーザーに対して有効になっているわけではありません。試用をご希望の場合は、メールでサポートチームにご連絡いただき、早期アクセスをお申し込みください。

QntrlのインバウンドREST Webサービスを使用すると、外部ユーザーやシステムが呼び出せるカスタムAPIエンドポイントを作成し、Qntrl内で特定の操作を実行できます。ユーザーがAPIを実行すると、Qntrlは要求を受信し、

FunctionスクリプトまたはCircuitで設定されたロジックに基づいて処理します。

主なポイント  

• カスタムエンドポイント：業務ワークフローに合わせたREST API URLを定義できます。例：https://<qntrl-domain>/webservice/<org_id>/<custom-endpoint>      

• セキュアアクセス：OAuthとAPIキー認証に対応しています。
• スマートロジック：カスタムスクリプト（Function）または自動フロー（Circuit）を実行できます。
  

ドメインをカスタマイズする場合は、Qntrlのホワイトラベル機能を使用します。

1. 外部システムがAPI要求を送信します。
   
2. Qntrlが要求を受信して認証します。
3. 設定済みのロジックがFunctionまたはCircuitを通じて実行されます。
4. 応答が返され、関連する処理がQntrl内で実行されます。
   

タブの作成     

1. 以下の順に（［設定］）→［WEB SERVICES］→［Inbound］→［REST］を選択します。
2. ［新しいInbound REST］をクリックします。
3. 次の項目を入力します。
   
1. ［名前］：タブの論理名（例：ジョブ、レイアウト）を入力します。これにより、関連するAPIをまとめてグループ化できます。
   
2. ［ベースURI］：このタブ内のAPIのベースパス（例：/jobs）を定義します。このプレフィックスは、このタブの下で作成されるすべてのAPIエンドポイントに含まれます。
   
3. ［認証方式］：Qntrlは、選択された認証方式を使用して受信API要求を検証します。次のいずれかを選択できます。
1. OAuth：組織のOAuthスコープまたはグローバルトークンでAPIを保護します。
2. APIキー：トークンベースの認証方式です。要求ヘッダーにAPIキーを追加します。APIキーの生成方法を確認する。
4. ［説明］：タブの概要、またはタブに含まれるAPIの目的について簡単な説明を追加します。
   
4. ［作成］をクリックします。
   

タブが作成されると、APIエンドポイントの詳細を定義する設定ウィンドウが開きます。

APIエンドポイントの設定     

• ［名前］：APIエンドポイントの名前を入力します。

• ［URL］：エンドポイントパス（例：/create）を定義します。これはタブのベースURIに追加されます。
• ［プレビュー］：ベースURIとエンドポイントパスに基づいて、完全なURLが自動生成されます。
  例：https://qntrl.com/webservice/668909960/jobs/create
• ［メソッド］：HTTPメソッド（GET、POST、PUT、DELETE、OPTIONS、PATCH）を選択します。
• ［リソースの種類］：このAPIが呼び出されたときに実行するハンドラーの種類を選択します。

• Function：Functionスクリプトを使用して要求を処理します。

• 既存のRESTタイプのFunctionを選択するか、新しく作成します。
• 新しいFunctionを作成する場合は、エディターにスクリプトを記述します。Functionは生成された名前で［Functions］タブに自動的に追加されます（後で名前を変更できます）。
• Functionスクリプト内で、受信した要求の処理方法と返す応答を定義できます。

• Circuit：APIが呼び出されたときに、事前定義済みのCircuitを実行します。Circuitでは、ファイル処理や応答設定（成功／エラーメッセージなど）はサポートされていません。

• ［リソース］：エンドポイントに関連付ける特定のFunctionまたはCircuitを選択します。

      

関数とCircuitにおけるリソース実行の仕組み     

関数リソース

• スクリプトから、要求パラメーター、ヘッダー、本文の内容、ファイルのアップロードにアクセスして処理できます。
  
• メッセージやHTTPステータスコードを含む、カスタムの成功レスポンスやエラーレスポンスを定義して返すことができます。
• 要求で送信されたファイルは、バイナリ入力として処理できます。
• 入力検証、動的処理、データ操作が必要な用途に適しています。
  

Circuitリソース

• APIにより、事前定義済みのQntrl Circuitが実行されます。
• Circuitは要求パラメーターを入力データとして受け取りますが、要求を操作したり検証を実行したりすることはできません。
• ファイル処理には対応していません。
• レスポンスのカスタマイズ（例：HTTPステータスコード、カスタムメッセージ）はできません。
  

対応関数  

Qntrlでは、受信REST APIの関数リソースを作成するために、次の言語に対応しています。

• JavaScript（ネイティブまたはCodexエンジン）

• その他のクラウド関数：Python、Java、Node.jsに対応しています。

/**
 * @param {ScriptedRestApiRequest} req
 * @param {ScriptedRestApiResponse} res
 */
function execute(req, res) {
try {
var requestHeaders = req.getRequestHeaders();
var requestParams = req.getRequestParams();
var uri = req.getUri();
console.log('要求 Headers ' + JSON.stringify(requestHeaders));
console.log('要求 Parameters ' + JSON.stringify(requestParams));
console.log('URI ' + uri);
// --- Read Body ---
var requestBody = '';
var readAsStream = true;
if (readAsStream)
{
let chunk;
let inputStream = req.getInputStream(); 
while( (chunk = inputStream.read()) != null){
 
let chunkStr = String.fromCharCode.apply(null, chunk);
requestBody += chunkStr;
} 
} else {
requestBody = req.getRequestBody();
}
// --- Prepare REST response ---
var responseData = {
status: 'success',
message: 'REST 要求 processed successfully using codex engine.'
};
// --- Set headers ---
        
let responseHeader = { '要求-id': '1718181881001' };
res.setResponseHeaders(responseHeader);
// --- Send Response ---
res.setStatus(200);
res.setContentType('application/json');
res.getOutputStream().write(JSON.stringify(responseData));
}
catch (e) {
res.setStatus(500);
res.setContentType('application/json');
res.getOutputStream().write(JSON.stringify({
status: 'error',
message: e.message + ''
}));
}
}

インポート com.zoho.cloud.function.Context;
インポート com.zoho.cloud.function.basic.*;
インポート org.json.JSONObject;
 
public class SampleRESTFunction implements ZCFunction {
	public void runner(Context context, BasicIO basicIO) throws Exception {
	// Read input parameters
String queryParameter = basicIO.getParameter('query_parameter').toString();
String header = basicIO.getParameter('header').toString();
String body = basicIO.getParameter('body').toString();
String url = basicIO.getParameter('url').toString();
 
// Write response
JSONObject response = new JSONObject();
JSONObject responseHeader = new JSONObject();
responseHeader.put('request_id', 'REQ-20251105-XYZ123');
responseHeader.put('timestamp', '2025-11-05T12:45:30Z');
responseHeader.put('content_type', 'application/json');
response.put('response_header', responseHeader);
response.put('status_code', 202);
response.put('body', 'Inbound REST 要求 processed sucessfully.');
basicIO.write(response.toString());
}
}

要求コンポーネントの設定     

• 要求パラメーター：クエリー値またはパス値として渡すパラメーターを定義します。
• ［パラメーター名］：入力パラメーターの名前です。
• ［データ型］：データ型（例：文字列、数値）を選択します。
• ［許可する正規表現］：パラメーター値の制限を設定します。
• ［最小長］：入力の最小長を定義します。
• ［最大長］：入力の最大長を定義します。
• ［初期値］：入力が指定されていない場合に使用する代替値です。
• ［必須］：パラメーターを必須にするかどうかを指定します。必須パラメーターが指定されていない場合、エラーが発生します。

      

• ［要求ヘッダー］：追加の検証用にカスタムヘッダーを定義します。
• 設定オプションは要求パラメーターと同じです。

• ［要求本文］：APIに最適な本文形式を選択します。
• ［なし］：要求本文はありません。
• ［Raw］：自由形式のデータ（例：JSON、XML）。
• 最小／最大長と必須の検証のみをサポートしています。
• ［x-www-form-urlencoded］：キーと値の本文形式（本文内のパラメーターのような形式）。
• ［ファイル］：バイナリファイルのアップロードが可能です（リソースの種類がFunctionの場合にのみサポートされます。）

• ［ポリシーの選択］：レート制限ポリシーを使用して、許可する要求数を制御します。
• ［レート制限ポリシーの選択］：既存のポリシーを選択するか、［新しいポリシーを追加］をクリックします。
• 新しいポリシーを追加するには：
• ［ポリシー名］：ポリシーのラベル。
• ［要求上限］：許可される要求の最大数。
• ［分］：レート制限の時間枠（例：1分あたり100件）。
• ［IP単位］：
• チェックあり：制限はIPアドレスごとに適用されます。
• チェックなし：制限は全体に適用されます。
• ［エラーコード］：制限を超過した場合に返されるコード。
• ［メッセージ］：定義した制限に達した場合にユーザーへ送信するエラーメッセージを定義します。
• ［保存］をクリックします。新しいポリシーが作成されます。

保存と公開     

• ［保存］をクリックしてエンドポイントを作成します。
• 左側の［リソース］配下に表示され、いつでも編集または削除できます。
• これで、エンドポイントはAPI要求を受信し、関連付けられたFunctionまたはCircuitを実行できる状態になります。

      

• 要求パラメーター、ヘッダー、本文のいずれかの検証に失敗した場合、Qntrlは要求を拒否します。

• 警告やエラーを処理して返せるのは、リソースとしてFunctionを使用している場合のみです。

• Circuitでは、詳細な入出力制御なしで基本的な自動化トリガーのみを利用できます。