# Conexão com o Salesforce Marketing Cloud O Salesforce Marketing Cloud é um fornecedor de software de automação e analytics de marketing para e-mail, dispositivos móveis, redes sociais e marketing on-line. Ele também oferece serviços de consultoria e implementação. Caso seja um usuário do Salesforce Marketing Cloud, você poderá conectar o AWS Glue à sua conta do Salesforce Marketing Cloud. Depois, você poderá usar o Salesforce Marketing Cloud como uma fonte de dados ou um destino em seus trabalhos de ETL. Execute esses trabalhos para transferir dados entre os serviços do Salesforce Marketing Cloud e da AWS ou de outras aplicações compatíveis. **Topics** + [Suporte do AWS Glue ao Salesforce Marketing Cloud](salesforce-marketing-cloud-support.md) + [Políticas que contêm as operações de API para criar e usar conexões](salesforce-marketing-cloud-configuring-iam-permissions.md) + [Configuração do Salesforce Marketing Cloud](salesforce-marketing-cloud-configuring.md) + [Configuração de conexões do Salesforce Marketing Cloud](salesforce-marketing-cloud-configuring-connections.md) + [Leitura de entidades do Salesforce Marketing Cloud](salesforce-marketing-cloud-reading-from-entities.md) + [Gravação em entidades do Salesforce Marketing Cloud](salesforce-marketing-cloud-writing-to-entities.md) + [Opções de conexão do Salesforce Marketing Cloud](salesforce-marketing-cloud-connection-options.md) + [Limitações e observações do conector do Salesforce Marketing Cloud](salesforce-marketing-cloud-connector-limitations.md) # Suporte do AWS Glue ao Salesforce Marketing Cloud O AWS Glue oferece suporte para o Salesforce Marketing Cloud da seguinte maneira: **Compatível como fonte?** Sim. É possível usar trabalhos ETL do AWS Glue para consultar dados do Salesforce Marketing Cloud. **Compatível como destino?** Não. **Versões compatíveis da API do Salesforce Marketing Cloud** As seguintes versões da API do Salesforce Marketing Cloud são compatíveis: + 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 Salesforce Marketing Cloud Antes de poder usar o AWS Glue para transferir dados do Salesforce Marketing Cloud, você precisa atender aos seguintes requisitos: ## Requisitos mínimos Estes são os requisitos mínimos: + Ter uma conta do Salesforce Marketing Cloud. Para obter mais informações, consulte [Criação de uma conta do Salesforce Marketing Cloud](#salesforce-marketing-cloud-configuring-creating-salesforce-marketing-cloud-account). + A conta do Salesforce Marketing Cloud estar habilitada para acesso à API. O acesso à API estar ativado por padrão para as edições Enterprise, Unlimited, Developer e Performance. Se você atender a esses requisitos, poderá conectar o AWS Glue à conta do Salesforce Marketing Cloud. Para conexões típicas, você não precisa fazer mais nada no Salesforce Marketing Cloud. ## Criação de uma conta do Salesforce Marketing Cloud Para o Salesforce Marketing Cloud, você precisa entrar em contato com o fornecedor para criar uma conta. Se você ou sua empresa tiver uma associação com a Salesforce, entre em contato com o gerente de contas da Salesforce para solicitar uma licença do Salesforce Marketing Cloud. Caso contrário, você pode solicitar o contato de um representante da Salesforce da seguinte maneira: 1. Acesse https://www.salesforce.com/in/products/marketing-cloud/overview/ e escolha **Cadastrar-se**. 1. Selecione o link **Entre em contato conosco** no canto superior direito da página. 1. Insira as informações necessárias e escolha **Entre em contato comigo**. Um representante da Salesforce entrará em contato com você para discutir suas necessidades. ## Criação de um projeto e de credenciais do OAuth 2.0 Para obter um projeto e credenciais do OAuth 2.0: 1. Faça login na instância do [Salesforce Marketing Cloud](https://mc.login.exacttarget.com/hub-cas/login) com seu nome de usuário e senha e autentique-se usando seu número de celular registrado. 1. Clique no seu perfil no canto superior direito e depois acesse **Configuração**. 1. Em **Ferramentas dr plataforma**, escolha **Aplicações** e, em seguida, escolha **Pacotes instalados**. ![\[\]](http://docs.aws.amazon.com/pt_br/glue/latest/dg/images/sfmc-platform-tools.png) 1. Na página **Pacotes instalados**, clique em **Novo** no canto superior direito. Forneça o nome e a descrição do pacote. Salve o pacote. Depois que o pacote for salvo, você poderá visualizar os detalhes dele. 1. Na página **Detalhes** do pacote, na seção **Componente**, escolha **Adicionar componente**. ![\[\]](http://docs.aws.amazon.com/pt_br/glue/latest/dg/images/sfmc-add-component.png) 1. Selecione o **Tipo de componente** “Integração de API” e clique em **Avançar**. 1. Selecione o **Tipo de integração** “Servidor a servidor” (que tem o tipo de concessão de credenciais do cliente do OAuth) e clique em **Avançar**. 1. Adicione os escopos com base nos seus requisitos e clique em **Salvar**. # Configuração de conexões do Salesforce Marketing Cloud O Salesforce Marketing Cloud oferece suporte ao tipo de concessão CLIENT CREDENTIALS para OAuth2. + Esse tipo de concessão é considerado OAuth 2.0 de 2 pernas, pois é usado pelos clientes para obter um token de acesso fora do contexto de um usuário. AWS Glue é capaz de usar o ID do cliente e o segredo do cliente para autenticar as APIs do Salesforce Marketing Cloud que são fornecidas pelos serviços personalizados que você define. + Cada serviço personalizado é de propriedade de um usuário somente de API que tem um conjunto de perfis e permissões que autorizam o serviço a realizar ações específicas. Um token de acesso é associado a um único serviço personalizado. + Esse tipo de concessão resulta em um token de acesso de curta duração, que pode ser renovado com uma chamada a um endpoint de identidade. + Para obter a documentação pública do Salesforce Marketing Cloud para OAuth 2.0 com credenciais de cliente, consulte [Configuração do seu ambiente de desenvolvimento para pacotes aprimorados](https://developer.salesforce.com/docs/marketing/marketing-cloud/guide/mc-dev-setup-enhanced.html). Para configurar uma conexão do Salesforce Marketing Cloud: 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 a aplicação conectada Segredo do consumidor com a chave `USER_MANAGED_CLIENT_APPLICATION_CLIENT_SECRET`. 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. Ao selecionar um **Tipo de conexão**, escolha Salesforce Marketing Cloud. 1. Forneça o `Subdomain Endpoint` da Salesforce Marketing Cloud à 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 Salesforce Marketing Cloud **Pré-requisito** Um objeto do Salesforce Marketing Cloud do qual você deseja ler. Você precisará do nome do objeto, como `Activity` ou `Campaigns`. A tabela a seguir mostra as entidades compatíveis. **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 | | --- | --- | --- | --- | --- | --- | --- | | Retorno de chamada de notificação de eventos | REST | Não | Não | Não | Sim | Não | | Seed-List | REST | Não | Sim | Não | Sim | Não | | Configuração | REST | Sim | Sim | Não | Sim | Não | | Verificação de domínio | REST | Sim | Sim | Sim | Sim | Não | | Etiquetas de objeto aninhadas | REST | Sim | Não | Não | Sim | Não | | Contato | REST | Não | Sim | Não | Sim | Não | | Assinatura de notificação de eventos | REST | Não | Não | Não | Sim | Não | | Sistema de mensagens | REST | Não | Sim | Não | Sim | Não | | Atividade | SOAP | Não | Não | Não | Sim | Sim | | Evento de devolução | SOAP | Não | Não | Não | Sim | Sim | | Evento de clique | SOAP | Não | Não | Não | Sim | Sim | | Área de conteúdo | SOAP | Não | Não | Não | Sim | Sim | | Extensão de dados | SOAP | Não | Sim | Não | Sim | Sim | | E-mail | SOAP | Não | Sim | Não | Sim | Sim | | Evento de e-mail encaminhado | SOAP | Não | Sim | Não | Sim | Sim | | OptinEvent de e-mail encaminhado | SOAP | Não | Sim | Não | Sim | Sim | | Link | SOAP | Não | Sim | Não | Sim | Sim | | Envio do link | SOAP | Não | Sim | Não | Sim | Sim | | Lista | SOAP | Não | Sim | Não | Sim | Sim | | Listar assinante | SOAP | Não | Sim | Não | Sim | Sim | | Evento não enviado | SOAP | Não | Sim | Não | Sim | Sim | | Evento aberto | SOAP | Não | Sim | Não | Sim | Sim | | Enviar | SOAP | Não | Sim | Não | Sim | Sim | | Evento enviado | SOAP | Não | Sim | Não | Sim | Sim | | Assinante | SOAP | Não | Sim | Não | Sim | Sim | | Evento de pesquisa | SOAP | Não | Sim | Não | Sim | Sim | | Evento cancelamento de assinatura | SOAP | Não | Sim | Não | Sim | Sim | | Eventos de auditoria | REST | Não | Sim | Sim | Sim | Não | | Campanhas | REST | Não | Sim | Sim | Sim | Não | | Interações | REST | Não | Sim | Sim | Sim | Não | | Ativos de conteúdo | REST | Não | Sim | Sim | Sim | Não | **Exemplo de REST**: ``` salesforcemarketingcloud_read = glueContext.create_dynamic_frame.from_options( connection_type="salesforcemarketingcloud", connection_options={ "connectionName": "connectionName", "ENTITY_NAME": "Campaigns", "API_VERSION": "v1", "INSTANCE_URL": "https://**********************.rest.marketingcloudapis.com" } ) ``` **Exemplo de SOAP**: ``` salesforcemarketingcloud_read = glueContext.create_dynamic_frame.from_options( connection_type="salesforcemarketingcloud", connection_options={ "connectionName": "connectionName", "ENTITY_NAME": "Activity", "API_VERSION": "v1", "INSTANCE_URL": "https://**********************.soap.marketingcloudapis.com" } ) ``` **Detalhes das entidades e dos campos do Salesforce Marketing Cloud**: As tabelas a seguir descrevem as entidades do Salesforce Marketing Cloud. Há entidades REST com metadados estáticos e entidades SOAP com metadados dinâmicos. **Entidades REST com metadados estáticos**: [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/pt_br/glue/latest/dg/salesforce-marketing-cloud-reading-from-entities.html) **Entidades SOAP com metadados dinâmicos**: [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/pt_br/glue/latest/dg/salesforce-marketing-cloud-reading-from-entities.html) ## Particionamento de consultas No Salesforce Marketing Cloud, os campos de tipo de dados Integer e DateTime oferecem suporte a 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 de carimbo de data e hora, aceitamos o formato de carimbo de data e hora do Spark usado nas consultas SQL do Spark. Exemplos de valores válidos: ``` “2024-05-07T02:03:00.00Z" ``` + `UPPER_BOUND`: um valor limite superior **exclusivo** do campo de partição escolhido. + `NUM_PARTITIONS`: o número de partições. Exemplo: ``` salesforcemarketingcloud_read = glueContext.create_dynamic_frame.from_options( connection_type="salesforcemarketingcloud", connection_options={ "connectionName": "connectionName", "ENTITY_NAME": "ListSubscriber", "API_VERSION": "v1", "PARTITION_FIELD": "CreatedDate", "LOWER_BOUND": "2023-09-07T02:03:00.000Z", "UPPER_BOUND": "2024-05-07T02:03:00.000Z", "NUM_PARTITIONS": "10" } ) ``` # Gravação em entidades do Salesforce Marketing Cloud **Pré-requisitos** + Um objeto do Salesforce Marketing no qual você deseja gravar. Você precisará especificar o nome do objeto, como `List` ou `Campaigns`, ou qualquer outra entidade descrita na tabela abaixo. + O conector do Salesforce Marketing Cloud é compatível com três operações de gravação: + INSERT + UPSERT + UPDATE Ao usar as operações de gravação `UPDATE` e `UPSERT`, você deverá fornecer opção `ID_FIELD_NAMES` para especificar o campo de ID externo para os registros. **Entidades compatíveis para destino**: | Entidade | Prioridade | Interface (REST, SOAP etc.) | Pode ser inserido | Pode ser atualizado | Pode ser upserted | | --- | --- | --- | --- | --- | --- | | Campanhas | P0 | REST | S- Único | S- Único | N | | Ativos de conteúdo | P0 | REST | S- Único, em massa | S- Único | N | | Contato | P1 | REST | S- Único | S- Único | N | | Verificação de domínio | P1 | REST | S- Único | S- Único, em massa | N | | Retorno de chamada de notificação de eventos | P1 | REST | S- Único | S- Único | N | | Assinatura de notificação de eventos | P1 | REST | S- Único | S- Único | N | | Sistema de mensagens | P1 | REST | S- Único | N | N | | Tags de objetos aninhados | P2 | REST | S- Único | S- Único | N | | Seed-List | P1 | REST | S- Único | S- Único | N | | Configuração | P1 | REST | S- Único | S- Único | N | | Extensão de dados | P0 | SOAP | S- Único | S- Único | S- Único | | E-mail | P0 | SOAP | S- Único | S- Único | N | | Lista | P0 | SOAP | S- Único | S- Único | N | | Enviar | P0 | SOAP | S- Único | N | N | | Assinante | P0 | SOAP | S- Único | S- Único | N | **Exemplo de operação INSERT para REST**: ``` salesforcemarketingcloud_write = glueContext.write_dynamic_frame.from_options( connection_type="salesforcemarketingcloud", connection_options={ "connectionName": "connectionName", "ENTITY_NAME": "Campaigns", "API_VERSION": "v1", "writeOperation" : "INSERT", "INSTANCE_URL": "https://**********************.rest.marketingcloudapis.com" } ) ``` **Exemplo de operação INSERT para SOAP**: ``` salesforcemarketingcloud_write = glueContext.write_dynamic_frame.from_options( connection_type="salesforcemarketingcloud", connection_options={ "connectionName": "connectionName", "ENTITY_NAME": "List", "API_VERSION": "v1", "writeOperation" : "INSERT", "INSTANCE_URL": "https://**********************.rest.marketingcloudapis.com" } ) ``` **Exemplo de operação UPDATE para REST**: ``` salesforcemarketingcloud_write = glueContext.write_dynamic_frame.from_options( connection_type="salesforcemarketingcloud", connection_options={ "connectionName": "connectionName", "ENTITY_NAME": "Campaigns", "API_VERSION": "v1", "writeOperation" : "UPDATE", "ID_FIELD_NAMES": "id", "INSTANCE_URL": "https://**********************.rest.marketingcloudapis.com" } ) ``` **Exemplo de operação UPDATE para SOAP**: ``` salesforcemarketingcloud_write = glueContext.write_dynamic_frame.from_options( connection_type="salesforcemarketingcloud", connection_options={ "connectionName": "connectionName", "ENTITY_NAME": "List", "API_VERSION": "v1", "writeOperation" : "UPDATE", "ID_FIELD_NAMES": "id", "INSTANCE_URL": "https://**********************.rest.marketingcloudapis.com" } ) ``` **Exemplo de operação UPSERT para SOAP**: ``` salesforcemarketingcloud_write = glueContext.write_dynamic_frame.from_options( connection_type="salesforcemarketingcloud", connection_options={ "connectionName": "connectionName", "ENTITY_NAME": "DataExtension/Insert-***E/6*******3", "API_VERSION": "v1", "writeOperation" : "UPSERT", "INSTANCE_URL": "https://**********************.rest.marketingcloudapis.com" } ) ``` # Opções de conexão do Salesforce Marketing Cloud Confira abaixo as opções de conexão do Salesforce Marketing Cloud: + `ENTITY_NAME`(string): (obrigatório) usado para leitura. O nome do objeto no Salesforce Marketing Cloud. + `API_VERSION`(string): (obrigatório) usado para leitura. Versão da API SOAP e REST do Salesforce Marketing Cloud 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. + `WRITE_OPERATION`(string): padrão: INSERT. Usado para gravação. O valor deve ser INSERT, UPDATE e UPSERT. + `ID_FIELD_NAMES` (String), Padrão: null. Necessário para UPDATE e UPSERT. # Limitações e observações do conector do Salesforce Marketing Cloud Confira abaixo as limitações ou as observações do conector do Salesforce Commerce Cloud: + Ao usar o filtro no campo de tipo de dados DateTime, você precisa passar o valor no formato “yyyy-mm-ddThh:MM:ssZ”. + Na Pré-visualização de dados, o valor boleano do tipo de dados aparece em branco. + Para entidades SOAP, você pode definir no máximo dois filtros, e para entidades REST, você pode definir somente um filtro, o que restringe o teste de particionamento com filtros. + Vários comportamentos inesperados foram observados do lado do SaaS: o campo `Link.Alias` na entidade “linksend” não é compatível com o operador CONTAINS (por exemplo, `Link.Alias CONTAINS "ViewPrivacyPolicy"`), e os operadores de filtro para entidades de extensão de dados (como EQUALS e GREATER THAN) não retornam os resultados esperados. + A API SOAP de ClickEvent do SFMC tem um atraso em refletir os registros recém-criados, portanto, os registros criados recentemente podem não estar imediatamente disponíveis na resposta da API. Exemplo: se você criar cinco novos registros de ClickEvent em **2025-01-10T14:30:00** e buscá-los imediatamente usando a API SOAP, a resposta poderá não incluir todos os cinco registros. Pode levar até cinco minutos para que os registros recém-criados apareçam na resposta da API. Esse atraso também pode afetar a recuperação de dados e as execuções programadas. + Dois formatos DateTime diferentes: **2025-03-11T04:46:00** (sem milissegundos) e **2025-03-11T04:46:00.000Z** são compatíveis ao realizar operações de gravação no AWS Glue (com milissegundos). + Para a entidade Event Notification Subscription, uma assinatura só pode ser criada para um URL de retorno de chamada verificado, e você pode ter até 200 assinaturas por retorno de chamada. + Para a entidade Event Notification Callback, um máximo de cinquenta registros pode ser criado por conta.