DataWorks:API のテスト、公開、およびバージョン管理

開発中の API のテスト

開発中の API は、開発環境である Service Development ページでテストできます。API をテストする前に、ウィザードモードまたはスクリプトモードで API を生成するか、既存のサービスを API として登録しておく必要があります。

操作手順：

1. DataWorks コンソール にログインします。対象のリージョンで、左側のナビゲーションウィンドウから データ分析とサービス > データサービス をクリックします。ドロップダウンリストからワークスペースを選択し、入力 データサービス をクリックします。

2. 左側の API リストで、テスト対象の API 名をダブルクリックして編集ページを開きます。

3. API 編集ページで、テスト ボタンをクリックして、Test APIs ダイアログボックスを開きます。

4. ダイアログボックスの左側ペインで、各リクエストパラメーターのテスト値を入力します。

5. Start Test をクリックして、API 呼び出しをトリガーします。

テスト結果の表示：

テスト完了後、ダイアログボックスの右側ペインで次の情報を確認できます。

• Request Details：API 呼び出しの完全なリクエスト情報（リクエストパス、ヘッダー、本文など）を表示します。これにより、リクエストの構造が正しいかどうかを検証できます。

• Response Details：API からのレスポンスデータ（実際のクエリ結果）を表示します。レスポンス内容を期待される結果と比較することで、API のロジックが正しいかどうかを確認できます。

• Response Duration：API リクエストのエンドツーエンドの応答時間を表示します。この情報を使用して API のパフォーマンスを評価できます。遅延が高い場合は、クエリロジックまたはデータソースの構成を最適化することを検討してください。

テストが失敗した場合は、返されたエラーメッセージを確認し、必要な変更を加えて再度 API をテストしてください。

公開済み API のテスト

公開済み API は、本番環境である Service Management ページでテストできます。これにより、本番環境での API の動作を検証できます。このテストを実行する前に、API を公開しておく必要があります。

操作手順：

1. データサービス ページで、上部のナビゲーションバーから Service Management をクリックします。

2. 左側のナビゲーションウィンドウで、Test APIs をクリックします。

3. ドロップダウンリストからテスト対象の API を選択し、すべてのリクエストパラメーターに値が設定されていることを確認します。

4. Start Test をクリックし、右側ペインで Request Details および Response Details を確認します。

注意事項：

• Test APIs ページはオンラインテスト機能のみを提供します。このページでは、API の通常のレスポンス例を更新することはできません。

• API に Pagination for Return Results が設定されている場合、返されるデータがソートされているかどうかは基盤となるデータソースに依存します。ソートを保証するには、ウィザードモードで API に Sort field を設定するか、スクリプトモードで SQL コードに ORDER BY 句を追加してください。

テスト結果の解釈と最適化

完全な API テスト結果は、次の 3 つの部分で構成されています。各部分を理解することで、問題を迅速に特定できます。

テスト結果が期待通りになったら、API を API Gateway に公開できます。

前提条件

API を公開する前に、次の要件を満たしていることを確認してください。

• API Gateway が有効化されていること：API Gateway コンソールにアクセスして、サービスを有効化してください。

  重要

  DataWorks と API Gateway 間のネットワークアーキテクチャ上の制限により、API Gateway インスタンスを購入する際は、Instance Type として専用型インスタンスのみがサポートされます。VPC 統合インスタンスは現時点でサポートされていません。

• API グループが作成されていること：API が公開されると、そのビジネスプロセスに関連付けられた API Gateway グループにデプロイされます。ビジネスプロセスが正しく API Gateway グループに関連付けられていることを確認してください。グループ名は、Workflow を右クリックして Change を選択することで確認できます。

公開プロセス

API の公開プロセスは、次の 3 ステップで構成されます：提出 → 承認 → 公開。

ステップ 1：API の提出

1. データサービス ページに移動します。サービス開発 ページの API リストで、公開対象の API 名をダブルクリックして編集ページを開きます。

2. 右上隅で、Submission をクリックします。

3. 提出が成功すると、V1 や V2 などの API バージョンが自動的に生成されます。このバージョンのステータスは、右側に表示される Version パネルで確認できます。

ステップ 2：公開依頼と承認待ち

1. 右側の Version パネルで、公開対象の API バージョンを見つけ、Publish をクリックします。

2. 画面の指示に従って依頼理由を入力し、Requested Permissions をクリックして公開依頼を提出します。

