Dataphin:付録：API 呼び出し例

SDK 呼び出し

Java SDK の概要

Dataphin Data Service Java SDK は、Data Service API を迅速に呼び出すための基本 SDK とサンプルコードを提供します。このセクションでは、Dataphin サービス Java SDK の使用方法について説明します。

Java SDK のコードファイル階層は次のとおりです。

Java SDK/

• demo/

  • ClientDemo.java は、同期 API 操作を呼び出すための例とメソッドを提供します。

  • AsyncClientDemo.java は、非同期 API 操作を呼び出すための例とメソッドを提供します。

• lib/

  • dataphin-sdk-core-java-v5.4.0.jar は、この SDK の依存関係パッケージです。

  • dataphin-sdk-core-java-v5.4.0-javadoc.jar は、依存関係パッケージの Javadoc です。

  • dataphin-sdk-core-java-v5.4.0-jar-with-dependencies.jar は、完全な依存関係パッケージです。

• ApiDocument_v5.4.0.md は、API 操作ドキュメントです。

• LICENSE はライセンスです。

Java SDK は、次の手順で取得できます。

1. Dataphin のホームページの上部メニューバーで、[サービス] > [アプリケーション管理] を選択します。

2. 左側のナビゲーションウィンドウで、[呼び出し手順] をクリックします。

3. [API 呼び出し手順] タブをクリックし、ページの右上隅にある [Java SDK ダウンロード] を選択して、ダウンロードした SDK JAR パッケージを pom.xml に追加します。

Java SDK 同期 API 呼び出しプロセス

ステップ 1：環境の準備

1. Dataphin サービス Java SDK には JDK 1.8 以降が必要です。

2. SDK が認証と署名情報を生成するために、認証キーのペア、つまり AppKey と AppSecret を準備する必要があります。

   [サービス] > [アプリケーション管理] > [マイアプリケーション] ページのリストから AppKey と AppSecret を取得できます。

   重要

   AppKey と AppSecret は、Dataphin Data Service がユーザーリクエストを認証するために使用するキーです。これらの 2 つの構成がクライアント側に保存されている場合は、適切に暗号化してください。

3. pom.xml ファイルに次の依存関係を追加します。dataphin-sdk-core-java を追加するときにエラーが発生した場合は、パス JAVA_SDK/lib/dataphin-sdk-core-java-v5.4.0.jar から JAR ファイルを手動で追加します。これは Java SDK の JAR パッケージです。

   説明

   dataphin-sdk-core-java は中央の Maven リポジトリでは使用できないため、SDK をダウンロードした後、会社の Maven リポジトリにアップロードするか、IDEA または Eclipse に手動でインポートする必要があります。

   <dependency>
       <groupId>com.alibaba.dt</groupId>
       <artifactId>dataphin-sdk-core-java</artifactId>
       <version>v5.4.0</version>
   </dependency>

ステップ 2：Java SDK API インターフェース呼び出しクラスをインポートする

1. [サービス] > [API マーケットプレイス] > [API] ページから対応する API ドキュメントをダウンロードできます。

