Dataphin:付録：API 呼び出しの例

SDK 呼び出し

Java SDK

Dataphin データサービスの Java SDK には、データサービス API を呼び出すためのベース SDK とサンプルコードが含まれています。

Java SDK のディレクトリ構造は次のとおりです。

Java SDK/

• demo/

  • ClientDemo.java：同期 API のサンプルコードとメソッド。

  • AsyncClientDemo.java：非同期 API のサンプルコードとメソッド。

• lib/

  • dataphin-sdk-core-java-v6.3.0.jar：SDK のコア依存パッケージ。

  • dataphin-sdk-core-java-v6.3.0-javadoc.jar：依存パッケージの Javadoc。

  • dataphin-sdk-core-java-v6.3.0-jar-with-dependencies.jar：すべての依存関係を含むスタンドアロン JAR パッケージ。

• ApiDocument_v6.3.0.md：API ドキュメント。

• LICENSE：ライセンス。

Java SDK を入手するには、次の手順に従います。

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

2. 左側のナビゲーションウィンドウで、[利用ガイド] をクリックします。

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

Java SDK API 呼び出しフロー

ステップ 1：環境の準備

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

2. アクセスキーペア (AppKey と AppSecret) を準備します。SDK はこのペアを認証と署名の生成に使用します。

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

   重要

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

3. 次の依存関係をpom.xml ファイルに追加します。dataphin-sdk-core-java を追加するときにエラーが発生した場合は、Java SDK に含まれているJAVA_SDK/lib/dataphin-sdk-core-java-v6.3.0.jar ファイルを手動で追加します。

   説明

   dataphin-sdk-core-java 依存関係は Maven セントラルリポジトリでは利用できません。SDK をダウンロードした後、会社の Maven リポジトリにアップロードするか、IDE (IntelliJ IDEA や Eclipse など) に手動でインポートする必要があります。

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

ステップ 2：API 呼び出しクラスのインポート

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

