alibabacloud-tablestore-ops

Tablestore の読み取り専用操作

このスキルでは、Alibaba Cloud Tablestore（OTS）のインスタンスとデータテーブルを照会する、CLI ベースの読み取り専用操作を提供します。Tablestore は、大量の構造化データの保存とアクセスに対応する、フルマネージド型の NoSQL データベースサービスです。

アーキテクチャ： Aliyun CLI (otsutil) → Tablestore Instance → Data Tables (Wide Table / TimeSeries)

対象範囲： このスキルでは、読み取り／クエリ操作のみを扱います。作成、更新、削除の操作は含まれません。

前提条件

• Tablestore サービスを有効化する必要があります。Alibaba Cloud Consoleを参照してください
• RAM Consoleから AccessKey ID と AccessKey Secret を取得してください

事前確認：Aliyun CLI が必要です（バージョン 3.3.0 以降）

Tablestore の操作は、Aliyun CLI に含まれる aliyun otsutil コマンドを使って実行します。 重要： otsutil サブコマンドは、Aliyun CLI のバージョン 3.3.0 以降でのみ使用できます。 Homebrew 版は古い場合があるため、公式 CDN から直接ダウンロードしてください。 インストール手順については、references/cli-installation-guide.mdを参照してください。

インストール

Aliyun CLI のインストール（バージョン 3.3.0 以降）

警告： Homebrew 版（brew install aliyun-cli）には otsutil が含まれていない場合があります。 otsutil に対応したバージョン 3.3.0 以降を確実に入手するため、必ず公式 CDN からダウンロードしてください。

オプション 1：バイナリをダウンロード（推奨）

プラットフォーム	ダウンロード
Mac（ユニバーサル）	Mac Universal
Linux（AMD64）	Linux AMD64
Linux（ARM64）	Linux ARM64
Windows（64 ビット）	Windows

オプション 2：Mac GUI インストーラー

Mac PKGをダウンロードし、ダブルクリックしてインストールしてください。

macOS／Linux のバイナリ設定

# Download (example for macOS Universal)
curl -L -o aliyun-cli.tgz https://aliyuncli.alicdn.com/aliyun-cli-macosx-latest-universal.tgz

# Extract
tar -xzf aliyun-cli.tgz

# Move to PATH
sudo mv aliyun /usr/local/bin/

# Verify installation and version (must be 3.3.0+)
aliyun version

# Verify otsutil is available
aliyun otsutil help

Windows の設定

1. 上記のダウンロードリンクから zip ファイルをダウンロードします
2. zip ファイルを展開して aliyun.exe を取り出します
3. ディレクトリを PATH 環境変数に追加します
4. aliyun version で確認します（3.3.0 以降と表示される必要があります）

パラメーターの確認

重要：パラメーターの確認 — コマンドを実行する前に、 ユーザーが設定可能なすべてのパラメーター（RegionId、インスタンス名、AccessKey、エンドポイントなど）を 必ずユーザーに確認してください。ユーザーの明示的な承認なしに値を推測したり、デフォルト値を使用したりしないでください。

パラメーター	必須	説明	デフォルト
--endpoint	はい（テーブル操作の場合）	インスタンスのエンドポイント URL	-
--instance	はい（テーブル操作の場合）	インスタンス名	-
-n（instanceName）	はい（describe_instance の場合）	インスタンス名	-
-r（regionId）	はい（インスタンス操作の場合）	リージョン ID（例：cn-hangzhou）	-
-t（tableName）	はい（テーブル操作の場合）	データテーブル名	-

注： AccessKey 認証情報は aliyun configure で設定します。コマンドのパラメーターとして渡すことはありません。

認証

事前確認：Alibaba Cloud の認証情報が必要です

セキュリティルール：

• AccessKey の値を表示または出力することは絶対にしないでください
• ユーザーに AccessKey をプレーンテキストで直接入力するよう求めることは絶対にしないでください
• 認証情報の設定には aliyun configure のみを使用してください

有効な認証情報がない場合：

1. Alibaba Cloud Consoleから AccessKey を取得します
2. セキュリティのため、AliyunOTSReadOnlyAccess 権限を持つ RAM ユーザーの認証情報を使用します
3. Aliyun CLI を使って認証情報を設定します

認証情報の設定（Aliyun CLI）

# Interactive configuration (recommended)
aliyun configure

