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

早期アクセス

この機能はすべてのユーザーに有効化されているわけではありません。お試しになりたい場合は、メールで早期アクセスについてサポートチームにお問い合わせください。

QntrlのインバウンドREST Webサービスでは、外部ユーザーやシステムが呼び出してQntrl内で特定の操作を実行できるカスタムAPIエンドポイントを作成できます。ユーザーがAPIをトリガーすると、Qntrlは要求を受信し、設定済みのロジックに基づいて、

FunctionスクリプトまたはCircuitで処理します。

主な特長  

• カスタムエンドポイント：ビジネスワークフローに固有のREST API URLを定義できます。例： https://<qntrl-domain>/webservice/<org_id>/<custom-endpoint>      

• 安全なアクセス：OAuthおよびAPIキー認証に対応しています。
• スマートロジック：カスタムスクリプト（Functions）または自動フロー（Circuits）をトリガーできます。
  

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

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

モジュールの作成     

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

モジュールが作成されると、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を作成する場合は、エディターでスクリプトを作成します。Functionは生成された名前でFunctionsモジュールに自動的に追加されます（名前は後で変更できます）。
• Functionスクリプト内で、受信した要求の処理方法と返す応答を定義できます。

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

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

      

関数とCircuitの違い：リソース実行の仕組み     

関数リソース

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

Circuitリソース

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

対応している関数  

Qntrlでは、受信REST APIで関数リソースを構築するために、次の言語をサポートしています。

• JavaScript（Nativeまたは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('Request Headers ' + JSON.stringify(requestHeaders));
console.log('Request 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 Request processed successfully using codex engine.'
};
// --- Set headers ---
        
let responseHeader = { 'request-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 + ''
}));
}
}

import com.zoho.cloud.function.Context;
import com.zoho.cloud.function.basic.*;
import 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 request 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では、詳細な入力／出力制御はできず、基本的な自動化トリガーのみ提供されます。