API の作成、公開、および呼び出し (Cloud-native API Gateway) - DataWorks

本トピックでは、Cloud-native API Gateway と DataWorks を使用して MaxCompute データテーブルをパブリック REST API として公開するエンドツーエンドの例を紹介します。

例の目的： MaxCompute 内の user_info テーブルに対する API を作成します。この API を使用すると、呼び出し側は user_id を指定してユーザー情報を照会できます。
最終的な結果：以下のようなパブリック URL（例：https://api.example.com/v1/user/info?user_id=10001）からアクセス可能な API と、安全かつ認証された方法での呼び出しが可能になります。

説明

レガシ API Gateway を使用している場合は、「データソースから API を生成する (API Gateway)」をご参照ください。
本トピックでは MaxCompute を例として使用しています。サポートされているデータソースの一覧については、「データソースの構成」をご参照ください。

仕組み

次の図は、API 呼び出し元から最終的なデータソースまでの完全なパスを示しており、各コンポーネントがどこで構成されるかを示しています。

前提条件

カテゴリ	要件	説明
アカウントと権限	Alibaba Cloud アカウントと権限	ご利用のアカウントには、Cloud-native API Gateway、DataWorks、および MaxCompute を使用するための権限が必要です。 DataWorks の該当ワークスペースに対して Development ロールが付与されている必要があります。
サービスの有効化	必要なクラウドサービスを有効化	Cloud-native API Gateway を有効化します。説明 Cloud-native API Gateway は API Gateway の新バージョンです。レガシ版を使用している場合は、「データソースから API を生成する (API Gateway)」をご参照ください。 Cloud-native API Gateway インスタンスやパブリックネットワークトラフィックなど、一部のサービスおよびリソースには料金が発生する場合があります。
リソースの準備	サーバーレスリソースグループ	サーバーレスリソースグループのネットワーク設定で、Data Service 用の VPC および vSwitch をバインドします。重要このリソースグループの VPC 情報をメモしておいてください。ゲートウェイインスタンスを作成する際に必要になります。ネットワーク接続を簡素化するために、ゲートウェイインスタンスとサーバーレスリソースグループに同じ VPC を使用することを強く推奨します。
	MaxCompute テストデータ	ご利用の MaxCompute プロジェクトで、次の DDL 文を実行して `user_info` テーブルを作成します。 `CREATE TABLE user_info (user_id BIGINT, user_name STRING, age BIGINT);` 次の DML 文を実行してテストデータを挿入します。 `INSERT INTO user_info VALUES (10001, 'Alice', 25), (10002, 'Bob', 30);`
	DataWorks データソース	DataWorks コンソールのワークスペース管理セクションで、上記の MaxCompute プロジェクトを指すデータソースを構成します。

ステップ 1：基本リソースの準備

このステップでは、API サービスをホストするゲートウェイインスタンス、パブリックアクセス用のドメイン名、および API を整理するための論理単位（REST API）を作成します。

1. ゲートウェイインスタンスの作成

ゲートウェイインスタンスは、API リクエストを処理するエンジンです。

Cloud-native API Gateway コンソールにログインします。左側のナビゲーションウィンドウで、Instance をクリックします。
上部のナビゲーションバーでリージョンを選択します。
重要
リージョンは、ご利用の DataWorks ワークスペースのリージョンと同じである必要があります。
Instance ページで、インスタンスの作成 をクリックします。
購入ページで、次のパラメーターを構成します。
- 商品タイプ： Pay-as-you-go または Subscription を選択します。テスト用途の場合は、従量課金を選択できます。
- ゲートウェイ名：識別しやすいカスタム名を入力します（例：dataservice-prod）。
- ゲートウェイ仕様：テスト用途の場合は、シングルノード仕様を選択できます。本番環境では、高レベルのサービスレベル契約（SLA）を確保するために、マルチノードゲートウェイ仕様の使用を推奨します。
- ネットワークタイプ：パブリックインターネットアクセス用に パブリック または パブリック + プライベート を選択します。パブリックネットワークトラフィックには料金が発生します。
- 独自のネットワーク： VPC を選択します。
  重要
  ネットワーク接続を確実にするために、サーバーレスリソースグループ と同じ VPC を選択することを強く推奨します。VPC が異なる場合は、後ほど手動でバックエンドサービスを作成する必要があります。