2. ClientDemo.java をインポートし、ClientDemo.java クラスのimport およびpackage 宣言を修正します。

   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 java.util.ArrayList;
   import java.util.HashMap;
   import java.util.List;
   import java.util.Map;
   import java.util.function.Consumer;
   
   /**
    * API 呼び出しの例。
    * <p>
    * 使用方法：
    *  1. HOST、APP_KEY、APP_SECRET、API_ID の定数を設定します。
    *  2. 必要に応じて、getClient() メソッドの変数と packQueryParamRequest() メソッドのパラメーター値を設定します。
    * 注意：
    *  getClient() のパラメーターは API によって異なる場合があります。異なる API 要件に対応するために、
    *  getClient() をリファクタリングして入力パラメーターを受け入れるようにすることができます。
    */
   public class ClientDemo {
   
       /**
        * ホストまたは IP アドレス。この値はデータサービスのネットワーク構成から取得します。
        */
       private static final String HOST = "xxx";
       /**
        * 呼び出し元アプリケーションの AppKey。
        */
       private static final String APP_KEY = "xxx";
       /**
        * 呼び出し元アプリケーションの 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();
   
       }
   
       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));
       }
   
       /**
        * 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");
           // 環境が指定されていないセカンドレベルドメインまたは独立ドメインを使用している場合は、「env」を設定する必要があります。
           // サポートされている値：「PROD」と「PRE」。基本モードでは「PROD」を使用します。開発・本番モードでは、「PROD」は本番データベースをクエリし、「PRE」は開発データベースをクエリします。
           // このパラメーターは、環境をすでに指定している独立ドメイン名を使用している場合は効果がありません。
           params.setEnv("PROD");
           // 接続タイムアウト (ミリ秒)。デフォルト：10,000。
           params.setConnectionTimeout(60000L);
           // 読み取りタイムアウト (ミリ秒)。デフォルト：10,000。
           params.setReadTimeout(60000L);
   
           ApiClient apiClient = new ApiClient(params);
           // (オプション) Impala タイプの API のタイムアウトとポーリング間隔を設定します。デフォルトのタイムアウト：300 秒。デフォルトの間隔：800 ミリ秒。
           // このパラメーターは Impala API にのみ影響します。他の 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");
           // 環境が指定されていないセカンドレベルドメインまたは独立ドメインを使用している場合は、「env」を設定する必要があります。
           // サポートされている値：「PROD」と「PRE」。基本モードでは「PROD」を使用します。開発・本番モードでは、「PROD」は本番データベースをクエリし、「PRE」は開発データベースをクエリします。
           // このパラメーターは、環境をすでに指定している独立ドメイン名を使用している場合は効果がありません。
           params.setEnv("PROD");
           // 接続タイムアウト (ミリ秒)。デフォルト：10,000。
           params.setConnectionTimeout(60000L);
           // 読み取りタイムアウト (ミリ秒)。デフォルト：10,000。
           params.setReadTimeout(60000L);
   
           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())
               .doOnError(t -> System.out.println("error:" + t))
               // 一時的な実行の場合、完了または失敗時に接続を閉じてリソースを解放します。
               .doFinally(s -> 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");
   
           /*
            * リクエストパラメーターのリスト。オプションのパラメーターは省略できます。必須パラメーターは提供する必要があり、そうしないとエラーが発生します。
            * `key` はクエリフィールドで、`value` はその対応する値です。
            * たとえば、`id` はリクエストフィールド名で、`1` はその値です。複数のクエリパラメーターを設定できます。
            * 注意：`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` を指定します。
            * 指定されたフィールドが存在しないか、アプリケーションに権限がない場合、エラーが発生します。このリストが提供されない場合、API はアプリケーションがアクセスを許可されているすべてのフィールドを返します。
            */
           List<String> returnFields = new ArrayList<>();
           // returnFields.add("id");
           // returnFields.add("name");
           queryParamRequest.setReturnFields(returnFields);
   
           /*
            * (オプション) ソートするフィールド。
            * 注意：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 分です。v3.5.6 以降、これは API 開発ページで設定できます。
            * 注意：API で結果キャッシュが有効になっていない場合、このパラメーターは無効です。
            */
           queryParamRequest.setUseResultCache(false);
   
           /*
            * 応答でフィールド名の大文字と小文字の区別を維持するかどうかを指定します。
            * アプリケーションが大文字と小文字を区別する場合は、これを `true` に設定します。
            * `false` の場合、直接接続 API からの応答のフィールド名はデフォルトで大文字になります。
            */
           queryParamRequest.setKeepColumnCase(true);
   
           /********* 機能パラメーター設定：終了 *********/
   
           return queryParamRequest;
       }
   
       /**
        * DML リクエストオブジェクトをパッケージ化します。
        */
       private static ManipulationParamRequest packDmlRequestParam() {
           ManipulationParamRequest manipulationParamRequest = new ManipulationParamRequest();
   
           /*
            * リクエストパラメーターのリスト。オプションのパラメーターは省略できます。必須パラメーターは提供する必要があり、そうしないとエラーが発生します。
            * `key` はフィールド名で、`value` はその対応する値です。
            * 複数のパラメーターを設定できます。
            * 注意：`IN` タイプのパラメーターの場合、値を `List` でラップします。
            */
           Map<String, Object> conditions = new HashMap<>();
           // conditions.put("id", 1);
           // conditions.put("age", Arrays.asList(10, 20, 30));
           manipulationParamRequest.setConditions(conditions);
   
           /*
            * バッチ操作の場合、入力パラメーターを `batchConditions` に追加します。
            * 注意：単一レコード操作の場合、シリアル化の問題を避けるために `conditions` マップを `batchConditions` に配置しないでください。
            */
           List<Map<String, Object>> batchConditions = new ArrayList<>();
           // batchConditions.add(new HashMap<>(conditions));
           manipulationParamRequest.setBatchConditions(batchConditions);
   
           /*
            * (オプション) API バージョン番号。これは開発環境の API にのみ設定できます。
            */
           // manipulationParamRequest.setApiVersion("V1");
   
           return manipulationParamRequest;
       }
   
       /**
        * フォーマットされた結果文字列を取得します。
        */
       private static String getResultString(ApiResponse response) {
           /*
            * ステップ 1：HttpResponse ヘッダーから詳細を取得する。
            *         `response.getHeaders().get(key)` を使用します。
            *         - `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` (各リクエストの一意の識別子) は常に含まれます。
            *         - 推奨：応答コードが 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` パラメーターを保存することを推奨します。例外が発生した場合は、この ID をテクニカルサポートに提供してください。
            */
           return result.toString();
       }
   
   }

