DataWorks:API の呼び出し

前提条件

DataService Studio API を呼び出す前に、次の 3 つの前提条件を満たす必要があります：

これら 3 つの要素の関係は、次のように考えることができます：API は「ドア」、アプリは「ID カード」、承認は「通行証」です。有効な ID カードと対応する通行証の両方を提示した場合にのみ、ドアを通過できます。

アプリの作成 (アプリアイデンティティ)

アプリは、API を呼び出すために使用する認証情報を格納するコンテナとして機能します。各アプリは、アカウントとパスワードに相当する独立した認証情報 (AppKey、AppSecret、AppCode) を持ちます。

自動作成されるデフォルトアプリ

DataWorks で初めて API を公開すると、システムは API Gateway にワークスペースと同じ名前のアプリを自動的に作成します。その後、そのワークスペース内のすべての API は、このデフォルトアプリに対して自動的に承認されます。つまり、次のようになります：

• 同じワークスペース内のメンバーは、デフォルトアプリの認証情報を直接使用して、そのワークスペース内の API を呼び出せます。

• デフォルトアプリの認証情報は、DataService Studio コンソールの Call APIs ページで確認できます。

アプリの手動作成

トラフィックを分離する必要がある場合や、呼び出し元ごとに権限を分ける必要がある場合は、API Gateway コンソールで新しいアプリを手動で作成できます：

1. API Gateway コンソールにログインします。

2. ナビゲーションペインで、Application Management を選択します。

3. [アプリの作成] をクリックし、アプリの名前と説明を入力します。

4. アプリの作成後、システムが AppKey、AppSecret、AppCode を生成します。

認可プロセス

認可は、特定の API を呼び出す権限をアプリに付与するプロセスです。認可されたアプリのみが、その認証情報を使用して API を正常に呼び出すことができます。

他のアカウントへの認可

他の Alibaba Cloud アカウント配下のワークスペースで API を利用できるようにする必要がある場合は、クロスアカウント認可を行う必要があります：

1. DataWorks コンソールにログインします。 左側のナビゲーションウィンドウで、[DataService Studio] をクリックします。 表示されるページで、ドロップダウンリストから目的のワークスペースを選択し、[DataService Studioに移動] をクリックします。

2. データサービス ページで、トップメニューバーの Service Management をクリックして Manage APIs ページを開きます。

3. Published APIs タブで、目的の API を探し、[操作] 列の 承認 をクリックします。

4. [API 認可] ダイアログボックスで、次のパラメーターを設定します:

   

   パラメータ	説明
   [API Name]	認可対象の API の名前です。このパラメータは変更できません。
   [認可する Alibaba Cloud アカウント ID]	この API を呼び出す権限を必要とする Alibaba Cloud アカウントの ID です。 ページでアカウント ID を確認できます。
   [Authorized Workspace]	ターゲット Alibaba Cloud アカウント配下のワークスペースの名前を選択します。
   [Authorization Validity Period]	認可の有効期間を選択します (次のセクションで説明します)。

5. Confirmをクリックして、承認を完了します。

認可の有効期間

認可の有効期間は、認可された側が API を呼び出すことができる期間を決定します：

認可ステータスの表示

Manage APIs ページでは、2 つの視点から認可ステータスを確認できます:

呼び出しを認可された API の表示

Authorized to Use タブをクリックすると、他のアカウントから呼び出しが承認されているすべての API の一覧が表示されます。このページでは、次の操作を実行できます。

• 承認された API をオンラインでテストするには、テスト をクリックします。詳細については、「API をテストする」をご参照ください。

• Delete をクリックして、API 呼び出しの承認を自主的に取り消します。

他者に認可した API の表示

Authorize Others to Use タブをクリックすると、他のワークスペースに対して権限を付与した API の一覧が表示されます。このページでは、次の操作を実行できます。

• テスト をクリックして、承認済みの API をオンラインでテストします。

• 特定のワークスペースの権限付与をキャンセルまたは変更するには、Manage をクリックします。

3つの認可シナリオ

API の認可の粒度は、チームの規模とセキュリティ管理の要件によって異なります。次の 3 つのシナリオでは、最も一般的な認可戦略について説明します。

シナリオ1：1つのワークスペース、1つの共有アプリ

