Dataphin:付録：API 呼び出し例

SDK 呼び出し

Java SDK の概要

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

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

Java SDK/

• demo/

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

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

• lib/

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

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

  • dataphin-sdk-core-java-v5.2.0-jar-with-dependencies.jar は、上記の依存パッケージの完全な依存パッケージです。

• ApiDocument_v5.2.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.6 以降のバージョンに適用できます。

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.2.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.2.0</version>
   </dependency>

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

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

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

   /*
    * Copyright 2018 Alibaba.com All right reserved. This software is the confidential and proprietary
    * information of Alibaba.com ("Confidential Information"). You shall not disclose such Confidential
    * Information and shall use it only in accordance with the terms of the license agreement you
    * entered into with Alibaba.com.
    */
   import java.util.HashMap;
   import java.util.List;
   
   import com.alibaba.cloudapi.sdk.constant.SdkConstant;
   import com.alibaba.cloudapi.sdk.enums.Scheme;
   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.schema.OrderBy;
   import com.alibaba.dt.dataphin.schema.QueryParamRequest;
   import com.alibaba.fastjson.JSONObject;
   
   import com.google.common.collect.Lists;
   import com.google.common.collect.Maps;
   
   import static com.alibaba.cloudapi.sdk.constant.SdkConstant.CLOUDAPI_LF;
   
   public class CallApiDemo {
   
       /**
        * アクセスドメイン名または IP アドレス。この値は、Data Service のネットワーク構成で取得できます。
        */
       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();
       }
   
       public static void syncGet() throws Exception {
           // ApiClient オブジェクトを取得します。
           ApiClient client = getClient();
           // 必要に応じて、戻り値のフィールドとクエリ条件を変更する必要があります。
           QueryParamRequest queryParamRequest = packRequestParam();
   
           ApiResponse response = client.getSync(API_ID, queryParamRequest);
           System.out.println(getResultString(response));
       }
   
       public static void syncList() throws Exception {
           // ApiClient オブジェクトを取得します。
           ApiClient client = getClient();
           // 必要に応じて、戻り値のフィールドとクエリ条件を変更する必要があります。
           QueryParamRequest queryParamRequest = packRequestParam();
   
           ApiResponse response = client.listSync(API_ID, queryParamRequest);
           System.out.println(getResultString(response));
       }
   
       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("--- メインスレッドは事前に終了します。 ---");
       }
   
       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("--- メインスレッドは事前に終了します。 ---");
       }
   
       private static ApiClient getClient() {
           ApiClientBuilderParams params = new ApiClientBuilderParams();
           // アプリケーションの AppKey。
           params.setAppKey(APP_KEY);
           // アプリケーションの AppSecret。
           params.setAppSecret(APP_SECRET);
           // アクセスドメイン名または IP アドレス。
           params.setHost(HOST);
           // デフォルトのプロトコルは HTTP です。API が HTTPS をサポートしている場合は、プロトコルを HTTPS に設定することもできます。
           params.setScheme(Scheme.HTTP);
           // ステージ環境変数。PRE は開発環境の API を指定し、RELEASE は本番環境の API を指定します。
           params.setStage("RELEASE");
           // 環境が指定されていない第 2 レベルドメイン名または独立ドメイン名を使用する場合は、env パラメーターを設定する必要があります。
           // 有効な値：PROD と PRE。基本モードを使用する場合は、このパラメーターを PROD に設定します。開発 - 本番モードを使用する場合は、このパラメーターを PROD に設定して本番環境のデータをクエリするか、PRE に設定して開発環境のデータをクエリします。
           // 環境にアクセスするための独立ドメイン名を指定している場合、env パラメーターは有効になりません。
           params.setEnv("PROD");
           return new ApiClient(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 タイプのパラメーターの場合は、List を使用してパラメーター値をラップします。
            */
           HashMap<String, Object> conditions = Maps.newHashMap();
           conditions.put("id", 1);
           conditions.put("age", Lists.newArrayList(10,20,30));
           queryParamRequest.setConditions(conditions);
   
           /*
            * 戻りパラメーターのリスト。このパラメーターは空にできません。
            * たとえば、id と name を返すように指定します。
            * 注：戻りパラメーターが存在しない場合、またはパラメーターに対する権限がない場合は、エラーが報告されます。
            */
           queryParamRequest.setReturnFields(Lists.newArrayList("id", "name"));
   
           /*
            * 並べ替えフィールド。このパラメーターはオプションです。
            * 注：Oracle または SQL Server を使用する場合は、並べ替えとページネーションを同時に使用する必要があります。
            * パラメーターを昇順または降順に並べ替えるかどうかを指定します。複数のフィールドを昇順または降順に並べ替えるように設定できます。
            * たとえば、返された結果を id で昇順に並べ替えます。
            */
           List<OrderBy> orderList = Lists.newArrayList();
           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 バージョン番号。このパラメーターはオプションです。このパラメーターは、開発環境でのみ設定できます。
            */
           queryParamRequest.setApiVersion("V1");
   
           /********* API 関連のビジネスパラメーター設定終了 *********/
   
   
   
           /********* 機能パラメーター設定開始 *********/
   
           /*
            * モデルキャッシュを使用するかどうかを指定します。
            * この機能を有効にすると、入力パラメーターと出力パラメーターが同じであるサービスユニット内の同じ API の解析頻度が減少します。これにより、クエリの効率が向上します。
            */
           queryParamRequest.setUseModelCache(Boolean.getBoolean("false"));
   
           /*
            * 結果キャッシュを使用するかどうかを指定します。
            * この機能を有効にすると、同じ条件と戻り値のフィールドを持つ同じ API のクエリ結果がキャッシュされます。
            * この機能は、変更されないデータのクエリに適しています。同じ SQL 文のクエリ頻度を減らし、クエリの効率を向上させます。
            * デフォルトのキャッシュ期間は 30 分です。バージョン 3.5.6 以降では、API 開発ページでキャッシュ期間を設定できます。
            * 注：API で結果キャッシュが有効になっていない場合、このパラメーターは無効です。
            */
           queryParamRequest.setUseResultCache(Boolean.getBoolean("false"));
   
           /*
            * フィールドの大文字と小文字を区別するかどうかを指定します。
            * フィールドの大文字と小文字が区別される場合は、このパラメーターを true に設定することをお勧めします。
            * このパラメーターを false に設定すると、直接接続 API によって返される結果のフィールド名はデフォルトで大文字になります。
            */
           queryParamRequest.setKeepColumnCase(true);
   
           /********* 機能パラメーター設定終了 *********/
   
           return queryParamRequest;
       }
   
       private static String getResultString(ApiResponse response) {
           StringBuilder result = new StringBuilder();
           result.append("ResultCode:").append(CLOUDAPI_LF).append(response.getCode()).append(CLOUDAPI_LF);
           result.append("RequestId:").append(response.getHeaders().get("x-ca-request-id")).append(CLOUDAPI_LF);
           result.append("ErrorCode:").append(response.getHeaders().get("x-ca-error-code")).append(CLOUDAPI_LF);
           if (200 != response.getCode()) {
               result.append("Error:").append(response.getHeaders().get("x-ca-error-message")).append(CLOUDAPI_LF);
           }
   
           result.append("ResultBody:").append(CLOUDAPI_LF).append(new String(response.getBody(), SdkConstant.CLOUDAPI_ENCODING));
           return result.toString();
       }

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

API を呼び出すには、まずクライアントを初期化する必要があります。ClientDemo.java のサンプルコードを参照し、対応する ApiClientBuilderParams クラスを使用して初期化できます。Host、APP_Key、APP_Secret 変数は実際のデータに置き換える必要があります。

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

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

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

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

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

  • テストケースでは、condition はビジネスリクエストパラメーターを指定し、returnFields は API 戻りパラメーターを指定します。パラメーターの詳細については、[サービス] > [呼び出し] > [承認済み API サービス] ページを参照してください。[アクション] 列で、ターゲット API の [デバッグ] をクリックして、デバッグページに移動します。

  • リクエストパラメーターの API_ID については、[サービス] > [呼び出し] > [承認済み API サービス] ページを参照してください。API_ID は [API] 列にあります。

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

ステップ 1：環境の準備

1. Dataphin サービス Java SDK は、JDK 1.6 以降のバージョンに適用できます。

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.2.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.2.0</version>
   </dependency>

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

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

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

   /*
    * Copyright 2018 Alibaba.com All right reserved. This software is the confidential and proprietary
    * information of Alibaba.com ("Confidential Information"). You shall not disclose such Confidential
    * Information and shall use it only in accordance with the terms of the license agreement you
    * entered into with Alibaba.com.
    */
   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 com.google.common.base.Splitter;
   import com.google.common.collect.Lists;
   import com.google.common.collect.Maps;
   
   import java.util.ArrayList;
   import java.util.HashMap;
   import java.util.List;
   
   public class CallAsyncApiDemo {
   
       /**
        * アクセスするドメイン名または IP アドレス。この値は、データサービスのネットワーク構成から取得します。
        */
       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();
   
           AsyncQueryResults asyncQueryResults = asyncApiClient.listAsyncWaitFinish(API_ID, queryParamRequest);
   
           System.out.println(JSONObject.toJSONString(asyncQueryResults));
   
           // リソースを解放するためにクライアントをシャットダウンします。
           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();
       }
   
       private 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 に設定します。開発 - 本番モードを使用する場合は、このパラメーターを 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 タイプの場合は、List を使用してパラメーター値をラップします（例：age パラメーター）。
            */
           HashMap<String, Object> conditions = Maps.newHashMap();
           conditions.put("id", 1);
           conditions.put("age", Lists.newArrayList(10,20,30));
           queryParamRequest.setConditions(conditions);
   
           /*
            * 戻りパラメーターのリスト。このパラメーターは必須です。
            * たとえば、id パラメーターと name パラメーターを返すように指定できます。
            * 注：戻りパラメーターが存在しない場合、または必要な権限がない場合は、エラーが報告されます。
            */
           queryParamRequest.setReturnFields(Lists.newArrayList("id", "name"));
   
           /*
            * 並べ替えフィールド。このパラメーターは必須ではありません。
            * 注：Oracle または SQL Server を使用する場合は、ページネーションに並べ替えを使用する必要があります。
            * 1 つ以上のフィールドと、各フィールドの並べ替え順序（昇順または降順）を指定できます。
            * たとえば、結果を ID で昇順に並べ替えることができます。
            */
           List<OrderBy> orderList = Lists.newArrayList();
           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 を呼び出すには、まずクライアントを初期化する必要があります。CallAsyncApiDemo.java のサンプルコードを参照し、対応する ApiClientBuilderParams クラスを使用して初期化できます。Host、APP_Key、APP_Secret 変数は実際のデータに置き換える必要があります。

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

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

  API インターフェースタイプは、LIST と GET に分かれています。LIST はページクエリをサポートしますが、GET はサポートしません。CallAsyncApiDemo.java の packRequestParam メソッドを参照し、QueryParamRequest のパラメーターを設定してください。

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

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

  • テストケースでは、condition はビジネスリクエストパラメーターを指定し、returnFields は API 戻りパラメーターを指定します。パラメーターの詳細については、[サービス] > [呼び出し] > [承認済み API サービス] ページに移動し、ターゲット API の [アクション] 列の [テスト] をクリックして、テストページに移動します。

  • リクエストパラメーターの API_ID は、[サービス]> [コール]> [承認済み API サービス]ページの API 列にあります。

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",
       "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。このパラメーターはオプションであり、プロキシモードを使用する場合に必要です。
       }
     }
   }

