Tablestore 只读操作

本 Skill 提供基于 CLI 的只读操作，用于查询阿里云 Tablestore（OTS）实例和数据表。Tablestore 是全托管 NoSQL 数据库服务，支持存储和访问大量结构化数据。

架构： Aliyun CLI (otsutil) → Tablestore 实例 → 数据表（宽表 / 时序表）

范围： 本 Skill 仅覆盖读/查询操作。不包含创建、更新或删除操作。

前置条件

预检查：需要 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 GUI 安装器

下载 Mac PKG 并双击安装。

macOS / Linux 二进制设置

下载（以 macOS Universal 为例）

curl -L -o aliyun-cli.tgz https://aliyuncli.alicdn.com/aliyun-cli-macosx-latest-universal.tgz

解压

tar -xzf aliyun-cli.tgz

移动到 PATH

sudo mv aliyun /usr/local/bin/

验证安装和版本（必须为 3.3.0+）

aliyun version

验证 otsutil 可用

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）是（实例操作）Region ID（例如 cn-hangzhou）-
-t（tableName）是（表操作）数据表名称-
注意： AccessKey 凭证通过 aliyun configure 配置，不作为命令参数传递。

认证

预检查：需要阿里云凭证
安全规则：
- 绝不回显或打印 AccessKey 值
- 绝不要求用户以明文直接输入 AccessKey
- 只能使用 aliyun configure 配置凭证
如果无有效凭证：
1. 从 阿里云控制台 获取 AccessKey
2. 为安全起见，使用具有 AliyunOTSReadOnlyAccess 权限的 RAM 用户凭证
3. 使用 Aliyun CLI 配置凭证

配置凭证（Aliyun CLI）

交互式配置（推荐）

aliyun configure

按提示操作：

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


### 使用特定 Profile 配置

创建命名 profile

aliyun configure --profile tablestore-user

为 otsutil 命令使用该 profile

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：配置实例（连接实例）

配置 endpoint 以选择要操作的实例。

重要： 执行任何表操作之前必须先配置实例。

命令格式：

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

Endpoint 格式：

  • 公网：https://&lt;instance_name&gt;.&lt;region_id&gt;.ots.aliyuncs.com
  • VPC：https://&lt;instance_name&gt;.&lt;region_id&gt;.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）配置实例 endpoint。

#### 任务 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否仅列出时序表名

示例：

列出当前类型的表

aliyun otsutil list

列出所有表

aliyun otsutil list -a

仅列出数据表

aliyun otsutil list -w

仅列出时序表

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 文件 |

**示例：**

描述当前选中的表

aliyun otsutil desc

描述特定表

aliyun otsutil desc -t mytable

以表格格式输出

aliyun otsutil desc -t mytable -f table

将表信息保存到文件

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 后：验证表 schema 和配置正确

相关 API

CLI 命令说明
aliyun otsutil config配置 CLI 访问（endpoint、实例）
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. 使用 Profile：使用 aliyun configure --profile &lt;name&gt; 为不同环境创建专用 profile
  7. 导出表 Schema：使用 aliyun otsutil desc -o &lt;file&gt; 导出和备份表定义

参考链接

参考说明
cli-installation-guide.mdAliyun CLI 安装指南
related-apis.md完整 CLI 命令参考
verification-method.md每个操作的验证步骤
ram-policies.mdRAM 权限要求
Aliyun CLI GitHubAliyun CLI 源代码和文档
Instance Operations Doc实例操作参考
Data Table Operations Doc数据表操作参考