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

早期アクセス

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

QntrlのInbound REST Web Serviceでは、外部ユーザーや外部システムが呼び出して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 SERVICES→Inbound→REST］を選択します。
   
3. ［新しい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、削除、OPTIONS、PATCH）を選択します。
• ［リソースの種類］：このAPIが呼び出されたときに実行するハンドラーの種類を選択します。

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

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

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

• ［リソース］：エンドポイントに関連付ける特定の関数または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に最適な本文形式を選択します。
• なし：リクエスト本文はありません。
• 未加工：任意形式のデータ（JSON、XMLなど）。
• 最小／最大長と必須の検証のみ対応しています。
• x-www-form-urlencoded：キーと値の本文形式（本文内のパラメーターのような形式）。
• ファイル：バイナリファイルをアップロードできます（リソースの種類がFunctionの場合にのみ対応しています。）

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

保存と公開     

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

      

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

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

• Circuitでは、詳細な入出力制御はできず、基本的な自動化トリガーのみが提供されます。