ステップ 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 は本番環境を示し、PRE は開発環境を示します。
   stage = json_obj["apiConfig"]["stage"]
   # 有効な値：PROD と PRE。基本モードを使用する場合は、PROD を渡します。開発 - 本番モードを使用する場合は、PROD は本番データベースがクエリされることを示し、PRE は開発データベースがクエリされることを示します。[大文字と小文字を区別]
   env = json_obj["apiConfig"]["env"]
   # リクエストパラメーター。このパラメーターは必須です。
   queryParam = json_obj["apiConfig"]["queryParamRequest"]
   
   # API が GET タイプか LIST タイプかを指定します。[大文字と小文字を区別]
   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)

ホワイトリスト呼び出し方式（プライベートデプロイメントの場合のみサポート）

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

開発プロセス

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

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

• API を作成する：[サービス] > [開発] > [API] ページで、直接データソースモード、論理テーブル API-SQL モード、論理テーブル API-ウィザードモード、登録済み API、または複合 API の 5 つの方法のいずれかを使用して 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	ヘッダー	はい	7229fc4974**	-cn-shanghai.alicloudapi.com。
   x-ca-key	ヘッダー	はい	2037**895	appkey。API を呼び出すための ID 識別子。
   x-ca-stage	ヘッダー	はい	RELEASE	環境識別子。RELEASE は本番環境へのアクセスに使用され、PRE は開発環境へのアクセスに使用されます。
   Content-Type	ヘッダー	はい	application/octet-stream; charset=utf-8	リクエスト形式。
   whitelist-flag	ヘッダー	はい	1	ホワイトリスト識別子（空ではない）。

