As traduções são geradas por tradução automática. Em caso de conflito entre o conteúdo da tradução e da versão original em inglês, a versão em inglês prevalecerá.

# Conector de ação APIs
<a name="action-connector-apis"></a>

O Action Connector APIs permite criar e gerenciar programaticamente conexões entre o Amazon Quick e serviços externos. Eles APIs oferecem suporte à funcionalidade de integração de ações que permite aos usuários realizar ações em aplicativos de terceiros diretamente das interfaces de chat e fluxos de trabalho automatizados do Amazon Quick.

## O que são conectores de ação APIs?
<a name="action-connector-apis-overview"></a>

Os conectores de ação servem como recursos fundamentais que permitem a integração com aplicativos próprios e de terceiros. Por meio deles APIs, você pode se autenticar em aplicativos, gerenciar permissões e controlar quais ações estão disponíveis para os usuários em seus aplicativos Amazon Quick.

### Como o Action Connector APIs oferece suporte às integrações de ações
<a name="action-connector-apis-task-integrations"></a>

O Action Connector APIs fornece a infraestrutura de back-end para as integrações do Amazon Quick Action. Ao criar um conector de ação por meio da API, você estabelece uma conexão segura que permite:
+ Execute ações em serviços externos por meio de interfaces de bate-papo.
+ Execute fluxos de trabalho automatizados em processos em segundo plano.
+ Integre serviços de terceiros aos aplicativos Amazon Quick.
+ Gerencie a autenticação e as permissões para acesso ao serviço.

Eles APIs lidam com os complexos fluxos de autenticação, gerenciamento de credenciais e controles de permissão necessários para conectar com segurança o Amazon Quick a serviços externos.

## Métodos de autenticação
<a name="action-connector-apis-authentication"></a>

O Action Connector APIs oferece suporte a vários métodos de autenticação para acomodar diferentes casos de uso e requisitos de segurança:

### Autenticação gerenciada (3LO)
<a name="qbs-action-connector-apis-managed-auth"></a>

O Three-Legged OAuth fornece a configuração mais simples para acesso pessoal a serviços de terceiros:
+ Nenhuma configuração inicial é necessária.
+ Autenticação específica do usuário por meio do login do provedor de serviços.
+ Atualização automática de tokens com ciclo de vida de 90 dias.
+ Armazenamento seguro de credenciais gerenciado pelo Amazon Quick.

### Service-to-service autenticação (2LO)
<a name="qbs-action-connector-apis-service-auth"></a>

Para integrações corporativas complexas:
+ Oferece suporte ao OAuth fluxo de credenciais do cliente.
+ Permite system-to-system interações.
+ Requer configuração de ID do cliente, segredo do cliente e URL do token.
+ Adequado para fluxos de trabalho automatizados que exigem segurança sofisticada.
+ OAuth - Registro dinâmico de clientes (DCR - aplicável somente para servidores MCP selecionados).

### Autenticação de chave de API
<a name="qbs-action-connector-apis-api-key"></a>

Autenticação simplificada para fluxos de trabalho automatizados:
+ Autenticação baseada em token único.
+ Permissões de nível de serviço.
+ Ideal para processos em segundo plano e ações agendadas.
+ Requer uma chave de API válida do serviço de destino.

### Autenticação básica
<a name="qbs-action-connector-apis-basic-auth"></a>

A autenticação básica fornece um método username/password de autenticação simples:
+ Usa cabeçalhos de autenticação básica HTTP padrão.
+ As credenciais são codificadas em base64.
+ Adequado para serviços que não oferecem suporte OAuth ou chaves de API.
+ Requer conexão HTTPS segura.
+ Não recomendado para serviços voltados ao público.

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

Nenhuma autenticação é necessária:
+ Usado para públicos APIs e serviços.
+ Não são necessárias credenciais ou tokens.
+ Limitado a operações públicas ou somente para leitura.
+ Normalmente usado para feeds de dados públicos e documentação.
+ Não deve ser usado para operações confidenciais.

## Permissões e controle de acesso
<a name="qbs-action-connector-apis-permissions"></a>

O Action Connector APIs implementa controles de permissão abrangentes por meio de listas de controle de acesso (ACLs):

