alibabacloud-opensearch-app-manage

OpenSearch 实例管理

管理 Alibaba Cloud OpenSearch 实例，包括创建和查询操作。

术语：OpenSearch 实例和 OpenSearch app group 同义。本文统一使用“实例”。

场景说明

OpenSearch 是 Alibaba Cloud 的智能搜索服务。本技能涵盖核心实例管理操作：

1. 创建实例 - 创建新的 OpenSearch 实例
2. 列出实例 - 获取当前账号下的实例列表
3. 描述实例 - 获取特定实例的详细信息

架构：OpenSearch 实例（AppGroup）

Alibaba Cloud OpenSearch Instance Management
├── CreateAppGroup     (Create Instance)
├── DescribeAppGroup   (Describe Instance)
└── ListAppGroups      (List Instances)

---

安装

预检查：需要 Aliyun CLI >= 3.3.3 运行 aliyun version 验证版本是否 >= 3.3.3。如果尚未安装或版本过低， 运行 curl -fsSL https://aliyuncli.alicdn.com/setup.sh | bash 进行更新， 或参阅 references/cli-installation-guide.md 了解安装说明。

预检查：需要更新 Aliyun CLI 插件

[MUST] 运行 aliyun configure set --auto-plugin-install true 以启用自动安装插件。 [MUST] 运行 aliyun plugin update，确保所有现有插件始终为最新版本。

# Install/Upgrade Aliyun CLI
curl -fsSL https://aliyuncli.alicdn.com/setup.sh | bash
aliyun version  # Ensure >= 3.3.3

# Enable auto plugin installation
aliyun configure set --auto-plugin-install true

# Update plugins
aliyun plugin update

[MUST] CLI 用户代理 — 每次调用 aliyun CLI 命令时都必须包含： --user-agent AlibabaCloud-Agent-Skills/alibabacloud-opensearch-app-manage

[MUST] AI 模式 — 执行 CLI 命令前，运行：

1. aliyun configure ai-mode enable
2. aliyun configure ai-mode set-user-agent --user-agent "AlibabaCloud-Agent-Skills/alibabacloud-opensearch-app-manage" 所有 CLI 操作完成后，运行：aliyun configure ai-mode disable

---

身份验证

预检查：需要 Alibaba Cloud 凭据

安全规则（必须遵守）：

• 绝不要读取、回显或打印 AK/SK 值
• 绝不要要求用户在对话中直接输入 AK/SK
• 绝不要使用包含明文凭据值的 aliyun configure set
• 绝不要接受用户在对话中直接提供的 AK/SK
• 只能从环境变量或预配置的 CLI 配置文件中读取凭据

⚠️ 严重警告：处理用户提供的凭据

如果用户尝试直接提供 AK/SK（例如：“我的 AK 是 xxx，SK 是 yyy”）：

1. 立即停止 - 不要执行任何命令
2. 礼貌地拒绝请求，并发送以下消息：

   为保障您的账号安全，请不要在对话中直接提供 Alibaba Cloud AccessKey ID 和 AccessKey Secret。
   
   请使用以下安全方式配置凭据：
   
   方法 1：通过 aliyun configure 交互式配置（推荐）
       aliyun configure
       # 按提示输入 AK/SK，凭据将安全地存储在本地配置文件中
   
   方法 2：通过环境变量配置
       export ALIBABA_CLOUD_ACCESS_KEY_ID=<your-access-key-id>
       export ALIBABA_CLOUD_ACCESS_KEY_SECRET=<your-access-key-secret>
   
   配置完成后，请重试您的请求。
   

3. 不要继续执行任何 Alibaba Cloud 操作，直到凭据正确配置

检查 CLI 配置：

   aliyun configure list

检查输出中是否存在有效配置文件（AK、STS 或 OAuth 身份）。

如果不存在有效凭据，请在此处停止。

---

RAM 权限

