本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。

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

動作連接器 APIs 可讓您以程式設計方式建立和管理 Amazon Quick 和外部服務之間的連線。這些 APIs支援動作整合功能，可讓使用者直接從 Amazon Quick Chat 介面和自動化工作流程在第三方應用程式中執行動作。

## 什麼是動作連接器 APIs？
<a name="action-connector-apis-overview"></a>

動作連接器可做為與第一個和第三方應用程式整合的基礎資源。透過這些 APIs，您可以對應用程式進行身分驗證、管理許可，以及控制哪些動作可供 Amazon Quick 應用程式內的使用者使用。

### 動作連接器 APIs如何支援動作整合
<a name="action-connector-apis-task-integrations"></a>

動作連接器 APIs為 Amazon Quick 動作整合提供後端基礎設施。當您透過 API 建立動作連接器時，您可以建立安全連線，讓您：
+ 透過聊天介面在外部服務中執行動作。
+ 在背景程序中執行自動化工作流程。
+ 將第三方服務與 Amazon Quick 應用程式整合。
+ 管理服務存取的身分驗證和許可。

APIs 可處理安全連接 Amazon Quick 與外部服務所需的複雜身分驗證流程、憑證管理和許可控制。

## 身分驗證方法
<a name="action-connector-apis-authentication"></a>

動作連接器 APIs支援多種身分驗證方法，以適應不同的使用案例和安全性需求：

### 受管身分驗證 (3LO)
<a name="qbs-action-connector-apis-managed-auth"></a>

三引號 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>

基本身分驗證提供簡單的使用者名稱/密碼身分驗證方法：
+ 使用標準 HTTP 基本身分驗證標頭。
+ 登入資料是 base64 編碼。
+ 適用於不支援 OAuth 或 API 金鑰的服務。
+ 需要安全的 HTTPS 連線。
+ 不建議用於公開的服務。

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

不需要身分驗證：
+ 用於公有 APIs和服務。
+ 不需要登入資料或字符。
+ 僅限唯讀或公有操作。
+ 通常用於公有資料摘要和文件。
+ 不應用於敏感操作。

## 許可和存取控制
<a name="qbs-action-connector-apis-permissions"></a>

動作連接器 APIs 透過存取控制清單 (ACLs) 實作全面的許可控制：

### 資源層級許可
<a name="qbs-action-connector-apis-resource-permissions"></a>
+ **擁有者** - 完全控制，包括刪除和許可管理。
+ **貢獻者** - 可以使用和修改連接器設定。
+ **檢視器** - 可以檢視連接器詳細資訊並使用啟用的動作。

### 用於許可管理的 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** - 使用管理員主控台建立檔案操作的動作，使用 webapp 從 S3 內容建立知識庫。
+ **Microsoft SharePoint** - 文件管理動作、內容索引。
+ **OneDrive** - 檔案操作、文件搜尋功能。
+ **Confluence** - 內容建立動作、知識庫整合。

### 僅限動作的連接器
<a name="qbs-action-connector-apis-task-only"></a>

專門用於沒有知識庫功能的動作執行：
+ **Salesforce** - 支援帳戶和聯絡人操作、自訂物件 CRUD 操作、銷售程序自動化的企業 CRM 整合。
+ **JIRA** - 問題追蹤和專案管理。
+ **Microsoft Outlook** - 傳送電子郵件、管理行事曆事件、存取聯絡人。
+ **Slack** - 通訊和通知工作流程。
+ **ServiceNow** - IT 服務管理操作。
+ **Zendesk** - 建立票證、更新案例、搜尋知識庫。
+ **PagerDuty** - 建立事件、管理呈報、更新通話中排程。
+ **Asana** - 建立動作、更新專案、管理團隊工作流程。
+ **BambooHR** - 存取員工資料、管理休假請求。
+ **智慧工作表** - 更新工作表、管理專案資料。
+ **FactSet** - 存取財務資料、產生報告。
+ **SAP** - 存取 SAP 系統、執行業務功能和管理企業資料。

### 僅限知識庫的連接器
<a name="qbs-action-connector-apis-data-only"></a>

專注於無動作功能的知識庫整合：
+ **Google Drive** - 文件索引和搜尋。
+ **Web 爬蟲程式** - 內容探索和索引。

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

### 憑證管理
<a name="qbs-action-connector-apis-credential-management"></a>
+ OAuth 動作連接器的自動重新整理字符處理。
+ 使用 安全儲存身分驗證憑證 AWS KMS。
+ 支援登入資料輪換和更新。
+ 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支援跨帳戶存取：
+ 在連接器建立期間指定不同的 AWS 帳戶 IDs。
+ 為跨帳戶存取設定適當的 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` - 動作設定無效。

在應用程式中實作適當的錯誤處理，以正常管理這些案例，並向使用者提供有意義的意見回饋。

## 搭配 CLI AWS 使用動作連接器 APIs
<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 參考文件，以取得詳細的參數規格。
+ 探索目標服務的特定連接器設定指南。
+ 實作適合您使用案例的身分驗證流程。
+ 設定生產部署的監控和錯誤處理。
+ 為您的組織設定許可和存取控制。