기계 번역으로 제공되는 번역입니다. 제공된 번역과 원본 영어의 내용이 상충하는 경우에는 영어 버전이 우선합니다.

# 작업 커넥터 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>

작업 커넥터 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>

3레깅 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** - 관리 콘솔을 사용하여 파일 작업에 대한 작업을 생성하고 웹 앱을 사용하여 S3 콘텐츠에서 지식 기반을 생성합니다.
+ **Microsoft SharePoint** - 문서 관리 작업, 콘텐츠 인덱싱.
+ **OneDrive** - 파일 작업, 문서 검색 기능.
+ **Confluence** - 콘텐츠 생성 작업, 지식 기반 통합.

### 작업 전용 커넥터
<a name="qbs-action-connector-apis-task-only"></a>

지식 기반 기능이 없는 작업 실행을 위한 전문 지식:
+ **Salesforce** - 계정 및 고객 응대 작업을 지원하는 엔터프라이즈 CRM 통합, 사용자 지정 객체 CRUD 작업, 영업 프로세스 자동화.
+ **JIRA** - 문제 추적 및 프로젝트 관리.
+ **Microsoft Outlook** - 이메일 전송, 일정 이벤트 관리, 연락처 액세스.
+ **Slack** - 통신 및 알림 워크플로.
+ **ServiceNow** - IT 서비스 관리 작업.
+ **Zendesk** - 티켓 생성, 사례 업데이트, 지식 기반 검색.
+ **PagerDuty** - 인시던트를 생성하고, 에스컬레이션을 관리하고, 대기 일정을 업데이트합니다.
+ **Asana** - 작업을 생성하고, 프로젝트를 업데이트하고, 팀 워크플로를 관리합니다.
+ **BambooHR** - 직원 데이터에 액세스하고 휴가 요청을 관리합니다.
+ **Smartsheet** - 시트를 업데이트하고 프로젝트 데이터를 관리합니다.
+ **FactSet** - 재무 데이터에 액세스하고 보고서를 생성합니다.
+ **SAP** - SAP 시스템에 액세스하고, 비즈니스 기능을 실행하고, 엔터프라이즈 데이터를 관리합니다.

### 지식 기반 전용 커넥터
<a name="qbs-action-connector-apis-data-only"></a>

작업 기능이 없는 지식 기반 통합에 중점을 둡니다.
+ **Google Drive** - 문서 인덱싱 및 검색.
+ **웹 크롤러** - 콘텐츠 검색 및 인덱싱.

## 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` - 작업 설정이 유효하지 않습니다.

애플리케이션에서 적절한 오류 처리를 구현하여 이러한 시나리오를 정상적으로 관리하고 사용자에게 의미 있는 피드백을 제공합니다.

## AWS CLI에서 작업 커넥터 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 참조 설명서를 검토하세요.
+ 대상 서비스에 대한 특정 커넥터 설정 가이드를 살펴봅니다.
+ 사용 사례에 적합한 인증 흐름을 구현합니다.
+ 프로덕션 배포에 대한 모니터링 및 오류 처리를 설정합니다.
+ 조직에 대한 권한 및 액세스 제어를 구성합니다.