# Conexão com o Adobe Marketo Engage O Adobe Marketo Engage é uma plataforma de automação de marketing que permite aos profissionais de marketing gerenciar programas e campanhas multicanais personalizados para clientes atuais e potenciais. **Topics** + [AWS Glue compatível com o Adobe Marketo Engage](adobe-marketo-engage-support.md) + [Políticas que contêm as operações de API para criar e usar conexões](adobe-marketo-engage-configuring-iam-permissions.md) + [Configurar o Adobe Marketo Engage](adobe-marketo-engage-configuring.md) + [Configuração de conexões do Adobe Marketo Engage](adobe-marketo-engage-configuring-connections.md) + [Leitura de entidades do Adobe Marketo Engage](adobe-marketo-engage-reading-from-entities.md) + [Gravação em entidades do Adobe Marketo Engage](adobe-marketo-engage-writing-to-entities.md) + [Opções de conexão do Adobe Marketo Engage](adobe-marketo-engage-connection-options.md) + [Limitações e notas do conector do Adobe Marketo Engage](adobe-marketo-engage-connector-limitations.md) # AWS Glue compatível com o Adobe Marketo Engage O AWS Glue é compatível com o Adobe Marketo Engage da seguinte forma: **Compatível como fonte?** Sim. Você pode usar trabalhos de ETL do AWS Glue para consultar dados do Adobe Marketo Engage. **Compatível como destino?** Sim. Você pode usar tarefas de ETL do AWS Glue para gravar dados no Adobe Marketo. **Versões da API compatíveis com o Adobe Marketo Engage** As seguintes versões da API do Adobe Marketo Engage são compatíveis: + v1 Para conferir a compatibilidade das entidades por versão específica, consulte as entidades compatíveis para a fonte. # 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. # Configurar o Adobe Marketo Engage Para usar o AWS Glue para transferir dados do Adobe Marketo Engage, os seguintes requisitos deverão ser atendidos: ## Requisitos mínimos São requisitos mínimos: + Uma conta do Adobe Marketo Engage com credenciais de cliente. + Sua conta do Adobe Marketo Engage tem acesso de API com uma licença válida. Caso atenda a esses requisitos, você poderá conectar o AWS Glue à sua conta do Adobe Marketo Engage. Para conexões típicas, você não precisa fazer mais nada no Adobe Marketo Engage. ## Obtenção de credenciais do Outh 2.0 Para obter credenciais de API para que você possa fazer chamadas autenticadas para sua instância, consulte [API REST do Adobe Marketo](https://experienceleague.adobe.com/en/docs/marketo-developer/marketo/rest/rest-api) # Configuração de conexões do Adobe Marketo Engage O Adobe Marketo Engage 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. O AWS Glue é capaz de usar o ID do cliente e o segredo do cliente para autenticar as APIs do Adobe Marketo Engage, 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 Adobe Marketo Engage sobre OAuth 2.0 com credenciais de cliente, consulte [Autenticação](https://developers.adobe-marketo-engage.com/rest-api/authentication/) no Guia do desenvolvedor do Adobe Marketo Engage. Para configurar uma conexão do Adobe Marketo Engage: 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. 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 Adobe Marketo Engage. 1. Forneça o `INSTANCE_URL` da instância do Adobe Marketo Engage à 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 Adobe Marketo Engage **Pré-requisito** Um objeto do Adobe Marketo Engage do qual você deseja ler. Você precisará do nome do objeto, como leads, atividades ou customobjects. As tabelas a seguir mostram as entidades compatíveis. **Entidades compatíveis quanto à origem (síncronas)**: | Entidade | Pode ser filtrada | Oferece suporte a limite | Oferece suporte a Ordenar por | Oferece suporte a Selecionar \$1 | Oferece suporte a particionamento | | --- | --- | --- | --- | --- | --- | | leads | Sim | Sim | Não | Sim | Não | | atividades | Sim | Sim | Não | Sim | Não | | customobjects | Sim | Sim | Não | Sim | Não | **Entidades compatíveis quanto à origem (assíncronas)**: | Entidade | Pode ser filtrada | Oferece suporte a limite | Oferece suporte a Ordenar por | Oferece suporte a Selecionar \$1 | Oferece suporte a particionamento | | --- | --- | --- | --- | --- | --- | | leads | Sim | Não | Não | Sim | Sim | | atividades | Sim | Não | Não | Sim | Não | | customobjects | Sim | Não | Não | Sim | Sim | **Exemplo:** ``` adobe-marketo-engage_read = glueContext.create_dynamic_frame.from_options( connection_type="adobe-marketo-engage", connection_options={ "connectionName": "connectionName", "ENTITY_NAME": "leads", "API_VERSION": "v2", "INSTANCE_URL": "https://539-t**-6**.mktorest.com" } ``` **Detalhes da entidades e dos campos do Adobe Marketo Engage**: **Entidades com metadados estáticos**: [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/pt_br/glue/latest/dg/adobe-marketo-engage-reading-from-entities.html) **Entidades com metadados dinâmicos**: Para as entidades a seguir, o Adobe Marketo Engage fornece endpoints para buscar metadados dinamicamente, para que o suporte do operador seja capturado no nível do tipo de dados de cada entidade. [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/pt_br/glue/latest/dg/adobe-marketo-engage-reading-from-entities.html) ## Consultas de particionamento É 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: ``` "2024-07-01T00:00:00.000Z" ``` + `UPPER_BOUND`: um valor limite superior **exclusivo** do campo de partição escolhido. + `NUM_PARTITIONS`: o número de partições. A tabela a seguir descreve os detalhes do suporte do campo de particionamento da entidade: [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/pt_br/glue/latest/dg/adobe-marketo-engage-reading-from-entities.html) Exemplo: ``` adobe-marketo-engage_read = glueContext.create_dynamic_frame.from_options( connection_type="adobe-marketo-engage", connection_options={ "connectionName": "connectionName", "ENTITY_NAME": "leads", "API_VERSION": "v1", "PARTITION_FIELD": "createdAt" "LOWER_BOUND": "2024-07-01T00:00:00.000Z" "UPPER_BOUND": "2024-07-02T00:00:00.000Z" "NUM_PARTITIONS": "10" } ``` # Gravação em entidades do Adobe Marketo Engage **Pré-requisitos** + Um objeto do Adobe Marketo em que você gostaria de gravar. Você precisará do nome do objeto, como `leads` ou `customobjects`. + O conector do Adobe Marketo é compatível com três operações de gravação: + INSERT + UPSERT + UPDATE + Para operações de gravação `UPSERT` e `UPDATE`, você deve fornecer a opção `ID_FIELD_NAMES` para especificar o campo ID para os registros. Ao trabalhar com a entidade `leads`, use `email` como `ID_FIELD_NAMES` para operações `UPSERT` e `id` para operações `UPDATE`. Para a entidade `customobjects`, use `marketoGUID` como `ID_FIELD_NAMES` para as operações `UPDATE` e `UPSERT`. **Entidades compatíveis para destino (Síncrono)** | Nome da entidade | Será compatível como conector de destino | Pode ser inserido | Pode ser atualizado | Pode ser upserted | | --- | --- | --- | --- | --- | | leads | Sim | Sim (em massa) | Sim (em massa) | Sim (em massa) | | customobjects | Sim | Sim (em massa) | Sim (em massa) | Sim (em massa) | **Exemplo:** **Operação INSERT:** ``` marketo_write = glueContext.write_dynamic_frame.from_options( frame=frameToWrite, connection_type="marketo", connection_options={ "connectionName": "connectionName", "ENTITY_NAME": "leads", "API_VERSION": "v1", "WRITE_OPERATION": "INSERT" } ``` **Operação UPDATE:** ``` marketo_write = glueContext.write_dynamic_frame.from_options( frame=frameToWrite, connection_type="marketo", connection_options={ "connectionName": "connectionName", "ENTITY_NAME": "leads", "API_VERSION": "v1", "WRITE_OPERATION": "UPDATE", "ID_FIELD_NAMES": "id" } ``` **nota** Para as entidades `leads` e `customobjects`, o Adobe Marketo fornece endpoints para buscar metadados dinamicamente, de forma que os campos graváveis sejam identificados na resposta da API do Marketo. # Opções de conexão do Adobe Marketo Engage Confira abaixo as opções de conexão do Adobe Marketo Engage: + `ENTITY_NAME`(string): (obrigatório) usado para leitura. O nome do seu objeto no Adobe Marketo Engage. + `API_VERSION`(string): (obrigatório) usado para leitura. A versão da API REST do Adobe Marketo Engage que você deseja usar. Por exemplo: v1. + `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. + `TRANSFER_MODE`(String): padrão: SYNC. Usado para leitura assíncrona. + `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 notas do conector do Adobe Marketo Engage Estas são as limitações ou notas do conector do Adobe Marketo Engage: + 'sinceDatetime' e 'activityTypeId' são parâmetros de filtro obrigatórios para a entidade Sync Activities. + As assinaturas recebem 50.000 chamadas de API por dia (que são reiniciadas diariamente às 00:00 CST). Uma capacidade diária adicional pode ser adquirida como parte de uma assinatura do Adobe Marketo Engage. Para referência, consulte [API REST do Adobe Marketo](https://experienceleague.adobe.com/en/docs/marketo-developer/marketo/rest/rest-api). + O período máximo para o filtro do intervalo de datas (`createdAt` ou `updatedAt`) é de 31 dias. Para referência, consulte [Bulk Extract - Marketo Developers](https://experienceleague.adobe.com/en/docs/marketo-developer/marketo/rest/bulk-extract/bulk-extract). + As assinaturas recebem no máximo 10 trabalhos de extração em lote na fila a qualquer momento. Para referência, consulte [Bulk Extract - Marketo Developers](https://experienceleague.adobe.com/en/docs/marketo-developer/marketo/rest/bulk-extract/bulk-extract). + Por padrão, os trabalhos de extração são limitados a 500 MB por dia (que são redefinidos diariamente às 00:00 CST). Uma capacidade diária adicional pode ser adquirida como parte de uma assinatura do Adobe Marketo Engage. Para referência, consulte [Bulk Extract - Marketo Developers](https://experienceleague.adobe.com/en/docs/marketo-developer/marketo/rest/bulk-extract/bulk-extract). + O número máximo de trabalhos de exportação simultâneos é 2. Para referência, consulte [Bulk Extract - Marketo Developers](https://experienceleague.adobe.com/en/docs/marketo-developer/marketo/rest/bulk-extract/bulk-extract). + O número máximo de trabalhos de exportação em fila (incluindo os trabalhos que estão sendo exportados atualmente) é 10. Para referência, consulte [Bulk Extract - Marketo Developers](https://experienceleague.adobe.com/en/docs/marketo-developer/marketo/rest/bulk-extract/bulk-extract). + O tamanho máximo de arquivo permitido é de 1 GB para extrair de um trabalho em lote. + Depois que um trabalho assíncrono for criado, o período de retenção do arquivo será de 7 dias antes da expiração. Para referência, consulte [Bulk Extract - Marketo Developers](https://experienceleague.adobe.com/en/docs/marketo-developer/marketo/rest/bulk-extract/bulk-extract). + `createdAt` ou `updatedAt` são parâmetros de filtro obrigatórios para a entidade Async Leads. + `createdAt` é um parâmetro de filtro obrigatório para a entidade Async Activities. + `updatedAt` é um parâmetro de filtro obrigatório para a entidade Async Custom Object. + Ao usar conectores SaaS do AWS Glue, os usuários não conseguem identificar quais registros específicos falharam durante uma operação de gravação nas plataformas SaaS de destino em casos de falhas parciais. + Ao usar operações de gravação SYNC, quaisquer campos com valores nulos no arquivo de entrada serão automaticamente descartados e não serão enviados para a plataforma SaaS. + Você pode criar ou atualizar até 300 registros em um lote para gravação SYNC. Para obter mais informações, consulte [Práticas recomendadas de integração do Adobe Marketo Engage](https://experienceleague.adobe.com/en/docs/marketo-developer/marketo/rest/marketo-integration-best-practices) e [Extração em lote](https://https://experienceleague.adobe.com/en/docs/marketo-developer/marketo/rest/bulk-extract/bulk-activity-extract).