3. リクエスト形式

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

     • host：API Gateway ドメイン名（[サービス] > [管理] > [ネットワーク構成] ページから取得できます）。

     • method：API リクエストメソッド、GET または LIST（[サービス] > [呼び出し] > [承認済み 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"}, // リクエストパラメーターのリスト。オプションのパラメーターは除外できますが、必須パラメーターは含める必要があります。
        "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 文の実行）

よくある質問

質問：API 呼び出しから 404 が返される 回答：

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

• 呼び出している API のタイプが LIST か GET かを確認してください。LIST/GET は URL の一部になるためです。

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

   public static ApiClient getClient() {
        if (apiClient == null) {
            synchronized (ClientDemo.class) {
                if (apiClient == null) {
                    ...
                    params.setStage("RELEASE");
                    params.setEnv("PROD");
                    apiClient = new ApiClient(params);
                    return apiClient;
                }
            }
   }

質問：API 呼び出しから 400 が返される 回答：

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

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

• 呼び出している API が承認されているかどうか、および承認された AppSecret と AppKey がパラメーター private static final String APP_KEY および private static final String APP_SECRETと一致するかどうかを確認してください。一致しない場合は、400 エラーが発生します。

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

質問：API 呼び出しから 403 が返される

回答：考えられる理由：① 呼び出しプロトコルが実際の構成と一致しない、② AppKey と AppSecret が正しくない。

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

  public static ApiClient getClient() {
        if (apiClient == null) {
            synchronized (ClientDemo.class) {
                if (apiClient == null) {
                    ... 
                    // デフォルトのプロトコルは HTTP です。プロトコルを HTTPS に設定できます。（OS ゲートウェイは HTTPS をサポートしていません!! OS 以外のゲートウェイは HTTPS をサポートできます。使用できるプロトコルは、呼び出す API によって異なります。）
                    // ここ
                    params.setScheme(Scheme.HTTP);
                      // または
                    params.setScheme(Scheme.HTTPS);
                    ...
                }
            }
        }
        return apiClient;
    }

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

質問：API 呼び出しからエラーが返される： return fields missing in param

回答：packRequestParamListSync メソッドまたは packRequestParamGetSync メソッド（API が GET タイプか LIST タイプかによって異なります）で、以下のスクリプトに従ってパラメーターを設定します。

ArrayList<String> returnFiles = Lists.newArrayList("api 戻り値フィールド 1","api 戻り値フィールド 2",..."api 戻り値フィールド n");
queryParamRequest.setReturnFields(returnFiles);

質問：IN 演算子を持つパラメーターの使用方法

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

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

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

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

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

質問： SDK を使用してページネーションでデータを取得する際、総数は正しいものの、データが重複してしまいます

原因: API コードでソートフィールドが使用されておらず、毎回の一意なソート結果が保証されていないか、あるいはデータベース自体がソートをサポートしていないため、ページネーションでデータを取得するたびにクエリ結果のソートに一貫性がなくなり、重複データやデータ損失が発生します。

回答: 返される結果のソートの安定性を確保してください。プライマリキーがある場合は、プライマリキーフィールドによるソートを追加します。プライマリキーがない場合は、複数のフィールドを使用してソート用の複合プライマリキーを構成し、毎回ソート結果が安定するようにします。