2. `ClientDemo.java` をインポートし、ClientDemo.java クラスのインポート文とパッケージ文を修正します。

   import java.util.*;
   import java.util.function.Consumer;
   
   import com.alibaba.cloudapi.sdk.constant.SdkConstant;
   import com.alibaba.cloudapi.sdk.enums.Scheme;
   import com.alibaba.cloudapi.sdk.model.ApiCallback;
   import com.alibaba.cloudapi.sdk.model.ApiRequest;
   import com.alibaba.cloudapi.sdk.model.ApiResponse;
   import com.alibaba.dt.dataphin.client.ApiClient;
   import com.alibaba.dt.dataphin.client.ApiClientBuilderParams;
   import com.alibaba.dt.dataphin.client.sse.SseApiClient;
   import com.alibaba.dt.dataphin.schema.ManipulationParamRequest;
   import com.alibaba.dt.dataphin.schema.OrderBy;
   import com.alibaba.dt.dataphin.schema.QueryParamRequest;
   import com.alibaba.fastjson.JSON;
   
   /**
    * 同期 API の例
    * <p>
    * 使用方法:
    *  まず、HOST、APP_KEY、APP_SECRET、および API_ID を構成します。
    *  次に、必要に応じて getClient() の変数と packQueryParamRequest() のパラメーター値を設定します。
    * 注:
    *  getClient() のパラメーターは、API ごとに異なる値を持つ場合があります。getClient() を変更して入力パラメーターを受け入れるようにすることで、さまざまな API に適応させることができます。
    */
   public class ClientDemo {
   
       /**
        * エンドポイントまたは IP アドレス。この値は DataService Studio のネットワーク構成から取得します。
        */
       private static final String HOST = "xxx";
       /**
        * この API を呼び出すために使用するアプリケーションの AppKey。
        */
       private static final String APP_KEY = "xxx";
       /**
        * この API を呼び出すために使用するアプリケーションの AppSecret。
        */
       private static final String APP_SECRET = "xxx";
       /**
        * 呼び出す API の ID。
        */
       private static final String API_ID = "xxx";
   
       public static void main(String[] args) throws Exception {
           // GET API を同期的に呼び出します。
           syncGet();
           // LIST API を同期的に呼び出します。
           syncList();
           // GET API を非同期的に呼び出します。
           asyncGet();
           // LIST API を非同期的に呼び出します。
           asyncList();
           // GET API をストリーム呼び出しします。
           fluxGet();
           // クエリの総数も取得するページ分割クエリ API。
           syncListWithTotalNum();
   
           // CREATE API を同期的に呼び出します。
           syncCreate();
           // UPDATE API を同期的に呼び出します。
           syncUpdate();
           // DELETE API を同期的に呼び出します。
           syncDelete();
       }
   
       private static void syncListWithTotalNum() {
           ApiClient client = getClient();
   
           // 必要に応じて、戻りフィールド、クエリ条件、およびその他のパラメーターを変更します。
           QueryParamRequest queryParamRequest = packRequestParamWithReturnNum();
   
           ApiResponse response = client.listSync(API_ID, queryParamRequest);
   
           String resultStr = getResultString(response);
   
           // ResultBody に totalNum を含めます
           System.out.println(resultStr);
       }
   
       /**
        * GET API を同期的に呼び出します。
        */
       public static void syncGet() {
           // ApiClient オブジェクトを取得します。
           ApiClient client = getClient();
   
           // 必要に応じて、戻りフィールド、クエリ条件、およびその他のパラメーターを変更します。
           QueryParamRequest queryParamRequest = packRequestParam();
   
           ApiResponse response = client.getSync(API_ID, queryParamRequest);
   
           System.out.println(getResultString(response));
       }
   
       /**
        * LIST API を同期的に呼び出します。
        */
       public static void syncList() {
           // ApiClient オブジェクトを取得します。
           ApiClient client = getClient();
   
           // 必要に応じて、戻りフィールド、クエリ条件、およびその他のパラメーターを変更します。
           QueryParamRequest queryParamRequest = packRequestParam();
   
           ApiResponse response = client.listSync(API_ID, queryParamRequest);
   
           System.out.println(getResultString(response));
       }
   
       /**
        * CREATE API を同期的に呼び出します。
        */
       public static void syncCreate() {
           // ApiClient オブジェクトを取得します。
           ApiClient client = getClient();
   
           // 必要に応じて入力パラメーターを変更します。
           ManipulationParamRequest manipulationParamRequest = packDmlRequestParam();
   
           ApiResponse response = client.createSync(API_ID, manipulationParamRequest);
   
           System.out.println(getResultString(response));
       }
   
       /**
        * UPDATE API を同期的に呼び出します。
        */
       public static void syncUpdate() {
           // ApiClient オブジェクトを取得します。
           ApiClient client = getClient();
   
           // 必要に応じて入力パラメーターを変更します。
           ManipulationParamRequest manipulationParamRequest = packDmlRequestParam();
   
           ApiResponse response = client.updateSync(API_ID, manipulationParamRequest);
   
           System.out.println(getResultString(response));
       }
   
       /**
        * DELETE API を同期的に呼び出します。
        */
       public static void syncDelete() {
           // ApiClient オブジェクトを取得します。
           ApiClient client = getClient();
   
           // 必要に応じて入力パラメーターを変更します。
           ManipulationParamRequest manipulationParamRequest = packDmlRequestParam();
   
           ApiResponse response = client.deleteSync(API_ID, manipulationParamRequest);
   
           System.out.println(getResultString(response));
       }
   
       /**
        * GET API を非同期的に呼び出します。
        * コールバックメソッドで応答を処理する必要があります。
        */
       public static void asyncGet() throws Exception {
           // ApiClient オブジェクトを取得します。
           ApiClient client = getClient();
           // 必要に応じて、戻りフィールド、クエリ条件、およびその他のパラメーターを変更します。
           QueryParamRequest queryParamRequest = packRequestParam();
   
           client.getAsync(API_ID, queryParamRequest,
                   new ApiCallback() {
                       @Override
                       public void onFailure(ApiRequest request, Exception e) {
                           e.printStackTrace();
                       }
   
                       @Override
                       public void onResponse(ApiRequest request, ApiResponse response) {
                           try {
                               System.out.println(getResultString(response));
                           } catch (Exception e) {
                               e.printStackTrace();
                           }
                       }
                   });
           System.out.println("--- メインスレッドは早期に終了します。 ---");
       }
   
       /**
        * LIST API を非同期的に呼び出します。
        * コールバックメソッドで応答を処理する必要があります。
        */
       public static void asyncList() throws Exception {
           // ApiClient オブジェクトを取得します。
           ApiClient client = getClient();
           // 必要に応じて、戻りフィールド、クエリ条件、およびその他のパラメーターを変更します。
           QueryParamRequest queryParamRequest = packRequestParam();
   
           client.listAsync(API_ID, queryParamRequest,
                   new ApiCallback() {
                       @Override
                       public void onFailure(ApiRequest request, Exception e) {
                           e.printStackTrace();
                       }
   
                       @Override
                       public void onResponse(ApiRequest request, ApiResponse response) {
                           try {
                               System.out.println(getResultString(response));
                           } catch (Exception e) {
                               e.printStackTrace();
                           }
                       }
                   });
           System.out.println("--- メインスレッドは早期に終了します。 ---");
       }
   
       /**
        * ApiClient オブジェクトを取得します。
        */
       public static ApiClient getClient() {
           ApiClientBuilderParams params = new ApiClientBuilderParams();
           // アプリケーションの AppKey。
           params.setAppKey(APP_KEY);
           // アプリケーションの AppSecret。
           params.setAppSecret(APP_SECRET);
           // エンドポイントまたは IP アドレス。
           params.setHost(HOST);
           // デフォルトのプロトコルは HTTP です。API に基づいてプロトコルを HTTPS に設定できます。
           // 注: Dataphin の組み込みゲートウェイは HTTPS をサポートしていません。Alibaba Cloud API Gateway は HTTPS をサポートしています。
           params.setScheme(Scheme.HTTP);
           // API にアクセスするためのデータ環境。RELEASE は本番環境を指定し、PRE は開発環境を指定します。
           params.setStage("RELEASE");
           // 環境が指定されていない第 2 レベルドメイン名または独立ドメイン名を使用する場合は、env パラメーターを設定する必要があります。
           // 有効な値: PROD と PRE。基本モードを使用する場合は、このパラメーターを PROD に設定します。Dev-Prod モードを使用する場合は、このパラメーターを PROD に設定して本番データベースのデータをクエリするか、PRE に設定して開発データベースのデータをクエリします。
           // 環境にアクセスするために独立ドメイン名を指定した場合、env パラメーターは有効になりません。
           params.setEnv("PROD");
   
           ApiClient apiClient = new ApiClient(params);
           // Impala データベースタイプのタイムアウト期間とポーリング間隔を設定します。これはオプションです。デフォルトのタイムアウト期間は 300 秒で、デフォルトのポーリング間隔は 800 ミリ秒です。
           // このパラメーターは Impala でのみ有効です。Impala 以外の API を呼び出すときにもこのパラメーターを設定する必要があります。デフォルト値のままにすることができます。
           apiClient.setImpalaTimeoutAndInterval(300, 800);
           return apiClient;
       }
   
       public static SseApiClient getSseClient() {
           ApiClientBuilderParams params = new ApiClientBuilderParams();
           // アプリケーションの AppKey。
           params.setAppKey(APP_KEY);
           // アプリケーションの AppSecret。
           params.setAppSecret(APP_SECRET);
           // エンドポイントまたは IP アドレス。
           params.setHost(HOST);
           // デフォルトのプロトコルは HTTP です。API に基づいてプロトコルを HTTPS に設定できます。
           // 注: Dataphin の組み込みゲートウェイは HTTPS をサポートしていません。Alibaba Cloud API Gateway は HTTPS をサポートしています。
           params.setScheme(Scheme.HTTP);
           // API にアクセスするためのデータ環境。RELEASE は本番環境を指定し、PRE は開発環境を指定します。
           params.setStage("RELEASE");
           // 環境が指定されていない第 2 レベルドメイン名または独立ドメイン名を使用する場合は、env パラメーターを設定する必要があります。
           // 有効な値: PROD と PRE。基本モードを使用する場合は、このパラメーターを PROD に設定します。Dev-Prod モードを使用する場合は、このパラメーターを PROD に設定して本番データベースのデータをクエリするか、PRE に設定して開発データベースのデータをクエリします。
           // 環境にアクセスするために独立ドメイン名を指定した場合、env パラメーターは有効になりません。
           params.setEnv("PROD");
           return new SseApiClient(params);
   
       }
   
       /**
        * コンシューマーを含む API を呼び出します。
        */
       public static void fluxGet() {
           Consumer<ApiResponse> consumer = r -> System.out.println(new String(r.getBody()));
           SseApiClient sseApiClient = getSseClient();
           // 短命なアプリケーションの場合、タスク完了後にクライアントのスレッドプールをシャットダウンしてリソースを解放できます。
           sseApiClient.getFlux(API_ID, packRequestParam())
                   // 一時的な実行の場合、完了時に接続を閉じてリソースを解放する必要があります。
                   .doOnComplete(sseApiClient::shutdown)
                   .subscribe(consumer);
       }
   
       private static QueryParamRequest packRequestParamWithReturnNum() {
           QueryParamRequest queryParamRequest = packRequestParam();
           queryParamRequest.setReturnTotalNum(true);
           return queryParamRequest;
       }
   
       /**
        * リクエストオブジェクトをパッケージ化します。
        */
       private static QueryParamRequest packRequestParam() {
           QueryParamRequest queryParamRequest = new QueryParamRequest();
   
           /********* API 関連のビジネスパラメーター設定開始 *********/
           /*
            * プロキシアカウントタイプ。このパラメーターはオプションです。
            * 注: プロキシモードを使用するには、次の条件を満たす必要があります:
            *  1. 行レベルの権限機能が有効になっている。
            *  2. アプリケーションにプロキシ権限が付与されている。
            *  3. API が行レベルの権限に関連付けられている。
            *
            * プロキシモードで認証を使用する場合、プロキシユーザーのアカウントタイプを指定する必要があります。
            *  ACCOUNT_NAME: Dataphin のユーザー名。
            *  USER_ID: Dataphin の一意の ID。
            *  SOURCE_USER_ID: ソースシステムのアカウント ID。
            * このパラメーターは、DelegationUid が設定されている場合にのみ構成する必要があります。このパラメーターを構成しない場合、デフォルトのタイプは USER_ID です。
            */
           queryParamRequest.setAccountType("USER_ID");
   
           /*
            * プロキシアカウント ID。このパラメーターはオプションです。
            * プロキシでアクセスするユーザー。選択した AccountType に基づいて、対応するアカウント ID を入力する必要があります。
            * このパラメーターを設定し、API が行レベルの権限ルールに関連付けられている場合、プロキシモードが認証に使用されます。
            */
           queryParamRequest.setDelegationUid("abcd");
   
           /*
            * リクエストパラメーターのリスト。オプションのパラメーターは指定しなくてもかまいません。必須パラメーターは指定する必要があります。そうしないと、エラーが返されます。
            * キーはクエリフィールドを指定し、値はクエリフィールドの値を指定します。
            * たとえば、id はリクエストフィールド名で、1 は id の値です。複数のクエリパラメーターを設定できます。
            * 注: IN タイプのパラメーターの場合、List を使用してパラメーター値をラップします。
            */
           Map<String, Object> conditions = new HashMap<>();
           conditions.put("id", 1);
           conditions.put("age", Arrays.asList(10, 20, 30));
           queryParamRequest.setConditions(conditions);
   
           /*
            * 返されるパラメーターのリスト。このパラメーターは空にできません。
            * たとえば、id と name を返すように指定します。
            * 注: 返されるパラメーターが存在しないか、パラメーターに対する権限がない場合、エラーが報告されます。
            */
           queryParamRequest.setReturnFields(Arrays.asList("id", "name"));
   
           /*
            * ソートフィールド。このパラメーターはオプションです。
            * 注: Oracle または SQL Server を使用する場合、ページネーションにはソートを使用する必要があります。
            * パラメーターを昇順または降順でソートするかどうかを指定します。複数のフィールドを昇順または降順でソートするように設定できます。
            * たとえば、返された結果を id で昇順にソートします。
            */
           List<OrderBy> orderList = new ArrayList<>();
           orderList.add(new OrderBy("id1", OrderBy.Order.ASC));
           orderList.add(new OrderBy("id2", OrderBy.Order.DESC));
           queryParamRequest.setOrderBys(orderList);
   
           /*
            * ページネーションパラメーター。このパラメーターはオプションで、LIST タイプの API でのみ有効です。
            */
           // データが取得される位置。
           queryParamRequest.setPageStart(0);
           // 各ページで取得するデータエントリの数。
           queryParamRequest.setPageSize(10);
   
           /*
            * API バージョン番号。このパラメーターはオプションで、開発環境の API でのみ設定できます。
            */
           // queryParamRequest.setApiVersion("V1");
   
           /********* API 関連のビジネスパラメーター設定終了 *********/
   
   
           /********* 機能パラメーター設定開始 *********/
   
           /*
            * モデルキャッシュを使用するかどうかを指定します。
            * この機能を有効にすると、同じ入力および出力パラメーターを持つサービスユニット内の同じ API の解析頻度が減少します。これにより、クエリ効率が向上します。
            */
           queryParamRequest.setUseModelCache(false);
   
           /*
            * 結果キャッシュを使用するかどうかを指定します。
            * この機能を有効にすると、同じ条件と返されたフィールドを持つ同じ API のクエリ結果がキャッシュされます。
            * この機能は、変更されないデータのクエリに適しています。同じ SQL 文のクエリ頻度を減らし、クエリ効率を向上させます。
            * デフォルトのキャッシュ期間は 30 分です。バージョン 3.5.6 以降、API 開発ページでキャッシュ期間を設定できます。
            * 注: API で結果キャッシュが有効になっていない場合、このパラメーターは無効です。
            */
           queryParamRequest.setUseResultCache(false);
   
           /*
            * フィールドの大文字と小文字を区別するかどうかを指定します。
            * フィールドで大文字と小文字が区別される場合は、このパラメーターを true に設定することをお勧めします。
            * このパラメーターが false に設定されている場合、直接接続 API によって返される結果のフィールド名はデフォルトで大文字になります。
            */
           queryParamRequest.setKeepColumnCase(true);
   
           /********* 機能パラメーター設定終了 *********/
   
           return queryParamRequest;
       }
   
       /**
        * DML リクエストオブジェクトをパッケージ化します。
        */
       private static ManipulationParamRequest packDmlRequestParam() {
           ManipulationParamRequest manipulationParamRequest = new ManipulationParamRequest();
   
           /*
            * リクエストパラメーターのリスト。オプションのパラメーターは指定しなくてもかまいません。必須パラメーターは指定する必要があります。そうしないと、エラーが返されます。
            * キーはフィールド名で、値はフィールドの値です。
            * たとえば、id はリクエストフィールド名で、1 は id の値です。複数のパラメーターを設定できます。
            * 注: IN タイプのパラメーターの場合、List を使用してパラメーター値をラップします。
            */
           Map<String, Object> conditions = new HashMap<>();
           conditions.put("id", 1);
           conditions.put("age", Arrays.asList(10, 20, 30));
           manipulationParamRequest.setConditions(conditions);
   
           /*
            * API がデータをバッチで処理する場合、入力パラメーターを batchConditions に入れる必要があります。
            */
           List<Map<String, Object>> batchConditions = new ArrayList<>();
           batchConditions.add(conditions);
           manipulationParamRequest.setBatchConditions(batchConditions);
   
           /*
            * API バージョン番号。このパラメーターはオプションで、開発環境の API でのみ設定できます。
            */
           // manipulationParamRequest.setApiVersion("V1");
   
           return manipulationParamRequest;
       }
   
       /**
        * 結果文字列を取得します。
        */
       private static String getResultString(ApiResponse response) {
           /*
            * ステップ 1: HttpResponse ヘッダーから詳細情報を取得する方法
            *         response.getHeaders().get(key)
            *         説明: キーは "date\server\transfer-encoding\keep-alive\vary\connection\content-type\x-ca-request-id\x-ca-error-message\x-ca-error-code" になります。
            *              API 呼び出しが失敗した場合、ヘッダーには x-ca-error-message (エラーメッセージの説明) と x-ca-error-code (ゲートウェイエラーコード) が含まれます。呼び出しが成功した場合、これらのヘッダーは存在しません。
            *              ただし、x-ca-request-id (各リクエストの一意の ID) は常に存在します。
            *         推奨: 返されたコードが 200 でない場合は、x-ca-error-message と x-ca-error-code を出力して問題をトラブルシューティングします。
            *         必須: ログの確認を容易にするために、使用中に x-ca-request-id を出力します。
            *
            * ステップ 2: 応答の詳細情報が以下に出力されます。実際の開発では、ステップ 1 で説明されているように、関連情報を出力することを選択できます。
            */
           System.out.println("詳細な応答情報: "+ SdkConstant.CLOUDAPI_LF + JSON.toJSONString(response) + SdkConstant.CLOUDAPI_LF);
   
           StringBuilder result = new StringBuilder();
           result.append("バックエンドサーバーからの応答").append(SdkConstant.CLOUDAPI_LF).append(SdkConstant.CLOUDAPI_LF);
           result.append("ResultCode:").append(SdkConstant.CLOUDAPI_LF).append(response.getCode()).append(SdkConstant.CLOUDAPI_LF).append(SdkConstant.CLOUDAPI_LF);
           result.append("RequestId:").append(SdkConstant.CLOUDAPI_LF).append(response.getHeaders().get("x-ca-request-id")).append(SdkConstant.CLOUDAPI_LF).append(SdkConstant.CLOUDAPI_LF);
           if (200 != response.getCode()) {
               result.append("ErrorCode:").append(SdkConstant.CLOUDAPI_LF).append(response.getHeaders().get("x-ca-error-code")).append(SdkConstant.CLOUDAPI_LF).append(SdkConstant.CLOUDAPI_LF);
               result.append("ErrorMessage:").append(SdkConstant.CLOUDAPI_LF).append(response.getHeaders().get("x-ca-error-message")).append(SdkConstant.CLOUDAPI_LF).append(SdkConstant.CLOUDAPI_LF);
           }
           result.append("ResultBody:").append(SdkConstant.CLOUDAPI_LF).append(new String(response.getBody(), SdkConstant.CLOUDAPI_ENCODING));
   
           /*
            * 結果を確認します。状態コードが 200 でない場合は、x-ca-error-message を確認してトラブルシューティングできます。
            * x-ca-request-id パラメーターを保存することをお勧めします。例外が発生した場合は、このパラメーターを提供して問題をトラブルシューティングしてください。
            */
           return result.toString();
       }
   
   }
   

