OpenAPI 规范集成 - Amazon 快速
您能做什么开始前的准备工作准备 OpenAPI 规范和身份验证设置 OpenAPI 规范集成格式和图案要求不支持的功能架构最佳实践支持的扩展架构验证和错误处理管理 OpenAPI 规范集成对 OpenAPI 规范集成进行故障排除

本文属于机器翻译版本。若本译文内容与英语原文存在差异，则一律以英文原文为准。

OpenAPI 规范集成

通过 OpenAPI 规范集成，您可以基于 OpenAPI 架构创建自定义集成。这样，您就可以连接到任何提供 OpenAPI 规范的 API。此集成仅支持操作执行，并且需要 Amazon Quick Pro 级别或更高的等级。

您能做什么

OpenAPI 规范集成提供了基于架构的连接，可帮助您进行自定义。 APIs

动作连接器

根据 OpenAPI 规范执行操作。根据提供的架构，通过动态生成的操作执行 API 调用、管理资源并与自定义服务进行交互。

基于架构的配置

导入 OpenAPI 规范以自动生成可用的操作和操作。支持 JSON 架构验证和参数映射。

开始前的准备工作

在设置 OpenAPI 规范集成之前，请确保具备以下条件：

  • 您的目标 API 的 OpenAPI 规范（版本 3.0.0 或更高版本）。

  • API 身份验证凭证（API 密钥或其他）。 OAuth

  • 亚马逊 Quick Author 或更高版本

  • API 文档和端点访问权限。

准备 OpenAPI 规范和身份验证

在 Amazon Quick 中设置集成之前，请准备好您的 OpenAPI 规范和身份验证凭证。您的 OpenAPI 规范必须满足成功集成的特定要求。

基本要求

您的 OpenAPI 规范必须满足这些基本要求。

  • OpenAPI 版本-需要版本 3.0.0 或更高版本。

  • 文件格式-仅限 JSON 格式（应用程序/json）。

  • 文件大小限制-整个 OpenAPI 规范的最大值为 1MB。

  • 操作限制-每个连接器最少 1 个，最多 100 个 API 操作。

必填架构字段

您的 OpenAPI 规范必须包含这些必填部分。

openapi

正在使用的 OpenAPI 版本（必须为 “3.0.0” 或更高版本）。

info

服务信息，包括标题、描述和版本。

服务器

API 连接的基本网址和服务器信息。

路径

包含 HTTP 方法和操作的 API 端点定义。

支持的身份验证方案

根据 OpenAPI 规范中支持的身份验证方法准备身份验证凭证。

OAuth 2.0

同时支持授权码授予流程和客户凭证授予流程。需要在安全方案中定义 authorizationURL、tokenURL 和作用域。

API 密钥

在查询参数或标头中传递的 API 密钥身份验证。

不使用身份验证

规范中未定义任何安全方案时的默认选项。

注意

OpenAPI 规范中不支持的身份验证方案将被忽略，连接器将默认为不进行身份验证。

设置 OpenAPI 规范集成

准备好 OpenAPI 规范和身份验证凭证后，请按照以下步骤创建 OpenAPI 规范集成。

  1. 在 Amazon Quick 控制台中，选择集成。

  2. 单击 “添加”（加上 “+” 按钮）。

  3. 在 “添加架构” 页面上，选择 “导入架构”，然后选择要导入的架构。

  4. 选择下一步。

  5. 填写集成详细信息，包括名称和描述。

  6. 查看根据您的 OpenAPI 规范生成的可用操作。

  7. 选择创建并继续。

  8. 选择要与之共享集成的用户。

  9. 单击下一步。

预期结果

成功设置后，您的 OpenAPI 规范集成将显示在集成列表中，其中包含基于您的架构动态生成的操作。该集成可用于 Amazon Quick 工作流程、自动化和 AI 代理，其任务与您的 OpenAPI 规范中定义的终端节点相对应。

格式和图案要求

您的 OpenAPI 规范必须遵循这些格式要求。

  • 路径模式-必须遵循模式:^/[^/]*(/[^/]*)*$并以正斜杠 (/) 开头。

  • 操作 IDs-必须遵循模式：^[a-zA-Z0-9_ ]{1,256}$。

  • 描述-所有操作和参数均为必填项，最多 5000 个字符。

  • 内容类型- application/json 仅支持请求和响应正文。

不支持的功能

