1. 接口描述
接口请求域名： tat.tencentcloudapi.com 。
在指定的实例上触发命令，调用成功返回执行活动ID（inv-xxxxxxxx），每个执行活动内部有一个或多个执行任务（invt-xxxxxxxx），每个执行任务代表命令在一台 CVM 或一台 Lighthouse 上的执行记录。
- 如果指定实例未安装 agent，或 agent 不在线，返回失败
- 如果命令类型与 agent 运行环境不符，返回失败
- 指定的实例需要处于 VPC 网络
- 指定的实例需要处于 RUNNING 状态
- 不可同时指定 CVM 和 Lighthouse
默认接口请求频率限制：20次/秒。
推荐使用 API Explorer
点击调试
API Explorer 提供了在线调用、签名验证、SDK 代码生成和快速检索接口等能力。您可查看每次调用的请求内容和返回结果以及自动生成 SDK 调用示例。
2. 输入参数
以下请求参数列表仅列出了接口请求参数和部分公共参数，完整公共参数列表见 公共请求参数。
| 参数名称 | 必选 | 类型 | 描述 |
|---|---|---|---|
| Action | 是 | String | 公共参数，本接口取值：InvokeCommand。 |
| Version | 是 | String | 公共参数，本接口取值：2020-10-28。 |
| Region | 是 | String | 公共参数，详见产品支持的 地域列表。 |
| CommandId | 是 | String | 待触发的命令ID。 示例值：cmd-ffxdx79i |
| InstanceIds.N | 是 | Array of String | 待执行命令的实例ID列表，上限200。 示例值：["lhins-ar5wyn40"] |
| Parameters | 否 | String | Command 的自定义参数。字段类型为json encoded string。如：{"varA": "222"}。 key为自定义参数名称，value为该参数的默认取值。kv均为字符串型。 如果未提供该参数取值，将使用 Command 的 DefaultParameters 进行替换。 自定义参数最多20个。 自定义参数名称需符合以下规范：字符数目上限64，可选范围【a-zA-Z0-9-_】。 示例值：{"varA": "222"} |
| Username | 否 | String | 在 CVM 或 Lighthouse 实例中执行命令的用户名称。 使用最小权限执行命令是权限管理的最佳实践，建议您以普通用户身份执行云助手命令。若不填，默认以 Command 配置的 Username 执行。 示例值：root |
| WorkingDirectory | 否 | String | 命令执行路径, 默认以Command配置的WorkingDirectory执行。 示例值：/root |
| Timeout | 否 | Integer | 命令超时时间，取值范围[1, 86400]。默认以Command配置的Timeout执行。 示例值：60 |
| OutputCOSBucketUrl | 否 | String | 指定日志上传的cos bucket 地址，必须以https开头，如 https://BucketName-123454321.cos.ap-beijing.myqcloud.com。 示例值：https://BucketName-123454321.cos.ap-beijing.myqcloud.com |
| OutputCOSKeyPrefix | 否 | String | 指定日志在cos bucket中的目录，目录命名有如下规则： 1. 可用数字、中英文和可见字符的组合，长度最多为60。 2. 用 / 分割路径，可快速创建子目录。 3. 不允许连续 / ；不允许以 / 开头；不允许以..作为文件夹名称。 示例值：aa/bb/cc |
3. 输出参数
| 参数名称 | 类型 | 描述 |
|---|---|---|
| InvocationId | String | 执行活动ID。 示例值：inv-8xgjrytm |
| RequestId | String | 唯一请求 ID，由服务端生成，每次请求都会返回（若请求因其他原因未能抵达服务端，则该次请求不会获得 RequestId）。定位问题时需要提供该次请求的 RequestId。 |
4. 示例
示例1 在 Lighthouse 触发命令
输入示例
POST / HTTP/1.1
Host: tat.tencentcloudapi.com
Content-Type: application/json
X-TC-Action: InvokeCommand
<公共请求参数>
{
"CommandId": "cmd-ffxdx79i",
"InstanceIds": [
"lhins-ar5wyn40"
]
}输出示例
{
"Response": {
"RequestId": "41417f50-51b5-4c8d-85b7-f6c508cb228f",
"InvocationId": "inv-8xgjrytm"
}
}5. 开发者资源
腾讯云 API 平台
腾讯云 API 平台 是综合 API 文档、错误码、API Explorer 及 SDK 等资源的统一查询平台，方便您从同一入口查询及使用腾讯云提供的所有 API 服务。
API Inspector
用户可通过 API Inspector 查看控制台每一步操作关联的 API 调用情况，并自动生成各语言版本的 API 代码，也可前往 API Explorer 进行在线调试。
SDK
云 API 3.0 提供了配套的开发工具集（SDK），支持多种编程语言，能更方便的调用 API。
- Tencent Cloud SDK 3.0 for Python: GitHub Gitee
- Tencent Cloud SDK 3.0 for Java: GitHub Gitee
- Tencent Cloud SDK 3.0 for PHP: GitHub Gitee
- Tencent Cloud SDK 3.0 for Go: GitHub Gitee
- Tencent Cloud SDK 3.0 for Node.js: GitHub Gitee
- Tencent Cloud SDK 3.0 for .NET: GitHub Gitee
- Tencent Cloud SDK 3.0 for C++: GitHub Gitee
- Tencent Cloud SDK 3.0 for Ruby: GitHub Gitee
命令行工具
6. 错误码
以下仅列出了接口业务逻辑相关的错误码，其他错误码详见 公共错误码。
| 错误码 | 描述 |
|---|---|
| FailedOperation.CVMError | 调用 CVM 失败。 |
| FailedOperation.LighthouseError | 调用 Lighthouse 失败。 |
| InternalError | 内部错误。 |
| InvalidParameter | 参数错误。 |
| InvalidParameter.InvalidUsername | 无效用户名。 |
| InvalidParameterValue | 参数取值错误。 |
| InvalidParameterValue.AgentUnsupportedCommandType | Agent不支持此命令类型。 |
| InvalidParameterValue.InconsistentInstance | 实例类型不一致。 |
| InvalidParameterValue.InvalidCommandId | CommandId 无效。 |
| InvalidParameterValue.InvalidInstanceId | 实例ID无效。 |
| InvalidParameterValue.InvalidOutputCOSBucketUrl | OutputCOSBucketUrl 无效。 |
| InvalidParameterValue.InvalidOutputCOSKeyPrefix | OutputCOSKeyPrefix 无效。 |
| InvalidParameterValue.InvalidWorkingDirectory | 命令执行路径不合法。 |
| InvalidParameterValue.LackOfParameterInfo | 已启用自定义参数功能，但缺失自定义参数信息。 |
| InvalidParameterValue.LimitExceeded | 超过参数限制。 |
| InvalidParameterValue.ParameterDisabled | 未启用自定义参数功能。 |
| InvalidParameterValue.ParameterInvalidJsonFormat | 参数为非法 json string 格式。 |
| InvalidParameterValue.ParameterKeyContainsInvalidChar | 参数 Key 包含非法字符。 |
| InvalidParameterValue.ParameterKeyDuplicated | 参数 Key 重复。 |
| InvalidParameterValue.ParameterKeyLenExceeded | 参数 Key 过长。 |
| InvalidParameterValue.ParameterNumberExceeded | 参数数目过多。 |
| InvalidParameterValue.ParameterValueNotString | 参数 Value 非 string 类型。 |
| InvalidParameterValue.SupportParametersOnlyIfEnableParameter | 未启用自定义参数功能。 |
| ResourceNotFound.CommandNotFound | 命令不存在。 |
| ResourceNotFound.InstanceNotFound | 实例不存在。 |
| ResourceNotFound.RoleNotFound | 角色不存在。 |
| ResourceUnavailable | 资源不可用。 |
| ResourceUnavailable.AgentNotInstalled | Agent 未安装。 |
| ResourceUnavailable.AgentStatusNotOnline | Agent 不在线。 |
| ResourceUnavailable.InstanceStateNotRunning | 实例未处于运行中。 |
| ResourceUnavailable.LighthouseUnsupportedRegion | Lighthouse 尚不支持指定的地域。 |
| UnauthorizedOperation.CamAuthFailed | CAM鉴权失败。 |
| UnauthorizedOperation.InvalidToken | Token 无效。 |
| UnauthorizedOperation.MFAExpired | Multi-Factor Authentication(MFA) 过期。 |
| UnauthorizedOperation.MFANotFound | Multi-Factor Authentication(MFA) 不存在。 |