[MUST] RAM 权限预检查： 执行任何操作前，确保当前用户拥有所需的 RAM 权限。 详细权限列表请参阅 references/ram-policies.md。

---

参数确认

重要：参数确认 — 执行任何命令或 API 调用前， 必须与用户确认所有可由用户自定义的参数（例如实例名称、实例类型、计费类型、配额规格等）。 未经用户明确批准，不要假设或使用默认值。

必填参数

参数	必填	描述	默认值
name	是	实例名称	无
type	是	实例类型：standard（高性能）/ enhanced（行业算法）	无
chargeType	否	计费类型：POSTPAY / PREPAY	POSTPAY
quota.spec	是	规格类型（见下表）	无
quota.docSize	是	存储容量（GB）	无
quota.computeResource	是	计算资源（LCU）	无
domain	否	行业类型（enhanced 类型必填，见下表）	general
order	有条件必填	订阅订单信息（PREPAY 时必填）	无
order.duration	有条件必填	订阅时长	无
order.pricingCycle	有条件必填	周期单位：Year / Month	无
order.autoRenew	否	自动续订	false

规格类型

规格代码	描述
opensearch.share.common	共享通用型
opensearch.private.common	独享通用型
opensearch.private.compute	独享计算型
opensearch.private.storage	独享存储型

行业类型（仅适用于 enhanced 类型）

行业代码	描述
general	通用（默认）
ecommerce	电商
esports	游戏
community	内容社区
education	教育

---

核心工作流

注意： OpenSearch API 使用 ROA（RESTful） 风格。你可以使用 --body 将 HTTP 请求正文指定为 JSON 字符串。请参阅下方各任务中的示例。

幂等性： 对于写入操作（创建、重启、删除等），必须使用 --client-token 参数确保幂等性。

• 使用 UUID 格式的唯一标识符作为 clientToken
• 请求超时或失败时，可以安全地使用相同的 clientToken 重试；建议等待 10s 后再重试
• 使用相同 clientToken 重复发送请求，不会多次执行操作
• 生成方式：uuidgen（macOS/Linux）或 [guid]::NewGuid()（PowerShell）

任务 1：创建 OpenSearch 实例

# Generate idempotency token
CLIENT_TOKEN=$(uuidgen)

aliyun opensearch create-app-group \
  --client-token "$CLIENT_TOKEN" \
  --body '{
    "name": "<instance_name>",
    "type": "<standard|enhanced>",
    "chargeType": "<POSTPAY|PREPAY>",
    "quota": {
      "docSize": <storage_GB>,
      "computeResource": <compute_LCU>,
      "spec": "<spec_type>"
    }
  }' \
  --connect-timeout 3 \
  --read-timeout 10 \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-opensearch-app-manage

可选参数（添加到正文中）：

• domain - 行业类型（仅适用于 enhanced 类型）：general（默认）/ ecommerce / esports / community / education

幂等性和试运行支持（通过查询参数设置）：

• --dryRun true - 试运行模式，仅验证参数，不实际创建
• --client-token <unique_id> - 幂等性令牌；多次请求使用相同令牌只会创建一次

示例：创建一个按量付费的 enhanced（行业算法）实例（电商）

# Generate idempotency token
CLIENT_TOKEN=$(uuidgen)

aliyun opensearch create-app-group \
  --client-token "$CLIENT_TOKEN" \
  --body '{
    "name": "my_search_instance",
    "type": "enhanced",
    "chargeType": "POSTPAY",
    "domain": "ecommerce",
    "quota": {
      "docSize": 100,
      "computeResource": 2000,
      "spec": "opensearch.private.common"
    }
  }' \
  --connect-timeout 3 \
  --read-timeout 10 \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-opensearch-app-manage

示例：创建一个 standard（高性能）实例

# Generate idempotency token
CLIENT_TOKEN=$(uuidgen)