ステップ 3：クライアントの初期化

API を呼び出すには、まずクライアントを初期化する必要があります。ClientDemo.java のgetClient メソッドを参照し、ApiClientBuilderParams クラスを使用して初期化します。HOST、APP_KEY、および APP_SECRET 定数のプレースホルダー値を置き換える必要があります。

ApiClientBuilderParams の共通パラメーターを次の表に示します。

ステップ 4：API メソッドリファレンス

• API リクエストタイプ

  • API リクエストは、クエリタイプ (LIST、GET) に分類されます。

  • LIST リクエストはページネーションをサポートしますが、GET リクエストはサポートしません。クエリパラメーターを設定するには、packRequestParam のClientDemo.java メソッドを参照し、QueryParamRequest オブジェクトのプロパティを設定します。

• API の呼び出し

  • SDK は、Dataphin API を呼び出すための同期メソッドと非同期メソッドの両方を提供します。API を呼び出す前に、Dataphin 内の API 構成で定義されているリクエストパラメーターを提供する必要があります。

  • コード例では、conditions はクエリ API のビジネスリクエストパラメーターを保持し、returnFields は応答フィールドを指定します。API のパラメーターを表示するには、[サービス] >[アプリケーション管理] >[承認済み API サービス] に移動し、API を見つけて、[アクション] 列の[デバッグ] をクリックします。

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

• ApiClient 呼び出しメソッド

  説明

  • 非同期呼び出しは非ブロッキングメカニズムを使用するため、メインスレッドは待機せずに作業を続行できます。コールバックが応答を処理するため、このアプローチは高レイテンシまたは長時間実行の API 呼び出しに最適です。

  • ストリーミング呼び出しはSseApiClient を使用してサーバー送信イベント (SSE) 通信を実装します。SSE は永続的な接続を維持するため、タスクまたは短命のアプリケーションが完了したらshutdown() メソッドを呼び出して接続を閉じ、システムリソースを解放する必要があります。

API のリクエストタイプと目的の呼び出しメソッドに対応する ApiClient メソッドを選択します。

Java SDK を使用した非同期 API 呼び出し

ステップ 1：環境の準備

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

2. AppKey と AppSecret から成るアクセスキーを準備します。SDK はこのキーを使用して認証および署名情報を生成します。

   [サービス] > [アプリケーション管理] > [マイアプリケーション] ページで AppKey と AppSecret を見つけます。

   重要

   AppKey と AppSecret は、Dataphin サービスへのリクエストを認証するために使用されるアクセスキーを形成します。クライアントにアクセスキーを保存する場合は、暗号化してください。

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

   説明

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

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

ステップ 2：サンプルコードの設定

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 によって異なる場合があります。複数の API をサポートするために、
    *  getClient() を変更して入力パラメーターを受け入れるようにします。
    */
   public class AsyncClientDemo {
   
       /**
        * ホストまたは 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";
       /**
        * バッチごとにフェッチするエントリ数。デフォルト：1,000。
        */
       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());
   
               // ジョブが完了するのを待ちます。本番コードでは Thread.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);
           // バッチごとにフェッチするエントリ数。デフォルト：1,000。
           params.setFetchSize(FETCH_SIZE);
           // ステージ環境：PRE は開発環境、RELEASE は本番環境。
           params.setStage("RELEASE");
           // 環境が指定されていないカスタムドメインを使用する場合は、env パラメーターを設定する必要があります。
           // 有効な値：PROD と PRE。基本モードでは PROD を使用します。開発・本番モードでは、PROD は本番データをクエリし、PRE は開発データをクエリします。
           // 環境固有のドメインをすでに指定している場合、このパラメーターは効果がありません。
           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。
            * 呼び出しが行われる代理のユーザー。ID は指定された AccountType と一致する必要があります。
            * このパラメーターを設定すると、API に関連付けられた行レベルセキュリティポリシーがある場合、認証に委任モードが有効になります。
            */
           // queryParamRequest.setDelegationUid("abcd");
   
           /*
            * リクエストパラメーター。オプションのパラメーターは省略できます。必須パラメーターは必須です。
            * キーはクエリフィールド名で、値はその対応する値です。
            * たとえば、「id」は値が 1 のリクエストフィールドです。複数のパラメーターを設定できます。
            * 注意：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」を返すように指定します。
            * フィールドが存在しないか、権限がない場合はエラーが発生します。省略した場合、アプリケーションがアクセスできるすべてのフィールドが返されます。
            */
           List<String> returnFields = new ArrayList<>();
           // returnFields.add("id");
           // returnFields.add("name");
           queryParamRequest.setReturnFields(returnFields);
   
           /*
            * (オプション) ソートフィールド。
            * 注意：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);
   
           /*
            * (オプション) API バージョン。開発環境の API にのみ設定できます。
            */
           // queryParamRequest.setApiVersion("V1");
   
           /********* API 関連のビジネスパラメーター設定の終了 *********/
   
   
           /********* 機能パラメーター設定の開始 *********/
   
           /*
            * フィールド名の大文字小文字を区別するかどうかを指定します。true である必要があります。
            */
           queryParamRequest.setKeepColumnCase(true);
   
           /********* 機能パラメーター設定の終了 *********/
   
           return queryParamRequest;
       }
   }

