本番環境で API を呼び出す方法 - Dataphin - Alibaba Cloud ドキュメントセンター

API を呼び出すとは、アプリケーションが実行時環境に基づいて現在の環境で API を呼び出すことを意味します。基本モードでは、実行時環境が開発環境であっても、読み取られるデータは依然として本番環境からのものです。企業向けの API エコシステムを構築する必要があるシナリオでは、カスタム開発のために API を呼び出したり、パートナーと API を共有したりして、企業の収益化とデータ価値の最大化を支援できます。このトピックでは、API の呼び出し方法について説明します。

前提条件

API が Data Service Marketplace に公開されています。詳細については、「API をテストして公開する」をご参照ください。
最初にアプリケーションを作成する必要があります。詳細については、「アプリケーションを作成する」をご参照ください。

API ドキュメントのエントリ説明

マーケットプレイスから API ドキュメントにアクセスする: トップメニューバーで [サービス] > [API Marketplace] をクリックし、左側のナビゲーションウィンドウで [API サービス] をクリックし、[API ドキュメント] の下にあるターゲット API の [ドキュメント] 列をクリックして、[API ドキュメント] ページに移動します。この方法では、本番環境の API ドキュメントにアクセスします。権限の有無にかかわらず、API ドキュメントを表示およびダウンロードできます。
呼び出しページから API ドキュメントにアクセスする: この方法は、API がアプリケーションに承認されており、ユーザーがアプリケーションに対する権限を持っている場合にのみサポートされます。トップメニューバーで [サービス] > [API 呼び出し] をクリックし、サービスプロジェクトを選択し、左側のナビゲーションウィンドウで [サービス呼び出し] > [承認済み API サービス] を選択し、ターゲット API のアクション列にある [表示] をクリックして、[API ドキュメント] ページに移動します。この方法では、開発環境の API ドキュメントにアクセスします。環境を切り替えたり、API ドキュメントをダウンロードしたりできます。

API ドキュメントとデバッグページの上部にある操作

[API の切り替え]：ページの左上隅で、表示する API を切り替えることができます。あいまい検索を使用して、名前または ID で API を検索できます。現在のユーザーが参加しているサービスプロジェクトで公開されている API の検索をサポートしています。システムは、最新の 9 つの API を推奨します。
[API ランタイム環境の切り替え]：
- [API ドキュメント]: [API 呼び出し] > [承認済み API サービス] ページからアクセスした API ドキュメントのみ、API ドキュメントを表示する権限を持つ環境 (開発環境、本番環境) の選択をサポートしています。ランタイム環境が開発環境の場合、共通リクエストパラメータリストで apiVersion パラメータがサポートされます。
- [API のデバッグ]：API をデバッグする権限を持つ環境（開発環境、本番環境）を選択できます。ランタイム環境が開発環境の場合、開発データソースがデバッグに使用されます。ランタイム環境が本番環境の場合、本番データソースがデバッグに使用されます。
  説明
  - ランタイム環境が開発環境の場合、組み合わせ API では、開発 - 本番モードで構成されたサブ API はデバッグに開発環境データソースを使用し、基本モードで構成されたサブ API はデバッグに本番環境データソースを使用します。
  - ランタイム環境が本番環境の場合、組み合わせ API では、開発 - 本番モードまたは基本モードのいずれかで構成されたサブ API はデバッグに本番環境データソースを使用します。
[API バージョンの切り替え]：ランタイム環境が開発環境の場合、API をデバッグするときに、ページの右上隅で API バージョンを切り替えることができます。送信済みバージョン（公開済みバージョンを含む）のみを選択できます。

ステップ 1：API のクエリとリクエスト

説明

API を使用する前に、API を所有するアプリケーションの権限をリクエストする必要があります。

