本文属于机器翻译版本。若本译文内容与英语原文存在差异，则一律以英文原文为准。
# 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 控制台中，选择**集成。**
1. 单击 “**添加**”（加上 “\$1” 按钮）。
1. 在 “添加架构” 页面上，选择 “**导入架构**”，然后选择要导入的架构。
1. 选择**下一步**。
1. 填写集成详细信息，包括名称和描述。
1. 查看根据您的 OpenAPI 规范生成的可用操作。
1. 选择**创建并继续**。
1. 选择要与之共享集成的用户。
1. 单击**下一步**。
### 预期结果
成功设置后，您的 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 关键字。
+ **循环引用**-不支持循环引用或循环引用（\$1ref 内的 \$1ref）。
+ **复杂的嵌套结构**-尽可能避免深度嵌套的对象结构。
## 架构最佳实践
在创建 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 集成详情页面中，选择共享。**
1. 配置共享选项：
+ **与特定用户共享**-输入用户名或电子邮件地址。
+ **与组织共享**-向组织中的所有用户开放。
1. 设置共享访问权限级别。
1. 选择 “**共享集成**” 以应用共享设置。
### 删除集成
请按照以下步骤永久移除您的 OpenAPI 集成。
1. **在 OpenAPI 集成详情页面中，选择删除。**
1. 查看删除的影响，包括使用此集成的所有工作流程或自动化。
1. 键入集成名称以确认删除。
1. 选择 “**删除集成**” 可将其永久删除。
## 对 OpenAPI 规范集成进行故障排除
使用这些疑难解答技巧来解决常见的 OpenAPI 规范集成问题。
架构验证错误
确保您的 OpenAPI 规范遵循正确的格式并包含所有必填字段。在导入之前，请使用 OpenAPI 验证器检查您的架构。
未生成任何任务
验证您的 OpenAPI 规范是否包含带有 HTTP 方法和操作的路径定义。 IDs操作是根据架构中定义的操作生成的。
身份验证失败次数
检查您的 OpenAPI 规范中定义的身份验证方案是否与实际的 API 要求相匹配，以及凭据配置是否正确。
操作执行失败
查看操作参数并确保它们与 OpenAPI 规范中的参数定义相匹配，包括必填字段和数据类型。