ステップ 3：クライアントの初期化

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

同期 API 呼び出しプロセスのステップ 3：通信チャネルクラスの初期化に記載されている appKey、appSecret、host、scheme、stage、env などの共通パラメーターに加えて、AsyncApiClient は非同期呼び出し専用の次のパラメーターもサポートしています。

ステップ 4：API 呼び出しの詳細

• API リクエストメソッド

  API リクエストメソッドには LIST と GET があります。LIST メソッドはページネーションをサポートしますが、GET メソッドはサポートしません。AsyncClientDemo.java ファイルの packRequestParam メソッドを参照して、QueryParamRequest のパラメーターを設定してください。

• API の呼び出し

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

  • デバッグのユースケースでは、conditions はビジネスリクエストパラメーターであり、returnFields は API の戻りパラメーターです。特定のパラメーターについては、[サービス] > [アプリケーション管理] > [承認済み API サービス] ページに移動し、対象の API の [アクション] 列で [デバッグ] をクリックしてデバッグページに移動します。

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

• AsyncApiClient 呼び出しメソッド

  説明

  呼び出しが完了したら、asyncApiClient.shutdown() を呼び出してクライアントを閉じ、スレッドプールなどのリソースを解放します。この例では Thread.sleep を使用して非ブロッキング効果を示しています。実際のシナリオでは sleep メソッドを使用して待機しないでください。ビジネスロジックでコールバックとメインプロセスの間の調整を処理することを推奨します。

  AsyncApiClient は 2 つの呼び出しメソッドを提供します。AsyncClientDemo.java の main メソッドで例を参照してください。

  • ブロッキング呼び出し：listAsyncWaitFinish/getAsyncWaitFinish メソッドを呼び出すと、メインスレッドはクエリが完了するのを待ち、直接 AsyncQueryResults オブジェクトを返します。このアプローチは、完全な結果を同期的に取得する必要があるシナリオに適しています。

    例：AsyncQueryResults results = asyncApiClient.listAsyncWaitFinish(API_ID, queryParamRequest);

  • 非ブロッキング呼び出し：listAsync/getAsync メソッドを呼び出し、AsyncApiCallBack コールバックを渡します。メソッドはすぐに AsyncJobContext を返します。context.getJobId() を呼び出してクエリのジョブ ID (jobId) を取得できます。クエリが完了すると、結果はコールバックの onResponse メソッドを通じて返されます。呼び出しが失敗した場合、例外情報は onFailure メソッドを通じて返されます。このタイプの呼び出しは、メインスレッドをブロックしたくないシナリオに適しています。

    例：AsyncJobContext context = asyncApiClient.listAsync(API_ID, queryParamRequest, callback);

