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

# 操作连接器
<a name="action-integrations"></a>

操作连接器使用与外部服务的安全连接，并根据您的身份验证级别和权限执行操作。

# 操作连接器的工作原理
<a name="int-actions-how-it-works"></a>

Amazon Quick 中的操作连接器可在 Amazon Quick 和外部服务之间创建安全连接。配置这些集成时，您可以根据自己的身份验证级别和权限执行操作。

## 核心组件
<a name="qbs-actions-how-it-works-qbs-actions-core-components"></a>

**动作连接器**  
与外部服务集成的基础资源。Amazon Quick 支持 15 种第三方集成和 5 种 AWS 服务集成。有关设置 AWS 内置服务操作连接器的信息，请参见[AWS 服务操作连接器](builtin-services-integration.md)。

**身份验证方法**  
操作连接器支持多种身份验证方法，包括托管 (3LO)、基于用户的自定义、API 密钥和 2LO。有关每种身份验证方法的详细信息，请参阅[身份验证方法](action-connector-apis.md#action-connector-apis-authentication)。

**实现类型**  
+ **用户触发的即时操作的按需操作-触发**操作时立即执行的实时操作。您可以通过聊天界面、控制面板或 Amazon Q 应用程序启动操作。示例包括创建工单、发送消息或查询数据。
+ **计划任务或系统触发任务的自动化工作流程**-根据计划或触发器执行的系统管理的操作。它们在后台运行，无需用户干预。示例包括数据同步、报告生成或系统维护。

**权限模型**  
+ **通过 3LO 获得个人访问权限——您可以通过 Three-L** egged 向 Amazon Quick 授予特定权限 OAuth，从而保持对服务访问权限的控制。权限与您在目标服务中的身份和证书相关联。
+ **自动化工作流程的服务级别权限**-这些权限适用于自动化工作流程，支持无需用户参与的 system-to-system交互。它们是在服务级别配置的，通常使用 API 密钥或服务帐号凭证。
+ **实体级访问控制**-管理对 Amazon Quick 中操作的访问权限，确定哪些用户或群组可以执行特定操作。这些控件与 Amazon Quick 更广泛的权限系统集成，可在整个平台上实现一致的访问管理。

# 操作类型
<a name="int-actions-types"></a>

Amazon Quick 支持两种调用操作的方法，每种方法都提供不同的用例和身份验证模型。

## 按需操作
<a name="qbs-actions-types-qbs-actions-on-demand"></a>

触发按需操作后，它们会立即执行。这些操作支持需要实时响应的交互式操作。

**主要特征：**
+ 用户发起的执行-您可以在聊天界面中通过自然语言触发操作。
+ 交互式表单完成-在操作执行之前，使用必填参数填写表单。
+ 即时响应-操作实时执行，并提供有关成功或失败的即时反馈。
+ 个人身份验证 (3LO)-使用您来自目标服务的个人凭据和权限。

**常见用例：**
+ 在 Jira 中创建门票。
+ 在 Slack 中发送消息。
+ 更新 Salesforce 记录。
+ 正在从中检索信息。 SharePoint

## 自动化工作流
<a name="qbs-actions-types-qbs-actions-automated-workflows"></a>

自动化工作流程按计划执行操作或响应特定的触发器。它们对于后台和系统级操作非常有用。

**主要特征：**
+ 系统级执行-操作根据预定义的触发器自动运行，无需用户干预。
+ 计划或事件触发-按基于时间的计划执行或响应特定的系统事件。
+ 非交互式操作-无需用户输入或完成表单即可在后台运行。
+ 服务级别身份验证-使用系统凭据而不是个人用户身份验证。

**常见用例：**
+ 定期进行数据同步。
+ 计划生成报告。
+ 自动更新门票。
+ 系统运行状况检查。

# 有界和无界代理人
<a name="int-actions-bounded-unbounded"></a>

Amazon Quick 提供两种类型的代理，它们提供不同级别的访问权限和功能：受限代理和无限制代理。了解这些代理类型之间的差异有助于您为自己的用例实施正确的解决方案。

## 受限特工
<a name="qbs-actions-bounded-unbounded-qbs-actions-bounded-agents"></a>

受限代理在定义的参数内运行，这些参数专门与 Amazon Quick 中的一个或多个空间相关联。这些代理只能访问与其分配的空间明确连接的资源并对其执行操作。例如，为人力资源部门配置的受限代理只能访问与人力资源相关的文档、数据集和执行与人力资源相关的操作。

使用限定代理进行：
+ 特定部门的工作流程（人力资源、财务、IT）。
+ 项目团队的合作。
+ 敏感数据处理。
+ 以合规为重点的运营。

界限性质可确保代理无法访问其指定空间之外的资源，从而增强安全性。这使得它非常适合数据隔离很重要的场景。

## 无界特工
<a name="qbs-actions-bounded-unbounded-qbs-actions-unbounded-agents"></a>

Unbounded 代理具有更广泛的访问能力，可以在 Amazon Quick 环境中使用所有已配置的操作和资源。这些代理不限于特定空间，可以访问系统中任何已正确配置的操作连接器。

将无界代理用于：
+ 全组织范围的协助。
+ 跨部门工作流程。
+ 通用操作。
+ 需要访问多个系统的场景。

# 先决条件
<a name="int-actions-prerequisites"></a>

在 Amazon Quick 中使用操作之前，请确保您具备以下条件：

## 许可证要求
<a name="qbs-actions-prerequisites-qbs-actions-license-requirements"></a>

以下 Amazon Quick 许可证之一：
+ Reader Pro-提供对数据的读取权限以及在连接的服务中执行操作的能力。
+ 作者-包括 Reader Pro 功能以及创建和修改内容和配置的功能。
+ Author Pro-全功能访问权限，包括高级操作配置和管理功能。

## 服务要求
<a name="qbs-actions-prerequisites-qbs-actions-service-requirements"></a>

对于第三方服务（例如 Jira 或 Salesforce），请确保您已具备以下条件：
+ 目标服务中的适当权限。
+ 每项服务的身份验证凭证。

对于 AWS 操作连接器，您需要对相关服务的管理员访问权限。

## AWS 账户要求
<a name="qbs-actions-prerequisites-qbs-actions-aws-account-requirements"></a>
+ 活跃 AWS 账户-启用账单且信誉良好的有效 AWS 账户。
+ 适当的 IAM 权限-允许 Amazon Quick 访问所需 AWS 服务的 IAM 角色和策略。
+ 所需的服务配额-您计划与操作集成的 AWS 服务有足够的服务限制。

# 支持的操作连接器类型和可用操作
<a name="action-connector-apis-supported-types"></a>

Amazon Quick 支持多种连接器类型，每种连接器都有特定的可用操作：

## 外部服务连接器
<a name="action-connector-apis-external-services"></a>
+ **Salesforce**-创建记录、更新机会、搜索账户、管理潜在客户。
+ **JIRA**-创建议题、更新工单、搜索项目、管理工作流程。
+ **微软 Outlook**-发送电子邮件、管理日历活动、访问联系人。
+ **Slack**-发送消息、创建频道、管理通知。
+ **ServiceNow**-创建事件、更新请求、管理工作流程。
+ **Zendesk**-创建工单、更新案例、搜索知识库。
+ **PagerDuty**-创建事件、管理升级、更新待命时间表。
+ **Asana**-创建操作、更新项目、管理团队工作流程。
+ **BambooHR**-访问员工数据，管理休假申请。
+ **Box**-管理文件、文件夹，并协作处理文档。
+ **Canva**-创建和编辑设计，管理模板和资产。
+ **FactSet**-访问财务数据，生成报告。
+ **GitHub**-管理存储库、议题、拉取请求和代码协作。
+ **HuggingFace**-访问 AI 模型、数据集和机器学习工作流程。
+ **HubSpot**-管理联系人、交易、营销活动和 CRM 数据。
+ **对讲机**-管理客户对话、支持工单和消息。
+ **线性**-创建和管理问题、项目和开发工作流程。
+ **星期一**-管理项目、任务和团队协作工作流程。
+ **概念**-创建和管理页面、数据库和协作工作区。
+ **Smartsheet**-更新工作表，管理项目数据。
+ **Confluenc** e-创建、更新和管理页面、空间和其他 Confluence 对象。
+ **SharePoint**-通过 19 个可用操作对 SharePoint 列表、项目和 Excel 文件执行操作，用于创建、更新、删除和检索 SharePoint 内容。
+ **OneDrive**-创建、更新、删除和管理 OneDrive 文件和文件夹。
+ **SAP**-访问 SAP S/4HANA 系统，对企业数据执行只读操作。

## AWS 服务连接器
<a name="action-connector-apis-aws-services"></a>
+ **Amazon S3**-上传文件、管理存储桶、检索对象。
+ **Amazon Bedrock**-生成内容、分析数据、处理请求。
+ **Amazon Textrac** t-从文档中提取文本和数据。
+ **Amazon Comp** rehend-自然语言处理和情感分析。
+ **Amazon Comprehend Medical-医学文本**分析和实体提取。

## 动作连接器兼容性矩阵
<a name="action-connector-compatibility-matrix"></a>

下表显示了每种操作连接器类型支持的 Amazon Quick 功能：


**操作连接器功能兼容性**  

| 动作连接器 | 聊天代理 | 流 | 仪表板视觉效果 | 仪表板提醒 | 自动化 | 同伴 | 
| --- | --- | --- | --- | --- | --- | --- | 
| AWS 内置服务 | 
| AWS 基岩特工运行时 | — | — | — | — | ✓ | — | 
| AWS 基岩数据自动化运行时 | — | — | — | — | ✓ | — | 
| AWS 基岩运行时间 | — | — | — | — | ✓ | — | 
| Amazon Comprehend | — | — | — | — | ✓ | — | 
| Amazon Comprehend Medical | — | — | — | — | — | — | 
| Amazon S3 | — | — | — | — | ✓ | — | 
| Amazon Textract | — | — | — | — | ✓ | — | 
| 外部服务连接器 | 
| Asana | ✓ | ✓ | — | — | — | ✓ | 
| Atlassian 融合云 | ✓ | ✓ | — | — | ✓ | ✓ | 
| Atlassian Jira Clou | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | 
| BambooHR | ✓ | ✓ | — | — | — | ✓ | 
| Box | ✓ | ✓ | — | — | — | — | 
| Canva | ✓ | ✓ | — | — | — | — | 
| FactSet | ✓ | ✓ | — | — | — | — | 
| GitHub | ✓ | ✓ | — | — | — | — | 
| HuggingFace | ✓ | ✓ | — | — | — | — | 
| HubSpot | ✓ | ✓ | — | — | — | — | 
| Intercom | ✓ | ✓ | — | — | — | — | 
| 线性 | ✓ | ✓ | — | — | — | — | 
| Monday | ✓ | ✓ | — | — | — | — | 
| 概念 | ✓ | ✓ | — | — | — | — | 
| 微软 OneDrive | ✓ | ✓ | — | — | ✓ | ✓ | 
| Microsoft Outlook | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | 
| 微软 SharePoint | ✓ | ✓ | — | — | ✓ | ✓ | 
| Microsoft Teams | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | 
| PagerDuty | ✓ | ✓ | — | — | ✓ | ✓ | 
| Salesforce | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | 
| SAP | ✓ | — | — | — | ✓ | ✓ | 
| ServiceNow | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | 
| Slack | ✓ | ✓ | ✓ | — | — | ✓ | 
| Smartsheet | ✓ | ✓ | — | — | — | ✓ | 
| Zendesk | ✓ | ✓ | — | — | — | ✓ | 
| 自定义连接器类型 | 
| 模型上下文协议（MCP） | ✓ | ✓ | — | — | ✓ | — | 
| OpenAPI | ✓ | ✓ | — | — | — | — | 
| REST API | — | — | — | — | ✓ | — | 

**身份验证 Support：**
+ **聊天代理和同伴**-Support 用户身份验证（3LO，基本）
+ D@@ **ashboard Visuals**-支持用户身份验证 (3LO)
+ **控制面板警报**-Support 系统身份验证（2LO 或 API 密钥）
+ **自动化**-Support 系统身份验证 (2LO)

# 动作连接器 APIs
<a name="action-connector-apis"></a>

操作连接器 APIs 允许您以编程方式创建和管理 Amazon Quick 与外部服务之间的连接。它们 APIs 支持操作集成功能，允许用户直接通过 Amazon Quick 聊天界面和自动工作流程在第三方应用程序中执行操作。

## 什么是动作连接器 APIs？
<a name="action-connector-apis-overview"></a>

操作连接器是支持与第一方和第三方应用程序集成的基础资源。通过这些 APIs，您可以对应用程序进行身份验证，管理权限，并控制用户可以在 Amazon Quick 应用程序中执行哪些操作。

### 动作连接器如何 APIs 支持动作集成
<a name="action-connector-apis-task-integrations"></a>

操作连接器为 Amazon 快速操作集成 APIs 提供后端基础架构。当你通过 API 创建操作连接器时，你会建立一个安全的连接，让你：
+ 通过聊天界面在外部服务中执行操作。
+ 在后台流程中执行自动化工作流程。
+ 将第三方服务与 Amazon Quick 应用程序集成。
+ 管理身份验证和服务访问权限。

他们 APIs 可以处理将 Amazon Quick 与外部服务安全连接所需的复杂身份验证流程、凭证管理和权限控制。

## 身份验证方法
<a name="action-connector-apis-authentication"></a>

操作连接器 APIs 支持多种身份验证方法，以适应不同的用例和安全要求：

### 托管身份验证 (3LO)
<a name="qbs-action-connector-apis-managed-auth"></a>

Three-Legged 为个人访问第三方服务 OAuth 提供了最简单的设置：
+ 无需初始配置。
+ 通过服务提供商登录进行用户特定的身份验证。
+ 自动刷新令牌，生命周期为 90 天。
+ 由 Amazon Quick 管理的安全凭证存储。

### Service-to-service 身份验证 (2LO)
<a name="qbs-action-connector-apis-service-auth"></a>

对于复杂的企业集成：
+ 支持客户端凭证 OAuth 流。
+ 启用 system-to-system互动。
+ 需要客户端 ID、客户端密钥和令牌 URL 配置。
+ 适用于需要复杂安全性的自动化工作流程。
+ OAuth -动态客户端注册（DCR-仅适用于选定的 MCP 服务器）。

### API 密钥身份验证
<a name="qbs-action-connector-apis-api-key"></a>

简化了自动化工作流程的身份验证：
+ 基于单一令牌的身份验证。
+ 服务级别权限。
+ 非常适合后台进程和计划操作。
+ 需要来自目标服务的有效 API 密钥。

### 基本身份验证
<a name="qbs-action-connector-apis-basic-auth"></a>

基本身份验证提供了一种简单的 username/password 身份验证方法：
+ 使用标准的 HTTP 基本身份验证标头。
+ 凭证采用 base64 编码。
+ 适用于不支持 API 密钥的服务 OAuth 或 API 密钥。
+ 需要安全的 HTTPS 连接。
+ 不建议用于面向公众的服务。

### 无
<a name="qbs-action-connector-apis-no-auth"></a>

无需身份验证：
+ 用于公共和 APIs 服务。
+ 无需凭证或令牌。
+ 仅限于只读或公共操作。
+ 通常用于公共数据源和文档。
+ 不应用于敏感操作。

## 权限和访问控制
<a name="qbs-action-connector-apis-permissions"></a>

操作连接器通过访问控制列表 (ACLs) APIs 实现全面的权限控制：

### 资源级权限
<a name="qbs-action-connector-apis-resource-permissions"></a>
+ **所有者**-完全控制，包括删除和权限管理。
+ **贡献者**-可以使用和修改连接器设置。
+ **Viewer**-可以查看连接器详细信息并使用已启用的操作。

### 用于权限管理的 API 操作
<a name="qbs-action-connector-apis-permission-operations"></a>
+ `DescribeActionConnectorPermissions`-检索当前权限设置。
+ `UpdateActionConnectorPermissions`-授予或撤消用户权限。

## 支持的连接器类别
<a name="qbs-action-connector-apis-categories"></a>

### 两用连接器
<a name="qbs-action-connector-apis-dual-purpose"></a>

这些连接器支持操作集成和知识库创建：
+ **Amazon S3**-使用管理控制台为文件操作创建操作，使用 web 应用程序从 S3 内容创建知识库。
+ **微软 SharePoint**-文档管理操作、内容索引。
+ **OneDrive**-文件操作、文档搜索功能。
+ **Confluence**-内容创建操作、知识库集成。

### 仅限操作的连接器
<a name="qbs-action-connector-apis-task-only"></a>

专门用于在没有知识库功能的情况下执行动作：
+ **Salesforce**-企业 CRM 集成，支持客户和联系人操作、自定义对象 CRUD 操作、销售流程自动化。
+ **JIRA**-问题跟踪和项目管理。
+ **微软 Outlook**-发送电子邮件、管理日历活动、访问联系人。
+ **Slack**-通信和通知工作流程。
+ **ServiceNow**-IT 服务管理操作。
+ **Zendesk**-创建工单、更新案例、搜索知识库。
+ **PagerDuty**-创建事件、管理升级、更新待命时间表。
+ **Asana**-创建操作、更新项目、管理团队工作流程。
+ **BambooHR**-访问员工数据，管理休假申请。
+ **Smartsheet**-更新工作表，管理项目数据。
+ **FactSet**-访问财务数据，生成报告。
+ **SAP**-访问 SAP 系统、执行业务职能和管理企业数据。

### 仅限知识库的连接器
<a name="qbs-action-connector-apis-data-only"></a>

专注于没有操作功能的知识库集成：
+ **Google 云端硬盘**-文档索引和搜索。
+ **网络爬虫**-内容发现和索引。

## API 生命周期管理
<a name="qbs-action-connector-apis-lifecycle"></a>

### 凭证管理
<a name="qbs-action-connector-apis-credential-management"></a>
+  OAuth 操作连接器的自动刷新令牌处理。
+ 使用安全存储身份验证凭据 AWS KMS。
+ Support 支持凭证轮换和更新。
+ Amazon S3 连接器的跨账户访问权限。

### 连接更新
<a name="qbs-action-connector-apis-connection-updates"></a>

使用 `UpdateActionConnector` API 执行以下操作：
+ 修改身份验证凭据。
+ 更新服务配置参数。
+ 更改操作连接器元数据。

### 监控和排查
<a name="qbs-action-connector-apis-monitoring"></a>
+ 通过 CloudWatch 指标跟踪 API 使用情况。
+ 监控连接运行状况和身份验证状态。
+ 针对常见故障场景实现错误处理。
+ 使用验证 APIs 来诊断配置问题。

## 速率限制和配额
<a name="qbs-action-connector-apis-rate-limiting"></a>

操作连接器 APIs 实现标准 AWS 的 API 速率限制：
+ 标准 AWS API 限制适用于所有操作。
+ 连接验证可能有其他限制。
+ 操作执行率取决于目标服务能力。
+ 为重试逻辑实现指数退避。

## 跨账户支持
<a name="qbs-action-connector-apis-cross-account"></a>

对于 Amazon S3 连接器， APIs 支持跨账户访问：
+ 在创建连接器 IDs 期间指定不同的 AWS 帐户。
+ 为跨账户访问配置适当的 IAM 权限。
+  AWS KMS 用于跨账户的安全凭证管理。
+ 在启用跨账户连接之前验证权限。

## 错误处理和故障排除
<a name="qbs-action-connector-apis-error-handling"></a>

操作连接器 APIs 返回标准 AWS 错误响应：

### 常见错误类型
<a name="qbs-action-connector-apis-common-errors"></a>
+ `AccessDeniedException`-操作权限不足。
+ `InvalidParameterValueException`-一个或多个参数值对该操作无效。
+ 配置参数无效-特定于服务的配置值不正确或缺失。
+ `ResourceNotFoundException`-未找到连接器或资源。
+ `ThrottlingException`-已超过速率限制。
+ `ConflictException`-资源冲突或名称重复。
+ `InternalFailureException`-请求处理过程中出现内部服务错误。
+ `ResourceExistsException`-尝试创建已存在的资源。
+ `InvalidNextTokenException`-提供的分页令牌无效或已过期。
+ `AccessTokenNotFoundException`-用户需要授权连接（即登录按钮）。UX 使用此异常来请求用户授权。
+ `TokenResponseException`-操作设置无效。

在应用程序中实施适当的错误处理，以优雅地管理这些场景并为用户提供有意义的反馈。

## 将操作连接器 APIs 与 AWS CLI 配合使用
<a name="qbs-action-connector-apis-cli-examples"></a>

您可以使用 AWS CLI 以编程方式管理操作连接器。以下示例演示了使用通用占位符值的常见操作。

### 创建操作连接器
<a name="create-action-connector-cli"></a>

使用`create-action-connector`命令创建用于与外部服务集成的新操作连接器。

```
aws quicksight create-action-connector \
  --aws-account-id "123456789012" \
  --name "MyS3Connector" \
  --action-connector-id "my-s3-connector-id" \
  --type "AMAZON_S3" \
  --authentication-config '{
    "AuthenticationType": "IAM",
    "AuthenticationMetadata": {
      "IamConnectionMetadata": {
        "RoleArn": "arn:aws:iam::123456789012:role/MyConnectorRole"
      }
    }
  }' \
  --enabled-actions "CreateBucket" "ListBuckets" \
  --description "S3 connector for automation workflows" \
  --region "us-east-1"
```

### 列出操作连接器
<a name="list-action-connectors-cli"></a>

使用`list-action-connectors`命令检索您账户中的所有操作连接器。

```
aws quicksight list-action-connectors \
  --aws-account-id "123456789012" \
  --max-results 10 \
  --region "us-east-1"
```

### 描述操作连接器
<a name="describe-action-connector-cli"></a>

使用`describe-action-connector`命令获取有关特定操作连接器的详细信息。

```
aws quicksight describe-action-connector \
  --aws-account-id "123456789012" \
  --action-connector-id "my-s3-connector-id" \
  --region "us-east-1"
```

### 更新操作连接器
<a name="update-action-connector-cli"></a>

使用`update-action-connector`命令修改现有操作连接器的配置。

```
aws quicksight update-action-connector \
  --aws-account-id "123456789012" \
  --action-connector-id "my-s3-connector-id" \
  --name "UpdatedS3Connector" \
  --authentication-config '{
    "AuthenticationType": "IAM",
    "AuthenticationMetadata": {
      "IamConnectionMetadata": {
        "RoleArn": "arn:aws:iam::123456789012:role/UpdatedConnectorRole"
      }
    }
  }' \
  --enabled-actions "CreateBucket" "ListBuckets" "DeleteBucket" \
  --region "us-east-1"
```

### 搜索操作连接器
<a name="search-action-connectors-cli"></a>

使用`search-action-connectors`命令根据特定条件查找操作连接器。

```
aws quicksight search-action-connectors \
  --aws-account-id "123456789012" \
  --max-results 5 \
  --filters '[{
    "Name": "ACTION_CONNECTOR_NAME",
    "Operator": "StringLike",
    "Value": "S3"
  }]' \
  --region "us-east-1"
```

### 管理操作连接器权限
<a name="update-action-connector-permissions-cli"></a>

使用`update-action-connector-permissions`命令授予或撤消操作连接器的权限。

```
aws quicksight update-action-connector-permissions \
  --aws-account-id "123456789012" \
  --action-connector-id "my-s3-connector-id" \
  --grant-permissions '[{
    "Actions": [
      "quicksight:DescribeActionConnector",
      "quicksight:UpdateActionConnector",
      "quicksight:DeleteActionConnector"
    ],
    "Principal": "arn:aws:quicksight:us-east-1:123456789012:user/default/myuser"
  }]' \
  --region "us-east-1"
```

### 查看操作连接器权限
<a name="describe-action-connector-permissions-cli"></a>

使用`describe-action-connector-permissions`命令查看操作连接器的当前权限。

```
aws quicksight describe-action-connector-permissions \
  --aws-account-id "123456789012" \
  --action-connector-id "my-s3-connector-id" \
  --region "us-east-1"
```

### 删除操作连接器
<a name="delete-action-connector-cli"></a>

使用`delete-action-connector`命令从您的账户中移除操作连接器。

```
aws quicksight delete-action-connector \
  --aws-account-id "123456789012" \
  --action-connector-id "my-s3-connector-id" \
  --region "us-east-1"
```

## 后续步骤
<a name="qbs-action-connector-apis-next-steps"></a>

了解操作连接器后 APIs，您可以：
+ 查看完整的 API 参考文档，了解详细的参数规范。
+ 浏览目标服务的特定连接器设置指南。
+ 实施适合您的用例的身份验证流程。
+ 为生产部署设置监控和错误处理。
+ 为您的组织配置权限和访问控制。

# 身份验证方法
<a name="quick-action-auth"></a>

Amazon Quick 支持多种身份验证方法，每种方法都针对特定的用例和安全要求而设计。

## 托管身份验证 (3LO)
<a name="quick-managed-auth"></a>

对于个人访问第三方服务，推荐使用三足式 OAuth (3LO) 身份验证方法。

**3LO 的主要特点：**
+ 无需初始配置。
+ 用户特定的身份验证。
+ 安全的凭证存储。
+ 自动刷新令牌。
+ 90 天刷新令牌生命周期。

**3LO 设置流程：**

1. 选择连接器。

1. 选择托管身份验证。

1. 完成服务提供商登录。

1. 授予所请求的权限。

1. 确认连接。

## 基于用户的自定义身份验证
<a name="quick-custom-user-auth"></a>

适用于需要特定组织控制或自定义配置的场景。

**必填信息：**
+ 客户端 ID。
+ 客户机密。
+ 域名网址。
+ 授权网址。
+ 令牌网址。
+ 重定向网址。

**配置步骤：**

1. 从服务提供商处获取凭证。

1. 配置身份验证设置。

1. 验证连接。

1. 测试访问权限。

在 Amazon Quick 控制台中配置基于用户的身份验证时，请从服务提供商那里获取正确的凭证并配置您的身份验证设置。然后验证连接并测试您的访问权限。

## API 密钥身份验证
<a name="quick-actions-api-key-auth"></a>

主要用于自动化工作流程和系统级访问。

**主要特点：**
+ 基于令牌的简单身份验证。
+ 单一凭证管理。
+ 服务级别权限。
+ 适用于自动化流程。

**设置要求：**

设置 API 密钥身份验证时，请确保您具备以下条件：
+ 来自服务的有效 API 密钥。
+ 适当的服务权限。
+ 秘密存储配置。

## Service-to-service authentication
<a name="quick-actions-service-to-service-auth"></a>

适用于需要复杂身份验证的自动化工作流程。

**配置要求：**
+ 客户端 ID。
+ 客户机密。
+ 域名网址。
+ 令牌网址。
+ 特定于服务的参数。

# 动作执行方法
<a name="int-actions-execution"></a>

Amazon Quick 提供了多种执行操作的方式，可适应不同的用例和交互偏好。

## 聊天界面
<a name="qbs-actions-execution-qbs-actions-chat-interface"></a>

您可以在 Amazon Quick 聊天中执行隐式操作。

### 隐式动作
<a name="qbs-actions-execution-qbs-actions-implicit-actions"></a>

Amazon Quick 还支持通过与代理的自然对话执行隐式操作。使用先进的自然语言处理，系统可以识别您的对话何时表明需要采取特定操作。对对话进行分析，以确定需要采取哪些措施来满足您的请求。

单个请求可能需要多个操作才能完成。发生这种情况时，系统会按顺序处理这些操作，指导您完成每个步骤。对于每项已确定的操作，系统都会显示相应的表单供您填写。每个操作完成后，您会收到确认信息，然后继续执行序列中的下一个操作。

例如，如果你问 “为这个问题创建 Jira 工单并在 Slack 中通知团队”，系统会：

1. 首先出示 Jira 工单创建表单。

1. 完成工单创建后，出示 Slack 消息表单。

1. 按顺序完成这两个操作。

在整个过程中，您可以通过多个操作来跟踪进度。当所有操作完成后，系统会提供一份全面的摘要，显示所有已执行的操作及其结果。如果需要，您可以访问相关文档，并查看在此过程中可能出现的任何错误状态。

# 监控和维护
<a name="int-actions-monitoring"></a>

监控操作连接器有助于确保性能可靠，并在问题影响用户之前将其识别出来。定期监控允许您跟踪使用模式、优化性能并保持与外部服务的健康连接。

## 性能监控
<a name="qbs-actions-monitoring-qbs-actions-performance-monitoring"></a>

您可以使用以下指标和分析来评估操作连接器的性能。

### CloudWatch 指标
<a name="qbs-actions-monitoring-qbs-actions-cloudwatch-metrics"></a>
+ 操作执行成功率-跟踪成功执行操作的百分比，以确定可靠性问题。
+ 响应时间-监控操作需要多长时间才能完成，并确定性能瓶颈。
+ 错误频率-跟踪错误模式以确定常见的故障点和需要改进的领域。
+ API 配额使用情况-根据服务限制监控使用情况，以防止限制并规划容量。

### 使用情况分析
<a name="qbs-actions-monitoring-qbs-actions-usage-analytics"></a>

为操作连接器收集了以下使用情况分析：
+ 活跃用户-跟踪有多少用户正在积极使用操作连接器来了解采用和使用模式。
+ 常用操作-确定哪些操作最常用于确定优化工作的优先级。
+ 执行模式-分析执行操作的时间和频率，以优化资源分配。
+ 错误趋势-监控一段时间内的错误模式，以确定系统性问题和改进机会。

## 连接运行状况
<a name="qbs-actions-monitoring-qbs-actions-connection-health"></a>

您可以使用以下连接运行状况工具评估操作连接器的运行状况：

### 状态监控
<a name="qbs-actions-monitoring-qbs-actions-status-monitoring"></a>
+ 连接状态-监控连接器是否处于活动状态且运行正常。
+ 身份验证有效性-跟踪身份验证令牌和凭据的状态以防止访问失败。
+ 令牌到期跟踪-监控身份验证令牌何时过期并需要续订。
+ 服务可用性-跟踪连接的外部服务的可用性和响应状态。

### 自动维护
<a name="qbs-actions-monitoring-qbs-actions-automated-maintenance"></a>
+ 令牌刷新处理。
+ 连接恢复。
+ 错误重试逻辑。
+ 性能优化。

## CloudWatch 指标参考
<a name="qbs-actions-monitoring-qbs-actions-cloudwatch-metrics-table"></a>


**可用 CloudWatch 指标**  

| 指标 | 说明 | 单位 | 
| --- | --- | --- | 
| ActionSuccess | 成功处决 | 计数 | 
| ActionLatency | 执行时间 | 毫秒 | 
| AuthFailures | 身份验证失败 | 计数 | 
| APIThrottling | API 限制事件 | 计数 | 

# 最佳实践
<a name="int-actions-best-practices"></a>

遵循操作连接器的最佳实践有助于确保安全、可靠和高效的操作。这些做法可帮助您保持最佳性能、保护敏感数据并最大限度地减少操作问题。

## 安全性
<a name="qbs-actions-best-practices-qbs-actions-security-best-practices"></a>

### 身份验证管理
<a name="qbs-actions-best-practices-qbs-actions-authentication-management"></a>
+ 定期轮换凭证-定期更新 API 密钥和 OAuth 令牌以维护安全。
+ 定期权限审查-每季度审核用户和服务权限，以确保访问权限最小。
+ 令牌生命周期监控-跟踪令牌到期日期，并在凭证到期之前设置提醒。
+ 访问审核日志-启用全面日志记录以跟踪谁访问了哪些服务以及何时访问了哪些服务。

### 访问控制
<a name="qbs-actions-best-practices-qbs-actions-access-control"></a>
+ 实现最低权限访问权限-仅授予每项操作正常运行所需的最低权限。
+ 定期权限审计-审查并验证当前权限是否符合实际使用模式和业务需求。
+ 文档访问模式-清晰记录谁有权访问哪些连接器以及为什么。
+ 监控异常使用情况-针对可能表明存在安全问题的异常访问模式设置警报。

## 性能
<a name="qbs-actions-best-practices-qbs-actions-performance-best-practices"></a>

### 操作配置
<a name="qbs-actions-best-practices-qbs-actions-action-configuration"></a>
+ 优化表单默认值-预先填充常用值以减少用户输入时间和错误。
+ 配置适当的超时-根据每项服务的典型响应时间设置实际的超时值。
+ 设置错误处理-使用清晰的用户消息和适当的重试逻辑，实现强大的错误处理。
+ 文档依赖关系-清楚地记录不同操作之间的任何先决条件或依赖关系。

### 资源管理
<a name="qbs-actions-best-practices-qbs-actions-resource-management"></a>
+ 监控 API 配额。
+ 跟踪使用模式。
+ 优化刷新计划。
+ 定期清理未使用的连接器。

## Maintenance
<a name="qbs-actions-best-practices-qbs-actions-maintenance-best-practices"></a>

### 常规行动
<a name="qbs-actions-best-practices-qbs-actions-regular-tasks"></a>
+ 查看连接器状态。
+ 更新配置。
+ 验证连接。
+ 文档更改。

### 问题排查
<a name="qbs-actions-best-practices-qbs-actions-troubleshooting-tasks"></a>
+ 监控错误模式。
+ 查看 CloudWatch 日志。
+ 跟踪解决时间。
+ 记录解决方案。

# 问题排查
<a name="int-actions-troubleshooting"></a>

当操作连接器遇到问题时，系统的故障排除可帮助您快速识别和解决问题。本指南涵盖了常见问题及其解决方案，以最大限度地减少停机时间并恢复功能。

## 常见问题和解决方案
<a name="qbs-actions-troubleshooting-qbs-actions-common-issues"></a>

### 身份验证问题
<a name="qbs-actions-troubleshooting-qbs-actions-authentication-problems"></a>

#### 代币到期
<a name="qbs-actions-troubleshooting-qbs-actions-token-expiration"></a>

```
Symptom: "Authentication token expired" error
Resolution:
```

1. 在控制台中选择 “重新连接”。

1. 完成身份验证流程。

1. 重试操作。

#### 权限错误
<a name="qbs-actions-troubleshooting-qbs-actions-permission-errors"></a>

```
Symptom: "Insufficient permissions" message
Resolution:
```

1. 验证服务权限。

1. 检查连接器配置。

1. 查看行动要求。

#### 连接失败
<a name="qbs-actions-troubleshooting-qbs-actions-connection-failures"></a>

```
Symptom: "Unable to connect to service" error
Resolution:
```

1. 验证服务可用性。

1. 检查网络连接。

1. 验证凭据。

1. 查看 服务配额。

### 针对具体行动的问题
<a name="qbs-actions-troubleshooting-qbs-actions-action-specific-issues"></a>

#### 表单提交失败
<a name="qbs-actions-troubleshooting-qbs-actions-form-submission-failures"></a>

##### 验证错误
<a name="qbs-actions-troubleshooting-qbs-actions-validation-errors"></a>
+ 选中必填字段。
+ 验证数据格式。
+ 查看字段限制。
+ 检查是否有特殊字符。

##### 超时问题
<a name="qbs-actions-troubleshooting-qbs-actions-timeout-issues"></a>
+ 降低表单的复杂性。
+ 检查网络延迟。
+ 查看服务响应时间。
+ 考虑分成多个动作。

#### 同步和性能问题
<a name="qbs-actions-troubleshooting-qbs-actions-sync-performance-issues"></a>

##### 响应时间慢
<a name="qbs-actions-troubleshooting-qbs-actions-slow-response-times"></a>

```
Resolution:
```

1. 查看 API 速率限制。

1. 查看并发执行情况。

1. 监控服务运行状况。

1. 优化动作配置。

##### 失败的执行
<a name="qbs-actions-troubleshooting-qbs-actions-failed-executions"></a>

```
Resolution:
```

1. 查看 CloudWatch 日志。

1. 检查错误消息。

1. 验证服务状态。

1. 测试连接运行状况。

## 常见错误消息
<a name="qbs-actions-troubleshooting-qbs-actions-error-messages"></a>


**错误代码和分辨率**  

| 错误代码 | 说明 | 解决方案 | 
| --- | --- | --- | 
| AUTH\$1001 | 身份验证失败 | 验证凭证并重试 | 
| CONN\$1002 | 连接超时 | 检查网络和服务状态 | 
| PERM\$1003 | 权限不足 | 查看所需权限 | 
| TOKEN\$1004 | 令牌已过期 | 重新启动身份验证 |