不支持以下 OpenAPI 功能，这些功能会导致验证错误。

  • 数组类型-不支持具有数组类型的架构（例如{"type": "array", "items": {"string"}}）。

  • 组合关键字 ——不支持 allOF、oneOf、anyOf 和 not 关键字。

  • 循环引用-不支持循环引用或循环引用（$ref 内的 $ref）。

  • 复杂的嵌套结构-尽可能避免深度嵌套的对象结构。

架构最佳实践

在创建 OpenAPI 规范时，请遵循以下最佳实践。

撰写有效的描述

使用这些指南撰写清晰而有用的描述。

  • 操作描述-描述操作的用途、何时使用它以及它的行为方式。

  • 参数描述-简洁地解释参数的用途和对操作行为的影响。

  • 自包含内容-确保描述在没有外部参考的情况下提供足够的指导。

  • 依赖关系清晰度-在描述中明确说明操作之间的依赖关系。

  • 操作引用-在引用其他操作时使用 operationID，而不是 API 路径。

参数结构建议

构造参数以获得最佳可用性。

  • 扁平化复杂对象-使用单独的参数（例如，开始日期、开始时间、结束日期、结束时间、结束时间），而不是嵌套对象。

  • 使用标准格式-使用 ISO-8601 日期和时间的 “日期时间” 或 “日期” 等标准格式值。

  • 清除参数名称-使用能清楚说明其用途的描述性参数名称。

  • 必填字段标记-根据 API 行为将参数正确标记为必填参数或可选参数。

支持的扩展

我们支持自定义 OpenAPI 扩展，以增强用户体验。

x-amzn-form-display-名字

在参数级别使用以覆盖确认表单中显示的默认字段名称。目前仅支持请求正文参数。

"x-amzn-form-display-name": "User Name"
x-amzn-operation-type

定义应将操作视为 “读取” 还是 “写入”。默认情况下，GET 方法是 “读取” 操作，所有其他 HTTP 方法都是 “写入” 操作。

"x-amzn-operation-type": "read"

架构验证和错误处理

当您上传 OpenAPI 规范时，我们会进行全面验证。

  • 文件大小验证-确保规格不超过 1MB。

  • 操作计数验证-验证定义了 1-100 个操作。

  • 架构结构验证-检查必填字段和格式是否正确。

  • 安全方案验证-验证支持的身份验证方法。

  • 内容类型验证-确保 application/json 仅使用。

验证错误显示在架构编辑器下方，必须先解决验证错误，然后才能创建集成。常见的验证问题包括：

  • 缺少必填字段（openapi、信息、服务器、路径）。

  • 路径模式或操作无效 IDs。

  • 不支持的架构功能（数组、组合关键字）。

  • 描述缺失或过长。

  • 架构定义中的循环引用。

管理 OpenAPI 规范集成

创建 OpenAPI 规范集成后，您可以通过多个选项对其进行管理。

共享集成

您可以与组织中的其他用户共享 OpenAPI 规范操作连接器。

  1. 在 OpenAPI 集成详情页面中，选择共享。

  2. 配置共享选项：

    • 与特定用户共享-输入用户名或电子邮件地址。

    • 与组织共享-向组织中的所有用户开放。

  3. 设置共享访问权限级别。

  4. 选择 “共享集成” 以应用共享设置。

删除集成

请按照以下步骤永久移除您的 OpenAPI 集成。

  1. 在 OpenAPI 集成详情页面中，选择删除。

  2. 查看删除的影响，包括使用此集成的所有工作流程或自动化。

  3. 键入集成名称以确认删除。

  4. 选择 “删除集成” 可将其永久删除。

对 OpenAPI 规范集成进行故障排除

使用这些疑难解答技巧来解决常见的 OpenAPI 规范集成问题。

架构验证错误

确保您的 OpenAPI 规范遵循正确的格式并包含所有必填字段。在导入之前，请使用 OpenAPI 验证器检查您的架构。

未生成任何任务

验证您的 OpenAPI 规范是否包含带有 HTTP 方法和操作的路径定义。 IDs操作是根据架构中定义的操作生成的。

身份验证失败次数

检查您的 OpenAPI 规范中定义的身份验证方案是否与实际的 API 要求相匹配，以及凭据配置是否正确。

操作执行失败

查看操作参数并确保它们与 OpenAPI 规范中的参数定义相匹配，包括必填字段和数据类型。