### Permissões em nível de recurso
<a name="qbs-action-connector-apis-resource-permissions"></a>
+ **Proprietário** - Controle total, incluindo exclusão e gerenciamento de permissões.
+ **Colaborador** - Pode usar e modificar as configurações do conector.
+ **Visualizador** - Pode visualizar detalhes do conector e usar ações habilitadas.

### Operações de API para gerenciamento de permissões
<a name="qbs-action-connector-apis-permission-operations"></a>
+ `DescribeActionConnectorPermissions`- Recupere as configurações de permissão atuais.
+ `UpdateActionConnectorPermissions`- Conceder ou revogar permissões de usuário.

## Categorias de conectores suportadas
<a name="qbs-action-connector-apis-categories"></a>

### Conectores de dupla finalidade
<a name="qbs-action-connector-apis-dual-purpose"></a>

Esses conectores oferecem suporte a integrações de ações e à criação de base de conhecimento:
+ **Amazon S3** — Use o Admin Console para criar ações para operações de arquivos, use o webapp para criar bases de conhecimento a partir do conteúdo do S3.
+ **Microsoft SharePoint** - Ações de gerenciamento de documentos, indexação de conteúdo.
+ **OneDrive**- Operações de arquivos, recursos de pesquisa de documentos.
+ **Confluence** — Ações de criação de conteúdo, integração da base de conhecimento.

### Conectores somente para ação
<a name="qbs-action-connector-apis-task-only"></a>

Especializado para execução de ações sem recursos de base de conhecimento:
+ **Salesforce** - Integração de CRM empresarial que suporta operações de contas e contatos, operações CRUD de objetos personalizados, automação de processos de vendas.
+ **JIRA** - Rastreamento de problemas e gerenciamento de projetos.
+ **Microsoft Outlook** - Envie e-mails, gerencie eventos do calendário, acesse contatos.
+ **Slack** - fluxos de trabalho de comunicação e notificação.
+ **ServiceNow**- Operações de gerenciamento de serviços de TI.
+ **Zendesk** — Crie tickets, atualize casos, pesquise na base de conhecimento.
+ **PagerDuty**- Crie incidentes, gerencie escalonamentos, atualize os horários de plantão.
+ **Asana** - Crie ações, atualize projetos, gerencie fluxos de trabalho da equipe.
+ **BambooHR** - Acesse dados de funcionários, gerencie solicitações de folga.
+ **Smartsheet** - Atualize planilhas, gerencie dados do projeto.
+ **FactSet**- Acesse dados financeiros, gere relatórios.
+ **SAP** - Acesse sistemas SAP, execute funções de negócios e gerencie dados corporativos.

### Conectores somente da base de conhecimento
<a name="qbs-action-connector-apis-data-only"></a>

Focado na integração da base de conhecimento sem recursos de ação:
+ **Google Drive** - indexação e pesquisa de documentos.
+ **Web Crawler** - descoberta e indexação de conteúdo.

## Gerenciamento do ciclo de vida da API
<a name="qbs-action-connector-apis-lifecycle"></a>

### Gerenciamento de credenciais
<a name="qbs-action-connector-apis-credential-management"></a>
+ Manipulação automática de tokens de atualização para conectores de OAuth ação.
+ Armazenamento seguro de credenciais de autenticação usando AWS KMS.
+ Support para rotação e atualizações de credenciais.
+ Acesso entre contas para conectores Amazon S3.

### Atualizações de conexão
<a name="qbs-action-connector-apis-connection-updates"></a>

Use a `UpdateActionConnector` API para:
+ Modifique as credenciais de autenticação.
+ Atualize os parâmetros de configuração do serviço.
+ Altere os metadados do conector de ação.

### Monitoramento e solução de problemas
<a name="qbs-action-connector-apis-monitoring"></a>
+ Acompanhe o uso da API por meio de CloudWatch métricas.
+ Monitore a integridade da conexão e o status da autenticação.
+ Implemente o tratamento de erros para cenários de falha comuns.
+ Use APIs a validação para diagnosticar problemas de configuração.

## Limitação de tarifas e cotas
<a name="qbs-action-connector-apis-rate-limiting"></a>

O Action Connector APIs implementa a limitação de taxa de AWS API padrão:
+ A AWS limitação padrão da API se aplica a todas as operações.
+ A validação da conexão pode ter limites adicionais.
+ As taxas de execução da ação dependem dos recursos do serviço alvo.
+ Implemente o recuo exponencial para a lógica de repetição.

