alibabacloud-tablestore-ops

Tablestore 只读操作

此技能提供基于 CLI 的 只读 操作，用于查询 Alibaba Cloud Tablestore 实例和数据表。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 otsutil 命令执行，该命令属于 Aliyun CLI。 重要： otsutil 子命令仅在 Aliyun CLI 3.3.0 或更高版本中提供。 Homebrew 版本可能已过时，请直接从官方 CDN 下载。 请参阅 references/cli-installation-guide.md 了解安装说明。

安装

安装 Aliyun CLI（版本 3.3.0+）

警告： Homebrew 版本（brew install aliyun-cli）可能不包含 otsutil。 请务必从官方 CDN 下载，以确保获取支持 otsutil 的 3.3.0+ 版本。

选项 1：下载二进制文件（推荐）

平台	下载
Mac（通用版）	Mac Universal
Linux（AMD64）	Linux AMD64
Linux（ARM64）	Linux ARM64
Windows（64 位）	Windows

选项 2：Mac 图形界面安装程序

下载 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 等）。 未经用户明确同意，不得假设或使用默认值。

参数	必填	说明	默认值
--endpoint	是（用于表操作）	实例 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（运行中）
4. 执行 aliyun otsutil list 后：确认出现预期的表名称
5. 执行 aliyun otsutil desc 后：确认表结构和配置正确

相关 API

CLI 命令	说明
aliyun otsutil config	配置 CLI 访问（endpoint、instance）
aliyun otsutil describe_instance	获取实例详情
aliyun otsutil list_instance	列出某个区域中的所有实例
aliyun otsutil use	选择数据表以供后续操作
aliyun otsutil list	列出当前实例下的表
aliyun otsutil desc	查看表的详细信息

完整 API 参考请参阅 references/related-apis.md。

最佳实践

1. 使用 RAM 用户：创建具有只读权限的 RAM 用户，而不是使用根账户凭据
2. 使用只读策略：为仅查询工作流应用 AliyunOTSReadOnlyAccess
3. 选择区域：选择离应用最近的区域以降低延迟
4. 网络类型：在生产环境中使用 VPC endpoint，以获得更好的安全性
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 源代码和文档
实例操作文档	实例操作参考
数据表操作文档	数据表操作参考