# Follow prompts:
# Aliyun Access Key ID [None]: <YOUR_ACCESS_KEY_ID>
# Aliyun Access Key Secret [None]: <YOUR_ACCESS_KEY_SECRET>
# Default Region Id [None]: cn-hangzhou
# Default output format [json]: json
# Default Language [zh]: en

特定のプロファイルで設定

# Create a named profile
aliyun configure --profile tablestore-user

# Use the profile for otsutil commands
aliyun otsutil --profile tablestore-user list_instance -r cn-hangzhou

サポートされている認証モード

モード	説明	設定コマンド
AK	AccessKey ID/Secret（デフォルト）	aliyun configure --mode AK
RamRoleArn	RAM ロールの引き受け	aliyun configure --mode RamRoleArn
EcsRamRole	ECS インスタンスロール	aliyun configure --mode EcsRamRole
OIDC	OIDC ロールの引き受け	aliyun configure --mode OIDC

RAM ポリシー

Tablestore の読み取り専用操作に必要な権限：

{
  "Version": "1",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "ots:GetInstance",
        "ots:ListInstance",
        "ots:ListTable",
        "ots:DescribeTable"
      ],
      "Resource": "acs:ots:*:*:instance/*"
    }
  ]
}

または、管理ポリシー AliyunOTSReadOnlyAccess を使用してください。

詳細な権限については、references/ram-policies.md を参照してください。

コアワークフロー

パート 1：インスタンスの読み取り操作

タスク 1：インスタンスの設定（インスタンスへの接続）

操作対象のインスタンスを選択するため、エンドポイントを設定します。

重要： テーブル操作を行う前に、インスタンスを設定する必要があります。

コマンド形式：

aliyun otsutil config --endpoint <endpoint> --instance <instanceName>

エンドポイント形式：

• パブリック：https://<instance_name>.<region_id>.ots.aliyuncs.com
• VPC：https://<instance_name>.<region_id>.vpc.tablestore.aliyuncs.com

例：

aliyun otsutil config --endpoint https://myinstance.cn-hangzhou.ots.aliyuncs.com --instance myinstance

応答：

{
  "Endpoint": "https://myinstance.cn-hangzhou.ots.aliyuncs.com",
  "AccessKeyId": "NTS**********************",
  "AccessKeySecret": "7NR2****************************************",
  "AccessKeySecretToken": "",
  "Instance": "myinstance"
}

タスク 2：インスタンスの詳細表示

名前、作成時刻、ステータス、クォータなど、インスタンスの詳細を確認します。

コマンド形式：

aliyun otsutil describe_instance -r <regionId> -n <instanceName>

例：

aliyun otsutil describe_instance -r cn-hangzhou -n myinstance

応答：

{
  "ClusterType": "ssd",
  "CreateTime": "2024-07-18 09:15:10",
  "Description": "First instance created by CLI.",
  "InstanceName": "myinstance",
  "Network": "NORMAL",
  "Quota": { "EntityQuota": 64 },
  "ReadCapacity": 5000,
  "Status": 1,
  "TagInfos": {},
  "UserId": "1379************",
  "WriteCapacity": 5000
}

ステータス値： 1 = 実行中。それ以外の値は異常なステータスを示します。

タスク 3：インスタンスの一覧表示

指定したリージョン内のすべてのインスタンスを取得します。

コマンド形式：

aliyun otsutil list_instance -r <regionId>

例：

aliyun otsutil list_instance -r cn-hangzhou

応答：

["myinstance", "another-instance"]

注： リージョン内にインスタンスがない場合は、空の配列 [] が返されます。

---

パート 2：データテーブルの読み取り操作

前提条件： テーブル操作を実行する前に、aliyun otsutil config（タスク 1）を使用してインスタンスのエンドポイントを設定する必要があります。

タスク 4：テーブルの選択（use）

以降の操作で使用するデータテーブルを選択します。

コマンド形式：

aliyun otsutil use --wc -t <tableName>

パラメーター	必須	説明
--wc	いいえ	対象がデータテーブル（ワイドカラム）またはインデックステーブルであることを示します
-t, --table	はい	テーブル名

例：

aliyun otsutil use -t mytable

タスク 5：テーブルの一覧表示（list）

現在のインスタンス内にあるテーブル名を一覧表示します。

コマンド形式：

aliyun otsutil list [options]

パラメーター	必須	説明
-a, --all	いいえ	すべてのテーブル名を一覧表示します（データテーブル + 時系列テーブル）
-d, --detail	いいえ	詳細情報とともにテーブルを一覧表示します
-w, --wc	いいえ	データテーブル（ワイドカラム）の名前のみを一覧表示します
-t, --ts	いいえ	時系列テーブルの名前のみを一覧表示します