## Suporte entre contas.
<a name="qbs-action-connector-apis-cross-account"></a>

Para conectores Amazon S3, eles APIs oferecem suporte ao acesso entre contas:
+ Especifique uma AWS conta diferente IDs durante a criação do conector.
+ Configure as permissões apropriadas do IAM para acesso entre contas.
+ Use AWS KMS para gerenciamento seguro de credenciais em todas as contas.
+ Valide as permissões antes de ativar conexões entre contas.

## Tratamento de erros e solução de problemas
<a name="qbs-action-connector-apis-error-handling"></a>

O conector de ação APIs retorna respostas AWS de erro padrão:

### Tipos de erro comuns
<a name="qbs-action-connector-apis-common-errors"></a>
+ `AccessDeniedException`- Permissões insuficientes para a operação.
+ `InvalidParameterValueException`- Um ou mais valores de parâmetros são inválidos para a operação.
+ Parâmetros de configuração inválidos - os valores de configuração específicos do serviço estão incorretos ou ausentes.
+ `ResourceNotFoundException`- Conector ou recurso não encontrado.
+ `ThrottlingException`- Limite de taxa excedido.
+ `ConflictException`- Conflito de recursos ou nomes duplicados.
+ `InternalFailureException`- Ocorreu um erro de serviço interno durante o processamento da solicitação.
+ `ResourceExistsException`- Tentativa de criar um recurso que já existe.
+ `InvalidNextTokenException`- O token de paginação fornecido é inválido ou expirou.
+ `AccessTokenNotFoundException`- O usuário precisa autorizar a conexão (ou seja, botão de assinatura). Essa exceção é usada pela UX para solicitar autorização aos usuários.
+ `TokenResponseException`- A configuração da ação não é válida.

Implemente o tratamento adequado de erros em seus aplicativos para gerenciar esses cenários com elegância e fornecer feedback significativo aos usuários.

## Usando o Action Connector APIs com AWS CLI
<a name="qbs-action-connector-apis-cli-examples"></a>

Você pode usar a AWS CLI para gerenciar os conectores de ação de forma programática. Os exemplos a seguir demonstram operações comuns usando valores genéricos de espaço reservado.

### Criando um conector de ação
<a name="create-action-connector-cli"></a>

Use o `create-action-connector` comando para criar um novo conector de ação para integração com serviços externos.

```
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"
```

### Listando conectores de ação
<a name="list-action-connectors-cli"></a>

Use o `list-action-connectors` comando para recuperar todos os conectores de ação em sua conta.

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

### Descrevendo um conector de ação
<a name="describe-action-connector-cli"></a>

Use o `describe-action-connector` comando para obter informações detalhadas sobre um conector de ação específico.

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

### Atualizando um conector de ação
<a name="update-action-connector-cli"></a>

Use o `update-action-connector` comando para modificar a configuração de um conector de ação existente.

```
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"
```

### Pesquisando conectores de ação
<a name="search-action-connectors-cli"></a>

Use o `search-action-connectors` comando para encontrar conectores de ação com base em critérios específicos.

```
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"
```

### Gerenciando permissões do conector de ação
<a name="update-action-connector-permissions-cli"></a>

Use o `update-action-connector-permissions` comando para conceder ou revogar permissões para um conector de ação.

```
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"
```

### Visualizando permissões do conector de ação
<a name="describe-action-connector-permissions-cli"></a>

Use o `describe-action-connector-permissions` comando para visualizar as permissões atuais de um conector de ação.

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

### Excluindo um conector de ação
<a name="delete-action-connector-cli"></a>

Use o `delete-action-connector` comando para remover um conector de ação da sua conta.

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

## Próximas etapas
<a name="qbs-action-connector-apis-next-steps"></a>

Depois de entender o conector de ação APIs, você pode:
+ Consulte a documentação completa de referência da API para obter especificações detalhadas dos parâmetros.
+ Explore guias de configuração de conectores específicos para seus serviços de destino.
+ Implemente fluxos de autenticação apropriados para seu caso de uso.
+ Configure o monitoramento e o tratamento de erros para implantações de produção.
+ Configure permissões e controles de acesso para sua organização.