シナリオの説明：単一の DataWorks ワークスペースのすべてのメンバーが、同じデフォルト アプリを使用して API を呼び出します。

使用するケース：メンバー間の信頼関係が高い小規模なチーム。異なるメンバーからのトラフィック ソースを区別する必要がない場合。最小限の設定で迅速に開始したい場合。

仕組み：API が公開されると、DataWorks はワークスペースと同じ名前のアプリを自動的に作成し、そのワークスペース内のすべての API に対する認可をそのアプリに付与します。ワークスペースのすべてのメンバーは、この一連の AppKey、AppSecret、および AppCode を共有します。

長所：設定が不要で、すぐに使用できます。 短所：個々のメンバーによる呼び出しを追跡できず、認証情報が漏えいした場合、ワークスペース全体に影響が及びます。

シナリオ2：RAM ユーザーごとに1つのアプリ

シナリオの説明：企業内の各 RAM ユーザー (サブアカウント) は、API Gateway で個別のアプリを作成し、API を呼び出すための個別の認可を受けます。

使用するケース：各ユーザーの API 呼び出しアクティビティを正確に追跡する必要がある場合。異なるユーザーに異なるスロットリング ポリシーを適用する必要がある場合。「1人に1つの認証情報」を義務付ける高いセキュリティおよびコンプライアンス要件を満たす必要がある場合。

仕組み：各 RAM ユーザーは API Gateway コンソールにログインして、自身のアプリを作成します。API 管理者は、各ユーザーのアプリに認可を付与します。その後、各ユーザーは自身のアプリの認証情報を使用して API を呼び出します。

長所：呼び出しアクティビティは個々のユーザーまで追跡可能であり、強力なセキュリティ分離を提供します。認証情報が漏えいした場合の影響は最小限です。 短所：新しいユーザーごとにアプリの作成と認可の設定が必要になるため、管理オーバーヘッドが高くなります。

シナリオ3：ユーザーグループごとに1つのアプリ

シナリオの説明：複数の RAM ユーザーを業務機能やチームに基づいてグループに分け、各グループのメンバーが単一のアプリを共有して API を呼び出します。

使用するケース：部門やプロジェクトごとに組織された大規模なチーム。異なるビジネス ラインからのトラフィックを区別する必要はあるが、個人からのトラフィックを区別する必要はない場合。管理コストとセキュリティのバランスを取りたい場合。

仕組み：ビジネスグループごとにアプリが作成されます。API 管理者は、各グループのアプリに API 認可を付与します。グループ内のメンバーは、そのグループのアプリの認証情報を共有します。

長所：適度なレベルの管理粒度を提供し、過剰な管理オーバーヘッドなしでビジネス レベルの区別を可能にします。 短所：同じグループ内のメンバー間で、それ以上の区別はできません。

シナリオの比較

認証情報の種類の区別

DataService Studio では、3 つの異なるタイプの認証情報を使用します。混乱を避けるため、それぞれの目的、取得元、ユースケースの違いを理解することが重要です。

簡潔に言うと： AccessKey はデータソース接続用、AppKey は API 呼び出し用、RAM はコンソールアクセス用です。それぞれ異なる目的を持ち、互換性はありません。

よくある誤解 1： 「API を呼び出すと 403 エラーが発生しますが、RAM 管理者権限を持っています。」 — RAM 権限は DataWorks コンソールへのアクセスを制御するものであり、API を呼び出す権限ではありません。API 呼び出し権限はアプリ認可によって制御されます。RAM 管理者であっても、API を呼び出すには認可されたアプリの AppKey と AppSecret が必要です。

よくある誤解 2： 「データソース設定の AccessKey と API 呼び出しの AppKey は同じですか?」 — いいえ。AccessKey は DataService Studio バックエンドがデータソースに接続するために使用し、AppKey は呼び出し元が API を呼び出すために使用します。この 2 つは完全に独立しています。

よくある誤解 3： 認可ページの「アカウント ID」には何を入力すればよいですか? — 認可ページには、Alibaba Cloud アカウント ID (数字の文字列) を入力する必要があります。RAM ユーザー名やログインメールアドレスではありません。アカウント ID を確認するには、アカウント管理ページにログインし、セキュリティ設定を確認してください。