• AsyncApiClient メソッドのリスト

  呼び出しタイプ	メソッド	適用可能な API タイプ	説明
  ブロッキング	getAsyncWaitFinish(apiId, queryParamRequest)	GET	クエリが完了するのを待ち、AsyncQueryResults オブジェクトを返します。
  ブロッキング	listAsyncWaitFinish(apiId, queryParamRequest)	LIST	クエリが完了するのを待ち、AsyncQueryResults を返します。
  非ブロッキング	getAsync(apiId, queryParamRequest, callback)	GET	AsyncApiCallBack コールバックを通じて結果を処理し、AsyncJobContext を返します。
  非ブロッキング	listAsync(apiId, queryParamRequest, callback)	LIST	結果は AsyncApiCallBack コールバックによって処理され、AsyncJobContext が返されます。
  ジョブ管理	getJobStatus(jobId)	-	非同期ジョブのステータスをクエリします。
  ジョブ管理	getJobResult(jobId, fetchSize)	-	ジョブのクエリ結果をバッチで取得します。
  ジョブ管理	cancelJob(jobId)	-	非同期ジョブをキャンセルします。
  ジョブ管理	closeJob(jobId)	-	非同期ジョブを閉じ、サーバーサイドのリソースを解放します。
  ジョブ管理	getJobExecutionLog(jobId)	-	トラブルシューティングのために非同期ジョブの実行ログを取得します。

Python SDK 呼び出しプロセス

ステップ 1：環境の準備

1. Python SDK には Python 3.9 以降が必要です。

   Python SDK を入手するには、次の手順に従います。

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

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

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

2. AppKey と AppSecret から成る認証キーペアを準備します。SDK はこのペアを使用して認証および署名情報を生成します。

   重要

   AppKey と AppSecret は、Dataphin がユーザーリクエストを認証するために使用する認証情報です。これらの認証情報をクライアントに保存する場合は、安全に暗号化してください。

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

   {
     "host": "Your_API_gateway_domain",
     "port": 80,
     "impalaConfig": {
       "pollingTimeout": 300,
       "pollingInterval": 800
     },
     "applicationConfig": {
       "appKey": "Your_AppKey",
       "appSecret": "Your_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"], // 戻りパラメーターのオプションのリスト。指定されたパラメーターが存在しないか、アクセス権がない場合はエラーが発生します。省略した場合、API はアプリケーションがアクセス権を持つすべてのパラメーターを返します。
         "orderBys": [{"field": "id", "order": "ASC"}], // オプションのソートフィールド。
         "useModelCache": "false", // モデルキャッシュを有効にします。これにより、同じサービスユニット内で同一の入出力パラメーターを持つ API 呼び出しの解析頻度が減り、クエリ効率が向上します。
         "useResultCache": "false", // 結果キャッシュを有効にします。これにより、同一の条件と戻りパラメーターを持つ同じ API 呼び出しのクエリ結果がキャッシュされます。
         "keepColumnCase": "true", // 戻りパラメーター名の大文字と小文字の区別を維持します。
         "apiVersion": "V1", // オプションの API バージョン。開発環境でのみ設定できます。
         "accountType": "USER_ID", // オプションの委任アカウントタイプ。委任モードを使用する場合に必須です。
         "delegationUid": "abcd", // オプションの委任アカウント ID。委任モードを使用する場合に必須です。
         "returnTotalNum": "false" // エントリの総数を返します。これを有効にするとパフォーマンスに影響する場合があります。
       },
       "manipulationParamRequest": {
         "conditions": {"id": "1"}, // 単一エントリを処理する API のリクエストパラメーター。必須パラメーターを含める必要があります。
         "batchConditions": [ // バッチでエントリを処理する API のリクエストパラメーター。必須パラメーターを含める必要があります。
           {"id": "1"},
           {"id": "2"}
         ]
       }
     }
   }

ステップ 2：Python SDK の設定

1. PyCharm などの Python IDE をインストールします。

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