ステップ 3：通信チャネルクラスを初期化する

API 操作を呼び出すには、まずクライアントを初期化する必要があります。ClientDemo.java の getClient メソッドを参照し、ApiClientBuilderParams クラスを使用して初期化できます。`Host`、`APP_Key`、および `APP_Secret` 変数を置き換える必要があります。

ステップ 4: API インターフェイスの説明

• API インターフェースタイプ

  • API 操作は、クエリタイプ (LIST および GET) と操作タイプ (CREATE、UPDATE、および DELETE) に分類されます。

  • LIST はページ分割クエリをサポートしますが、GET はサポートしません。QueryParamRequest のパラメーターを設定するには、ClientDemo.java の packRequestParam メソッドをご参照ください。

  • 操作タイプの API 操作については、ClientDemo.java の packDmlRequestParam メソッドを参照して、ManipulationParamRequest のパラメーターを設定してください。

• API インターフェースの呼び出し

  • SDK の LIST メソッドと GET メソッドは、Dataphin Data Service の汎用メソッドです。SDK は、同期呼び出しメソッドと非同期呼び出しメソッドの両方を提供します。API を呼び出す前に、Dataphin Data Service で定義した API に従って、関連するリクエストパラメーターを入力する必要があります。

  • このユースケースでは、conditions はクエリ API 操作のビジネスリクエストパラメーターを指定し、returnFields は API 応答パラメーターを指定します。パラメーターの詳細については、[サービス] > [アプリケーション管理] > [承認済み API サービス] ページに移動してください。対象の API 操作の [アクション] 列で、[テスト] をクリックしてテストページを開きます。

  • API 操作の場合、ビジネスパラメーターは API に構成されたデータ量に応じて異なる方法で渡されます。単一エントリデータの場合、入力パラメーターを conditions パラメーターで渡します。バッチデータの場合、入力パラメーターを batchConditions パラメーターで渡します。

  • リクエストパラメーターの API_ID は、[サービス] > [アプリケーション管理] > [承認済み API サービス] ページの API 列にあります。