- ゾーン選択： 自動割り当て を選択するか、インスタンスを異なる可用性ゾーンおよび vSwitch に手動で割り当てます。
- Resource Group：リソース管理戦略に基づいてリソースグループを選択します。
Buy Now をクリックして支払いを完了します。インスタンスの作成には約 1～5 分かかります。インスタンスステータスが 実行中 に変わると、インスタンスの作成が完了します。

詳細については、「ゲートウェイインスタンスの作成」をご参照ください。

2. ドメイン名の追加

説明

VPC 内からのみ API にアクセスする必要がある場合は、ドメイン名を追加する必要はありません。

ドメイン名は、ご利用の API のパブリックエントリポイントです。

Cloud-native API Gateway コンソールの左側ナビゲーションウィンドウで、ドメイン名 を選択します。上部ナビゲーションバーで選択されているリージョンが、ご利用のゲートウェイインスタンスのリージョンと同じであることを確認してください。
ドメイン名の追加 をクリックし、次の情報を構成します。
- ドメイン名：ご自身のドメイン名を入力します（例：api.example.com）。中国本土のリージョンで使用するスタンドアロンドメイン名には、ICP 登録が必要です。
- 契約：データ転送を保護するために、HTTPS の選択を推奨します。HTTPS を選択する場合は、既存の SSL 証明書を選択する必要があります。
- その他の構成：セキュリティ要件に基づき、強制 HTTPS および HTTP/2 の有効化 を有効にし、TLS バージョン を指定することを推奨します。

詳細については、「ドメイン名の作成」をご参照ください。

3. REST API の作成

REST API は、同じ Base Path を持つ一連の API を管理するための論理コンテナです。DataWorks のビジネスプロセス は、REST API にバインドされます。

説明

REST API は、レガシ API Gateway の API グループ に相当します。

Cloud-native API Gateway コンソールの左側ナビゲーションウィンドウで、API をクリックします。上部ナビゲーションバーで正しいリージョンが選択されていることを確認してください。
Create API をクリックします。Create API ページで、REST API カードの Create をクリックします。
REST API の作成 パネルで、次のパラメーターを構成します。
- API Name： API コレクションの名前を入力します。名前は、現在のリージョン内でグローバルに一意である必要があります（例：dataservice-user-api）。
- Base Path： API のベースパスで、URL の一部となります。たとえば、このパラメーターを /v1 に設定できます。最終的なアクセスパスは protocol://domain/BasePath/APIPath になります。
- Version Management：必要に応じてこの機能を有効化します。

詳細については、「REST API の作成およびインターフェイスの追加」をご参照ください。

ステップ 2：API の作成と構成

このステップでは、DataWorks で API のロジックを定義し、データソースに接続してパラメーターを構成します。

1. ビジネスプロセスの作成

ビジネスプロセスは、関連する一連の API を整理し、API Gateway の REST API にバインドするために使用されます。

DataWorks コンソール に移動します。左側のナビゲーションウィンドウで、データサービス > サービス開発 を選択します。
新規アイコンをクリックし、Create Workflow を選択します。
Create Workflow ダイアログボックスで、次のパラメーターを構成します。
- Workflow Name：ワークスペース内で一意となるカスタム名を入力します（例：User Query Service）。名前は 4～50 文字である必要があります。
- Gateway Type： Cloud-native API Gateway を選択します。
- REST API：ドロップダウンリストから、ステップ 1 で作成した REST API（例：dataservice-user-api）を選択します。API が表示されない場合は、Refresh ボタンをクリックします。
  重要
  一度ビジネスプロセスを REST API にバインドすると、バインドを変更することはできません。慎重に REST API を選択してください。

2. ウィザードモードによる API の生成

サービス開発 ページで、新規アイコンにカーソルを合わせ、Create API > Generate API をクリックします。
Generate API ダイアログボックスで、Wizard Mode を選択し、API の基本情報を構成します。
- Location：前のステップで作成した Workflow（User Query Service）を選択します。
- API Name： API の名前を入力します（例：Query user by user ID）。
- APIPath： API の具体的なパス（例：/user/info）。これは Base Path と連結されて、完全な URL パスを形成します。API パスはスラッシュ（/）で始まり、200 文字を超えてはなりません。
- Request Method： GET または POST を選択します。GET メソッドを使用する場合、リクエストパラメーターはクエリ文字列内に配置する必要があります。
- Response Type： JSON を選択します。
作成をクリックして、GUI ベースの API 編集ページに移動します。
説明
スクリプトモードで API を作成する場合は、「スクリプトモードによる API の生成」をご参照ください。

3. API の構成