Dataphin ホームページのトップメニューバーで、[サービス] > [API Marketplace] を選択します。
[API] タブをクリックし、[API ドキュメント] の下にあるターゲット API の [ドキュメント] 列をクリックして、[API ドキュメント] ページに移動します。この方法では、本番環境の API ドキュメントにアクセスします。パスは、API が公開されているかどうかによって異なる場合があります。詳細については、「API ドキュメントのエントリ説明」をご参照ください。
[API ドキュメント] ページで、API の [基本情報]、[ソート設定] (コードレス UI モードのサービスユニット API でのみサポート)、[ビジネスリクエストパラメータリスト]、[共通リクエストパラメータリスト]、[行レベル権限リスト]、[レスポンスパラメータリスト]、[JSON レスポンス例] を確認して、ビジネス要件を満たしているかどうかを確認します。
説明
- API タイプが直接データソース API、サービスユニット API、または組み合わせ API で、行レベルの権限が有効になっている場合は、行レベルの権限リスト情報を表示できます。
- 呼び出しモードが非同期呼び出しの場合、API データキャッシングはサポートされていません。データはカーソルを使用して段階的に取得できます。したがって、非同期呼び出しではキャッシュと結果のページング構成は不要であり、共通リクエストパラメータには PageSize と PageStart 情報は表示されません。
現在の API がビジネス要件を満たしていることを確認したら、API サービスページの [今すぐリクエスト] の下の [リクエストステータス] 列をクリックします。 [管理ハブ] > [権限管理] > [自分の権限] > [データサービス権限] ページにリダイレクトされ、API の権限をリクエストできます。詳細については、「API 権限をリクエストする」をご参照ください。

ステップ 2：API のデバッグ

API 権限のリクエストが完了したら、API をデバッグして正しく動作することを確認できます。

トップメニューバーで [呼び出し] をクリックし、サービスプロジェクトを選択します。
左側のナビゲーションウィンドウで [サービス呼び出し] > [承認済み API サービス] を選択します。[承認済み API サービス] ページで、ターゲット API のアクション列の [デバッグ] をクリックして、[API デバッグ] ページに移動します。
[API デバッグ] ページで、デバッグ入力値を構成します。デバッグパラメータと API が期待どおりに動作するかどうかをテストする方法の詳細については、「ステップ 1：API をテストする」をご参照ください。
API デバッグページの上部でドメイン名を表示できます。このドメイン名は内部テストにのみ使用されます。呼び出す実際のドメイン名については、「ドメイン名を表示する」をご参照ください。
[API デバッグ] ページの [オプションのレスポンスパラメータリスト] セクションで、右上隅で承認済みアプリケーションをすばやく切り替えることができます。

手順 3: ドキュメントのダウンロード

API ドキュメントをダウンロードして他の開発者と共有し、使用の柔軟性を高めることができます。ドキュメントは、簡単に編集できる Word 形式、または Alibaba Cloud Model Studio プラグイン登録用の OpenAPI 仕様 YAML ドキュメントとしてダウンロードできます。

OpenAPI YAML ファイルのダウンロード

Dataphin ホームページで、トップメニューバーの [サービス] > [API Marketplace] をクリックします。
左側のナビゲーションウィンドウで [API サービス] をクリックし、ターゲット API を選択し、[API ドキュメント] の下の [ドキュメント] 列をクリックします。
[API ドキュメント] ページで、右上隅の [OpenAPI YAML ファイルのダウンロード] をクリックします。

[OpenAPI YAML ファイルのダウンロード] ダイアログボックスで、パラメータを構成します。

パラメータ	説明
[フォーマット]	[Alibaba Cloud Model Studio] と [OpenAPI 仕様] の 2 つの形式でファイルをダウンロードできます。
操作 ID	インターフェイスの操作 ID。インターフェイス操作の一意の識別子として使用されます。英字とアンダースコア（_）のみがサポートされ、最大 200 文字です。
[概要]	操作の説明。最大 200 文字。
[コードプレビュー]	設定が完了すると、コード（JSON 形式）をリアルタイムでプレビューできます。コードのパラメータの説明については、「OpenAPI 仕様」をご参照ください。 openapi: 3.0.1 info: title: sq_test_mysql description: "" version: V1.4 servers: - url: http://528fdcdcc62d4f4eb8f10ad99cdda9f3-cn-shanghai.alicloudapi.com paths: /list/10172: post: summary: "" operationId: "" parameters: - name: appKey in: query description: API へのアクセスにバインドされているアプリケーションキー // アプリケーションキー required: true schema: type: string example: "2000001" - name: env in: query description: API が配置されている環境 // API が存在する環境 required: true schema: type: string example: "prod:Production environment, pre:Staging environment" // "prod:本番環境、pre:ステージング環境" requestBody: content: application/json: schema: required: - returnFields type: object properties: useModelCache: type: boolean description: "SQL 翻訳キャッシュを有効にするかどうか。クエリのパフォーマンスを向上させるのに役立ちます" // "SQL 翻訳キャッシュを有効にするかどうか。クエリのパフォーマンス向上に役立ちます。" default: false pageStart: type: integer description: ページングクエリの開始位置 // ページングクエリの開始位置 format: int32 pageSize: type: integer description: ページングクエリで返されるレコード数 // ページングクエリで返されるレコード数 format: int32 returnFields: type: array items: type: string example: "[id, name, sexo]" conditions: required: - sex type: object properties: namee: type: string example: null sex: type: string example: null idd: type: string example: null description: 入力パラメータ条件 // 入力パラメータの条件 useResultCache: type: boolean description: "API クエリ結果キャッシュを有効にするかどうか。クエリのパフォーマンスを向上させるのに役立ちます" // "API クエリ結果キャッシュを有効にするかどうか。クエリのパフォーマンス向上に役立ちます。" default: false orderBys: type: array description: ソートフィールド // ソートフィールド items: type: object properties: field: type: string description: ソートタイプ、列挙値（大文字に注意）、ASC または DESC のみ // ソートタイプ、列挙値（大文字に注意）、ASC または DESC のみ order: type: string description: ソートタイプ、列挙値（大文字に注意）、ASC または DESC のみ // ソートタイプ、列挙値（大文字に注意）、ASC または DESC のみ example: ASC or DESC // ASC または DESC required: true