Java SDK 非同期 API 呼び出しプロセス

ステップ 1：環境の準備

1. Dataphin サービス Java SDK には JDK 1.8 以降が必要です。

2. SDK が認証と署名情報を生成するために、認証キーのペア、つまり AppKey と AppSecret を準備する必要があります。

   [サービス] > [アプリケーション管理] > [マイアプリケーション] ページのリストから AppKey と AppSecret を取得できます。

   重要

   AppKey と AppSecret は、Dataphin サービスがユーザーリクエストを認証するために使用するキーです。これらの 2 つの構成がクライアント側に保存されている場合は、適切に暗号化してください。

3. pom.xml ファイルに次の依存関係を追加します。dataphin-sdk-core-java を追加するときにエラーが発生した場合は、JAVA_SDK/lib/dataphin-sdk-core-java-v5.4.0.jar パスから JAR ファイルを手動で追加する必要があります。これは Java SDK の JAR パッケージです。

   説明

   dataphin-sdk-core-java は中央の Maven リポジトリには存在しません。したがって、SDK をダウンロードした後、会社の Maven リポジトリにアップロードするか、IDEA または Eclipse に手動でインポートする必要があります。

   <dependency>
       <groupId>com.alibaba.dt</groupId>
       <artifactId>dataphin-sdk-core-java</artifactId>
       <version>v5.4.0</version>
   </dependency>

ステップ 2：Java SDK API インターフェース呼び出しクラスをインポートする

1. [サービス] > [API マーケットプレイス] > [API] ページのリストから対応する API ドキュメントをダウンロードできます。