3. ワークスペースに承認プロセスが設定されている場合、公開依頼は DataWorks Approval Center でレビューされる必要があります。承認担当者は、Approval Center > To Be Processed ページで依頼の詳細を確認し、処理できます。

4. 承認後、Version パネル内の API ステータスが To Be Requested から Can Be Published に変更されます。

ステップ 3：API の公開

1. 依頼が承認された後、API 編集ページで右側のナビゲーションウィンドウから Version をクリックします。Can Be Published ステータスの API バージョンを見つけます。

2. Publish ボタンをクリックし、システムが公開成功を示すまで待ちます。

3. API が公開されると、DataWorks はその API を API のビジネスプロセスに関連付けられた API Gateway グループにデプロイします。

公開の確認

公開後、次の方法で API を確認および管理できます。

• API Gateway での表示：API Gateway コンソール にログインします。左側のナビゲーションウィンドウで、Manage APIs > Service List を選択して、公開済み API 情報を表示します。速度制限やアクセスの制御などのポリシーも設定できます。

• アプリケーションからの呼び出し：API をご自身のアプリケーションで使用する場合、API Gateway でアプリケーションを作成し、API へのアクセス権限を付与した上で、AppKey と AppSecret を使用した暗号化された署名で呼び出す必要があります。API Gateway は、主流のプログラミング言語向けの SDK も提供しており、アプリケーションへの API 統合を迅速に行えます。詳細については、「API 呼び出しの例」をご参照ください。SDK 統合については、「SDK のダウンロードと使用」をご参照ください。

• プロトコルの変更：公開済み API について、Service Management > Published APIs タブに移動します。API の [操作] 列で、More > Change Protocol を選択して、アクセスプロトコル（HTTP から HTTPS など）を変更できます。プロトコルの変更は即時反映されます。ただし、元のプロトコルを削除すると、そのプロトコルを使用した API 呼び出しは失敗します。慎重に操作してください。

Alibaba Cloud Marketplace への出品（オプション）

Alibaba Cloud Marketplace は幅広いカテゴリをカバーしており、データの収益化を支援します。

DataService Studio で作成または登録された API が API Gateway に公開された後、Alibaba Cloud Marketplace に出品して販売できます。これにより、企業はデータの収益化を実現し、商用化プロセスを完了できます。

要件：

• Alibaba Cloud Marketplace に参加できるのはビジネスアカウントのみです。

• API を出品する前に、ISV として Alibaba Cloud Marketplace に参加する必要があります。プロセスの詳細については、「Alibaba Cloud Marketplace 参加プロセス」をご参照ください。

操作手順：

1. Alibaba Cloud ISV ポータルに移動します。

2. 左側のナビゲーションウィンドウで、商品 > Commodity Manager をクリックします。

3. Create Product をクリックします。

4. Access Information ページで、プロダクト名、価格戦略、API バインディングなどのパラメーターをガイドに従って設定し、出品プロセスを完了します。

バージョン履歴の表示

1. DataWorks コンソール にログインします。対象のリージョンで、左側のナビゲーションウィンドウから データ分析とサービス > データサービス をクリックします。ドロップダウンリストからワークスペースを選択し、入力 データサービス をクリックします。

2. Service Development ページの API リストで、表示対象の API 名をダブルクリックして編集ページを開きます。

3. ページ右側の Version ボタンをクリックしてバージョンパネルを開き、バージョン情報と詳細を表示します。このパネルには、現在の API のすべての履歴バージョン情報が表示されます。

   説明

   各バージョンの [操作] 列には、API Details リンクが表示されます。これをクリックすると、リクエストパラメーター、レスポンスパラメーター、データソース構成など、そのバージョンの完全な構成情報を表示できます。

   フィールド	説明
   API ID	現在の API の一意の識別子。
   Version	バージョン番号。提出のたびに増分されます（V1、V2、V3...）。
   Submitted By	このバージョンを提出したユーザー。
   Submitted At	このバージョンが提出された時刻（秒単位）。
   Status	Publish（現在のライブバージョン） Can Be Published（テストおよび提出済みのバージョン） Batch Synchronization（履歴バージョン）

バージョンの比較

API が複数回反復された場合、具体的な変更内容を把握するために異なるバージョンを比較する必要があるかもしれません。

操作手順：

