# Conexão ao Kustomer
O Kustomer é uma poderosa plataforma de experiência do cliente que reúne tudo o que você precisa para atender melhor seus clientes em uma ferramenta fácil de usar.
**Topics**
+ [Suporte do AWS Glue para o Kustomer](kustomer-support.md)
+ [Políticas que contêm as operações de API para criar e usar conexões](kustomer-configuring-iam-permissions.md)
+ [Configuração do Kustomer](kustomer-configuring.md)
+ [Configuração de conexões do Kustomer](kustomer-configuring-connections.md)
+ [Leitura de entidades do Kustomer](kustomer-reading-from-entities.md)
+ [Opções de conexão do Kustomer](kustomer-connection-options.md)
+ [Limitações do Kustomer](kustomer-connection-limitations.md)
# Suporte do AWS Glue para o Kustomer
O AWS Glue oferece suporte ao Kustomer da seguinte forma:
**Compatível como fonte?**
Sim. Você pode usar trabalhos de ETL do AWS Glue para consultar dados do Kustomer.
**Compatível como destino?**
Não.
**Versões compatíveis da API do Kustomer**
Estas são as versões compatíveis da API do Kustomer:
+ v1
# Políticas que contêm as operações de API para criar e usar conexões
O exemplo de política a seguir descreve as permissões necessárias do AWS IAM para criar e usar conexões. Se você estiver criando um novo perfil, crie uma política que contenha o seguinte:
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"glue:ListConnectionTypes",
"glue:DescribeConnectionType",
"glue:RefreshOAuth2Tokens",
"glue:ListEntities",
"glue:DescribeEntity"
],
"Resource": "*"
}
]
}
```
------
Se você não quiser usar o método acima, como alternativa use as seguintes políticas do IAM gerenciadas:
+ [AWSGlueServiceRole](https://console.aws.amazon.com/iam/home#policies/arn:aws:iam::aws:policy/service-role/AWSGlueServiceRole) – Concede acesso a recursos que vários processos do AWS Glue exigem para fazer a execução em seu nome. Esses recursos incluem o AWS Glue, Amazon S3, IAM, CloudWatch Logs e Amazon EC2. Se você seguir a convenção de nomenclatura para os recursos especificados nesta política, os processos do AWS Glue terão as permissões necessárias. Esta política geralmente é anexada a funções especificadas durante a definição de crawlers, trabalhos e endpoints de desenvolvimento.
+ [AWSGlueConsoleFullAccess](https://console.aws.amazon.com/iam/home#policies/arn:aws:iam::aws:policy/AWSGlueConsoleFullAccess): concede acesso total aos recursos do AWS Glue quando uma identidade à qual a política está anexada usa o Console de Gerenciamento da AWS. Se você seguir a convenção de nomenclatura para os recursos especificados nesta política, os usuários poderão acessar todos os recursos do console. Esta política geralmente é anexada aos usuários do console do AWS Glue.
# Configuração do Kustomer
Antes de usar o AWS Glue para transferir dados do Kustomer aos destinos compatíveis, os seguintes requisitos deverão ser atendidos:
## Requisitos mínimos
Estes são os requisitos mínimos:
+ Você tem uma conta no Kustomer que contém os dados que deseja transferir.
+ Nas configurações da sua conta, você criou uma chave de API. Para obter mais informações, consulte [Criação de uma chave de API](#kustomer-configuring-creating-an-api-key).
+ Você fornece a chave de API para o AWS Glue ao criar a conexão.
Se você atender a esses requisitos, poderá conectar o AWS Glue à sua conta do Kustomer.
## Criação de uma chave de API
Para criar uma chave de API que você usará para criar uma conexão com o conector do Kustomer no AWS Glue Studio:
1. Faça login no [painel do Kustomer usando suas credenciais](https://amazon-appflow.kustomerapp.com/login).
1. No menu à esquerda, escolha o ícone **Settings**.
1. Expanda o menu suspenso **Security** e selecione **API Keys**.
1. Na página de criação da chave de API, selecione **Add an API Key** no canto superior direito.
1. Preencha as entradas obrigatórias para a chave de API que está sendo criada.
+ Name: qualquer nome para sua chave de API.
+ Roles: a opção “org” deve ser selecionada para que as APIs do Kustomer funcionem.
+ Expires (in days): o número de dias durante o qual você deseja que a chave de API seja válida. Você pode manter como **Never expires**, se a opção de nunca expirar for adequada para o seu caso de uso.
1. Escolha **Criar**.
1. Armazene o valor da chave de API (token) para uso posterior na criação de uma conexão com o conector do Kustomer no AWS Glue Studio.
# Configuração de conexões do Kustomer
Para configurar uma conexão do Kustomer:
1. No AWS Secrets Manager, crie um segredo com os seguintes detalhes:
1. Para a aplicação conectada gerenciada pelo cliente, o segredo deve conter o segredo do consumidor da aplicação conectada com a chave `apiKey`.
1. Observação: é necessário criar um segredo para a sua conexão no AWS Glue.
1. No AWS Glue Glue Studio, crie uma conexão em **Conexões de dados** seguindo estas etapas:
1. Em **Conexões**, escolha **Criar conexão**.
1. Ao selecionar uma **Fonte de dados**, selecione o Kustomer.
1. Selecione o perfil do AWS IAM que o AWS Glue pode assumir e tem permissões para as seguintes ações:
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"secretsmanager:DescribeSecret",
"secretsmanager:GetSecretValue",
"secretsmanager:PutSecretValue",
"ec2:CreateNetworkInterface",
"ec2:DescribeNetworkInterfaces",
"ec2:DeleteNetworkInterface"
],
"Resource": "*"
}
]
}
```
------
1. Selecione o `secretName` que você deseja usar para essa conexão no AWS Glue para colocar os tokens.
1. Selecione as opções de rede se quiser usar sua rede.
1. Conceda permissão ao perfil do IAM associado ao seu trabalho do AWS Glue para ler `secretName`.
# Leitura de entidades do Kustomer
**Pré-requisito**
Um objeto do Kustomer do qual você deseja ler. Você precisará do nome do objeto, como Marcas ou Cartões. A tabela a seguir mostra as entidades compatíveis.
**Entidades compatíveis quanto à origem**:
| Entidade | Pode ser filtrada | Oferece suporte a limite | Oferece suporte a Ordenar por | Oferece suporte a Selecionar \$1 | Oferece suporte a particionamento |
| --- | --- | --- | --- | --- | --- |
| Marcas | Não | Sim | Não | Sim | Não |
| Cartões | Não | Sim | Não | Sim | Não |
| Configurações de chat | Não | Não | Não | Sim | Não |
| Empresas | Sim | Sim | Sim | Sim | Sim |
| Conversas | Sim | Sim | Sim | Sim | Sim |
| Clientes | Sim | Sim | Sim | Sim | Sim |
| Pesquisas de clientes fixadas | Não | Sim | Não | Sim | Não |
| Posição das pesquisas de clientes | Não | Não | Não | Sim | Não |
| Hooks de e-mail | Não | Sim | Não | Sim | Não |
| Webhooks | Não | Sim | Não | Sim | Não |
| Artigos da base de conhecimento | Não | Sim | Não | Sim | Não |
| Categorias da base de conhecimento | Não | Sim | Não | Sim | Não |
| Formulários da base de conhecimento | Não | Sim | Não | Sim | Não |
| Rotas da base de conhecimento | Não | Sim | Não | Sim | Não |
| Tags da base de conhecimento | Não | Sim | Não | Sim | Não |
| Modelos da base de conhecimento | Não | Sim | Não | Sim | Não |
| Temas da base de conhecimento | Não | Sim | Não | Sim | Não |
| Klasses | Não | Sim | Não | Sim | Não |
| KViews | Não | Sim | Não | Sim | Não |
| Mensagens | Sim | Sim | Sim | Sim | Sim |
| Observações | Sim | Sim | Sim | Sim | Sim |
| Notificações | Não | Sim | Não | Sim | Não |
**Exemplo:**
```
Kustomer_read = glueContext.create_dynamic_frame.from_options(
connection_type="kustomer",
connection_options={
"connectionName": "connectionName",
"ENTITY_NAME": "brands",
"API_VERSION": "v1"
}
```
## Detalhes das entidades e dos campos do Kustomer
Para obter mais informações sobre os detalhes das entidades e dos campos, consulte:
+ [Marcas](https://api.kustomerapp.com/v1/brands)
+ [Cartões](https://api.kustomerapp.com/v1/cards)
+ [Configurações de chat](https://api.kustomerapp.com/v1/chat/settings)
+ [Empresas](https://api.kustomerapp.com/v1/companies)
+ [Conversas](https://api.kustomerapp.com/v1/conversations)
+ [Clientes](https://api.kustomerapp.com/v1/customers)
+ [Pesquisas de clientes fixadas](https://api.kustomerapp.com/v1/customers/searches/pinned)
+ [Posições das pesquisas de clientes](https://api.kustomerapp.com/v1/customers/searches/positions)
+ [Hooks de e-mail](https://api.kustomerapp.com/v1/hooks/email)
+ [Webhooks](https://api.kustomerapp.com/v1/hooks/web)
+ [Artigos da base de conhecimento](https://api.kustomerapp.com/v1/kb/articles)
+ [Categorias da base de conhecimento](https://api.kustomerapp.com/v1/kb/categories)
+ [Formulários da base de conhecimento]( https://api.kustomerapp.com/v1/kb/forms)
+ [Rotas da base de conhecimento](https://api.kustomerapp.com/v1/kb/routes)
+ [Tags da base de conhecimento](https://api.kustomerapp.com/v1/kb/tags)
+ [Modelos da base de conhecimento](https://api.kustomerapp.com/v1/kb/templates)
+ [Temas da base de conhecimento](https://api.kustomerapp.com/v1/kb/themes)
+ [Klasses](https://api.kustomerapp.com/v1/klasses)
+ [Kviews](https://api.kustomerapp.com/v1/kviews)
+ [Mensagens](https://api.kustomerapp.com/v1/messages)
+ [Observações](https://api.kustomerapp.com/v1/notes)
+ [Notificações](https://api.kustomerapp.com/v1/notifications)
API do Kustomer v1
[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/pt_br/glue/latest/dg/kustomer-reading-from-entities.html)
## Particionamento de consultas
**Particionamento com base em campo**
É possível fornecer as opções adicionais do Spark `PARTITION_FIELD`, `LOWER_BOUND`, `UPPER_BOUND` e `NUM_PARTITIONS` se quiser utilizar a simultaneidade no Spark. Com esses parâmetros, a consulta original seria dividida em `NUM_PARTITIONS` subconsultas, que poderiam ser executadas pelas tarefas do Spark simultaneamente.
+ `PARTITION_FIELD`: o nome do campo a ser usado para particionar a consulta.
+ `LOWER_BOUND`: um valor limite inferior **inclusivo** do campo de partição escolhido.
Para o campo DateTime, aceitamos o valor no formato ISO.
Exemplo de valor válido:
```
"2023-01-15T11:18:39.205Z"
```
+ `UPPER_BOUND`: um valor limite superior **exclusivo** do campo de partição escolhido.
+ `NUM_PARTITIONS`: o número de partições.
Os detalhes do suporte do campo de particionamento relativo às entidades são capturados na seguinte tabela:
[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/pt_br/glue/latest/dg/kustomer-reading-from-entities.html)
Exemplo:
```
Kustomer_read = glueContext.create_dynamic_frame.from_options(
connection_type="kustomer",
connection_options={
"connectionName": "connectionName",
"ENTITY_NAME": "conversation",
"API_VERSION": "v1",
"PARTITION_FIELD": "createdAt"
"LOWER_BOUND": "2023-01-15T11:18:39.205Z"
"UPPER_BOUND": "2023-02-15T11:18:39.205Z"
"NUM_PARTITIONS": "2"
}
```
# Opções de conexão do Kustomer
Estas são as opções de conexão do Kustomer:
+ `ENTITY_NAME`(string): (obrigatório) usado para leitura. O nome do seu objeto no Kustomer.
+ `API_VERSION`(string): (obrigatório) usado para leitura. A versão da API Rest do Kustomer que você deseja usar.
+ `SELECTED_FIELDS`(Lista): padrão: vazio(SELECIONE \$1). Usado para leitura. Colunas que deseja selecionar para o objeto.
+ `FILTER_PREDICATE`(string): padrão: vazio. Usado para leitura. Deve estar no formato Spark SQL.
+ `QUERY`(String): padrão: vazia. Usado para leitura. Consulta completa do Spark SQL.
+ `PARTITION_FIELD`(String): usado para leitura. Campo a ser usado para particionar a consulta.
+ `LOWER_BOUND`(String): usado para leitura. Um valor limite inferior inclusivo do campo de partição escolhido.
+ `UPPER_BOUND`(String): usado para leitura. Um valor limite superior exclusivo do campo de partição escolhido.
+ `NUM_PARTITIONS`(Inteiro): padrão: 1. Usado para leitura. Número de partições para leitura.
+ `INSTANCE_URL` (String): (obrigatório) usado para leitura. URL de instância do Kustomer.
# Limitações do Kustomer
Estas são as limitações ou observações do Kustomer:
+ Não há suporte para a entidade `Customer Searches`, pois a documentação da API do Kustomer não declarou nenhum endpoint para ela.
+ A entidade `Klasses` não oferece suporte à filtragem e à transferência incremental.
+ O suporte ao recurso de ordenação está disponível para vários campos aplicáveis em uma única solicitação.
No entanto, observou-se que essa funcionalidade de ordenação em vários campos apresenta um comportamento inconsistente por parte do SaaS para algumas combinações. Ele é imprevisível, uma vez que pode haver “n” combinações que talvez mostrem resultados de ordenação incorretos. Por exemplo:
Para a entidade `Customers`, ordenar por `progressiveStatus desc, name asc` não produz o resultado ordenado correto. Ele classifica apenas com base na ordem `progressiveStatus`. Se esse comportamento for observado, você pode usar um único campo para fazer a ordenação.
+ Apenas as entidades `Conversations` e `Messages` oferecem suporte à ordenação no campo “id” como um parâmetro de consulta. Por exemplo: https://api.kustomerapp.com/v1/conversations?sort=desc (classifica os resultados por “id” em ordem decrescente)
Além disso, qualquer outro filtro ou ordenação em qualquer outro campo é traduzido em um corpo de solicitação POST com o endpoint da API como POST https://api.kustomerapp.com/v1/customers/search Para permitir o suporte à ordenação por “id” em `Conversations` e `Messages`, somente a ordenação por id deve estar presente ou qualquer outro filtro e/ou ordenação em outro campo aplicável.
+ O Kustomer permite a busca de, no máximo, 10 mil registros, independentemente de a solicitação ser filtrada ou não filtrada. Devido a essa limitação, haverá uma perda de dados para qualquer entidade que tiver mais de 10 mil registros. Existem duas soluções alternativas possíveis que você pode executar para mitigar essa limitação parcialmente:
+ Aplique filtros para buscar um conjunto específico de registros.
+ Se houver mais de 10 mil registros com um filtro aplicado, aplique um valor de filtro sucessivo em uma nova solicitação subsequente ou aplique intervalos nos filtros. Por exemplo:
filterExpression da 1.ª solicitação: `modifiedAt >= 2022-03-15T05:26:23.000Z and modifiedAt < 2023-03-15T05:26:23.000Z`
Suponha que isso esgote o limite de 10 mil registros.
Outra solicitação pode ser acionada com filterExpression: `modifiedAt >= 2023-03-15T05:26:23.000Z`
+ Como um comportamento de SaaS, o operador `CONTAINS` no Kustomer oferece suporte à correspondência somente para palavras completas, e não a correspondências parciais de uma palavra. Por exemplo: “body CONTAINS 'test record'” fará a correspondência a um registro que tenha “test” no campo “body”. No entanto, “body CONTAINS 'test'” não fará a correspondência a um registro que tenha “testAnotherRecord” no campo “body”.