2. AsyncClientDemo.java をインポートし、AsyncClientDemo.java クラスのインポート文とパッケージ文を修正します。

   package com.alibaba.dt.dataphin;
   
   import com.alibaba.cloudapi.sdk.enums.Scheme;
   import com.alibaba.cloudapi.sdk.model.ApiRequest;
   import com.alibaba.dt.dataphin.client.ApiClientBuilderParams;
   import com.alibaba.dt.dataphin.client.DataphinDataServiceException;
   import com.alibaba.dt.dataphin.client.async.AsyncApiCallBack;
   import com.alibaba.dt.dataphin.client.async.AsyncApiClient;
   import com.alibaba.dt.dataphin.client.async.AsyncJobContext;
   import com.alibaba.dt.dataphin.schema.AsyncQueryResults;
   import com.alibaba.dt.dataphin.schema.OrderBy;
   import com.alibaba.dt.dataphin.schema.QueryParamRequest;
   import com.alibaba.fastjson.JSONObject;
   
   import java.util.ArrayList;
   import java.util.Arrays;
   import java.util.HashMap;
   import java.util.List;
   
   /**
    * 非同期 API の例
    * <p>
    * 使用方法:
    *  まず、HOST、APP_KEY、APP_SECRET、および API_ID を構成します。
    *  次に、必要に応じて getClient() の変数と packQueryParamRequest() のパラメーター値を設定します。
    * 注:
    *  getClient() のパラメーターは、API ごとに異なる値を持つ場合があります。getClient() を変更して入力パラメーターを受け入れるようにすることで、さまざまな API に適応させることができます。
    */
   public class AsyncClientDemo {
   
       /**
        * エンドポイントまたは IP アドレス。この値は DataService Studio のネットワーク構成から取得します。
        */
       private static final String HOST = "xxx";
       /**
        * この API を呼び出すために使用するアプリケーションの AppKey。
        */
       private static final String APP_KEY = "xxx";
       /**
        * この API を呼び出すために使用するアプリケーションの AppSecret。
        */
       private static final String APP_SECRET = "xxx";
       /**
        * 呼び出す API の ID。
        */
       private static final String API_ID = "xxx";
       /**
        * 各バッチでクエリするエントリの数。デフォルト値: 1000。
        */
       private static final Integer FETCH_SIZE = 1000;
   
       public static void main(String[] args) throws Exception {
           //  ブロッキング呼び出し
           callAsyncApiBlock();
           //  非ブロッキング呼び出し
           callAsyncApiNotBlock();
       }
   
       /**
        * ブロッキング呼び出し
        */
       @SuppressWarnings("all")
       private static void callAsyncApiBlock() {
   
           // AsyncApiClient オブジェクトを取得します。
           AsyncApiClient asyncApiClient = getClient();
   
           // 必要に応じて、戻りフィールド、クエリ条件、およびその他のパラメーターを変更します。
           QueryParamRequest queryParamRequest = packRequestParam();
   
           try {
               AsyncQueryResults asyncQueryResults = asyncApiClient.listAsyncWaitFinish(API_ID, queryParamRequest);
   
               System.out.println(JSONObject.toJSONString(asyncQueryResults));
           } catch (Throwable e) {
               e.printStackTrace();
           }
   
           // クライアントをシャットダウンしてリソースを解放します。
           asyncApiClient.shutdown();
       }
   
       /**
        * 非ブロッキング呼び出し
        */
       @SuppressWarnings("all")
       private static void callAsyncApiNotBlock() {
   
           // AsyncApiClient オブジェクトを取得します。
           AsyncApiClient asyncApiClient = getClient();
   
           // 必要に応じて、戻りフィールド、クエリ条件、およびその他のパラメーターを変更します。
           QueryParamRequest queryParamRequest = packRequestParam();
   
           try {
               AsyncApiCallBack callback = new AsyncApiCallBack() {
                   @Override
                   public void onFailure(ApiRequest request, DataphinDataServiceException e) {
                       System.out.println(e.getMessage());
                   }
   
                   @Override
                   public void onResponse(ApiRequest request, AsyncQueryResults results) {
                       System.out.println(JSONObject.toJSONString(results));
                   }
               };
   
               AsyncJobContext context = asyncApiClient.listAsync(API_ID, queryParamRequest, callback);
   
               // リクエストが成功した場合、リクエストの jobId が返されます。
               System.out.printf("jobId: %s", context.getJobId());
   
               // 実行が完了するのを待ちます。実際のシナリオでは、sleep メソッドを使用して待機しないでください。
               Thread.sleep(600000);
           } catch (Exception e) {
               e.printStackTrace();
           }
   
           // クライアントをシャットダウンしてリソースを解放します。
           asyncApiClient.shutdown();
       }
   
       /**
        * AsyncApiClient オブジェクトを取得します。
        */
       public static AsyncApiClient getClient() {
           ApiClientBuilderParams params = new ApiClientBuilderParams();
           // アプリケーションの AppKey。
           params.setAppKey(APP_KEY);
           // アプリケーションの AppSecret。
           params.setAppSecret(APP_SECRET);
           // エンドポイントまたは IP アドレス。
           params.setHost(HOST);
           // デフォルトのプロトコルは HTTP です。API に基づいてプロトコルを HTTPS に設定できます。
           // 注: Dataphin の組み込みゲートウェイは HTTPS をサポートしていません。Alibaba Cloud API Gateway は HTTPS をサポートしています。
           params.setScheme(Scheme.HTTP);
           // 各バッチでクエリするエントリの数。デフォルト値: 1000。
           params.setFetchSize(FETCH_SIZE);
           // ステージ環境変数。PRE は開発環境の API を指定し、RELEASE は本番環境の API を指定します。
           params.setStage("RELEASE");
           // 環境が指定されていない第 2 レベルドメイン名または独立ドメイン名を使用する場合は、env パラメーターを設定する必要があります。
           // 有効な値: PROD と PRE。基本モードを使用する場合は、このパラメーターを PROD に設定します。Dev-Prod モードを使用する場合は、このパラメーターを PROD に設定して本番環境のデータをクエリするか、PRE に設定して開発環境のデータをクエリします。
           // 環境にアクセスするために独立ドメイン名を指定した場合、env パラメーターは有効になりません。
           params.setEnv("PROD");
           return new AsyncApiClient(params);
       }
   
       /**
        * リクエストオブジェクトをパッケージ化します。
        */
       private static QueryParamRequest packRequestParam() {
           QueryParamRequest queryParamRequest = new QueryParamRequest();
   
           /********* API 関連のビジネスパラメーターの構成 - 開始 *********/
           /*
            * プロキシアカウントのタイプ。このパラメーターは必須ではありません。
            * 注: プロキシモードを使用するには、次の条件を満たす必要があります:
            *  1. 行レベルの権限機能が有効になっている。
            *  2. アプリケーションにプロキシ権限が付与されている。
            *  3. API が行レベルの権限ルールに関連付けられている。
            *
            * プロキシモードで認証を使用する場合、プロキシユーザーのアカウントタイプを指定する必要があります。
            *  ACCOUNT_NAME: Dataphin のユーザー名。
            *  USER_ID: Dataphin の一意の ID。
            *  SOURCE_USER_ID: ソースシステムのアカウント ID。
            * このパラメーターは、DelegationUid が設定されている場合にのみ必須です。このパラメーターを指定しない場合、デフォルト値の USER_ID が使用されます。
            */
           queryParamRequest.setAccountType("USER_ID");
   
           /*
            * プロキシアカウントの ID。このパラメーターは必須ではありません。
            * プロキシでアクセスするユーザー。選択した AccountType に基づいて、対応するアカウント ID を入力する必要があります。
            * このパラメーターを設定し、API が行レベルの権限ルールに関連付けられている場合、プロキシモードが認証に使用されます。
            */
           queryParamRequest.setDelegationUid("abcd");
   
           /*
            * リクエストパラメーターのリスト。オプションのパラメーターは指定しなくてもかまいません。必須パラメーターは指定する必要があります。そうしないと、エラーが返されます。
            * キーはクエリフィールドを指定し、値はクエリフィールドの値を指定します。
            * たとえば、id はリクエストフィールド名で、1 は id の値です。複数のクエリパラメーターを指定できます。
            * 注: パラメーターが IN タイプの場合、age パラメーターのように List を使用してパラメーター値をラップします。
            */
           HashMap<String, Object> conditions = new HashMap<>();
           conditions.put("id", 1);
           conditions.put("age", Arrays.asList(10,20,30));
           queryParamRequest.setConditions(conditions);
   
           /*
            * 返されるパラメーターのリスト。このパラメーターは必須です。
            * たとえば、id パラメーターと name パラメーターを返すように指定できます。
            * 注: 返されるパラメーターが存在しないか、必要な権限がない場合、エラーが報告されます。
            */
           queryParamRequest.setReturnFields(Arrays.asList("id", "name"));
   
           /*
            * ソートフィールド。このパラメーターは必須ではありません。
            * 注: Oracle または SQL Server を使用する場合、ページネーションにはソートを使用する必要があります。
            * 1 つ以上のフィールドと、各フィールドのソート順 (昇順または降順) を指定できます。
            * たとえば、結果を ID で昇順にソートできます。
            */
           List<OrderBy> orderList = new ArrayList<>();
           orderList.add(new OrderBy("id1", OrderBy.Order.ASC));
           orderList.add(new OrderBy("id2", OrderBy.Order.DESC));
           queryParamRequest.setOrderBys(orderList);
   
           /*
            * API のバージョン番号。このパラメーターは必須ではなく、開発環境でのみ設定できます。
            */
           queryParamRequest.setApiVersion("V1");
   
           /********* API 関連のビジネスパラメーターの構成 - 終了 *********/
   
   
           /********* 機能パラメーターの構成 - 開始 *********/
   
           /*
            * フィールドの大文字と小文字を区別するかどうかを指定します。値を true に設定します。
            */
           queryParamRequest.setKeepColumnCase(true);
   
           /********* 機能パラメーターの構成 - 終了 *********/
   
           return queryParamRequest;
       }
   }

