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

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

前提条件

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

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

マーケットプレイスから 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 ドキュメントを表示できます。ランタイム環境が開発環境の場合、共通リクエストパラメーターのリストには 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 をデバッグする場合、入力パラメーターは 1,000 文字を超えることはできません。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 Specification] の 2 つのフォーマットでダウンロードできます。
operationID	インターフェイスの操作 ID で、インターフェイス操作の一意の識別子として使用されます。英字とアンダースコア (_) のみがサポートされており、最大 200 文字です。
summary	操作の説明。最大 200 文字。
コードプレビュー	設定が完了すると、コード (JSON フォーマット) をリアルタイムでプレビューできます。コード内のパラメーターの説明については、「OpenAPI Specification」をご参照ください。 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 が配置されている環境 required: true schema: type: string example: "prod:本番環境, pre:ステージング環境" requestBody: content: application/json: schema: required: - returnFields type: object properties: useModelCache: type: boolean description: "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 クエリ結果キャッシュを有効にするかどうか。クエリパフォーマンスの向上に役立ちます" default: false orderBys: type: array description: ソートフィールド items: type: object properties: field: type: string description: ソートタイプ、列挙値 (大文字に注意)、ASC または DESC のみ order: type: string description: ソートタイプ、列挙値 (大文字に注意)、ASC または DESC のみ example: 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 と呼び出し例を管理し、呼び出し手順を編集できます。

DataService Studio ページで、メニューバーの [アプリケーション管理] をクリックします。左側のナビゲーションウィンドウで、[呼び出し命令] をクリックします。
呼び出し手順ページで、[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 です。
      ファイルをローカルコンピュータにダウンロードできます。
    - [表示]：呼び出し例を API 呼び出し手順ページに表示するかどうかを決定します。保存後、このオプションはデフォルトで有効になります。呼び出し例を無効にすることができます。
    - [保存]：変更または新しく追加された呼び出し例を保存します。
    - [編集]/[削除]：カスタム呼び出し例の構成情報を変更または削除します。
  - [ソート]: クリック [ソート]し、呼び出し例をドラッグしてソートし、右上隅にある [完了] ボタンをクリックしてソートを完了します。ここでのソート順は、[API 呼び出し手順] ページのデフォルトの表示順序に影響します。
    説明
    最大 10 個の API 呼び出し例を作成できます（システムによってデフォルトで提供される呼び出し例を含む）。
    システムによってデフォルトで提供される呼び出し例は編集または削除できませんが、表示するかどうかを選択できます。
- [呼び出し手順の編集]：ビジネスシナリオに基づいて API 呼び出し手順を変更します。
呼び出し例の指示に従って API を呼び出します。