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

# 动作连接器 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 参考文档，了解详细的参数规范。
+ 浏览目标服务的特定连接器设置指南。
+ 实施适合您的用例的身份验证流程。
+ 为生产部署设置监控和错误处理。
+ 为您的组织配置权限和访问控制。