ステップ 3：通信チャネルクラスを初期化する

API 操作を呼び出すには、まずクライアントを初期化する必要があります。AsyncClientDemo.java の getClient メソッドを参照し、ApiClientBuilderParams クラスを使用して初期化できます。Host、APP_Key、および APP_Secret 変数を置き換える必要があります。

ステップ 4: API インターフェイスの説明

• API インターフェースタイプ

  API は LIST と GET に分類されます。LIST はページ分割クエリをサポートしますが、GET はサポートしません。詳細については、AsyncClientDemo.java の packRequestParam メソッドを参照して、QueryParamRequest のパラメーターを設定してください。

• API インターフェースの呼び出し

  • SDK の LIST メソッドと GET メソッドは、Dataphin Data Service の汎用メソッドです。SDK は、同期呼び出しメソッドと非同期呼び出しメソッドの両方を提供します。API を呼び出す前に、Dataphin Data Service で定義した API に従って、関連するリクエストパラメーターを入力する必要があります。

  • ユースケースでは、conditions パラメーターはビジネスリクエストパラメーターを指定し、returnFields パラメーターは API 応答パラメーターを指定します。パラメーターの詳細については、[サービス] > [アプリケーション管理] > [承認済み API サービス] ページに移動してください。対象の API 操作の [アクション] 列で、[テスト] をクリックしてテストページに移動します。

  • リクエストパラメーターの API_ID を取得するには、[サービス] > [アプリケーション管理] > [承認済み API サービス] ページに移動し、API 列で API_ID を見つけます。

Python SDK 呼び出しプロセス

ステップ 1：環境の準備

1. Python SDK は、Python 3.9 以降のバージョンに適用できます。

   Python SDK は、次の手順で取得できます。

   1. Dataphin のホームページで、上部メニューバーの [サービス] > [アプリケーション管理] に移動します。

   2. 左側のナビゲーションウィンドウで、[呼び出し手順] をクリックします。

   3. [API 呼び出し例] タブをクリックし、ページの右上隅にある [Python 呼び出し例ダウンロード] ボタンをクリックして、Python SDK コアパッケージを取得します。

2. SDK が認証と署名情報を生成するために、認証キーのペア、つまり AppKey と AppSecret を準備します。

   重要

   AppKey と AppSecret は、Dataphin サービスがユーザーリクエストを認証するために使用するキーです。これらの 2 つの構成がクライアント側に保存されている場合は、適切に暗号化してください。

3. 次の形式の JSON ファイルを準備します。

   {
     "host": "API ゲートウェイのドメイン名",
     "port": 80,
     "impalaConfig": {
       "pollingTimeout": 300,
       "pollingInterval": 800
     },
     "applicationConfig": {
       "appKey": "機密データを入力",
       "appSecret": "機密データを入力"
     },
     "apiConfig": {
       "apiNo": 10008,
       "scheme": "HTTP",
       "stage": "RELEASE",
       "env": "PROD",
       "method": "LIST", // GET、LIST、CREATE、UPDATE、または DELETE。大文字と小文字を区別します。
       "queryParamRequest": {
         "conditions": {"id": "1"}, // リクエストパラメーターのリスト。オプションのパラメーターは省略できますが、必須パラメーターは指定する必要があります。
         "returnFields": ["id", "name", "age"], // 返されるパラメーターのリスト。このパラメーターは必須です。返されるパラメーターが存在しないか、必要な権限がない場合、エラーが報告されます。
         "orderBys": [{"field": "id", "order": "ASC"}], // ソートフィールド。このパラメーターはオプションです。
         "useModelCache": "false", // モデルキャッシュを使用するかどうかを指定します。このパラメーターを有効にすると、入力パラメーターと出力パラメーターが同じ場合、同じサービスユニット内の API の解析頻度が減少します。これにより、クエリ効率が向上します。
         "useResultCache": "false", // 結果キャッシュを使用するかどうかを指定します。このパラメーターを有効にすると、条件と返されたフィールドが同じ場合、API のクエリ結果がキャッシュされます。
         "apiVersion": "V1", // API バージョン番号。このパラメーターはオプションで、開発環境でのみ設定できます。
         "accountType": "USER_ID", // プロキシアカウントタイプ。このパラメーターはオプションで、プロキシモードを使用する場合に必須です。
         "delegationUid": "abcd" // プロキシアカウント ID。このパラメーターはオプションで、プロキシモードを使用する場合に必須です。
       },
       "manipulationParamRequest": {
         "conditions": {"id": "1"}, // "単一" データ量の API のリクエストパラメーター。オプションのパラメーターは省略できますが、必須パラメーターは指定する必要があります。
         "batchConditions": [ // "バッチ" データ量の API のリクエストパラメーター。オプションのパラメーターは省略できますが、必須パラメーターは指定する必要があります。
           {"id": "1"},
           {"id": "2"}
         ]
       }
     }
   }

