# Conectar ao Zendesk O Zendesk é uma solução de gerenciamento de help desk baseada na nuvem que oferece ferramentas personalizáveis para criar um portal de atendimento ao cliente, uma base de conhecimento e comunidades on-line. **Topics** + [Suporte do AWS Glue ao Zendesk](zendesk-support.md) + [Políticas que contêm as operações de API para criar e usar conexões](zendesk-configuring-iam-permissions.md) + [Configurar o Zendesk](zendesk-configuring.md) + [Configuração de conexões do Zendesk](zendesk-configuring-connections.md) + [Leitura de entidades do Zendesk](zendesk-reading-from-entities.md) + [Opções de conexão do Freshdesk](zendesk-connection-options.md) + [Limitações](zendesk-limitations.md) # Suporte do AWS Glue ao Zendesk O AWS Glue oferece suporte ao Zendesk da seguinte forma: **Compatível como fonte?** Sim. É possível usar trabalhos de ETL do AWS Glue para consultar dados do Zendesk. **Compatível como destino?** Não. **Versões da API do Zendesk compatíveis** As seguintes versões da API do Zendesk são compatíveis + v2 # 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 utilizar o método acima, 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. # Configurar o Zendesk Para usar o AWS Glue para transferir dados do Zendesk, os seguintes requisitos deverão ser atendidos: ## Requisitos mínimos São requisitos mínimos: + Uma conta do Zendesk. Para obter mais informações, consulte [Criar uma conta do Zendesk](#zendesk-configuring-creating-account). + Sua conta do Zendesk está habilitada para acesso à API. + A conta do Zendesk permite a instalação de aplicações conectadas. Caso atenda a esses requisitos, você poderá conectar o AWS Glue à sua conta do Zendesk. ## Criar uma conta do Zendesk Para criar uma conta do Zendesk: 1. Acesse https://www.zendesk.com/in/register/ 1. Insira detalhes como seu e-mail de trabalho, nome, sobrenome, número de telefone, cargo, nome da empresa, número de funcionários na empresa, senha e idioma preferido. Em seguida, escolha **Concluir inscrição no teste**. 1. Depois que a conta for criada, clique no link de verificação que recebeu para verificar seu endereço de e-mail. 1. Assim que o endereço de e-mail profissional for verificado, você será redirecionado para sua conta do Zendesk. Escolha a opção **Comprar Zendesk** para seu plano preferido. Observação: para o conector Zendesk, recomenda-se comprar o plano Suite Enterprise. ## Criação de uma aplicação cliente e de credenciais do OAuth 2.0 Para criar uma aplicação cliente e credenciais do OAuth 2.0: 1. Faça login na conta do Zendesk na qual você deseja que a aplicação OAuth 2.0 seja criada https://www.zendesk.com/in/login/ 1. Clique no ícone de engrenagem. Escolha o link **Ir para o centro de administração** para abrir a página do centro de administração. 1. Escolha **Aplicações e integrações** na barra lateral esquerda e, em seguida, selecione **APIs** > **API do Zendesk**. 1. Na página da API do Zendesk, escolha a guia **Clientes OAuth**. 1. Escolha **Adicionar cliente OAuth** no lado direito. 1. Preencha os seguintes campos para criar um cliente: 1. Nome do cliente: insira um nome para sua aplicação. Esse é o nome que os usuários verão quando solicitados a conceder acesso à sua aplicação e quando verificarem a lista de aplicações de terceiros que têm acesso ao seu Zendesk. 1. Descrição: opcional. Uma breve descrição da sua aplicação que os usuários verão quando solicitados a conceder acesso a ele. 1. Empresa: opcional. O nome da empresa que os usuários verão quando solicitados a conceder acesso à sua aplicação. As informações podem ajudá-los a entender a quem estão concedendo acesso. 1. Logotipo: opcional. O logotipo que os usuários verão quando solicitados a conceder acesso à sua aplicação. A imagem pode ser JPG, GIF ou PNG. Para obter melhores resultados, faça upload de uma imagem quadrada. Ela será redimensionada para a página de autorização. 1. Identificador exclusivo: o campo é preenchido automaticamente com uma versão reformatada do nome que você inseriu para a aplicação. Você pode alterá-lo, se desejar. 1. URLs de redirecionamento: insira o URL ou URLs que o Zendesk deve usar para enviar a decisão do usuário de conceder acesso à sua aplicação. Por exemplo: https://us-east-1.console.aws.amazon.com/gluestudio/oauth 1. Clique em **Salvar**. 1. Depois que a página for atualizada, um novo campo **Segredo** pré-preenchido aparecerá na parte inferior. Esse é o valor de "client\$1secret" definido na especificação do OAuth2. Copie o valor do segredo para a sua área de transferência e salve-o em um lugar seguro. Observação: os caracteres podem ultrapassar a largura da caixa de texto, portanto, certifique-se de selecionar tudo antes de copiar. 1. Clique em **Salvar**. # Configuração de conexões do Zendesk O conector do Zendesk oferece suporte ao tipo de concessão de código de autorização. + Esse tipo de concessão é considerado um OAuth de “três pernas”, pois conta com o redirecionamento dos usuários para um servidor de autorização de terceiros para autenticar o usuário. É usado ao criar conexões por meio do console do AWS Glue. O usuário que estiver criando uma conexão pode, por padrão, contar com uma aplicação conectada pertencente ao AWS Glue (aplicação cliente gerenciada pelo AWS Glue), na qual ele não precisa fornecer quaisquer informações relacionadas ao OAuth, exceto o URL da instância do Zendesk. O console do AWS Glue redirecionará o usuário para o Zendesk, onde ele deverá fazer login e dar autorização para que as permissões solicitadas pelo AWS Glue acessem a instância do Zendesk. + Os usuários ainda podem optar por criar sua própria aplicação conectada no Zendesk e fornecer seus próprios ID e segredo do cliente ao criar conexões por meio do console do AWS Glue. Nesse cenário, você ainda será redirecionado para o Zendesk para fazer login e autorizar o acesso do AWS Glue aos seus recursos. + Esse tipo de concessão resulta em um token de acesso. O token de acesso nunca expira. Para obter a documentação pública do Zendesk sobre como criar uma aplicação conectada para o fluxo de código de autorização do OAuth, consulte [Tokens do OAuth para tipos de concessão](https://developer.zendesk.com/api-reference/ticketing/oauth/grant_type_tokens/). Para configurar uma conexão do Zendesk: 1. No AWS Secrets Manager, crie um segredo com os seguintes detalhes: 1. Para o tipo de concessão AuthorizationCode: para uma aplicação conectada gerenciada pelo cliente, o segredo deve conter o segredo do consumidor da aplicação conectada com a chave `USER_MANAGED_CLIENT_APPLICATION_CLIENT_SECRET`. 1. Nota: é preciso criar um segredo por conexão em AWS Glue. 1. No AWS Glue Glue Studio, crie uma conexão em **Conexões de dados** seguindo estas etapas: 1. Ao selecionar um **Tipo de conexão**, escolha Zendesk. 1. Forneça o INSTANCE\$1URL do Zendesk ao qual deseja se conectar. 1. Forneça o ambiente do Zendesk. 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 Zendesk **Pré-requisito** Um objeto do Zendesk-do qual você deseja ler. Você precisará do nome do objeto, como tíquete, usuário ou artigo, conforme mencionado na tabela a seguir. | Entidade | Pode ser filtrada | Oferece suporte a limite | Oferece suporte a Ordenar por | Oferece suporte a Selecionar \$1 | Oferece suporte a particionamento | | --- | --- | --- | --- | --- | --- | | Tíquete | S | S | S | S | N | | Usuário | S | S | S | S | N | | Organização | S | S | S | S | N | | Artigo | S | S | N | S | N | | Evento do tíquete | S | S | N | S | N | | Evento de métrica do tíquete | S | S | N | S | N | | Comentário do tíquete | S | S | S | S | N | | Campo do tíquete | S | S | N | S | N | | Métrica do tíquete | S | S | N | S | N | | Atividade do tíquete | S | S | N | S | N | | Ignorar tíquete | N | S | N | S | N | | Grupo | S | S | S | S | N | | Associação a grupos | N | S | S | S | N | | Classificação de satisfação | S | S | N | S | N | | Visualizar | S | S | S | S | N | | Trigger | S | S | S | S | N | | Categoria do gatilho | N | S | S | S | N | | Macro | S | S | S | S | N | | Automação | N | S | S | S | N | **Exemplo:** ``` Zendesk_read = glueContext.create_dynamic_frame.from_options( connection_type="Zendesk", connection_options={ "connectionName": "connectionName", "ENTITY_NAME": "Account", "API_VERSION": "v2" } ``` **Detalhes das entidades e dos campos do Zendesk**: [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/pt_br/glue/latest/dg/zendesk-reading-from-entities.html) **nota** Os tipos de dados Struct e List são convertidos no tipo de dados String na resposta do conector. ## Particionamento de consultas Não há suporte para partições no Zendesk. # Opções de conexão do Freshdesk Estas são as opções de conexão do Zendesk: + `ENTITY_NAME`(string): (obrigatório) usado para leitura. O nome do seu objeto no Zendesk. + `API_VERSION`(string): (obrigatório) usado para leitura. A versão da API Rest do Zendesk que você deseja usar. Por exemplo: v2. + `SELECTED_FIELDS`(Lista): padrão: vazio(SELECIONE \$1). Usado para leitura. Colunas que deseja selecionar para o objeto. Por exemplo: id, nome, url, created\$1at + `FILTER_PREDICATE`(string): padrão: vazio. Usado para leitura. Deve estar no formato Spark SQL. Por exemplo: group\$1id = 100 + `QUERY`(string): padrão: vazio. Usado para leitura. Consulta completa do Spark SQL. Por exemplo: "SELECT id, url FROM users WHERE role=\$1"end-user\$1"" + `PARTITION_FIELD`(string): usado para leitura. Campo a ser usado para particionar a consulta. O campo padrão é `update_at` para entidades que oferecem suporte à API de exportação incremental (`created_at` para `ticket-events` e `time` para `ticket-metric-events`). + `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. Opcional: essa opção será tratada pelo conector se não for fornecida na opção de trabalho. Valor padrão: "2024-05-01T20:55:02.000Z" + `NUM_PARTITIONS`(Inteiro): padrão: 1. Usado para leitura. Número de partições para leitura. Opcional: essa opção será tratada pelo conector se não for fornecida na opção de trabalho. Valor padrão: 1. + `IMPORT_DELETED_RECORDS`(string): (padrão): FALSE. Usado para leitura. Para obter os registros excluídos durante a consulta. + `ACCESS_TOKEN`: token de acesso a ser usado na solicitação. + `INSTANCE_URL`: URL da instância em que o usuário deseja executar as operações. Por exemplo: https://yoursubdomain.zendesk.com # Limitações São limitações do conector do Zendesk: + A paginação baseada em offset limita o número de páginas que podem ser buscadas a 100, mas seu uso não é recomendado, pois o número total de registros que podem ser buscados é 10.000. No entanto, a paginação baseada em cursor implementada para o conector Zendesk consegue superar essa limitação. Somente o operador de filtro EQUAL\$1TO é compatível com a API do Zendesk. Em função dessa limitação, não há suporte a particionamento pelo conector Zendesk. + Para a entidade "Evento de tíquete", o limite de taxa é de 10 solicitações por minuto. Ao executar uma tarefa de ETL do AWS Glue, você pode receber um erro 429 (excesso de solicitações).