構成が完了したら、[ダウンロード] をクリックして、ファイルをローカルコンピュータにダウンロードします。

API ドキュメントのダウンロード

Dataphin ホームページで、トップメニューバーの [サービス] > [API Marketplace] をクリックします。
左側のナビゲーションウィンドウで [API サービス] をクリックし、[API ドキュメント] の下にあるターゲット API の [ドキュメント] 列をクリックします。
[API ドキュメント] ページで、右上隅の [API ドキュメントのダウンロード] をクリックして、単一の API ドキュメントをダウンロードします。[API サービス] ページで複数の API を選択し、下部の [API ドキュメントのダウンロード] をクリックして、API ドキュメントを一括ダウンロードすることもできます。
説明
- ダウンロードされた API ドキュメントには、便宜上、API に基づいて生成された具体的な呼び出し例が含まれています。また、「API 呼び出しテンプレート」に従って呼び出し例を構成することもできます。
- API ドキュメントは Word 形式でローカルコンピュータにダウンロードできます。
- API ドキュメントには、目次、ドキュメントバージョン、API 呼び出し例、インターフェイスリスト (インターフェイス別に整理され、各インターフェイスには基本情報、ソート設定 (コードレス UI モードのサービスユニット API のみ)、ビジネスリクエストパラメータリスト、共通リクエストパラメータリスト、行レベル権限リスト (直接データソース API、サービスユニット API、または組み合わせ API で行レベルの権限が有効になっている場合にのみサポート)、レスポンスパラメータリスト、JSON レスポンス例、および API の具体的な呼び出し例が含まれます) が含まれています。
- ネットワークで構成された API ゲートウェイが Alibaba Cloud API Gateway で、パブリック第 2 レベルドメイン/内部 VPC ドメインが有効で、すべてのユーザーに表示される場合、ダウンロードされた API ドキュメントで正しいホスト情報を確認できます。内部ゲートウェイの場合は、ドメイン名の表示が [はい] に設定されている場合にのみ、正しいホスト情報を確認できます。

API 呼び出しテンプレート

説明

スーパー管理者のみが SDK と呼び出し例を管理し、呼び出し手順を編集できます。

