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á.

# Conectores de ação
<a name="action-integrations"></a>

Os conectores de ação usam conexões seguras com serviços externos e executam ações com base em seu nível de autenticação e permissões.

# Como funcionam os conectores de ação
<a name="int-actions-how-it-works"></a>

Os conectores de ação no Amazon Quick criam conexões seguras entre o Amazon Quick e serviços externos. Ao configurar essas integrações, você pode realizar ações com base no seu nível de autenticação e nas permissões.

## Componentes principais
<a name="qbs-actions-how-it-works-qbs-actions-core-components"></a>

**Conectores de ação**  
Os recursos fundamentais que se integram aos serviços externos. O Amazon Quick oferece suporte a 15 integrações de terceiros e 5 integrações AWS de serviços. Para obter informações sobre como configurar conectores de ação de serviço AWS integrados, consulte[AWS conectores de ação de serviço](builtin-services-integration.md).

**Métodos de autenticação**  
Os conectores de ação oferecem suporte a vários métodos de autenticação, incluindo gerenciado (3LO), personalizado baseado no usuário, chave de API e 2LO. Para obter informações detalhadas sobre cada método de autenticação, consulte[Métodos de autenticação](action-connector-apis.md#action-connector-apis-authentication).

**Tipos de implementação**  
+ **Ações sob demanda para operações imediatas acionadas pelo usuário - operações** em tempo real que são executadas imediatamente quando você as aciona. Você pode iniciar ações por meio de interfaces de bate-papo, painéis ou Amazon Q Apps. Os exemplos incluem a criação de tickets, o envio de mensagens ou a consulta de dados.
+ **Fluxos de trabalho automatizados para tarefas agendadas ou acionadas pelo sistema** - operações gerenciadas pelo sistema que são executadas com base em agendamentos ou acionadores. Eles são executados em segundo plano sem a intervenção do usuário. Os exemplos incluem sincronização de dados, geração de relatórios ou manutenção do sistema.

**Modelos de permissão**  
+ **Permissões de acesso pessoal por meio do 3LO** - Você pode conceder permissões específicas ao Amazon Quick por meio do Three-Legged OAuth, mantendo o controle sobre o acesso ao serviço. As permissões estão vinculadas à sua identidade e credenciais no serviço de destino.
+ **Permissões em nível de serviço para fluxos de trabalho automatizados - Aplicadas a fluxos** de trabalho automatizados, essas permissões oferecem suporte a system-to-system interações sem o envolvimento do usuário. Eles são configurados no nível do serviço e normalmente usam chaves de API ou credenciais da conta de serviço.
+ **Controles de acesso em nível de entidade - Controle** o acesso às ações no Amazon Quick, determinando quais usuários ou grupos podem executar ações específicas. Esses controles se integram ao sistema de permissões mais amplo do Amazon Quick para um gerenciamento consistente de acesso em toda a plataforma.

# Tipos de ações
<a name="int-actions-types"></a>

O Amazon Quick oferece suporte a dois métodos de invocação de ações, cada um atendendo a diferentes casos de uso e modelos de autenticação.

## Ações sob demanda
<a name="qbs-actions-types-qbs-actions-on-demand"></a>

As ações sob demanda são executadas imediatamente quando você as aciona. Essas ações oferecem suporte a operações interativas que exigem resposta em tempo real.

**Características principais:**
+ Execução iniciada pelo usuário - Você aciona ações por meio de linguagem natural na interface de bate-papo.
+ Preenchimento interativo do formulário - Você preenche os formulários com os parâmetros necessários antes que a ação seja executada.
+ Resposta imediata - As ações são executadas em tempo real e fornecem feedback instantâneo sobre o sucesso ou o fracasso.
+ Autenticação pessoal (3LO) - usa suas credenciais e permissões individuais do serviço de destino.

**Casos de uso comuns:**
+ Criação de tickets no Jira.
+ Envio de mensagens no Slack.
+ Atualização de registros do Salesforce.
+ Recuperando informações de SharePoint.

## Fluxos de trabalho automatizados
<a name="qbs-actions-types-qbs-actions-automated-workflows"></a>

Os fluxos de trabalho automatizados executam ações em um cronograma ou em resposta a acionadores específicos. Eles são úteis para operações em segundo plano e no nível do sistema.

**Características principais:**
+ Execução no nível do sistema: as ações são executadas automaticamente sem a intervenção do usuário com base em acionadores predefinidos.
+ Agendado ou acionado por eventos - Execute em horários baseados em horários ou em resposta a eventos específicos do sistema.
+ Operação não interativa - Execute em segundo plano sem exigir a entrada do usuário ou o preenchimento do formulário.
+ Autenticação em nível de serviço - use credenciais do sistema em vez da autenticação de usuário individual.

**Casos de uso comuns:**
+ Sincronização regular de dados.
+ Geração programada de relatórios.
+ Atualizações automatizadas de tíquetes.
+ Verificações de integridade do sistema.

# Agentes limitados e ilimitados
<a name="int-actions-bounded-unbounded"></a>

O Amazon Quick oferece dois tipos de agentes que fornecem níveis diferentes de acesso e funcionalidade: agentes limitados e ilimitados. Entender as diferenças entre esses tipos de agentes ajuda você a implementar a solução certa para seu caso de uso.

## Agentes vinculados
<a name="qbs-actions-bounded-unbounded-qbs-actions-bounded-agents"></a>

Os agentes vinculados operam dentro de parâmetros definidos, especificamente vinculados a um ou mais espaços no Amazon Quick. Esses agentes só podem acessar e realizar ações em recursos que estejam explicitamente conectados aos espaços atribuídos. Por exemplo, um agente limitado configurado para o espaço de RH só pode acessar documentos relacionados ao RH, conjuntos de dados e executar ações relacionadas ao RH.

Use agentes limitados para:
+ Fluxos de trabalho específicos do departamento (RH, Finanças, TI).
+ Colaborações da equipe do projeto.
+ Tratamento de dados confidenciais.
+ Operações focadas na conformidade.

A natureza limitada fornece segurança aprimorada ao garantir que o agente não possa acessar recursos fora dos espaços designados. Isso o torna ideal para cenários em que o isolamento de dados é importante.

## Agentes ilimitados
<a name="qbs-actions-bounded-unbounded-qbs-actions-unbounded-agents"></a>

Agentes ilimitados têm recursos de acesso mais amplos e podem trabalhar em todas as ações e recursos configurados no ambiente Amazon Quick. Esses agentes não estão restritos a espaços específicos e podem acessar qualquer conector de ação devidamente configurado disponível no sistema.

Use agentes ilimitados para:
+ Assistência em toda a organização.
+ Fluxos de trabalho interdepartamentais.
+ Ações de uso geral.
+ Cenários que exigem acesso a vários sistemas.

# Pré-requisitos
<a name="int-actions-prerequisites"></a>

Antes de usar ações no Amazon Quick, verifique se você tem o seguinte:

## Requisitos de licença
<a name="qbs-actions-prerequisites-qbs-actions-license-requirements"></a>

Uma das seguintes licenças do Amazon Quick:
+ Reader Pro - Fornece acesso de leitura aos dados e a capacidade de executar ações em serviços conectados.
+ Autor - Inclui recursos do Reader Pro, além da capacidade de criar e modificar conteúdo e configurações.
+ Author Pro - Acesso completo aos recursos, incluindo configuração avançada de ações e recursos administrativos.

## Requisitos de serviço
<a name="qbs-actions-prerequisites-qbs-actions-service-requirements"></a>

Para serviços de terceiros (como Jira ou Salesforce), certifique-se de ter:
+ Permissões apropriadas nos serviços de destino.
+ Credenciais de autenticação para cada serviço.

Para conectores de AWS ação, você precisa de acesso administrativo aos serviços relevantes.

## AWS requisitos de conta
<a name="qbs-actions-prerequisites-qbs-actions-aws-account-requirements"></a>
+  AWS Conta ativa - Uma AWS conta válida com cobrança ativada e em situação regular.
+ Permissões apropriadas do IAM — funções e políticas do IAM que permitem que o Amazon Quick acesse os AWS serviços necessários.
+ Cotas de serviço necessárias - Limites de serviço suficientes para os AWS serviços que você planeja integrar às suas ações.

# Tipos de conectores de ação compatíveis e ações disponíveis
<a name="action-connector-apis-supported-types"></a>

O Amazon Quick oferece suporte a vários tipos de conectores, cada um com ações específicas disponíveis:

## Conectores de serviço externos
<a name="action-connector-apis-external-services"></a>
+ **Salesforce** - Crie registros, atualize oportunidades, pesquise contas, gerencie leads.
+ **JIRA** - Crie problemas, atualize tickets, pesquise projetos, gerencie fluxos de trabalho.
+ **Microsoft Outlook** - Envie e-mails, gerencie eventos do calendário, acesse contatos.
+ **Slack** - Envie mensagens, crie canais, gerencie notificações.
+ **ServiceNow**- Crie incidentes, atualize solicitações, gerencie fluxos de trabalho.
+ **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.
+ **Caixa** - Gerencie arquivos, pastas e colabore em documentos.
+ **Canva** - Crie e edite designs, gerencie modelos e ativos.
+ **FactSet**- Acesse dados financeiros, gere relatórios.
+ **GitHub**- Gerencie repositórios, problemas, pull requests e colaboração de código.
+ **HuggingFace**- Acesse modelos de IA, conjuntos de dados e fluxos de trabalho de aprendizado de máquina.
+ **HubSpot**- Gerencie contatos, negócios, campanhas de marketing e dados de CRM.
+ **Intercom** - Gerencie conversas com clientes, tickets de suporte e mensagens.
+ **Linear** - Crie e gerencie problemas, projetos e fluxos de trabalho de desenvolvimento.
+ **Segunda-feira** - Gerencie projetos, tarefas e fluxos de trabalho de colaboração em equipe.
+ **Noção** - Crie e gerencie páginas, bancos de dados e espaços de trabalho colaborativos.
+ **Smartsheet** - Atualize planilhas, gerencie dados do projeto.
+ **Confluence** - Crie, atualize e gerencie páginas, espaços e outros objetos do Confluence.
+ **SharePoint**- Execute ações em SharePoint listas, itens e arquivos do Excel com 19 ações disponíveis para criar, atualizar, excluir e recuperar conteúdo SharePoint .
+ **OneDrive**- Crie, atualize, exclua e gerencie OneDrive arquivos e pastas.
+ **SAP** - Acesse os sistemas SAP S/4HANA para realizar operações somente de leitura em dados corporativos.

## AWS conectores de serviço
<a name="action-connector-apis-aws-services"></a>
+ **Amazon S3** — Faça upload de arquivos, gerencie buckets, recupere objetos.
+ **Amazon Bedrock** — gere conteúdo, analise dados, processe solicitações.
+ **Amazon Textract** — Extraia texto e dados de documentos.
+ **Amazon Comprehend** — Processamento de linguagem natural e análise de sentimentos.
+ **Amazon Comprehend Medical — Análise de texto médico** e extração de entidades.

## Matriz de compatibilidade do conector de ação
<a name="action-connector-compatibility-matrix"></a>

A tabela a seguir mostra quais recursos do Amazon Quick são compatíveis com cada tipo de conector de ação:


**Compatibilidade do recurso Action Connector**  

| Conector de ação | Agentes de bate-papo | Fluxos | Visuais do painel | Alertas do painel | Automações | Companheiros | 
| --- | --- | --- | --- | --- | --- | --- | 
| AWS Serviços integrados | 
| AWS Tempo de execução do Bedrock Agent | — | — | — | — | ✓ | — | 
| AWS Tempo de execução da automação de dados Bedrock | — | — | — | — | ✓ | — | 
| AWS Tempo de execução do Bedrock | — | — | — | — | ✓ | — | 
| Amazon Comprehend | — | — | — | — | ✓ | — | 
| Amazon Comprehend Medical | — | — | — | — | — | — | 
| Amazon S3 | — | — | — | — | ✓ | — | 
| Amazon Textract | — | — | — | — | ✓ | — | 
| Conectores de serviço externo | 
| Asana | ✓ | ✓ | — | — | — | ✓ | 
| Atlassian Confluence Cloud | ✓ | ✓ | — | — | ✓ | ✓ | 
| Atlassian Jira Cloud | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | 
| BambooHR | ✓ | ✓ | — | — | — | ✓ | 
| Box | ✓ | ✓ | — | — | — | — | 
| Canva | ✓ | ✓ | — | — | — | — | 
| FactSet | ✓ | ✓ | — | — | — | — | 
| GitHub | ✓ | ✓ | — | — | — | — | 
| HuggingFace | ✓ | ✓ | — | — | — | — | 
| HubSpot | ✓ | ✓ | — | — | — | — | 
| Intercom | ✓ | ✓ | — | — | — | — | 
| Linear | ✓ | ✓ | — | — | — | — | 
| Segunda-feira | ✓ | ✓ | — | — | — | — | 
| Noção | ✓ | ✓ | — | — | — | — | 
| Microsoft OneDrive | ✓ | ✓ | — | — | ✓ | ✓ | 
| Microsoft Outlook | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | 
| Microsoft SharePoint | ✓ | ✓ | — | — | ✓ | ✓ | 
| Microsoft Teams | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | 
| PagerDuty | ✓ | ✓ | — | — | ✓ | ✓ | 
| Salesforce | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | 
| SAP | ✓ | — | — | — | ✓ | ✓ | 
| ServiceNow | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | 
| Slack | ✓ | ✓ | ✓ | — | — | ✓ | 
| Smartsheet | ✓ | ✓ | — | — | — | ✓ | 
| Zendesk | ✓ | ✓ | — | — | — | ✓ | 
| Tipos de conectores personalizados | 
| Protocolo de contexto para modelos (MCP) | ✓ | ✓ | — | — | ✓ | — | 
| OpenAPI | ✓ | ✓ | — | — | — | — | 
| API REST | — | — | — | — | ✓ | — | 

**Support de autenticação:**
+ **Agentes e acompanhantes de bate-papo** - Support a autenticação do usuário (3LO, Basic)
+ **Dashboard Visuals** - Support user authentication (3LO)
+ **Alertas do painel** - Support system authentication (2LO ou API Key)
+ **Automations** - Support system authentication (2LO)

# 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.

# Métodos de autenticação
<a name="quick-action-auth"></a>

O Amazon Quick oferece suporte a vários métodos de autenticação, cada um projetado para casos de uso e requisitos de segurança específicos.

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

Three-Legged OAuth (3LO) é o método de autenticação recomendado para acesso pessoal a serviços de terceiros.

**Principais características do 3LO:**
+ Nenhuma configuração inicial é necessária.
+ Autenticação específica do usuário.
+ Armazenamento seguro de credenciais.
+ Atualização automática de tokens.
+ Ciclo de vida do token de atualização de 90 dias.

**Processo de configuração do 3LO:**

1. Selecione o conector.

1. Escolha a autenticação gerenciada.

1. Login completo do provedor de serviços.

1. Conceda as permissões solicitadas.

1. Confirme a conexão.

## Autenticação personalizada baseada no usuário
<a name="quick-custom-user-auth"></a>

Para cenários que exigem controle organizacional específico ou configuração personalizada.

**Informações necessárias:**
+ ID do cliente.
+ Segredo do cliente.
+ URL do domínio.
+ URL de autorização.
+ URL do token.
+ URL de redirecionamento.

**Etapas de configuração:**

1. Obtenha credenciais do provedor de serviços.

1. Defina as configurações de autenticação.

1. Valide a conexão.

1. Teste as permissões de acesso.

Ao configurar a autenticação baseada no usuário no console do Amazon Quick, obtenha as credenciais adequadas do seu provedor de serviços e defina suas configurações de autenticação. Em seguida, valide a conexão e teste suas permissões de acesso.

## Autenticação de chave de API
<a name="quick-actions-api-key-auth"></a>

Usado principalmente para fluxos de trabalho automatizados e acesso em nível de sistema.

**Principais atributos:**
+ Autenticação simples baseada em tokens.
+ Gerenciamento único de credenciais.
+ Permissões de nível de serviço.
+ Adequado para processos automatizados.

**Requisitos de configuração:**

Ao configurar a autenticação por chave de API, verifique se você tem o seguinte:
+ Chave de API válida do serviço.
+ Permissões de serviço apropriadas.
+ Configuração de armazenamento secreto.

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

Para fluxos de trabalho automatizados que exigem autenticação complexa.

**Requisitos de configuração:**
+ ID do cliente.
+ Segredo do cliente.
+ URL do domínio.
+ URL do token.
+ Parâmetros específicos do serviço.

# Métodos de execução de ações
<a name="int-actions-execution"></a>

O Amazon Quick fornece várias maneiras de executar ações, acomodando diferentes casos de uso e preferências de interação.

## Interface de bate-papo
<a name="qbs-actions-execution-qbs-actions-chat-interface"></a>

Você pode executar ações implícitas no Amazon Quick Chat.

### Ações implícitas
<a name="qbs-actions-execution-qbs-actions-implicit-actions"></a>

O Amazon Quick também oferece suporte à execução de ações implícitas por meio de conversas naturais com agentes. Usando processamento avançado de linguagem natural, o sistema pode identificar quando sua conversa indica a necessidade de ações específicas. As conversas são analisadas para determinar quais ações são necessárias para atender à sua solicitação.

Uma única solicitação pode exigir várias ações para ser concluída. Quando isso acontece, o sistema manipula essas ações sequencialmente, orientando você em cada etapa. Para cada ação identificada, o sistema apresenta o formulário apropriado para você preencher. Depois que cada ação for concluída, você receberá uma confirmação antes de passar para a próxima ação na sequência.

Por exemplo, se você perguntar “Crie um ticket do Jira para esse problema e notifique a equipe no Slack”, o sistema:

1. Primeiro, apresente o formulário de criação de tíquetes do Jira.

1. Depois de concluir a criação do ticket, mostre o formulário de mensagem do Slack.

1. Conclua as duas ações em sequência.

Durante todo o processo, você pode acompanhar seu progresso por meio de várias ações. Quando todas as ações são concluídas, o sistema fornece um resumo abrangente mostrando todas as ações executadas e seus resultados. Você pode acessar a documentação relacionada, se necessário, e revisar quaisquer estados de erro que possam ter ocorrido durante o processo.

# Monitoramento e manutenção
<a name="int-actions-monitoring"></a>

O monitoramento de seus conectores de ação ajuda a garantir um desempenho confiável e a identificar problemas antes que eles afetem os usuários. O monitoramento regular permite rastrear padrões de uso, otimizar o desempenho e manter conexões saudáveis com serviços externos.

## Monitoramento do desempenho
<a name="qbs-actions-monitoring-qbs-actions-performance-monitoring"></a>

Você pode avaliar o desempenho do conector de ação usando as seguintes métricas e análises.

### CloudWatch métricas
<a name="qbs-actions-monitoring-qbs-actions-cloudwatch-metrics"></a>
+ Taxas de sucesso na execução de ações - Acompanhe a porcentagem de execuções de ações bem-sucedidas para identificar problemas de confiabilidade.
+ Tempos de resposta - Monitore quanto tempo as ações levam para serem concluídas e identificar gargalos de desempenho.
+ Frequências de erro - Acompanhe os padrões de erro para identificar pontos de falha comuns e áreas de melhoria.
+ Uso da cota da API - monitore o uso em relação aos limites do serviço para evitar a limitação e planeje a capacidade.

### Análise de uso
<a name="qbs-actions-monitoring-qbs-actions-usage-analytics"></a>

As seguintes análises de uso são coletadas para conectores de ação:
+ Usuários ativos - Acompanhe quantos usuários estão usando ativamente conectores de ação para entender os padrões de adoção e uso.
+ Ações populares - identifique quais ações são usadas com mais frequência para priorizar os esforços de otimização.
+ Padrões de execução - Analise quando e com que frequência as ações são executadas para otimizar a alocação de recursos.
+ Tendências de erro - monitore os padrões de erro ao longo do tempo para identificar problemas sistêmicos e oportunidades de melhoria.

## Integridade de conexão
<a name="qbs-actions-monitoring-qbs-actions-connection-health"></a>

Você pode avaliar a integridade do conector de ação usando as seguintes ferramentas de integridade da conexão:

### Monitoramento de status
<a name="qbs-actions-monitoring-qbs-actions-status-monitoring"></a>
+ Estado da conexão - Monitore se os conectores estão ativamente conectados e funcionando corretamente.
+ Validade da autenticação - Acompanhe o status dos tokens e credenciais de autenticação para evitar falhas de acesso.
+ Rastreamento da expiração do token - Monitore quando os tokens de autenticação expirarão e precisarão ser renovados.
+ Disponibilidade do serviço - Acompanhe a disponibilidade e o status da resposta dos serviços externos conectados.

### Manutenção automatizada
<a name="qbs-actions-monitoring-qbs-actions-automated-maintenance"></a>
+ Tratamento da atualização do token.
+ Recuperação da conexão.
+ Erro na lógica de repetição.
+ Otimização de desempenho.

## CloudWatch referência de métricas
<a name="qbs-actions-monitoring-qbs-actions-cloudwatch-metrics-table"></a>


**CloudWatch Métricas disponíveis**  

| Métrica | Description | Unidade | 
| --- | --- | --- | 
| ActionSuccess | Execuções bem-sucedidas | Contagem | 
| ActionLatency | Tempo de Execução | Milissegundos | 
| AuthFailures | Autenticações falhadas | Contagem | 
| APIThrottling | Eventos de limitação de API | Contagem | 

# Práticas recomendadas
<a name="int-actions-best-practices"></a>

Seguir as melhores práticas para conectores de ação ajuda a garantir operações seguras, confiáveis e eficientes. Essas práticas ajudam você a manter o desempenho ideal, proteger dados confidenciais e minimizar problemas operacionais.

## Segurança
<a name="qbs-actions-best-practices-qbs-actions-security-best-practices"></a>

### Gerenciamento de autenticação
<a name="qbs-actions-best-practices-qbs-actions-authentication-management"></a>
+ Rotação regular de credenciais - atualize as chaves e OAuth tokens da API de forma programada para manter a segurança.
+ Revisões periódicas de permissões - Audite as permissões de usuários e serviços trimestralmente para garantir o acesso com privilégios mínimos.
+ Monitoramento do ciclo de vida do token - Acompanhe as datas de expiração do token e configure alertas antes que as credenciais expirem.
+ Registro de auditoria de acesso - habilite um registro abrangente para rastrear quem acessou quais serviços e quando.

### Controle de acesso
<a name="qbs-actions-best-practices-qbs-actions-access-control"></a>
+ Implemente o acesso com privilégios mínimos - conceda somente as permissões mínimas necessárias para que cada ação funcione adequadamente.
+ Auditorias regulares de permissões - revise e valide se as permissões atuais estão alinhadas aos padrões reais de uso e às necessidades comerciais.
+ Padrões de acesso a documentos - mantenha uma documentação clara de quem tem acesso a quais conectores e por quê.
+ Monitore anomalias de uso - Configure alertas para padrões de acesso incomuns que possam indicar problemas de segurança.

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

### Configuração de ações
<a name="qbs-actions-best-practices-qbs-actions-action-configuration"></a>
+ Otimize os padrões do formulário - preencha previamente os valores comumente usados para reduzir o tempo de entrada e os erros do usuário.
+ Configure tempos limite apropriados - Defina valores de tempo limite realistas com base nos tempos de resposta típicos de cada serviço.
+ Configure o tratamento de erros - Implemente um tratamento robusto de erros com mensagens claras do usuário e uma lógica de repetição, quando apropriado.
+ Documente dependências - documente claramente quaisquer pré-requisitos ou dependências entre ações diferentes.

### Gerenciamento de recursos
<a name="qbs-actions-best-practices-qbs-actions-resource-management"></a>
+ Monitore as cotas da API.
+ Acompanhe os padrões de uso.
+ Otimize os cronogramas de atualização.
+ Limpeza regular de conectores não utilizados.

## Manutenção
<a name="qbs-actions-best-practices-qbs-actions-maintenance-best-practices"></a>

### Ações regulares
<a name="qbs-actions-best-practices-qbs-actions-regular-tasks"></a>
+ Revise o status do conector.
+ Atualize as configurações.
+ Valide as conexões.
+ Alterações no documento.

### Solução de problemas
<a name="qbs-actions-best-practices-qbs-actions-troubleshooting-tasks"></a>
+ Monitore os padrões de erro.
+ Revise CloudWatch os registros.
+ Monitore os tempos de resolução.
+ Soluções de documentos.

# Solução de problemas
<a name="int-actions-troubleshooting"></a>

Quando os conectores de ação encontram problemas, a solução sistemática de problemas ajuda você a identificar e resolver problemas rapidamente. Esta orientação aborda problemas comuns e suas soluções para minimizar o tempo de inatividade e restaurar a funcionalidade.

## Problemas e soluções comuns de
<a name="qbs-actions-troubleshooting-qbs-actions-common-issues"></a>

### Problemas de autenticação
<a name="qbs-actions-troubleshooting-qbs-actions-authentication-problems"></a>

#### Expiração do token
<a name="qbs-actions-troubleshooting-qbs-actions-token-expiration"></a>

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

1. Escolha “Reconectar” no console.

1. Fluxo completo de autenticação.

1. Repita a ação.

#### Erros de permissão
<a name="qbs-actions-troubleshooting-qbs-actions-permission-errors"></a>

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

1. Verifique as permissões do serviço.

1. Verifique a configuração do conector.

1. Analise os requisitos de ação.

#### Falhas de conexão
<a name="qbs-actions-troubleshooting-qbs-actions-connection-failures"></a>

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

1. Verifique a disponibilidade do serviço.

1. Verifique a conectividade da rede.

1. Valide as credenciais.

1. Analise as cotas de serviço do .

### Questões específicas da ação
<a name="qbs-actions-troubleshooting-qbs-actions-action-specific-issues"></a>

#### Falhas no envio do formulário
<a name="qbs-actions-troubleshooting-qbs-actions-form-submission-failures"></a>

##### Erros de validação
<a name="qbs-actions-troubleshooting-qbs-actions-validation-errors"></a>
+ Verifique os campos obrigatórios.
+ Verifique os formatos dos dados.
+ Revise as limitações do campo.
+ Verifique se há caracteres especiais.

##### Problemas de tempo limite
<a name="qbs-actions-troubleshooting-qbs-actions-timeout-issues"></a>
+ Reduza a complexidade do formulário.
+ Verifique a latência da rede.
+ Analise os tempos de resposta do serviço.
+ Considere realizar várias ações.

#### Problemas de sincronização e desempenho
<a name="qbs-actions-troubleshooting-qbs-actions-sync-performance-issues"></a>

##### Mostrar tempos de resposta
<a name="qbs-actions-troubleshooting-qbs-actions-slow-response-times"></a>

```
Resolution:
```

1. Verifique os limites de taxa da API.

1. Revise as execuções simultâneas.

1. Monitore a integridade do serviço.

1. Otimize a configuração da ação.

##### Execuções com falha
<a name="qbs-actions-troubleshooting-qbs-actions-failed-executions"></a>

```
Resolution:
```

1. Revise CloudWatch os registros.

1. Verifique as mensagens de erro.

1. Verifique o status do serviço.

1. Teste a integridade da conexão.

## Mensagens de erro comuns
<a name="qbs-actions-troubleshooting-qbs-actions-error-messages"></a>


**Códigos de erro e resoluções**  

| Código de erro | Description | Resolução | 
| --- | --- | --- | 
| AUTH\$1001 | Falha na autenticação | Verifique as credenciais e tente novamente | 
| CONN\$1002 | Tempo limite da conexão | Verifique o status da rede e do serviço | 
| PERM\$1003 | Permissões insuficientes | Revise as permissões necessárias | 
| TOKEN\$1004 | Token expirado | Reiniciar a autenticação |