認証方法

API Gateway は 2 つの認証方法をサポートしています。DataService Studio はワークスペース内の API に「Alibaba Cloud アプリ認証」を追加します。呼び出し元は、セキュリティ要件に基づいて特定の認証方法を選択できます。

簡易認証 (AppCode)

呼び出し元は、認証には AppCode を HTTP リクエストヘッダーに追加するだけです。署名計算は必要ありません。

リクエスト例：

GET /api/v1/users?name=test HTTP/1.1
Host: your-api-endpoint.cn-shanghai.alicloudapi.com
Authorization: APPCODE 3f963a8e1cd7492bbd8a5e2e5e4c****

署名認証 (AppKey + AppSecret)

呼び出し元は、AppSecret を使用してリクエストコンテンツの HMAC-SHA256 署名を計算し、AppKey と署名値をリクエストヘッダーに追加する必要があります。API Gateway はリクエストを受信すると、同じ AppSecret を使用して署名を再計算し、受信した署名と比較して呼び出し元を検証します。

リクエスト例 (ヘッダーのみ)：

X-Ca-Key: 12345678
X-Ca-Signature: BASE64_ENCODED_SIGNATURE
X-Ca-Timestamp: 1741593600000
X-Ca-Nonce: unique-uuid-string
X-Ca-Signature-Headers: X-Ca-Key,X-Ca-Nonce,X-Ca-Timestamp

認証方法の比較

署名アルゴリズム

署名認証は、HMAC-SHA256 アルゴリズムに基づいています。コアとなるプロセスは以下の通りです。

署名プロセス

1. 署名対象の文字列の構築：HTTP メソッド (例：GET または POST)、Accept ヘッダー、Content-MD5 (リクエストボディの MD5 値)、Content-Type、Date、署名対象のカスタムヘッダー (X-Ca-*、アルファベット順にソート)、および正規化された URL (パス + ソートされたクエリパラメーター) を連結します。

2. HMAC-SHA256 を使用した署名の計算：Signature = Base64 (HMAC-SHA256 (AppSecret, StringToSign))

3. リクエストヘッダーへの署名情報の追加：これには、X-Ca-Key (AppKey)、X-Ca-Signature (署名)、X-Ca-Timestamp (ミリ秒単位のタイムスタンプ)、X-Ca-Nonce (リプレイ攻撃を防ぐための UUID)、および X-Ca-Signature-Headers (署名に含まれるヘッダーのリスト) が含まれます。

主な考慮事項

署名アルゴリズムを実装する際には、よくあるエラーを避けるために、以下の点にご注意ください。

• パラメーターのソート：URL クエリパラメーターと署名に含まれるヘッダーは、キーのアルファベット順 (ASCII 順) にソートする必要があります。

• URL エンコーディング：スペースや非 ASCII 文字など、パラメーター値に含まれる特殊文字は URL エンコードする必要があります。

• 改行文字：署名対象の文字列の行を区切るには、改行文字 (\n, LF) を使用してください。キャリッジリターンとラインフィードの組み合わせ (\r\n, CRLF) は使用しないでください。

• 空の値の処理：リクエストにボディがない場合、Content-MD5 の値は (null ではなく) 空文字列になります。Accept などのヘッダーが存在しない場合も、同様に空文字列を使用してください。

• タイムスタンプの精度：X-Ca-Timestamp は、ミリ秒単位のタイムスタンプである必要があります。クライアントとサーバーの間の時刻差は 15 分を超えることはできません。

• ノンスの一意性：各リクエストに対して、一意の UUID を X-Ca-Nonce として生成する必要があります。ノンスを再利用すると、リプレイ攻撃防止メカニズムが作動します。

認証情報の確認

アプリを作成して権限を付与した後、API を呼び出すには AppKey、AppSecret、または AppCode を取得する必要があります。DataService Studio では、これらの認証情報を簡単に確認できます。

DataService Studio コンソールで認証情報を確認する

1. DataWorks コンソールにログインします。 左側のナビゲーションウィンドウで、[DataService Studio] をクリックします。 表示されるページで、ドロップダウンリストから目的のワークスペースを選択し、[DataService Studioに移動] をクリックします。

2. DataService Studio ページで、上部メニューの [Service Management] をクリックします。

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