ステップ 2：Python SDK をデプロイする

1. Python 開発ツール PyCharm をインストールします。

2. Python プロジェクトを開きます。

3. Demo クラスの起動パラメーターで JSON ファイルのパスを設定します。

4. 具体的な呼び出しについては、demo.py を参照してください。

ステップ 3：API を呼び出す

1. JSON ファイルで呼び出しパラメーター情報を構成します。

2. Python SDK は、JSON ファイルを読み取って API 呼び出しの基本パラメーターをアセンブルします。

3. apiClient.callApi メソッドを呼び出します。詳細については、demo.py ファイルをご参照ください。

   # -*- coding: utf-8 -*-
   import dataapi
   import sys
   
   with open(str(sys.argv[1]), encoding="utf-8") as f:
       json_obj = eval(f.read().replace('\n\u200b', ''))
   # これは JSON ファイルからコンテキストを読み取ります。JSON ファイルが不要な場合は、対応する値を直接入力します。
   
   # ゲートウェイのアドレス。
   host = json_obj["host"]
   # ゲートウェイのポート。
   port = json_obj["port"]
   # このパラメーターはオプションで、Impala タイプの API でのみ有効です。ポーリングのタイムアウト期間。
   pollingTimeout = json_obj["impalaConfig"]["pollingTimeout"]
   # このパラメーターはオプションで、Impala タイプの API でのみ有効です。ポーリング間隔。
   pollingInterval = json_obj["impalaConfig"]["pollingInterval"]
   # この API を呼び出すために使用するアプリケーションに関する情報。
   appKey = json_obj["applicationConfig"]["appKey"]
   appSecret = json_obj["applicationConfig"]["appSecret"]
   # API に関する情報。
   apiId = json_obj["apiConfig"]["apiNo"]
   # API を呼び出すメソッド。有効な値: HTTP および HTTPS。注: プライベートゲートウェイは HTTP のみをサポートします。大文字と小文字を区別します。
   scheme = json_obj["apiConfig"]["scheme"]
   # 環境。RELEASE は本番環境を示します。
   stage = json_obj["apiConfig"]["stage"]
   # 有効な値: PROD および PRE。基本モードを使用する場合、このパラメーターを PROD に設定します。Dev-Prod モードを使用する場合、PROD は本番データベースがクエリされることを示し、PRE は開発データベースがクエリされることを示します。大文字と小文字を区別します。
   env = json_obj["apiConfig"]["env"]
   # クエリ API のリクエストパラメーター。
   queryParam = json_obj["apiConfig"]["queryParamRequest"]
   # 操作 API のリクエストパラメーター。
   manipulationParam = json_obj["apiConfig"]["manipulationParamRequest"]
   # API が GET、LIST、CREATE、UPDATE、または DELETE タイプであるかどうかを指定します。大文字と小文字を区別します。
   method = json_obj["apiConfig"]["method"]
   
   if (host == None or host == ""):
       raise Exception("ホスト情報がありません。")
   
   if (appKey == None or appKey == ""):
       raise Exception("appKey 情報がありません。")
   
   if (appSecret == None or appSecret == ""):
       raise Exception("appSecret 情報がありません。")
   
   if (method == None or method == ""):
       raise Exception("メソッド情報がありません。")
   
   if (apiId == None or apiId == ""):
       raise Exception("apiNo 情報がありません。")
   
   # Impala を構成します。
   impalaConfig = dataapi.ImpalaConfig(pollingTimeout=pollingTimeout, pollingInterval=pollingInterval)
   # アプリケーションを構成します。
   appConfig = dataapi.AppConfig(appKey=appKey, appSecret=appSecret)
   apiConfig = dataapi.ApiConfig(apiId, scheme, stage, env, queryParam, method)
   myConfig = dataapi.MyConfig(host, port, impalaConfig, appConfig, apiConfig)
   
   apiClient = dataapi.ApiClient(myConfig)
   
   # 同期クエリ API リクエスト。
   resp = apiClient.callApi(queryParam)
   print(resp)
   
   # 非同期クエリ API リクエスト。
   asyncResp = apiClient.asyncCallApi(queryParam)
   print(asyncResp)
   
   # Flux API リクエスト。
   sseClient = dataapi.SseApiClient(myConfig)
   fluxResp = sseClient.fluxCallApi(queryParam)
   for item in fluxResp:
       print(item)
   
   # 同期操作 API リクエスト。
   resp = apiClient.callApi(manipulationParam)
   print(resp)

ホワイトリスト呼び出しメソッド (プライベートデプロイメントでのみサポート)

API のホワイトリスト認証フリーアクセス ポリシーを設定することで、API 呼び出しプロセスを簡素化できます。IP ホワイトリスト ポリシーはアプリケーションレベルのポリシーであり、現在、プライベートクラウドのみがこの呼び出し方式をサポートしています。

開発プロセス

ステップ 1: バックエンドの構成

ホワイトリスト方式で API にアクセスするには、Data Service で API、アプリケーション、アプリケーションホワイトリストを作成し、アプリケーションと API をバインドする必要があります。

• API 操作の作成: [サービス] > [API 開発] > [API サービス] ページで、メソッドを選択します。詳細については、「API の作成」をご参照ください。

• アプリケーションとアプリケーションホワイトリストの作成: アプリケーションは、本番環境で API 操作を呼び出すために使用されます。アプリケーションのホワイトリストを設定することもできます。アプリケーションとホワイトリストの作成方法の詳細については、「マイアプリケーションの作成と管理」をご参照ください。

• アプリケーションと API のバインド：API を使用するには、API がアタッチされているアプリケーションから権限をリクエストする必要があります。詳細については、「API 権限を管理する」をご参照ください。

ステップ 2: リクエストの開始

1. リクエストタイプ：POST

   POST リクエストのみがサポートされています。リクエスト本文は JSON 文字列でなければならず、Content-Type は application/octet-stream; charset=utf-8 に設定する必要があります。

2. 共通入力パラメーターを設定する

   パラメーター名	場所	必須	例	説明
   accept	ヘッダー	はい	application/json; charset=utf-8	応答形式。
   host	ヘッダー	はい	gateway.aliyun.com	API ゲートウェイのドメイン名。
   x-ca-key	ヘッダー	はい	機密データを入力	appkey。API を呼び出すための ID 識別子。
   x-ca-stage	ヘッダー	はい	RELEASE	環境識別子。 RELEASE: 本番環境にアクセスします。 PRE: 開発環境にアクセスします。
   Content-Type	ヘッダー	はい	application/octet-stream; charset=utf-8	リクエスト形式。
   whitelist-flag	ヘッダー	はい	1	ホワイトリスト識別子。このパラメーターは空にできません。固定値: 1。