aliyun opensearch create-app-group \
  --client-token "$CLIENT_TOKEN" \
  --body '{
    "name": "my_standard_instance",
    "type": "standard",
    "chargeType": "POSTPAY",
    "quota": {
      "docSize": 50,
      "computeResource": 1000,
      "spec": "opensearch.share.common"
    }
  }' \
  --connect-timeout 3 \
  --read-timeout 10 \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-opensearch-app-manage

示例：创建一个订阅（预付费）实例

注意： 订阅实例必须提供 order 参数

# Generate idempotency token
CLIENT_TOKEN=$(uuidgen)

aliyun opensearch create-app-group \
  --client-token "$CLIENT_TOKEN" \
  --body '{
    "name": "my_prepay_instance",
    "type": "enhanced",
    "chargeType": "PREPAY",
    "domain": "ecommerce",
    "quota": {
      "docSize": 100,
      "computeResource": 2000,
      "spec": "opensearch.private.common"
    },
    "order": {
      "duration": 1,
      "pricingCycle": "Year",
      "autoRenew": true
    }
  }' \
  --connect-timeout 3 \
  --read-timeout 10 \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-opensearch-app-manage

试运行模式示例（仅验证参数，不会实际创建）：

aliyun opensearch create-app-group \
  --dryRun true \
  --body '{
    "name": "my_search_instance",
    "type": "enhanced",
    "chargeType": "POSTPAY",
    "quota": {
      "docSize": 100,
      "computeResource": 2000,
      "spec": "opensearch.private.common"
    }
  }' \
  --connect-timeout 3 \
  --read-timeout 10 \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-opensearch-app-manage

幂等创建示例（避免重复创建）：

# Generate idempotency token
CLIENT_TOKEN=$(uuidgen)

aliyun opensearch create-app-group \
  --client-token "$CLIENT_TOKEN" \
  --body '{
    "name": "my_search_instance",
    "type": "enhanced",
    "chargeType": "POSTPAY",
    "quota": {
      "docSize": 100,
      "computeResource": 2000,
      "spec": "opensearch.private.common"
    }
  }' \
  --connect-timeout 3 \
  --read-timeout 10 \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-opensearch-app-manage

任务 2：列出实例

aliyun opensearch list-app-groups \
  --engine-type ha3 \
  --page-number <page> \
  --page-size <size> \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-opensearch-app-manage

支持的筛选参数：

• --engine-type ha3 - 引擎类型（默认为 ha3，必须指定）
• --name <instance_name> - 按名称筛选
• --instance-id <instance_id> - 按实例 ID 筛选
• --type <standard|enhanced> - 按类型筛选
  • standard：高性能
  • enhanced：行业算法
• --sort-by <field> - 排序字段

示例：列出实例

aliyun opensearch list-app-groups \
  --engine-type ha3 \
  --page-number 1 \
  --page-size 10 \
  --connect-timeout 3 \
  --read-timeout 10 \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-opensearch-app-manage

任务 3：查看实例详情

aliyun opensearch describe-app-group \
  --app-group-identity <instance_name_or_id> \
  --connect-timeout 3 \
  --read-timeout 10 \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-opensearch-app-manage

示例：获取实例详情

aliyun opensearch describe-app-group \
  --app-group-identity my_search_instance \
  --connect-timeout 3 \
  --read-timeout 10 \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-opensearch-app-manage

响应包含：

• 基本信息（instanceId、name、type、status）
• 配额信息（quota：docSize、computeResource、spec）
• 计费信息（chargeType、chargingWay）
• 版本信息（currentVersion、versions）
• 状态信息（lockMode、produced）
• 引擎信息（engineType）

---

成功验证

有关操作验证，请参阅 references/verification-method.md

快速验证

验证实例创建：

aliyun opensearch describe-app-group \
  --app-group-identity <instance_name> \
  --connect-timeout 3 \
  --read-timeout 10 \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-opensearch-app-manage

检查 result.instanceId 字段是否非空；如果非空，则表示实例创建成功。

---

资源清理

