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

早期アクセス

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

QntrlのInbound REST Web Serviceを使用すると、外部ユーザーや外部システムが呼び出せるカスタムAPIエンドポイントを作成し、Qntrl内で特定の処理を実行できます。ユーザーが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 SERVICES］→［Inbound］→［REST］を選択します。
   
3. ［New Inbound 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は生成された名前でFunctionsモジュールに自動的に追加されます（後で名前を変更できます）。
• Functionスクリプト内で、受信要求の処理方法と返す応答を定義できます。

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

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

      

関数とサーキット：リソース実行の仕組み     

関数リソース

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

サーキットリソース

• APIにより、事前定義されたQntrlサーキットが実行されます。
• サーキットは要求パラメーターを入力データとして受け取りますが、要求の操作や検証は実行できません。
• ファイル処理には対応していません。
• レスポンスのカスタマイズ（例：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('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());
}
}

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

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

      

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

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

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

保存と公開     

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

      

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

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

• Circuitでは、詳細な入出力制御を伴わない基本的な自動化トリガーのみを提供します。