3. 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
   
   # 以下のコードは JSON ファイルから構成を読み取ります。
   # または、変数に直接値を割り当てることもできます。
   with open(str(sys.argv[1]), encoding="utf-8") as f:
       json_obj = eval(f.read().replace('\n\u200b', ''))
   
   # API ゲートウェイのエンドポイント。
   host = json_obj["host"]
   # API ゲートウェイのポート。
   port = json_obj["port"]
   # ポーリングタイムアウト。このパラメーターは Impala タイプの API にのみ適用されます。
   pollingTimeout = json_obj["impalaConfig"]["pollingTimeout"]
   # ポーリング間隔。このパラメーターは Impala タイプの API にのみ適用されます。
   pollingInterval = json_obj["impalaConfig"]["pollingInterval"]
   # API を呼び出すアプリケーションの AppKey。
   appKey = json_obj["applicationConfig"]["appKey"]
   # API を呼び出すアプリケーションの AppSecret。
   appSecret = json_obj["applicationConfig"]["appSecret"]
   # API の ID。
   apiId = json_obj["apiConfig"]["apiNo"]
   # リクエストプロトコル：HTTP または HTTPS。注意：プライベートゲートウェイは HTTP のみをサポートします。この値は大文字と小文字を区別します。
   scheme = json_obj["apiConfig"]["scheme"]
   # 環境ステージ。これを「RELEASE」に設定します。
   stage = json_obj["apiConfig"]["stage"]
   # データ環境。有効な値：PROD と PRE。基本モードでは PROD を使用します。
   # 開発・本番モードでは、PROD は本番データベースをクエリし、PRE は開発環境をクエリします。この値は大文字と小文字を区別します。
   env = json_obj["apiConfig"]["env"]
   # クエリ API のリクエストパラメーター。
   queryParam = json_obj["apiConfig"]["queryParamRequest"]
   # 操作 API のリクエストパラメーター。
   manipulationParam = json_obj["apiConfig"]["manipulationParamRequest"]
   # リクエストメソッド：GET、LIST、CREATE、UPDATE、または DELETE。この値は大文字と小文字を区別します。
   method = json_obj["apiConfig"]["method"]
   
   if (host is None or host == ""):
       raise Exception("host is missing")
   
   if (appKey is None or appKey == ""):
       raise Exception("appKey is missing")
   
   if (appSecret is None or appSecret == ""):
       raise Exception("appSecret is missing")
   
   if (method is None or method == ""):
       raise Exception("method is missing")
   
   if (apiId is None or apiId == ""):
       raise Exception("apiNo is missing")
   
   # Impala 構成
   impalaConfig = dataapi.ImpalaConfig(pollingTimeout=pollingTimeout, pollingInterval=pollingInterval)
   # アプリケーション構成
   appConfig = dataapi.AppConfig(appKey=appKey, appSecret=appSecret)
   # API 構成
   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 リクエストを行います。
   sseClient = dataapi.SseApiClient(myConfig)
   fluxResp = sseClient.fluxCallApi(queryParam)
   for item in fluxResp:
       print(item)
   
   # 同期操作 API リクエストを行います。
   resp = apiClient.callApi(manipulationParam)
   print(resp)

ホワイトリスト API 呼び出し (プライベートデプロイメントのみ)

ホワイトリストを使用して API 呼び出しを簡素化し、パスワードなしのアクセスを実現できます。このアプリケーションレベルのセキュリティポリシーは、プライベートクラウド環境でのみ利用可能です。

手順

ステップ 1：バックエンドの設定

ホワイトリストを使用して API を呼び出すには、まず Data Service で API とアプリケーションを作成し、アプリケーションのホワイトリストを設定し、アプリケーションに API の呼び出しを承認する必要があります。

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

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

• アプリケーションへの API 呼び出しの承認：アプリケーションに API を呼び出す権限を付与します。詳細については、「API 権限の管理」をご参照ください。

ステップ 2：リクエストの送信

1. リクエストメソッド：POST

   POST リクエストのみがサポートされています。リクエストボディは JSON 文字列である必要があります。

2. 共通リクエストパラメーターの設定

   パラメーター	場所	必須	例	説明
   accept	ヘッダー	はい	application/json; charset=utf-8	応答フォーマット。
   host	ヘッダー	はい	gateway.aliyun.com	API Gateway ドメイン名。
   x-ca-key	ヘッダー	はい	Your_appKey	API を呼び出すアプリケーションを識別する appKey。
   x-ca-stage	ヘッダー	はい	RELEASE	環境識別子。 RELEASE は本番環境を指定します。 PRE は開発環境を指定します。
   Content-Type	ヘッダー	はい	application/octet-stream; charset=utf-8	リクエストフォーマット。
   whitelist-flag	ヘッダー	はい	1	ホワイトリスト呼び出しを示すフラグ。値は 1 である必要があります。