データサービスページで、トップメニューバーの [呼び出し] をクリックし、左側のナビゲーションウィンドウの [呼び出し手順] をクリックして、呼び出し手順ページに移動します。
呼び出し手順ページで、[API 呼び出し手順] タブをクリックして、API 呼び出し手順ページに移動します。
[API 呼び出し手順] ページで、「API 呼び出し例」のテンプレートを表示し、次の操作を実行します。
- [デフォルトの呼び出し例のダウンロード]：[デフォルトの呼び出し例のダウンロード] をクリックして、同期呼び出しと非同期呼び出しを含む API 呼び出し例をダウンロードできます。
- [Python 呼び出し例のダウンロード]：Python を使用して API を呼び出す必要がある場合は、[Python 呼び出し例のダウンロード] をクリックして、Python 例の圧縮ファイルをダウンロードします。
- [Java SDK のダウンロード]：Java SDK を使用して API を呼び出す必要がある場合は、[Java SDK のダウンロード] をクリックして、Java SDK コードパッケージをダウンロードします。
- [SDK と呼び出し例の管理]：[SDK と呼び出し例の管理] ボタンをクリックして、SDK と呼び出し例の管理ページに移動します。このページでは、API 呼び出し例を一元管理したり、新しい呼び出し例を追加したり、呼び出し例をソートしたりできます。
  - [追加]：下部の [追加] ボタンをクリックして、呼び出し例を追加します。
    - [名前]：呼び出し例の名前を入力します。これは API 呼び出し手順ページに表示されます。名前は一意である必要があります。10 文字以内、最大 50 文字以内を入力することをお勧めします。
    - [説明]：呼び出し例の簡単な説明を入力して、関連するビジネス担当者がその目的を理解できるようにします。最大 100 文字。
    - [ファイルのアップロード]：[アップロード] ボタンをクリックして、ローカルコンピュータからファイルを選択し、Dataphin にアップロードします。サポートされているファイル形式は、zip、rar、doc、docx、PDF、jpg で、最大ファイルサイズは 200 MB です。アップロードボタンを使用してローカルコンピュータからファイルを選択し、Dataphin にアップロードします。サポートされているファイル形式には、
      ファイルをローカルコンピュータにダウンロードできます。
    - [表示]：呼び出し例を API 呼び出し手順ページに表示するかどうかを決定します。保存後、このオプションはデフォルトで有効になります。呼び出し例を無効にすることができます。
    - [保存]：変更または新しく追加された呼び出し例を保存します。
    - [編集]/[削除]：カスタム呼び出し例の構成情報を変更または削除します。
  - [ソート]: クリック [ソート]し、呼び出し例をドラッグしてソートし、右上隅にある [完了] ボタンをクリックしてソートを完了します。ここでのソート順は、[API 呼び出し手順] ページのデフォルトの表示順序に影響します。
    説明
    最大 10 個の API 呼び出し例を作成できます（システムによってデフォルトで提供される呼び出し例を含む）。
    システムによってデフォルトで提供される呼び出し例は編集または削除できませんが、表示するかどうかを選択できます。
- [呼び出し手順の編集]：ビジネスシナリオに基づいて API 呼び出し手順を変更します。
呼び出し例の指示に従って API を呼び出します。

API 戻りレコード制限

API を呼び出した後、データをクエリできます。次の表に、さまざまなサービスタイプとデータソースでサポートされているクエリレコード制限を示します。

データソースタイプ	クエリあたりの最大レコード数	合計クエリレコード制限	ページングクエリのサポート
単一物理テーブルサービスユニット
MySQL	10000	上限なし	サポート
AnalyticDB for MySQL 2.0			サポート
Elasticsearch			サポート
Microsoft SQL Server			サポートしていません
PostgreSQL			サポート
AnalyticDB for MySQL 3.0			サポート
AnalyticDB for PostgreSQL			サポート
Hologres			サポート
Hbase (0.9.4/1.1.x/1.2.1/2.x)	10000	10000	サポート
Oracle			サポート
MongoDB			サポート
複数物理テーブルサービスユニット
MySQL	10000	上限なし	サポート
AnalyticDB for MySQL 2.0			サポート
Elasticsearch			サポート
Microsoft SQL Server			サポートしていません
PostgreSQL			サポート
AnalyticDB for MySQL 3.0			サポート
AnalyticDB for PostgreSQL			サポート
Hologres			サポート
Hbase (0.9.4/1.1.x/1.2.1/2.x)	10000	10000	サポート
Oracle			サポート
MongoDB			サポート
直接データソース API
Impala	10000	上限なし	サポート
Oracle			サポート
MySQL			サポート
PostgreSQL			サポート
Microsoft SQL Server			サポート
Hologres			サポート
Lindorm			サポート
ClickHouse			サポート
StarRocks			サポート
TDengine			サポートしていません
SAP HANA			サポートしていません
SelectDB			サポート
Hbase (0.9.4/1.1.x/1.2.1/2.x)	1	上限なし	サポートしていません
ElasticSearch	10000	10000	サポート
論理テーブル API
なし	10000	10000	サポート
Dataphin データソース
Dataphin データソース	10000	上限なし	サポート

SDK を介して API を呼び出すときに、9000 から 10000 のレコードをクエリする必要がある場合は、パブリックリクエストパラメータ PageStart を 9000 に、PageSize を 1000 に構成します。