Skill: sdk-team/alibabacloud-tablestore-ops (version 0.0.1)

--- name: alibabacloud-tablestore-ops description: | Alibaba Cloud Tablestore (OTS) Read-Only Operations Skill. Use for querying Tablestore instances and data tables via Aliyun CLI. Triggers: "tablestore", "ots", "表格存储", "list instance", "describe instance", "list table", "describe table", "aliyun otsutil" --- # Tablestore Read-Only Operations This skill provides CLI-based **read-only** operations for querying Alibaba Cloud Tablestore (OTS) instances and data tables. Tablestore is a fully managed NoSQL database service that supports storing and accessing large amounts of structured data. **Architecture:** `Aliyun CLI (otsutil) → Tablestore Instance → Data Tables (Wide Table / TimeSeries)` > **Scope:** This skill only covers read/query operations. No create, update, or delete operations are included. ## Prerequisites - Tablestore service must be activated. See [Alibaba Cloud Console](https://otsnext.console.aliyun.com/) - Obtain AccessKey ID and AccessKey Secret from [RAM Console](https://ram.console.aliyun.com/manage/ak) > **Pre-check: Aliyun CLI Required (Version 3.3.0+)** > > Tablestore operations are performed via `aliyun otsutil` command, which is part of the Aliyun CLI. > **IMPORTANT:** The `otsutil` subcommand is only available in Aliyun CLI version **3.3.0 or later**. > The Homebrew version may be outdated - download directly from the official CDN. > See [references/cli-installation-guide.md](references/cli-installation-guide.md) for installation instructions. ## Installation ### Install Aliyun CLI (Version 3.3.0+) > **WARNING:** The Homebrew version (`brew install aliyun-cli`) may not include `otsutil`. > Always download from the official CDN to ensure you get version 3.3.0+ with otsutil support. **Option 1: Download Binary (Recommended)** | Platform | Download | |----------|----------| | Mac (Universal) | [Mac Universal](https://aliyuncli.alicdn.com/aliyun-cli-macosx-latest-universal.tgz) | | Linux (AMD64) | [Linux AMD64](https://aliyuncli.alicdn.com/aliyun-cli-linux-latest-amd64.tgz) | | Linux (ARM64) | [Linux ARM64](https://aliyuncli.alicdn.com/aliyun-cli-linux-latest-arm64.tgz) | | Windows (64-bit) | [Windows](https://aliyuncli.alicdn.com/aliyun-cli-windows-latest-amd64.zip) | **Option 2: Mac GUI Installer** Download [Mac PKG](https://aliyuncli.alicdn.com/aliyun-cli-latest.pkg) and double-click to install. ### macOS / Linux Binary Setup ```bash # 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 Setup 1. Download the zip file from the download link above 2. Extract the zip file to get `aliyun.exe` 3. Add the directory to your PATH environment variable 4. Verify: `aliyun version` (must show 3.3.0 or later) ## Parameter Confirmation > **IMPORTANT: Parameter Confirmation** — Before executing any command, > ALL user-customizable parameters (e.g., RegionId, instance names, AccessKey, endpoint, etc.) > MUST be confirmed with the user. Do NOT assume or use default values without explicit user approval. | Parameter | Required | Description | Default | |-----------|----------|-------------|---------| | `--endpoint` | Yes (for table ops) | Instance endpoint URL | - | | `--instance` | Yes (for table ops) | Instance name | - | | `-n` (instanceName) | Yes (for describe_instance) | Instance name | - | | `-r` (regionId) | Yes (for instance ops) | Region ID (e.g., cn-hangzhou) | - | | `-t` (tableName) | Yes (for table ops) | Data table name | - | > **Note:** AccessKey credentials are configured via `aliyun configure`, not passed as command parameters. ## Authentication > **Pre-check: Alibaba Cloud Credentials Required** > > **Security Rules:** > - **NEVER** echo or print AccessKey values > - **NEVER** ask the user to input AccessKey directly in plain text > - **ONLY** configure credentials using `aliyun configure` > > **If no valid credentials exist:** > 1. Obtain AccessKey from [Alibaba Cloud Console](https://ram.console.aliyun.com/manage/ak) > 2. For security, use RAM user credentials with `AliyunOTSReadOnlyAccess` permission > 3. Configure credentials using Aliyun CLI ### Configure Credentials (Aliyun CLI) ```bash # 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 ``` ### Configure with Specific Profile ```bash # 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 ``` ### Supported Authentication Modes | Mode | Description | Configure Command | |------|-------------|-------------------| | AK | AccessKey ID/Secret (default) | `aliyun configure --mode AK` | | RamRoleArn | RAM role assumption | `aliyun configure --mode RamRoleArn` | | EcsRamRole | ECS instance role | `aliyun configure --mode EcsRamRole` | | OIDC | OIDC role assumption | `aliyun configure --mode OIDC` | ## RAM Policy Required permissions for Tablestore read-only operations: ```json { "Version": "1", "Statement": [ { "Effect": "Allow", "Action": [ "ots:GetInstance", "ots:ListInstance", "ots:ListTable", "ots:DescribeTable" ], "Resource": "acs:ots:*:*:instance/*" } ] } ``` Or use the managed policy: `AliyunOTSReadOnlyAccess` See [references/ram-policies.md](references/ram-policies.md) for detailed permissions. ## Core Workflow ### Part 1: Instance Read Operations #### Task 1: Configure Instance (Connect to Instance) Configure the endpoint to select which instance to operate on. > **Important:** You must configure the instance before performing any table operations. **Command Format:** ```bash aliyun otsutil config --endpoint <endpoint> --instance <instanceName> ``` **Endpoint Format:** - Public: `https://<instance_name>.<region_id>.ots.aliyuncs.com` - VPC: `https://<instance_name>.<region_id>.vpc.tablestore.aliyuncs.com` **Example:** ```bash aliyun otsutil config --endpoint https://myinstance.cn-hangzhou.ots.aliyuncs.com --instance myinstance ``` **Response:** ```json { "Endpoint": "https://myinstance.cn-hangzhou.ots.aliyuncs.com", "AccessKeyId": "NTS**********************", "AccessKeySecret": "7NR2****************************************", "AccessKeySecretToken": "", "Instance": "myinstance" } ``` #### Task 2: Describe Instance View instance details including name, creation time, status, and quota. **Command Format:** ```bash aliyun otsutil describe_instance -r <regionId> -n <instanceName> ``` **Example:** ```bash aliyun otsutil describe_instance -r cn-hangzhou -n myinstance ``` **Response:** ```json { "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 } ``` **Status Values:** `1` = Running. Other values indicate abnormal status. #### Task 3: List Instances Get all instances in a specified region. **Command Format:** ```bash aliyun otsutil list_instance -r <regionId> ``` **Example:** ```bash aliyun otsutil list_instance -r cn-hangzhou ``` **Response:** ```json ["myinstance", "another-instance"] ``` > **Note:** Returns empty array `[]` if no instances exist in the region. --- ### Part 2: Data Table Read Operations > **Prerequisite:** You must first configure an instance endpoint using `aliyun otsutil config` (Task 1) before running table operations. #### Task 4: Select Table (`use`) Select a data table for subsequent operations. **Command Format:** ```bash aliyun otsutil use --wc -t <tableName> ``` | Parameter | Required | Description | |-----------|----------|-------------| | `--wc` | No | Indicates the target is a data table (wide column) or index table | | `-t, --table` | Yes | Table name | **Example:** ```bash aliyun otsutil use -t mytable ``` #### Task 5: List Tables (`list`) List table names under the current instance. **Command Format:** ```bash aliyun otsutil list [options] ``` | Parameter | Required | Description | |-----------|----------|-------------| | `-a, --all` | No | List all table names (data tables + timeseries tables) | | `-d, --detail` | No | List tables with detailed information | | `-w, --wc` | No | List only data table (wide column) names | | `-t, --ts` | No | List only timeseries table names | **Examples:** ```bash # 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 ``` #### Task 6: Describe Table (`desc`) View detailed table information including primary keys, TTL, max versions, and throughput. **Command Format:** ```bash aliyun otsutil desc [-t <tableName>] [-f <format>] [-o <outputPath>] ``` | Parameter | Required | Description | |-----------|----------|-------------| | `-t, --table` | No | Table name. If omitted, describes the currently selected table (via `use`) | | `-f, --print_format` | No | Output format: `json` (default) or `table` | | `-o, --output` | No | Save output to a local JSON file | **Examples:** ```bash # 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 ``` **Example Response:** ```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 } } ``` **Response Fields:** | Field | Description | |-------|-------------| | `Name` | Table name | | `Meta.Pk` | Primary key columns: `C`=name, `T`=type (`string`/`integer`/`binary`), `Opt`=option (`none`/`auto`) | | `Option.TTL` | Data time-to-live in seconds (`-1` = never expire) | | `Option.Version` | Max attribute column versions retained | | `CU.Read` / `CU.Write` | Reserved read/write capacity units | ## Success Verification See [references/verification-method.md](references/verification-method.md) for detailed verification steps. **Quick Verification:** 1. After `aliyun otsutil config`: Response should show correct Endpoint and Instance 2. After `aliyun otsutil list_instance`: Verify expected instance names appear in the list 3. After `aliyun otsutil describe_instance`: Verify Status=1 (Running) 4. After `aliyun otsutil list`: Verify expected table names appear 5. After `aliyun otsutil desc`: Verify table schema and configuration are correct ## Related APIs | CLI Command | Description | |-------------|-------------| | `aliyun otsutil config` | Configure CLI access (endpoint, instance) | | `aliyun otsutil describe_instance` | Get instance details | | `aliyun otsutil list_instance` | List all instances in a region | | `aliyun otsutil use` | Select a data table for subsequent operations | | `aliyun otsutil list` | List tables under the current instance | | `aliyun otsutil desc` | View detailed table information | See [references/related-apis.md](references/related-apis.md) for complete API reference. ## Best Practices 1. **Use RAM Users**: Create RAM users with read-only permissions instead of using root account credentials 2. **Use ReadOnly Policy**: Apply `AliyunOTSReadOnlyAccess` for query-only workflows 3. **Region Selection**: Choose the region closest to your application for lower latency 4. **Network Type**: Use VPC endpoint for better security in production environments 5. **Credential Security**: Use `aliyun configure` for credential management; never hardcode credentials 6. **Use Profiles**: Create dedicated profiles for different environments using `aliyun configure --profile <name>` 7. **Export Table Schema**: Use `aliyun otsutil desc -o <file>` to export and backup table definitions ## Reference Links | Reference | Description | |-----------|-------------| | [cli-installation-guide.md](references/cli-installation-guide.md) | Aliyun CLI installation guide | | [related-apis.md](references/related-apis.md) | Complete CLI command reference | | [verification-method.md](references/verification-method.md) | Verification steps for each operation | | [ram-policies.md](references/ram-policies.md) | RAM permission requirements | | [Aliyun CLI GitHub](https://github.com/aliyun/aliyun-cli) | Aliyun CLI source code and documentation | | [Instance Operations Doc](https://help.aliyun.com/zh/tablestore/developer-reference/instance-operations) | Instance operations reference | | [Data Table Operations Doc](https://help.aliyun.com/zh/tablestore/developer-reference/widecolumn-modeled-data-table-operations-with-tablestore-cli) | Data table operations reference |


Security scan verdicts — ClawScan: suspicious | static analysis: clean | VirusTotal: clean | SkillSpector: suspicious (HIGH)