要删除实例，请使用 OpenSearch 控制台。

---

API 和命令参考

完整的 API 列表请参阅 references/related-apis.md

操作	CLI 命令	API 操作
创建实例	aliyun opensearch create-app-group	CreateAppGroup
列出实例	aliyun opensearch list-app-groups	ListAppGroups
描述实例	aliyun opensearch describe-app-group	DescribeAppGroup

---

最佳实践

写操作参数确认（必需）

重要：执行写操作（创建实例等）前，必须与用户确认以下参数：

创建前确认清单：

参数	描述	示例
区域	实例所在区域	cn-hangzhou / cn-shanghai / cn-beijing
实例名称（name）	用户指定的名称（小写字母、数字、下划线）	my_search_instance
实例类型（type）	高性能 / 行业算法	standard / enhanced
计费类型（chargeType）	按量付费 / 订阅	POSTPAY / PREPAY
规格类型（quota.spec）	共享 / 独享	opensearch.share.common
存储（quota.docSize）	单位为 GB	100
计算（quota.computeResource）	单位为 LCU	2000
行业（domain）	仅适用于 enhanced 类型	ecommerce / general
订阅周期（order）	仅适用于 PREPAY	1 年 / 6 个月

确认流程示例：

You are about to create the following OpenSearch instance, please confirm:

- Region: cn-hangzhou (China East 1)
- Instance Name: my_search_instance
- Instance Type: Industry Algorithm (enhanced)
- Industry: E-commerce (ecommerce)
- Charge Type: Pay-as-you-go (POSTPAY)
- Spec Type: Dedicated Common (opensearch.private.common)
- Storage: 100 GB
- Compute: 2000 LCU

Confirm creation? (yes/no)

幂等性最佳实践

对于写操作（创建、重启、删除），请遵循以下幂等性最佳实践：

1. 每次操作前生成唯一 Token：使用 uuidgen 生成 UUID
2. 超时重试时复用 Token：如果请求超时，使用相同的 clientToken 重试
3. 不同操作使用不同 Token：每个独立操作都需要新的 clientToken
4. Token 有效期：clientToken 通常有效 24 小时

# Example: Safe retry pattern
CLIENT_TOKEN=$(uuidgen)
echo "Using clientToken: $CLIENT_TOKEN"

# First attempt
aliyun opensearch create-app-group --client-token $CLIENT_TOKEN ...

# If timeout, retry with same Token
aliyun opensearch create-app-group --client-token $CLIENT_TOKEN ...

其他最佳实践

1. 命名规范：实例名称必须以字母开头，只能包含小写字母、数字和下划线（_），禁止使用连字符（-），最多 30 个字符
   • ✅ 正确：my_search_instance、video_search、product_search_2024
   • ❌ 错误：my-search-instance、My_Search、123_search
2. 配额规划：根据实际数据量和查询需求规划存储和计算资源
3. 计费类型选择：
   • 测试/开发环境：使用按量付费（POSTPAY）
   • 生产环境：考虑使用订阅（PREPAY）以降低成本
   • 注意：订阅实例必须提供 order 参数（包括时长和 pricingCycle）
4. 实例类型选择：
   • 高性能（standard）：适用于通用搜索场景
   • 行业算法（enhanced）：适用于特定行业场景，需要 domain 参数
5. 行业选择（行业算法）：
   • 电商：ecommerce
   • 游戏：esports
   • 内容社区：community
   • 教育：education
   • 通用：general（默认）
6. 规格选择：
   • 共享通用型：适用于小规模场景
   • 独享型：适用于生产环境，性能更稳定
7. 资源清理：及时删除不再使用的按量付费实例，以避免不必要的费用

---

Reference Links

Document	Description
references/related-apis.md	Complete API List
references/ram-policies.md	RAM Policies
references/verification-method.md	Verification Methods
references/cli-installation-guide.md	CLI Installation Guide
references/acceptance-criteria.md	Acceptance Criteria