volcengine-sdk-generator

火山引擎 SDK 生成器

默认生成常规火山引擎 API 调用示例。默认输出应聚焦于 API 调用本身：身份验证设置、请求对象/参数、调用以及打印响应。 除非用户明确要求，否则不要添加重试、代理、连接池、调试日志或其他高级 SDK 配置。

对于高级 SDK 配置问题，请使用 references/ 下按语言分类的文件。这些参考文件内容完整；请直接依据其中的内容作答。

主题	参考文件
Go SDK 配置	references/sdk-integration-go.md
Python SDK 配置	references/sdk-integration-python.md
Java SDK 配置	references/sdk-integration-java.md
Node.js SDK 配置	references/sdk-integration-nodejs.md
PHP SDK 配置	references/sdk-integration-php.md

核心规则

• API 发现使用 scripts/rg_rank.py，该脚本会同时使用 Channel=service 和 Channel=api 调用 API Explorer 搜索。选定具体 API 后，以直接模式调用 scripts/make_code.py，并传入 --service-code、--api-version 和 --action。
• API 发现仅支持在线搜索。搜索端点不需要 cookies、登录状态、UID、DID、UUID 或特定于浏览器的标头。脚本仅将 Query、Channel、Limit 和 Offset 作为查询参数发送。
• rg_rank.py 会保留 Channel=api 的顺序，但版本选择除外：当同一个 service_code + action 有多个版本，且用户未指定版本时，它会将该组中 IsRecommended=1 的结果移到其他版本之前。它还会将 Channel=service 结果作为单独的服务元数据纳入。
• 如果在线搜索失败，请报告返回的搜索错误。不要猜测 API，也不要回退到捆绑的目录。
• 将用户的原始请求用作 --query；不要将其改写成猜测的 API 名称或 SDK 方法。
• 只有当用户使用 等等、不对、重新来、我改主意、其实想要、其实是想要、应该是 或 改成 等词语明确更正自己的请求时，才提取较短的 --query；提取出的查询必须是用户请求中的连续子串，不能是猜测的 API 名称。
• 当请求中出现多个资源或服务，且用户没有明确更正自己的请求时，使用原始请求运行一次 rg_rank.py。如果返回的候选项仍有歧义，请简要列出候选项并询问用户选择哪一个。
• 对于 api、sdk 或 demo 这类纯泛化查询，仍会在线搜索，但很可能产生歧义。请用具体的资源或操作词完善查询。
• ServiceCode 区分大小写。调用 make_code.py 时，保留所选 API 记录中的确切 service_code 值；例如，Kafka 不能写成 kafka。
• 当同一个 service_code + action 出现在多个 API 版本中，且用户未指定版本时，即使其 remote_rank 较低，也要选择 is_recommended=true 的结果。如果用户指定了版本，则使用该确切版本。
• 只有在选定具体 API 后，才获取 api-swagger。
• 获取 api-swagger 时可以同时包含 Version 和 APIVersion，因为该端点需要这两个参数；make-code 负载不得包含 Version。
• 调用 make-code 时传入 ApiAction、ServiceCode、APIVersion、Region 和 Params。
• 不要向 make-code 发送 Version。
• Params 必须来自用户。不要根据 swagger 示例自动填充。
• Swagger 用于提供 API 元数据、必填参数提示和轻量验证。不要为 make-code 序列化查询数组、表单数组或 .N 参数；应将用户的 JSON 对象作为 Params 传入。
• 如果用户遗漏了必填的顶层参数，只模拟这些必填的顶层参数，并明确标记为模拟值。不要模拟可选参数。如果必填的顶层参数是对象或数组，则仅递归填充必填的子字段或项。
• 模拟值必须首先从获取的 swagger 中得出：优先使用 example，然后是 examples、default、enum，最后才使用与类型和约束相符的回退值。如果 swagger 示例已被屏蔽，例如 **** 或 XX，请跳过该示例并使用有效的回退值。
• 模拟值注释默认使用中文，并在目标语言支持行注释时放在模拟赋值行附近；不要在返回代码的顶部重复添加模拟值说明。
• 返回的 SDK 代码必须打印 API 响应值。脚本会后处理 Python、Go、Java 和 PHP 的固定 make-code 模板，以赋值响应并打印响应值。
• 将 scripts/make_code.py 生成的代码作为主要 SDK 示例返回。不要将 SDK 请求构造、身份验证设置或响应处理改写为自定义应用，除非用户明确要求。如果添加可选的格式化或便利逻辑，请保留生成代码中的有效响应打印语句，例如 print(resp)、fmt.Println(resp)、System.out.println(resp)、print_r($response) 或 console.log(response)。
• 如果未指定语言，则返回 DemoSdk 中的所有语言。
• SDK 安装／依赖信息是单独按需提供的功能。只有当用户明确询问如何安装 SDK，或询问应使用哪个包／版本（关键词例如依赖、安装、install、版本、包、maven、go get、pip、composer、npm）时，才使用 --service-code 和 --api-version 运行 scripts/sdk_info.py（复用所选 API 的值；可添加 --language 筛选 go/python/java/php/nodejs 中的一种）。它会返回实时安装命令（RunCommand），以及各语言对应的包和版本。正常生成代码时不要运行此脚本。
• 如果 API 匹配存在歧义，请简要列出候选项并询问用户选择哪一个。用户选择后，不要添加后续执行流程说明，例如表示你将获取 swagger、模拟必填参数并调用 make-code。