1. Version パネルで、比較対象の 2 つのバージョンを選択します。

2. パネル下部の Compare ボタンをクリックします。

3. 表示される History Version Contrast ダイアログボックスで、2 つのバージョンの差分を確認します。

比較の詳細：

• ウィザードモードの API：リクエストパラメーターおよびレスポンスパラメーターの差分を表示します。パラメーター名、タイプ、必須かどうかの変更が含まれます。

• スクリプトモードの API：SQL スクリプトのテキスト差分を表示します。追加、削除、変更されたコード行がハイライトされます。

バージョン比較機能は、共同作業シナリオで特に役立ち、レビュアーが各変更の詳細を迅速に把握するのに役立ちます。

バージョンのロールバック

新しいバージョンに問題が発生した場合や期待通りでない場合は、API を以前の安定バージョンに迅速にロールバックできます。

操作手順：

1. Version パネルで、対象の履歴バージョンを見つけます。

2. そのバージョンの [操作] 列で、ロールバック をクリックします。

3. 表示される Confirm that you want to roll back the current version ダイアログボックスで、Confirm をクリックします。

バージョン管理戦略

適切なバージョン管理習慣により、本番環境でのインシデントリスクを大幅に低減できます。

• 変更の追跡：変更を提出する際、提出ノートに変更内容とその理由を明確に記述してください。これにより、チームメンバーがバージョン比較を使用して変更の背景を理解しやすくなります。

• カナリア検証：重要な変更を行う場合は、本番環境に公開する前にテスト環境で徹底的な検証を行うことを推奨します。

• 迅速なロールバック：本番環境で問題が発覚した場合、根本原因の調査よりも先にバージョンロールバック機能を使用してサービスを復旧させることを優先してください。バージョンのロールバックは、修正して再公開するよりも迅速であり、ビジネスへの影響を最小限に抑えられます。

• 定期的なクリーンアップ：使用されていない API は速やかに非公開および削除することを推奨します。これにより、管理の複雑さと潜在的なセキュリティリスクを軽減できます。

共同作業ワークフロー

チームでの共同作業シナリオでは、次のワークフローを推奨します。

1. 開発者が Service Development ページで API を作成および構成します。

2. 開発者が開発環境でテストを行い、機能が正しいことを確認します。

3. 開発者が API を提出し、新しいバージョンを生成して公開依頼を開始します。

4. 承認者が DataWorks Approval Center で公開依頼をレビューし、バージョン比較機能を使用して変更内容を確認できます。

5. 承認後、開発者が最終的な公開操作を実行します。

6. 運用エンジニアが Service Management ページで公開済み API のオンラインテストおよびモニタリングを実施します。

7. 問題が発見された場合、バージョンをロールバックしてサービスを迅速に復旧させるか、API を非公開にして修正を行います。

このプロセスに従うことで、チームは API ライフサイクル全体を効率的に管理しながら、リリース品質を確保できます。

レスポンス例の制限事項

API 編集ページでは、API ドキュメントに期待されるレスポンスデータ構造を表示するために Normal Response Example を設定できます。次の制限事項にご注意ください。

• 自動同期なし：API テストのレスポンスは、API の通常のレスポンス例を自動的に更新しません。API 編集ページでレスポンス例を手動で編集または貼り付ける必要があります。

• サイズ制限：通常のレスポンス例には文字数制限があります。例として数百件のレコードを含むなど、例データが大きすぎる場合、保存に失敗する可能性があります。典型的なレコードを 2～3 件のみ保持することを推奨します。

• 変更は公開後に反映：通常のレスポンス例を変更した後、API Gateway ドキュメントで変更を反映させるには、API を再提出および再公開する必要があります。

データソーススキーマ変更の対処

API に関連付けられたデータソーステーブルのスキーマが変更された場合（フィールドの追加、削除、タイプの変更など）、公開済み API はこれらの変更を自動的に検出しません。これらの変更に対処しないと、次の問題が発生する可能性があります。

操作手順：

1. API 編集ページに移動し、スキーマ変更を反映するように API 構成を変更します。

   1. ウィザードモード：テーブルを再選択すると、システムが自動的にフィールドリストをリフレッシュします。

   2. スクリプトモード：SQL ステートメントでフィールド名またはテーブル名を手動で変更します。

2. 構成を保存した後、変更を検証するために再度 API をテストします。

3. API を提出および再公開します。