3. リクエストフォーマット

   • POST URL の形式は次のとおりです：http://[host]/method/apiId?appKey=[appKey]&env=[env]

     • host：API Gateway ドメイン名。これは[サービス] > [サービス管理] > [ネットワーク構成] ページで確認できます。

     • method：API リクエストメソッド：GET/LIST。これは[サービス] > [アプリケーション管理]> [承認済み API サービス]> [デバッグ] ページで確認できます。

     • apiId：API の一意の ID。これは[サービス] > [アプリケーション管理]> [承認済み API サービス]> [デバッグ] ページで確認できます。

     • appKey：API にバインドされているアプリケーションの一意の識別子。これは[サービス] > [アプリケーション管理] > [マイアプリケーション] ページで確認できます。

     • env：環境識別子。本番環境には PROD を、開発環境には PRE を使用します。

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

4. Postman での呼び出し例

   1. ステップ 1：リクエスト URL

      POST リクエスト URL は次のとおりです：http://[host]/method/apiId?appKey=[appKey]&env=[env]

   2. ステップ 2：ヘッダーの設定

      次のコードブロックはヘッダーの例を示しています。

      accept:application/json;charset=utf-8
      x-ca-key:Your_appKey
      host:Your_API_Gateway_domain
      x-ca-stage:RELEASE
      Content-Type:application/octet-stream;charset=utf-8
      whitelist-flag:1

   3. ステップ 3：リクエストボディの設定

      次のコードブロックはリクエストボディの例を示しています。

      {
        "conditions": {"id": "1"}, // リクエストパラメーターリスト。必要に応じてオプションのパラメーターを渡します。必須パラメーターは提供する必要があります。
        "batchConditions": [{"id": "1"}], // バッチ入力を持つ操作 API のリクエストパラメーター。必要に応じてオプションのパラメーターを渡します。必須パラメーターは提供する必要があります。
        "returnFields": ["id", "name", "age"], // 戻りパラメーターのオプションのリスト。指定されたパラメーターが存在しないか、アクセス権がない場合はエラーが発生します。省略した場合、API はアクセス権を持つすべてのパラメーターを返します。
        "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) を確認してください。

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

• API が正しい環境に公開されていることを確認してください。

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

• x-ca-timestamp が 15 分の有効期間内であること、および x-ca-nonce が 15 分以内に再利用されていないことを確認してください。各 API リクエストに対して、x-ca-timestamp を現在の時刻に設定し、新しい x-ca-nonce を生成してください。nonce の生成には UUID を使用します。これは特定の形式要件のない一意の識別子です。

• AppKey と AppSecret に先頭または末尾のスペースがないことを確認してください。

• API がご利用のアプリケーションに対して承認されていること、およびリクエスト内の AppKey と AppSecret が承認されたアプリケーションのものと一致することを確認してください。

• クライアント側の署名値に余分なスペースがないか確認してください。クライアント側の stringToSign 値がサーバーが期待するものと異なる場合、Invalid Signature エラーが発生します。たとえば、Content-Type ヘッダーのクライアント側署名が Content-Type:application/octet-stream; charset=utf-8 (スペースあり) であるのに対し、サーバーに送信されたヘッダーが Content-Type:application/octet-stream;charset=utf-8 (スペースなし) である場合、署名検証は失敗します。

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

回答：

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

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

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

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

回答：SDK で API を呼び出す際、IN 演算子を使用するパラメーターの値をリストとして渡します。例：

• パラメーター名が 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));

質問 5：SDK を使用してページ分割されたデータを取得すると、総レコード数は正しいのに、重複したレコードが返されます。

原因：この問題は、クエリ結果のソート順が安定していないために発生します。これは、API コードがユニークな順序を保証するためのソートフィールドを使用していない場合や、基盤となるデータベースがソートをサポートしていない場合に発生する可能性があります。その結果、ページ分割されたリクエスト間で順序が変わり、データの重複や欠落が発生することがあります。

回答：結果のソート順が安定していることを確認してください。プライマリキーが存在する場合は、それをソートフィールドに追加します。プライマリキーがない場合は、複数のフィールドを使用して複合プライマリキーを作成し、ソートします。これにより、すべてのリクエストで安定したソート順が保証されます。

質問 6：SDK を使用してページネーションでデータを取得する際、総数を返すようにパラメーターを設定するにはどうすればよいですか？

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

// エントリの総数を返すかどうかを指定します (ページネーションをサポートする API の場合)。
queryParamRequest.setReturnTotalNum(false);