例：

# List tables of the current type
aliyun otsutil list

# List all tables
aliyun otsutil list -a

# List only data tables
aliyun otsutil list -w

# List only timeseries tables
aliyun otsutil list -t

タスク 6：テーブルの詳細表示（desc）

主キー、TTL、最大バージョン数、スループットなど、テーブルの詳細情報を確認します。

コマンド形式：

aliyun otsutil desc [-t <tableName>] [-f <format>] [-o <outputPath>]

パラメーター	必須	説明
-t, --table	いいえ	テーブル名。省略すると、現在選択されているテーブル（use で選択）を表示します
-f, --print_format	いいえ	出力形式：json（デフォルト）または table
-o, --output	いいえ	出力をローカルの JSON ファイルに保存します

例：

# Describe the currently selected table
aliyun otsutil desc

# Describe a specific table
aliyun otsutil desc -t mytable

# Output in table format
aliyun otsutil desc -t mytable -f table

# Save table info to file
aliyun otsutil desc -t mytable -o /tmp/table_meta.json

応答例：

{
  "Name": "mytable",
  "Meta": {
    "Pk": [
      { "C": "uid", "T": "string", "Opt": "none" },
      { "C": "pid", "T": "integer", "Opt": "none" }
    ]
  },
  "Option": {
    "TTL": -1,
    "Version": 1
  },
  "CU": {
    "Read": 0,
    "Write": 0
  }
}

応答フィールド：

フィールド	説明
Name	テーブル名
Meta.Pk	主キー列：C=名前、T=型（string／integer／binary）、Opt=オプション（none／auto）
Option.TTL	データの有効期間（秒）（-1 = 期限切れにならない）
Option.Version	保持する属性列の最大バージョン数
CU.Read / CU.Write	予約済みの読み取り／書き込み容量ユニット

成功の確認

詳しい確認手順については、references/verification-method.md を参照してください。

簡易確認：

1. aliyun otsutil config の実行後：レスポンスに正しい Endpoint と Instance が表示されることを確認します
2. aliyun otsutil list_instance の実行後：一覧に想定されるインスタンス名が表示されることを確認します
3. aliyun otsutil describe_instance の実行後：Status=1（Running）であることを確認します
4. aliyun otsutil list の実行後：想定されるテーブル名が表示されることを確認します
5. aliyun otsutil desc の実行後：テーブルのスキーマと設定が正しいことを確認します

関連 API

CLI コマンド	説明
aliyun otsutil config	CLI アクセス（エンドポイント、インスタンス）を設定します
aliyun otsutil describe_instance	インスタンスの詳細を取得します
aliyun otsutil list_instance	リージョン内のすべてのインスタンスを一覧表示します
aliyun otsutil use	以降の操作で使用するデータテーブルを選択します
aliyun otsutil list	現在のインスタンスにあるテーブルを一覧表示します
aliyun otsutil desc	テーブルの詳細情報を表示します

API リファレンス全体については、references/related-apis.md を参照してください。

ベストプラクティス

1. RAM ユーザーを使用する：root アカウントの認証情報を使わず、読み取り専用権限を持つ RAM ユーザーを作成します
2. ReadOnly ポリシーを使用する：クエリ専用のワークフローには AliyunOTSReadOnlyAccess を適用します
3. リージョンの選択：レイテンシーを低減するため、アプリケーションに最も近いリージョンを選択します
4. ネットワークタイプ：本番環境でセキュリティを強化するには、VPC エンドポイントを使用します
5. 認証情報のセキュリティ：認証情報の管理には aliyun configure を使用し、認証情報をハードコードしないでください
6. プロファイルを使用する：aliyun configure --profile <name> を使用して、環境ごとに専用のプロファイルを作成します
7. テーブルスキーマをエクスポートする：aliyun otsutil desc -o <file> を使用して、テーブル定義をエクスポートし、バックアップします

参考リンク

参考資料	説明
cli-installation-guide.md	Aliyun CLI のインストールガイド
related-apis.md	CLI コマンドのリファレンス全体
verification-method.md	各操作の確認手順
ram-policies.md	RAM 権限の要件
Aliyun CLI GitHub	Aliyun CLI のソースコードとドキュメント
インスタンス操作ドキュメント	インスタンス操作のリファレンス
データテーブル操作ドキュメント	データテーブル操作のリファレンス