4. [Call APIs] ページで、次の認証情報を確認してコピーできます： AppKey (アプリの一意の識別子)、 AppSecret (署名認証に使用します。機密として保持してください)、 AppCode (簡易認証に使用します)。

API Gateway コンソールで認証情報を確認する： API Gateway コンソールにログインし、App Management で対象のアプリを見つけて詳細ページを開くと、AppKey、AppSecret、AppCode を確認できます。

API Gateway SDK を使用した API の呼び出し

API Gateway は、API コールを迅速に統合できるよう、さまざまなプログラミング言語向けの SDK を提供しています。SDK には署名アルゴリズムの実装が組み込まれているため、署名を手動で計算する必要はありません。AppKey と AppSecret を提供するだけで済みます。詳細については、「API の呼び出し」ドキュメントおよび「SDK のダウンロードと使用方法」をご参照ください。

サポートされている SDK 言語

SDK を使用する利点

HTTP リクエストを手動で構築する場合と比較して、SDK を使用して API コールを行うと、次の利点があります。

• 自動署名：SDK は HMAC-SHA256 署名アルゴリズムを実装しているため、開発者は署名の詳細を処理する必要がありません。

• 自動リトライ：一部の SDK には、ネットワーク例外に対する組み込みのリトライメカニズムがあります。

• パラメーター検証：SDK は、リクエストを送信する前に基本的なパラメーターを検証します。

• パフォーマンス最適化：SDK は通常、コネクションプーリングや HTTP/2 などのテクノロジーを使用してネットワークパフォーマンスを最適化します。

クイック統合の例 (Java)

次の例は、API Gateway Java SDK を使用して API を呼び出す方法を示しています。

// 1. Maven 依存関係を追加
// <dependency>
//     <groupId>com.aliyun.api.gateway</groupId>
//     <artifactId>sdk-core-java</artifactId>
//     <version>LATEST_VERSION</version>
// </dependency>

// 2. クライアントを初期化
HttpClientBuilderParams params = new HttpClientBuilderParams();
params.setAppKey("your_app_key");
params.setAppSecret("your_app_secret");

ApacheHttpClient client = new ApacheHttpClient(params);

// 3. リクエストを構築
IoTApiRequest request = new IoTApiRequest();
request.setDomain("your-api-endpoint.cn-shanghai.alicloudapi.com");
request.setPath("/api/v1/query");
request.setHttpMethod("GET");
request.putQueryParam("pageSize", "10");
request.putQueryParam("pageNum", "1");

// 4. 呼び出しを実行
ApiResponse response = client.execute(request);
System.out.println("Response: " + response.getBody());

クイック統合の例 (Python)

# 1. SDK をインストール
# pip install aliyun-api-gateway-sdk

# 2. API を呼び出し
from com.alibaba.cloudapi.sdk.client import DefaultClient
from com.alibaba.cloudapi.sdk.model import HttpClientBuilderParams

params = HttpClientBuilderParams()
params.app_key = "your_app_key"
params.app_secret = "your_app_secret"
params.host = "your-api-endpoint.cn-shanghai.alicloudapi.com"

client = DefaultClient(params)
response = client.get(
    path="/api/v1/query",
    query_params={"pageSize": "10", "pageNum": "1"},
    headers={"Accept": "application/json"}
)

print(f"Status: {response.status_code}")
print(f"Body: {response.content}")

エンドツーエンドのワークフロー

エンドツーエンドのワークフローは、開発者が API を公開し、デフォルトアプリが自動的に作成され、認可されることで始まります。アカウント間で API を共有するには、所有者が手動で認可を付与する必要があります。その後、API 呼び出し元はアプリから認証情報 (AppKey、AppSecret、または AppCode) を取得し、認証方法を選択します。最後に、呼び出し元は SDK または直接の HTTP リクエストを使用して API を呼び出します。API Gateway がリクエストを検証し、DataService Studio がクエリを実行し、結果が呼び出し元に返ります。

関連トピック

• API を公開する： API Gateway に API を公開する方法を説明します。

• API を認可する：認可操作と、他者に認可した API の管理方法を説明します。

• API をテストする：サービス管理ページで公開済みまたは認可済みの API をテストします。