API キーまたはアクセスキーペアを使用して、Tablestore のナレッジストレージサービスおよびメモリストレージサービスにアクセスするアプリケーションを認証します。API キーはアクセスキーペアを管理する必要がなく、作成と無効化を個別に実行できるため、AI アプリケーションを迅速に統合する用途に適しています。このトピックでは、API キーの作成方法と使用方法について説明します。
認証方法の選択
アプリケーションがアクセスするリソースに基づいて認証方法を選択します。
| 認証方法 | シナリオ | サポート対象範囲 | 使用上の注意 |
| API キー | アプリケーションがナレッジストレージサービスとメモリストレージサービスの API のみを呼び出す場合 | ナレッジストレージサービスとメモリストレージサービスのすべての API | 統合が容易です。HTTPS が必須です。OSS またはその他の Tablestore API へのアクセスはサポートしていません。 |
| アクセスキーペア | アプリケーションが OSS またはその他の Tablestore の機能にもアクセスする必要がある場合、または RAM アクセスポリシーを使用してきめ細かなアクセス制御が必要な場合 | RAM アイデンティティに付与された権限によって決まります。 | 本番環境では、RAM ユーザーのアクセスキーペアまたは STS の一時的なアクセス認証情報を使用することを推奨します。Alibaba Cloud アカウントのアクセスキーペアは使用しないでください。 |
ナレッジストレージ API とメモリストレージ API のみを呼び出す場合は、API キーを使用することを推奨します。ローカルファイルを OSS にアップロードしてからナレッジベースにインポートする必要がある場合、またはその他の Tablestore API にアクセスする必要がある場合は、アクセスキーペアまたは STS の一時的なアクセス認証情報を使用してください。
アクセスキーペアの作成と承認、および RAM アクセスポリシーの設定方法については、「アクセス権限の設定」をご参照ください。
制限
API キーには次の制限があります。
サポート対象 API:API キーを使用してアクセスできるのは、ナレッジストレージサービスおよびメモリストレージサービスの API のみです。これには、両サービスの作成、クエリ、取得、削除 API を含みます。OSS またはその他の Tablestore API にアクセスするには、アクセスキーペアを使用してください。
HTTPS:API キーでナレッジストレージサービスおよびメモリストレージサービスにアクセスするには、HTTPS エンドポイントを使用する必要があります。
権限:API キーを作成すると、システムは専用 RAM ユーザーを自動的に作成し、
AliyunOTSFullAccessアクセスポリシーを RAM ユーザーにアタッチします。API キーの権限は RAM ユーザーの権限と同じです。権限チェック:API キーを使用してナレッジストレージサービスおよびメモリストレージサービスにアクセスする場合、システムは API 操作の権限と
ots:CallWithBearerToken権限の両方をチェックします。RAM ユーザーにいずれかの権限がない場合、リクエストは拒否されます。権限の調整:API キーの権限を調整するには、RAM コンソールに移動して、専用 RAM ユーザーのアクセスポリシーを変更します。
ots:CallWithBearerToken権限は維持してください。そうしない場合、API キーを使用するリクエストは拒否されます。
API キーの作成
Tablestore コンソールにログインします。
左側のナビゲーションペインで、[API Key] をクリックします。
[API Key] ページで、[Create API Key] をクリックします。
[Create API Key] ダイアログボックスで、[Expiration time] を設定します。
[Create] をクリックします。
API キーが作成されると、キーの値が表示されます。
キーの値は API キーの作成時に一度だけ表示され、再表示はできません。キーは安全に保管してください。
API キーの使用
SDK または curl で API キーを使用して、ナレッジストレージサービスおよびメモリストレージサービスにアクセスします。次の例では、your-api-key、your-instance.cn-beijing.ots.aliyuncs.com、your-instance-name をお客様自身の値に置き換えてください。
API キーを使用してサービスにアクセスする場合は、HTTPS エンドポイントを使用する必要があります。
Python
AgentStorage Python SDK をインストールします:pip install tablestore-agent-storage
from tablestore_agent_storage import AgentStorageClient
# API キーでクライアントを初期化
client = AgentStorageClient(
api_key="your-api-key",
ots_endpoint="https://your-instance.cn-beijing.ots.aliyuncs.com",
ots_instance_name="your-instance-name",
)
# ナレッジベースを作成
client.create_knowledge_base({"knowledgeBaseName": "product_docs"})
# 作成済みのナレッジベースを一覧表示
response = client.list_knowledge_base()
for kb in response["data"]["knowledgeBases"]:
print(kb["knowledgeBaseName"])
# ナレッジベースから取得
results = client.retrieve({
"knowledgeBaseName": "product_docs",
"retrievalQuery": {"type": "TEXT", "text": "your query"}
})
for item in results["data"]["retrievalResults"]:
print(item["content"])TypeScript
AgentStorage TypeScript SDK をインストールします:npm install @tablestore/agent-storage
import { AgentStorageClient } from '@tablestore/agent-storage';
// API キーでクライアントを初期化
const client = new AgentStorageClient({
apiKey: 'your-api-key',
endpoint: 'https://your-instance.cn-beijing.ots.aliyuncs.com',
instanceName: 'your-instance-name',
});
// ナレッジベースを作成
await client.createKnowledgeBase({ knowledgeBaseName: 'product_docs' });
// 作成済みのナレッジベースを一覧表示
const response = await client.listKnowledgeBase({});
for (const kb of response.data.knowledgeBases) {
console.log(kb.knowledgeBaseName);
}
// ナレッジベースから取得
const results = await client.retrieve({
knowledgeBaseName: 'product_docs',
retrievalQuery: { type: 'TEXT', text: 'your query' },
});
for (const item of results.data.retrievalResults) {
console.log(item.content);
}curl
HTTP リクエストを使用してサービスに直接アクセスするには、リクエストヘッダーに x-ots-apikey と x-ots-instancename フィールドを追加してください。
curl -X POST 'https://your-instance.cn-beijing.ots.aliyuncs.com/CreateKnowledgeBase' \
-H 'x-ots-instancename: your-instance-name' \
-H 'x-ots-apikey: your-api-key' \
-H 'Content-Type: application/json' \
-d '{"knowledgeBaseName": "product_docs"}'次の例は、curl を使用して作成済みのナレッジベースを一覧表示する方法を示しています。
curl -X POST 'https://your-instance.cn-beijing.ots.aliyuncs.com/ListKnowledgeBase' \
-H 'x-ots-instancename: your-instance-name' \
-H 'x-ots-apikey: your-api-key' \
-H 'Content-Type: application/json' \
-d '{}'