3. リクエスト形式

   • URL：POST [host]/method/apiId?appKey=アプリケーションの AppKey&env=PROD

     • host: API Gateway のドメイン名。これは サービス > サービス管理 > ネットワーク構成 ページから取得できます。

     • method: API 操作の操作タイプ。GET、LIST、CREATE、UPDATE、または DELETE のいずれかです。操作タイプは [サービス] > [アプリケーション管理] > [承認済み API サービス] > [テスト] ページから取得できます。

     • apiId: API 操作の一意の識別子。これは サービス > アプリケーション管理 > 承認済み API サービス > テスト ページから取得できます。

     • appKey: API 操作がバインドされているアプリケーションの一意の識別子。これは サービス > アプリケーション管理 > マイアプリケーション ページから取得できます。

     • env：環境識別子。PROD は本番環境の API へのアクセスを示し、PRE は開発環境の API へのアクセスを示します。

     リクエスト URL の例：gateway.aliyun.com/list/12345?appKey=xxx&env=PROD。

4. PostMan 呼び出し例の使用

   1. ステップ 1：リクエストアドレス

      [host]/method/apiId?appKey=your_AppKey&env=PROD に POST リクエストを送信します。

   2. ステップ 2：ヘッダーに入力する

      ヘッダーに入力します。詳細については、「共通入力パラメーターを設定する」をご参照ください。

      ヘッダーの例は次のとおりです。

      accept:application/json;charset=utf-8
      x-ca-key:Your sensitive data
      host:Your API gateway domain name
      x-ca-stage:RELEASE
      Content-Type:application/octet-stream;charset=utf-8
      whitelist-flag:1

   3. ステップ 3：本文に入力する

      説明

      Content-Type には application/octet-stream; charset=utf-8 を使用します。

      本文の例：

      {
        "conditions": {"id": "1"}, // リクエストパラメーターのリスト。オプションのパラメーターは省略できますが、必須パラメーターは指定する必要があります。
        "batchConditions": [{"id": "1"}], // "バッチ" データ量の操作タイプ API のリクエストパラメーター。オプションのパラメーターは省略できますが、必須パラメーターは指定する必要があります。
        "returnFields": ["id", "name", "age"], // 返されるパラメーターのリスト。このパラメーターは必須です。返されるパラメーターが存在しないか、必要な権限がない場合、エラーが報告されます。
        "orderBys": [{"field": "id", "order": "ASC"}], // ソートフィールド。このパラメーターはオプションです。
        "useModelCache": "false", // モデルキャッシュを使用するかどうかを指定します。このパラメーターを有効にすると、入力パラメーターと出力パラメーターが同じ場合、同じサービスユニット内の API の解析頻度が減少します。これにより、クエリ効率が向上します。
        "useResultCache": "false", // 結果キャッシュを使用するかどうかを指定します。このパラメーターを有効にすると、条件と返されたフィールドが同じ場合、API のクエリ結果がキャッシュされます。
        "apiVersion": "V1", // API バージョン番号。このパラメーターはオプションで、開発環境でのみ設定できます。
        "accountType": "USER_ID", // プロキシアカウントタイプ。このパラメーターはオプションで、プロキシモードを使用する場合に必須です。
        "delegationUid": "abcd" // プロキシアカウント ID。このパラメーターはオプションで、プロキシモードを使用する場合に必須です。
      }

エラーコード

クライアントエラー

サーバー側エラー (API 呼び出し)

API サーバーエラーを以下に示します。

サーバー側エラー (SQL 文の実行)

よくある質問

質問 1: API 呼び出しで 404 エラーが返されます。 回答:

• 独立ドメインをアタッチしている場合は、プロトコルが HTTP か HTTPS かを確認してください。

• 呼び出している API の操作タイプが、API の定義されたタイプと一致していることを確認してください。操作タイプは URL の一部であるため、正しいメソッドを呼び出していることを確認してください。

• API が対応する環境に公開されているかどうかを確認してください。

質問 2: API 呼び出しで 400 エラーが返されます。 回答:

• x-ca-timestamp が 15 分の有効期間内にあるかどうか、および x-ca-nonce が 15 分以内に再利用されたかどうかを確認してください。API リクエストごとに、x-ca-timestamp に現在の時刻を使用し、新しい x-ca-nonce を生成することをお勧めします。UUID を使用して `x-ca-nonce` 値を生成できます。これは一意の識別子として機能し、特定の形式要件はありません。

• AppKey と AppSecret の前後にスペースがあるかどうかを確認してください。

• API 操作が承認されており、承認されたアプリケーションの AppKey と AppSecret が APP_KEY および APP_SECRET パラメーターと一致していることを確認してください。

• クライアントの署名値に、サーバーに送信された値にない余分なスペースが含まれているかどうかを確認してください。stringToSign 値にスペースがないか確認してください。たとえば、クライアント署名 Content-Type:application/octet-stream; charset=utf-8 にスペースが含まれているが、サーバーに送信された値が Content-Type:application/octet-stream;charset=utf-8 である場合、Invalid Signature エラーが報告されます。

質問 3: API 呼び出しで 403 エラーが返されます。

回答:

• API が HTTP プロトコルまたは HTTPS プロトコルを使用するように構成されているかどうかを確認し、コードで対応するパラメーターを設定します。

• AppKey と AppSecret が正しいかどうかを確認してください。

• 呼び出している API の操作タイプが、API の定義されたタイプと一致していることを確認してください。操作タイプは URL の一部であるため、正しいメソッドを呼び出していることを確認してください。

質問 4: API 呼び出しで次のエラーが返されます: return fields missing in param

回答: packRequestParam メソッドで、パラメーターを次のように設定します:

List<String> returnFields = Lists.newArrayList("API 戻りフィールド 1","API 戻りフィールド 2",..."API 戻りフィールド n");
queryParamRequest.setReturnFields(returnFields);

質問 5: IN 演算子を持つパラメーターはどのように使用しますか?

回答: SDK を使用して API 呼び出しを行う場合、IN パラメーターについては、LIST を使用して値を渡す必要があります。 例：

• パラメーター名が p1、パラメータータイプが String または Date、パラメーター値が a、b、c の場合、パラメーターを次のように設定する必要があります。

Map<String, Object> conditions = Maps.newHashMap();
conditions.put("p1",Lists.newArrayList("a", "b", "c"));

• パラメーター値が 1、2、3 の数値型の場合は、次のようにパラメーターを設定する必要があります。

Map<String, Object> conditions = Maps.newHashMap();
conditions.put("p1",Lists.newArrayList(1,2,3));

質問 6: SDK を使用してページ分割されたデータを取得すると、合計データ数は正しいですが、一部のデータが重複しています。

原因: これは、API コードがソートフィールドを使用して各クエリの一意のソート結果を保証していないか、データベース自体がソートをサポートしていないために発生します。これにより、ページ分割でデータを取得するたびにクエリ結果のソートが不整合になり、データの重複やデータの損失が発生します。

回答: 返される結果のソートが安定していることを確認してください。プライマリキーが存在する場合は、プライマリキーフィールドによるソートを追加します。プライマリキーが存在しない場合は、複数のフィールドを使用して複合プライマリキーを形成し、各クエリでソート結果が安定するようにします。

質問 7: SDK を使用してページ分割されたデータを取得する場合、合計数を返すようにパラメーターを設定するにはどうすればよいですか?

回答: packRequestParam メソッドで、パラメーターを次のように設定します:

// 合計数を返すかどうかを指定します (ページ分割クエリをサポートする API の場合)。
queryParamRequest.setReturnTotalNum(false);