工作流

1. 解析用户请求：

   • API 提示：操作、中文名称、服务代码或自然语言描述。
   • 语言：Python、Go、Java、PHP、cURL、Node.js 或未指定。
   • 参数：用户提供的 JSON 对象。
   • 区域：用户提供的值，或默认值 cn-beijing。

2. 每次请求都要定位或验证 API 一次。如果用户已提供 service_code、api_version 和 action，则在直接模式下使用这些准确值；make_code.py 会通过在线 api-swagger 响应验证它们。对于自然语言请求，先调用 scripts/rg_rank.py 并传入 --query。除非明确的自我纠正关键词指向后续目标，否则使用完整的原始请求；如果是这种情况，则使用最后一个目标子串。

3. 选定 service_code、api_version 和 action 后，在直接 API 模式下调用 scripts/make_code.py，并传入 --service-code、--api-version 和 --action。如果缺少顶层必填参数，脚本只会为这些必填顶层参数填入基于 swagger 的模拟值，并在返回的代码中添加中文注释。只有当在线结果中的 API 选择确实存在歧义时，才请求用户澄清；澄清时，只列出候选项并请用户选择。

4. 参数准备好后，通过脚本调用 make-code 并返回官方代码。不要将生成的示例改写成手写工具；任何自定义格式处理都只能作为补充，并且必须保留当前生效的响应输出。

命令

搜索在线候选项：

python3 scripts/rg_rank.py \
  --query '角色扮演' \
  --limit 10 \
  --format text

直接 API 模式：

在 TRN 示例中，<account-id> 是 Volcengine 账户 ID 片段，例如经过掩码处理的 2134xxxyyy。

python3 scripts/make_code.py \
  --service-code sts \
  --api-version 2018-01-01 \
  --action AssumeRole \
  --language python \
  --params-json '{"DurationSeconds":3600,"RoleSessionName":"demo","RoleTrn":"trn:iam::<account-id>:role/demo"}'

当 API Explorer 元数据刚刚更改，或生成的代码看起来已过时，请使用 --refresh-swagger：

python3 scripts/make_code.py \
  --service-code sts \
  --api-version 2018-01-01 \
  --action AssumeRole \
  --refresh-swagger \
  --params-json '{}'

按需获取 SDK 安装／依赖信息（仅当用户询问安装、软件包或版本时）：

python3 scripts/sdk_info.py \
  --service-code sts \
  --api-version 2018-01-01 \
  --language go