Cloud-native API Gateway と DataWorks を使用して、MaxCompute データテーブルを外部からアクセス可能な REST API として公開します。
-
目的の例:MaxCompute の
user_infoテーブル用の API を作成します。この API を使用すると、呼び出し元はuser_idを指定してユーザー情報を照会できます。 -
最終結果:
https://api.example.com/v1/user/info?user_id=10001のような URL で、公開アクセス可能な認証済み API が作成されます。
-
レガシー API ゲートウェイを使用する場合は、「データソースから API を生成する (API Gateway)」をご参照ください。
-
このトピックでは MaxCompute を例として使用しています。サポートされているデータソースの一覧については、「データソースの設定」をご参照ください。
仕組み
次の図は、呼び出し元からデータソースまでのリクエストパスと、各コンポーネントがどこに位置するかを示しています。
前提条件
|
カテゴリ |
要件 |
説明 |
|
アカウントと権限 |
Alibaba Cloud アカウントと権限 |
アカウントには、Cloud-native API Gateway、DataWorks、MaxCompute を使用する権限が必要です。 DataWorks の関連ワークスペースにおいて、開発者 ロールを持っている必要があります。 |
|
サービスのアクティブ化 |
必要なクラウドサービスをアクティブ化する |
Cloud-native API Gateway をアクティブ化します。 説明
|
|
リソースの準備 |
サーバーレスリソースグループ |
サーバーレスリソースグループのネットワーク設定で、Data Service の VPC と vSwitch を関連付けます。 重要
このリソースグループの VPC を記録しておいてください。ネットワーク接続を簡素化するため、ゲートウェイインスタンスと Data Service リソースグループが同じ VPC を共有することを推奨します。 |
|
MaxCompute テストデータ |
MaxCompute プロジェクトで、次の DDL ステートメントを実行して 次の DML ステートメントを実行してテストデータを挿入します。 |
|
|
DataWorks データソース |
DataWorks の **[ワークスペース管理]** セクションで、上記の MaxCompute プロジェクトを指すデータソースを設定します。 |
ステップ 1:Cloud-native API Gateway コンソールでの基本リソースの準備
API サービスをホストするゲートウェイインスタンス、パブリックドメイン名、REST API リソースを作成します。
1. ゲートウェイインスタンスの作成
ゲートウェイインスタンスは、API リクエストを処理するエンジンです。
-
クラウドネイティブ API ゲートウェイコンソールにログインします。左側のナビゲーションペインで、インスタンス をクリックします。
-
上部メニューからリージョンを選択します。
重要リージョンは、DataWorks ワークスペースのリージョンと同じである必要があります。
-
インスタンス ページで、インスタンスの作成 をクリックします。
-
購入ページで、次のパラメータを設定します。
-
[商品タイプ]: 従量課金 と サブスクリプション がサポートされています。テスト目的の場合、従量課金を選択できます。
-
[ゲートウェイ名] :識別しやすいカスタム名を入力します (例:
dataservice-prod) 。 -
[ゲートウェイ仕様] :テスト用にはシングルノード、本番環境の SLA コンプライアンスのためにはマルチノードを選択します。
-
[ネットワークアクセスタイプ] :インターネットアクセスを有効にするには、[パブリック] または [パブリック + プライベート] を選択します。パブリックアクセスを使用すると、トラフィック料金が発生します。
-
[VPC]: VPC を選択します。
重要前提条件の [サーバーレスリソースグループ] と同じ VPC を使用することを強く推奨します。VPC が異なる場合は、後でバックエンドサービスを手動で作成する必要があります。
-
[ゾーンの選択] :[自動割り当て] を選択するか、異なるゾーンと vSwitch にインスタンスを手動で割り当てることができます。
-
[リソースグループ]:リソース管理ポリシーに基づいてリソースグループを選択します。
-
-
今すぐ購入 をクリックして支払いを完了します。インスタンスの作成には約 1~5 分かかります。ステータスが 実行中 に変わると、インスタンスの準備は完了です。
詳細については、「ゲートウェイインスタンスの作成」をご参照ください。
2. ドメイン名の追加
VPC 内でのみ API にアクセスする必要がある場合は、ドメイン名を申請する必要はありません。
ドメイン名は、API のパブリックアクセスエントリポイントとして機能します。
-
クラウドネイティブ API ゲートウェイコンソールの左側のナビゲーションペインで、ドメイン名 をクリックします。上部のリージョンがゲートウェイインスタンスと一致することを確認します。
-
[ドメイン名の追加] をクリックして、次の情報を設定します。
-
[ドメイン名]:独自のドメイン名 (例:
api.example.com) を入力します。中国リージョンで使用される独立ドメイン名は、ICP 申請を完了する必要があります。 -
[プロトコル]: 安全なデータ伝送のために HTTPS を選択します。既存の SSL 証明書を選択する必要もあります。
-
[その他の設定] :[HTTPS の強制] と [HTTP/2 の有効化] を有効にし、セキュリティ要件に基づいて [TLS バージョン] を選択します。
-
詳細については、「ドメイン名の追加」をご参照ください。
3. REST API の作成
[REST API] は、共有の ベースパス 配下で API をグループ化します。DataWorks の [ワークフロー] は [REST API] にバインドされます。
レガシー API Gateway と比較すると、[REST API] は [API グループ] に相当します。
-
Cloud-native API Gateway コンソールの左側のナビゲーションペインで、API をクリックします。上部のリージョンが正しいことを確認します。
-
APIの作成 をクリックします。APIの作成 ページで、REST API カードの下にある 作成 を選択します。
-
[REST API の作成] パネルで、次の設定を行います。
-
[API 名]: API コレクションに名前を付けます。名前は、
dataservice-user-apiのように、現在のリージョン内でグローバルに一意である必要があります。 -
[ベースパス] :API の [ベースパス] で、URL の一部です。たとえば、
/v1に設定します。最終的なアクセスパスはプロトコル://ドメイン名/ベースパス/API パスになります。 -
[バージョン管理]: 必要に応じて有効にします。
-
詳細については、「REST API の作成」をご参照ください。
ステップ 2:DataWorks での API の作成と設定
API ロジックを定義し、データソースに接続し、DataWorks でパラメータを設定します。
1. ワークフローの作成
ワークフローは関連する API を整理し、API Gateway の REST API に関連付けます。
-
DataWorks コンソールに移動します。 左側のナビゲーションペインで、DataService Studio > サービス開発 に移動します。
-
左上の作成アイコンをクリックし、ビジネスフローの作成 を選択します。
-
ビジネスフローの作成 ダイアログボックスで、次の設定を構成します:
-
[サービス名]:ワークスペース内で一意のカスタム名を、
User Query Workflowのように入力します。名前は 4〜50 文字の長さにする必要があります。 -
[ゲートウェイタイプ]: クラウドネイティブ API Gateway を選択します。
-
[REST API]:ドロップダウンリストから、ステップ 1 で作成した REST API を選択します (たとえば、
dataservice-user-api)。 表示されない場合は、パージ ボタンをクリックします。重要ワークフローが REST API に関連付けられた後、この関連付けは変更できません。慎重に進めてください。
-
2. ウィザードモードでの API の生成
-
サービス開発 ページで、左上隅にある作成アイコンにマウスを合わせ、APIの作成 > APIの生成 をクリックします。
-
APIの生成 ダイアログで、コードレス UI を選択し、API の基本情報を設定します:
-
[ターゲットフォルダ]:前の手順で作成したビジネスフロー (
User Query Workflow) を選択します。 -
[API 名]: 特定の API の名前を入力します。例:
Query User by User ID。 -
[API パス]: API の具体的なパス (
/user/infoなど) です。このパスはBase Pathと連結されて完全な URL パスを構成します。API Path は/で始まり、長さは 200 文字以内である必要があります。 -
[リクエストメソッド]: [GET] または [POST] を選択します。[GET] を選択した場合、リクエストパラメーターは QUERY 文字列にのみ配置できます。
-
[戻り値の型]: JSON を選択します。
-
-
[作成] をクリックして、グラフィカル API 編集ページに移動します。
説明スクリプトモードで API を作成するには、「スクリプトモードで API を作成する」をご参照ください。
3. API の設定
API 編集ページで、[テーブルの選択] > [パラメータの選択] > [パラメータの設定] という手順で、API を定義します。
-
テーブルの選択 (データソースとテーブル)
ページの左側にある [テーブルの選択] セクションで、次の設定を行います。
-
[データソースタイプ]: MaxCompute(ODPS) を選択します。
-
[データソース名]: 前提条件で設定したデータソースを選択します。
-
[データテーブル名]:
user_infoテーブルを選択します。 -
MaxCompute データソースを使用する場合、パフォーマンスを向上させるために加速方式を設定する必要があります。
-
-
パラメータの選択 (リクエストとレスポンス)
テーブルを選択すると、下の [パラメータの選択] セクションにテーブルのすべての列が表示されます。
-
リクエストパラメーターの設定:
user_id列を選択し、リクエストパラメーターに設定 をクリックします。 -
レスポンスパラメーターの設定:
user_idとuser_name列を選択し、戻りパラメーターに設定 をクリックします。
-
-
リクエストパラメーターの詳細を設定: ページの右側にある リクエストパラメーター タブで、
user_idパラメーターの [サンプル値] を設定します (例:10001)。これにより、後続のテストが容易になります。ベストプラクティス:クエリパフォーマンスを最適化するために、インデックス付きの列をリクエストパラメータとして設定します。
-
サービスリソースグループと環境の設定
ページの右側にある [サービスリソースグループ] セクションで、次の設定を行います。
-
[リソースグループタイプ]:[データサービス専用リソースグループ] を選択し、ドロップダウンリストから現在のワークスペースに関連付けられているリソースグループを選択します。
-
[環境構成]:
-
[タイムアウト時間]: Cloud-native API Gateway が DataWorks からの応答を待機する最大時間。例:
3秒。 -
[ページングサイズ]: 1 回の API コールで返されるレコードの最大数です。例:
2000。
-
-
-
セキュリティ認証の設定
右側のセキュリティ認証セクションで、コンシューマー認証を有効にし、認証タイプを選択します。
説明DataWorks は、Cloud-native API Gateway にワークスペースと同じ名前のコンシューマーを自動的に作成します。手動で作成する必要はありません。
認証方法
説明
適用シナリオ
API Key
クライアントは各リクエストに認証情報を含め、ゲートウェイはその有効性と権限を検証します。機密性の低い操作に適しています。JWT や HMAC よりもセキュリティが低いため、認証情報は慎重に保護してください。
中程度のセキュリティ要件を持つ軽量で迅速な統合シナリオに適しています。
JWT
JSON Web Token (JWT) は、HMAC、RSA、または ECDSA 署名を使用して、クライアントとサーバー間で検証可能なクレームを送信し、ゲートウェイでの ID 検証とアクセス制御を可能にします。
分散システムとシングルサインオン (SSO) シナリオに適しています。
HMAC
クライアントは署名キーでリクエストコンテンツに署名し、サーバー検証のために署名をリクエストと共に送信します。
データの整合性と改ざん防止に対する高い要件を持つシナリオに適しています。
-
API の保存:すべての設定が完了したら、上部のツールバーにある [保存] アイコンをクリックします。
ステップ 3:API のテスト、送信、デプロイ
1. API のテスト
API は、送信する前にテストに合格する必要があります。
-
API 編集ページで、ツールバーの API テスト ボタンをクリックします。
-
API テスト ダイアログで、
user_idリクエストパラメーターに既存のサンプル値 (たとえば、10001) を入力し、次に テストの開始 をクリックします。 -
右側のレスポンス内容で、データが期待どおりかを確認します。 応答時間はパフォーマンスの評価に使用できます。
-
テストが失敗した場合は、エラーメッセージに基づいて、データソース、テーブル、パラメータ、またはリソースグループの設定を確認してください。
2. API の送信
テストが成功したら、API を送信してデプロイ可能なバージョンを生成します。
-
API 編集ページで、ツールバーの コミット ボタンをクリックします。
-
送信後、システムによって API バージョンが生成され、右側のバージョン管理タブに表示されます。
-
ワークスペースに承認プロセスが設定されている場合、API バージョンのステータスは リクエスト待ち になります。公開のリクエスト をクリックしてリクエストを開始する必要があります。承認者がリクエストを承認すると、ステータスは 公開可能 に変わります。
承認プロセスが設定されていない場合、バージョンのステータスは通常、直接 [公開可能] になります。
3. Cloud-native API Gateway への API のデプロイ
API を本番環境にデプロイします。
-
API 編集ページの右側にあるバージョンタブで、ステータスが公開可能のバージョンを見つけ、操作列の公開をクリックします。
-
クラウドネイティブ API Gateway への API の公開 ダイアログで、以下の 3 つの必須設定を構成します。
-
[ドメイン名]: ステップ 1 で追加したドメイン名を選択します。
重要同じ [REST API] 配下のすべての API は、同じドメイン名を共有します。デプロイ中にドメイン名を変更すると、同じ [REST API] 配下のすべての API を呼び出すために使用されるドメイン名に影響します。
-
[ゲートウェイインスタンス]: ステップ 1 で作成したゲートウェイインスタンスを選択します。
-
[バックエンドサービス]:
-
ゲートウェイインスタンスの VPC が DataWorks リソースグループの VPC と [同じ] 場合は、[デフォルト] を選択します。
-
VPC が [異なる] 場合は、Cloud-native API Gateway に作成したバックエンドサービスを選択する必要があります。
バックエンドサービスの作成
-
-
デプロイ後、API はライブになり、アクセス URL で呼び出すことができます。
ステップ 4:API の呼び出しと検証
ステップ 2 で設定した認証方法に基づいて、認証情報を使用して API にアクセスします。
-
デプロイ済みの API のバージョン タブで、デプロイしたばかりのバージョンを見つけ、右側にあるサービス管理をクリックして API 管理ページに移動し、API の詳細を表示します。
-
API 管理ページで、API 名 / API パス の下にあるアドレスをクリックすると、API の詳細が表示されます。
-
呼び出しの構築と実行
-
サンプル URL:API の詳細からアクセス URL をコピーします。
-
認証情報:サービス管理 > API 呼び出し > クラウドネイティブ API Gateway に移動して、各種メソッドの認証の詳細を表示します。
-
呼び出し方法:
curlまたは他の HTTP クライアントを使用し、リクエストヘッダーにAppKeyとAppSecretを含めて呼び出しを行います。詳細については、「API の呼び出し」をご参照ください。
curl 呼び出しの例:
API Key 認証
# api.example.com を実際のドメイン名に置き換えます curl "https://api.example.com/v1/user/info?user_id=10001" \ -X GET \ -H "Content-Type: application/json; charset=utf-8" \ -H "Authorization: Bearer <API_KEY>"HMAC 認証
詳細な呼び出しプロセスについては、「HMAC 認証を使用して API を呼び出す」をご参照ください。
# api.example.com を実際のドメイン名に置き換えます curl "https://api.example.com/v1/user/info?user_id=10001" \ -X GET \ -H "x-ca-key: Access Key" \ -H "x-ca-signature: <Base64EncodedSignature>" \ -H "x-ca-signature-method: HmacSHA256" \ -H "Date: Wed, 01 Jan 2025 00:00:00 GMT" \ -H "Accept: application/json" \ -
-
期待されるレスポンスの表示:すべてが正しく動作している場合、次のような JSON レスポンスが表示されます。
{ "data": { "user_id": 10001, "user_name": "Alice" }, "success": true }
API のマルチバージョンサポート
Cloud-native API Gateway は、同じ API を複数のゲートウェイインスタンスにデプロイすることをサポートしており、異なる環境 (テスト環境と本番環境) を対象としたり、異なるビジネスニーズに対応したりできます。
複数ゲートウェイインスタンスへの API のデプロイ
バージョン パネルで、ステータスが 公開可能 のバージョンの 公開 をクリックします。クラウドネイティブ API Gateway への API の公開 ダイアログボックスで、別の ゲートウェイインスタンス を選択して、対応するゲートウェイインスタンスに API をデプロイします。この操作を繰り返すことで、同じ API を複数のインスタンスにデプロイできます。
同じゲートウェイインスタンス内では、新しいバージョンをデプロイすると、以前のバージョンが自動的にアンデプロイされます。異なるゲートウェイインスタンス間のバージョンは独立しており、[デプロイ済み] 状態で共存できます。
サービス管理でのマルチバージョン表示
API が複数のゲートウェイインスタンスにデプロイされると、サービス管理 ページの表示が次のように変更されます。
API 管理リスト
サービス管理 の 公開された API タブでは、同じ API ID がデプロイされたゲートウェイインスタンスごとに表示されます。 ゲートウェイインスタンス 列には、各レコードのインスタンス名とゲートウェイ ID が表示されます。
API 詳細ページ
API 名をクリックすると、その詳細ページが開きます。上部にある ゲートウェイインスタンス セレクターでインスタンスを切り替えて、各デプロイのアクセス URL、リクエストパラメーター、レスポンスパラメーターを表示できます。