# Conexão com o Twilio O Twilio fornece ferramentas de comunicação programáveis para fazer e receber chamadas telefônicas, enviar e receber mensagens de texto e realizar outras funções de comunicação usando suas APIs de serviços da Web. As APIs do Twilio alimentam sua plataforma de comunicações. Por trás dessas APIs há uma camada de software conectando e otimizando redes de comunicação em todo o mundo para permitir que seus usuários liguem e enviem mensagens para qualquer pessoa, globalmente. Como usuário do Twilio, é possível conectar o AWS Glue à sua conta do Twilio. Em seguida, será possível usar o Twilio como fonte de dados nos seus trabalhos de ETL. Execute esses trabalhos para transferir dados entre o Twilio e serviços da AWS ou outras aplicações com suporte. **Topics** + [Suporte do AWS Glue para o Twilio](twilio-support.md) + [Políticas que contêm as operações de API para criar e usar conexões](twilio-configuring-iam-permissions.md) + [Configuração do Twilio](twilio-configuring.md) + [Configuração de conexões do Twilio](twilio-configuring-connections.md) + [Leitura de entidades do Twilio](twilio-reading-from-entities.md) + [Opções de conexão do Twilio](twilio-connection-options.md) + [Limitações e notas do conector do Twilio](twilio-connector-limitations.md) # Suporte do AWS Glue para o Twilio O AWS Glue oferece suporte ao Twilio da seguinte forma: **Compatível como fonte?** Sim. É possível usar trabalhos de ETL do AWS Glue para consultar seus dados do Twilio. **Compatível como destino?** Nº **Versões da API do Twilio com suporte** Há suporte para as seguintes versões da API do Twilio: + v1 + 2010-04-01 # 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 Twilio Antes de poder usar o AWS Glue para transferir dados do Twilio, os seguintes requisitos deverão ser atendidos: ## Requisitos mínimos Estes são os requisitos mínimos: + Você tem uma conta do Twilio com nome de usuário e senha. + Sua conta do Twilio está habilitada para acesso à API. Se você atender a esses requisitos, poderá conectar o AWS Glue à sua conta do Twilio. Para conexões típicas, você não precisa fazer mais nada no Twilio. # Configuração de conexões do Twilio O Twilio oferece suporte a nome de usuário e senha para autenticação básica. A autenticação básica é um método de autenticação simples em que os clientes fornecem credenciais diretamente para acessar recursos protegidos. O AWS Glue é capaz de usar o nome de usuário (SID da conta) e a senha (token de autenticação) para autenticar as APIs do Twilio. Para obter a documentação pública do Twilio para o fluxo de autenticação básica, consulte [Autenticação básica \$1 Twilio](https://www.twilio.com/docs/glossary/what-is-basic-authentication). Para configurar uma conexão do Twilio: 1. No AWS Secrets Manager, crie um segredo com os seguintes detalhes: + Para a autenticação básica: o segredo deve conter o segredo do consumidor da aplicação conectada com o **SID da conta** (nome de usuário) e o **Token de autenticação** (senha). **nota** É 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. Ao selecionar um **Tipo de conexão**, escolha Twilio. 1. Forneça o `[Edge\$1Location](https://www.twilio.com/docs/global-infrastructure/edge-locations)` da instância do Twilio à qual você deseja se conectar. 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 Twilio **Pré-requisito** Um objeto do Twilio do qual você deseja ler. Você precisará do nome do objeto, como `SMS-Message` ou `SMS-CountryPricing`. **Entidades compatíveis quanto à origem**: | Entidade | Interface | Pode ser filtrada | Oferece suporte a limite | Oferece suporte a Ordenar por | Oferece suporte a Selecionar \$1 | Oferece suporte a particionamento | | --- | --- | --- | --- | --- | --- | --- | | SMS-Message | REST | Sim | Sim | Não | Sim | Sim | | SMS-CountryPricing | REST | Não | Não | Não | Sim | Não | | Voice-Call | REST | Sim | Sim | Não | Sim | Não | | Voice-Application | REST | Sim | Sim | Não | Sim | Não | | Voice-OutgoingCallerID | REST | Sim | Sim | Não | Sim | Não | | Voice-Queue | REST | Sim | Sim | Não | Sim | Não | | Conversations-Conversation | REST | Sim | Sim | Não | Sim | Não | | Conversations-User | REST | Não | Sim | Não | Sim | Não | | Conversas-Função | REST | Não | Sim | Não | Sim | Não | | Conversations-Configuration | REST | Não | Não | Não | Sim | Não | | Conversations-AddressConfiguration | REST | Sim | Sim | Não | Sim | Não | | Conversations-WebhookConfiguration | REST | Não | Não | Não | Sim | Não | | Conversations-ParticipantConversation | REST | Não | Não | Não | Sim | Não | | Conversations-Credential | REST | Não | Sim | Não | Sim | Não | | Conversations-ConversationService | REST | Não | Sim | Não | Sim | Não | **Exemplo:** ``` twilio_read = glueContext.create_dynamic_frame.from_options( connection_type="twilio", connection_options={ "connectionName": "connectionName", "ENTITY_NAME": "sms-message", "API_VERSION": "2010-04-01", "Edge_Location": "sydney.us1" } ``` **Detalhes de entidade e campo do Twilio**: [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/pt_br/glue/latest/dg/twilio-reading-from-entities.html) ## Particionamento de consultas **Campos com suporte a particionamento**: No Twilio, os campos de tipo de dados DateTime oferecem suporte ao particionamento baseado em campos. É 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. No campo Datetime, aceitamos o formato de carimbo de data/hora do Spark usado em consultas SQL do Spark. Exemplos de valores válidos: ``` "2024-05-01T20:55:02.000Z" ``` + `UPPER_BOUND`: um valor limite superior **exclusivo** do campo de partição escolhido. + `NUM_PARTITIONS`: o número de partições. Exemplo: ``` twilio_read = glueContext.create_dynamic_frame.from_options( connection_type="twilio", connection_options={ "connectionName": "connectionName", "ENTITY_NAME": "sms-message", "API_VERSION": "2010-04-01", "PARTITION_FIELD": "date_sent" "LOWER_BOUND": "2024-05-01T20:55:02.000Z" "UPPER_BOUND": "2024-06-01T20:55:02.000Z" "NUM_PARTITIONS": "10" } ``` # Opções de conexão do Twilio Estas são as opções de conexão do Twilio: + `ENTITY_NAME`(string): (obrigatório) usado para leitura. O nome do seu objeto no Twilio. + `EDGE_LOCATION`(string): (obrigatório) um local da borda válido do Twilio. + `API_VERSION`(string): (obrigatório) usado para leitura. Versão da API Rest do Twilio que você deseja usar. O Twilio oferece suporte a duas versões de API: 'v1' e '2010-04-01'. + `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. Um URL válido da instância do Twilio. # Limitações e notas do conector do Twilio Estas são as limitações ou notas do conector do Twilio: + Não há suporte para o particionamento com base em registros, e não há provisão para a recuperação da contagem total de registros do Twilio. + Os campos `date_sent`, `start_time` e `end_time` são do tipo de dados Datetime, mas, na filtragem, eles só oferecem suporte a valores de data (os componentes de hora não são considerados). + A filtragem dos campos "de" ou "para" funciona somente se os valores não incluírem nenhum prefixo (por exemplo, um protocolo ou rótulo). Se houver um prefixo, a filtragem do respectivo campo não funcionará. Por exemplo, se você passar "para": "whatsapp:\$114xxxxxxxxxx" como filtro, o Twilio não retornará uma resposta. Você precisa passá-lo como "para": "\$114xxxxxxxx", e então ele retornará os registros, se existirem. + O filtro de campo "identidade" é obrigatório ao consultar a entidade `conversation-participant-conversation`.