API 編集ページで、テーブルの選択 > パラメーターの選択 > パラメーターの構成 のワークフローに従って、API のコアロジックを定義します。

テーブルの選択（データソースおよびテーブル）
ページ左側の テーブルの選択 エリアで、次のパラメーターを構成します。
- Data Source Type： MaxCompute (ODPS) を選択します。
- Data Source Name：前提条件で構成したデータソースを選択します。
- Data Table Name： user_info テーブルを選択します。
- MaxCompute データソースを使用する場合は、パフォーマンスを向上させるために Acceleration Method を構成する必要があります。
パラメーターの選択（リクエストおよびレスポンス）
テーブルを選択すると、そのフィールドが パラメーターの選択 セクションに表示されます。
- リクエストパラメーターの構成： user_id フィールドのチェックボックスをオンにし、Set as Req Param チェックボックスをオンにします。
- レスポンスパラメーターの構成： user_id および user_name フィールドのチェックボックスをオンにし、Set as Resp Param チェックボックスをオンにします。
リクエストパラメーターの詳細構成 右側の Request Parameters タブで、user_id パラメーターの サンプル値 を指定します（例：10001）。これにより、以降のテストが簡素化されます。
ベストプラクティス：クエリパフォーマンスを最適化するために、インデックスフィールドをリクエストパラメーターに設定します。
サービスリソースグループおよび環境の構成
右側の サービスリソースグループ セクションで、次のパラメーターを構成します。
- リソースグループタイプ： 排他的データサービスリソースグループ を選択し、ドロップダウンリストから現在のワークスペースにバインドされているリソースグループを選択する必要があります。
- 環境構成：
  - タイムアウト： Cloud-native API Gateway が DataWorks からの応答を待機する最大時間（例：3 秒）。
  - Maximum Number of Data Records for a Single Request： 1 回の API 呼び出しで返されるレコードの最大数（例：2000 レコード）。

セキュリティ認証の構成

右側のセキュリティ認証セクションで設定を構成します。コンシューマー認証を有効化すると、次の 3 つの認証方式から選択できます。

説明

各ワークスペースについて、DataWorks は Cloud-native API Gateway にワークスペースと同じ名前のコンシューマーを自動的に作成します。手動でコンシューマーを作成する必要はありません。

方式	説明	ユースケース
API キー	クライアントが指定された方法でリクエストに認証情報を追加し、ゲートウェイがその有効性と権限を検証します。この方式は機密性の低い操作に適用され、JWT および AccessKey ペア認証よりもセキュリティが低くなります。認証情報は適切に管理・保護する必要があります。	軽量で迅速な統合および一般的なセキュリティ要件を持つシナリオに適しています。
JWT	JSON Web トークン（JWT）は、クライアントとサーバー間で情報を安全に送信するための標準です。HMAC、RSA、または ECDSA 署名を使用して、情報が検証可能かつ信頼できることを保証します。JWT 認証は、ゲートウェイで本人確認およびアクセスの制御を実装するために使用できます。	分散システムおよびシングルサインオン（SSO）シナリオに適しています。
HMAC	これは HMAC アルゴリズムを使用した AccessKey ペアベースの署名認証方式です。API を呼び出す際、クライアントは署名キーを使用してリクエスト内容の署名を計算し、サーバーに送信して検証を行います。	データ整合性が高く、データ改ざんに対する保護が必要なシナリオに適しています。

API の保存：すべてのパラメーターを構成したら、上部ツールバーの保存アイコンをクリックします。

ステップ 3：API のテスト、コミット、および公開

1. API のテスト

コミットする前に、API のテストを成功させる必要があります。

API 編集ページで、ツールバーの Test APIs ボタンをクリックします。
Test APIs ダイアログボックスで、user_id リクエストパラメーターに既存の値（例：10001）を入力し、Start Test をクリックします。
右側の Response Details を確認し、返されたデータが期待通りであることを確認します。Response Duration はパフォーマンスを示します。
テストが失敗した場合は、エラーメッセージに基づいてデータソース、テーブル、パラメーター、またはリソースグループの構成を確認します。

2. API のコミット

テストが成功したら、API をコミットして公開準備が整ったバージョンを生成します。

API 編集ページで、ツールバーの Submission ボタンをクリックします。
API をコミットすると、システムが自動的にバージョンを生成します。右側の Version Management タブでバージョンを確認できます。
ご利用のワークスペースに 承認プロセス が構成されている場合、API バージョンのステータスは To Be Requested になります。Request to Publish をクリックして承認依頼を提出する必要があります。申請が承認されると、ステータスは Can Be Published に変わります。
承認プロセスが構成されていない場合、バージョンステータスは通常 公開可能 になります。

3. API を Cloud-native API Gateway に公開

これは、API を本番環境にデプロイするための最終ステップです。

API 編集ページの右側にある Version タブで、ステータスが Can Be Published であるバージョンを見つけ、アクション列の Publish をクリックします。
Publish API to Cloud-native API Gateway ダイアログボックスで、次の必須パラメーターを構成します。
- ドメイン名： ステップ 1 で追加したドメイン名を選択します。
  重要
  同じ REST API 配下のすべての API は、同じドメイン名を共有します。公開時にドメイン名を変更すると、同じ REST API 配下のすべての API に影響します。
- Gateway Instance： ステップ 1 で作成したゲートウェイインスタンスを選択します。
- Backend Service：
  - ゲートウェイインスタンスの VPC が DataWorks リソースグループの VPC と同一の場合、デフォルト を選択します。
  - VPC が異なる場合、Cloud-native API Gateway で作成したバックエンドサービスを選択する必要があります。
    バックエンドサービスの作成
    ステップ 1 でゲートウェイインスタンスに選択した VPC がサーバーレスリソースグループの VPC と異なる場合のみ、このステップを実行してください。 VPC が同じ場合は、このセクションをスキップしてください。
    バックエンドサービスにより、異なる VPC 間で Data Service へのリクエストを送信できます。
    Cloud-native API Gateway コンソールの Instance リストで、対象インスタンスの ID をクリックします。
    インスタンス詳細ページの左側ナビゲーションウィンドウで、サービス を選択します。
    サービスの作成 をクリックします。プロンプトが表示された場合は、まず Source タブでソースを作成します。
    サービスの作成 時に、サービス名を構成し、作成済みのソースに関連付けます。
    詳細については、「サービスの作成」をご参照ください。

API を公開すると、API はアクティブになり、呼び出しアドレスを使用して呼び出せるようになります。

ステップ 4：API の呼び出しと検証

ステップ 2.3.5 で構成した認証方式に対応する認証情報を使用して API を呼び出します。

デプロイ済み API の Version タブで、直前に公開したバージョンを見つけ、右側の Service Management をクリックして API 管理ページに移動し、API の詳細を確認します。
API 管理で、API Name/Path の下のアドレスをクリックして、API の詳細を表示します。
API 呼び出しの構築と実行
- サンプル URL： API の詳細から呼び出し URL をコピーします。
- 認証情報： Service Management > Call APIs > Cloud-native API Gateway を選択して、呼び出し認証方式を確認します。
- 呼び出し方法： curl または他の HTTP クライアントを使用して、リクエストヘッダーに AppKey および AppSecret を含めて呼び出します。
  詳細については、「コンシューマーの管理」をご参照ください。
cURL 呼び出しの例：
API キー認証
```
# 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 認証
呼び出しプロセスの詳細については、「AccessKey ペア（HMAC）認証」をご参照ください。
```
# 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 を複数のゲートウェイインスタンスに公開したりできます。

複数のゲートウェイインスタンスへの公開

Version パネルで、Can Be Published ステータスのバージョンを見つけ、Publish をクリックします。Publish API to Cloud-native API Gateway ダイアログボックスで、別の Gateway Instance を選択します。この操作を繰り返して、同じ API を複数のゲートウェイインスタンスに公開できます。

説明

同じゲートウェイインスタンス内では、新しいバージョンを公開すると古いバージョンが自動的にオフラインになります。異なるゲートウェイインスタンス内のバージョンは互いに影響せず、同時に 公開済み ステータスになることができます。

サービス管理における複数バージョン

API を複数のゲートウェイインスタンスに公開すると、Service Management ページの表示が次のように変化します。

API 管理リスト

Service Management の Published APIs タブでは、同じ API ID に対して複数のレコードが表示されます。各レコードは公開されたゲートウェイインスタンスに対応しています。リストの Gateway Instance 列には、各レコードのゲートウェイインスタンスの名前と ID が表示されます。

API 詳細ページ

API 名をクリックして API 詳細ページに移動すると、ページ上部に Gateway Instance ドロップダウンリストが表示されます。このリストを使用してゲートウェイインスタンスを切り替えることで、異なるインスタンスにおける API の詳細（呼び出し URL、リクエストパラメーター、レスポンスパラメーターなど）を確認できます。

仕組み