# Destinations ### Destinations #### API Rest Agnostic A seguir temos as configurações necessárias para cadasdtrar um REST API com "destination". ````json ```json "rest_api": [ { "id": "instanceid", "method": "POST", "base_url": "https://api.rd.services", "routes": { "contacts": "/platform/contacts", "deals": "/platform/deals", "companies": "/platform/companies" }, "docs": "https://developers.rdstation.com/en/reference/contacts", "is_active": true, "api_key": "asas", "api_version": "v15.0", "auth_type": { "type": "Bearer", "settings": { "token": "samplexasasadda" } }, "headers": { "Content-Type": "application/json", "accept": "application/json" } } ] }, ``` ```` **method** O atributo é o tipo de VERBO padrão que será utilizado caso uma rota não tenha um verbo definido. **routes** São as rotas configuradas como destino e podem ser definidas a partir de uma condição em **Filtros**. Ao apontar para um destino API Rest Agnostic iremos enviar o evento "as-is" para a base\_url + route selecionada e utilizar o tipo de verbo para requisição da rota ou o default. ````json // Sample routes ```json "routes": { "contacts": { "path": "/platform/contacts", "method": "POST" }, "deals": { "path": "/platform/deals/", "method": "GET" }, "companies": "/platform/companies" }, ``` ```` **{{route}}** Se for adicionado {{route}} na base\_url a rota default será interpolado no local exato onde {{route}} foi inserido. Logo, se você precisa alterar a ordem da concactenação utilize {{route}}. Se ```typescript "base_url": "http://localhost:3000/{{route}}?access_key={{access_key}}" ``` Quando a rota ou qualquer rota for interpolada na base\_url, ao invés de concatenar base\_url com rota.default.path será interpolado no local exatado de route. O resultado do uso de {{route}} na base url irá resultar em para o exemplo com \`deals\`. > base\_url + deals.path > > DE: > > PARA: [http://localhost:3000/](http://localhost:3000/{{route}}?access_key={{access_key}}")platform/deals/[?access\_key={{access\_key}}"](http://localhost:3000/{{route}}?access_key={{access_key}}") Sem {{route}} o resultado seria > base\_url + deals.path > > DE: [http://localhost:3000/?access\_key={{access\_key}}"](http://localhost:3000/{{route}}?access_key={{access_key}}") > > PARA: " **api\_version** Caso \`api\_version\` esteja definido é necessário que \`base\_url\` tenha a variável de interpolação \`{{api\_version}}\` para a correta aplicação da versão. Veja o exemplo. ```json "rest_api": [ { "id": "instanceid", "method": "POST", "base_url": "https://api.rd.services/{{api_version}}", ... ``` **auth\_type** Há variadas possibilidades para autenticar em uma API REST. No Agnostic Data temos algumas suportadas para a implementação de um destination REST. > **Lembre-se** > > * Existem duas formas de fluxo de dados: > * **1) Destinations** são fluxos onde todo o payload será encaminhado para o destino > * no máximo o usuário pode remover alguns campos via **filtros** para casos como supressão de dados pessoais, etc. > * **2) Actions**: é possível introspectar no conteúdo do evento e modificar, incrementar, adicionar dados ao evento ou outras ações. > * Uma função poderá ouvir o gatilho de uma action para executar qualquer manipulação. (Atualmente essa estratégia está em beta fechado). > * Temos dois tipos de tratamentos > * **Diretos** onde para cada evento (tupla) poderá ser enviado para um destination (evento original ou supressão de alguns campos ou uma action (conteúdo personalizado) > * **Aggregations** quando uma computação/processamento de agregação de dados é realizada. (a definir) **Settings para auth\_type** *Quando auth\_type {type: "access\_key"}* Com auth\_type "access\_key" será substituída as variáveis em settings como parâmetros de URL (querystring), desta forma, a a url\_base deverá ter os mesmos nomes de variáveis dentro de settings para serem interpoladas. No exemplo abaixo, aplicamos o auth\_type "access\_key" para a URL do Google Analytics Measurement. Veja o exemplo. **URL base Google Analytics Measurement ID** ""; ```javascript const project_settings = { { "id": "instanceid", "method": "POST", "base_url": "https://www.google-analytics.com/mp/collect?measurement_id={{measurement_id}}&api_secret={{api_secret}}" ... "auth_type": { "type": "access_key", "settings": { "measurement_id": "1293912831737687", "api_secret": "meusegredo" } } ... } } ``` > Lembre-se: acima temos apenas um exemplo para o Google Analytics Measurement, contudo para o GA Measurement a implemente oficial do Agnostic Data basta informar id e access\_token pela console de cadastro de destinations, onde **id** é measurement\_id e **access\_token** é api\_secret. *Quando auth\_type {type: "Bearer"}* ```javascript const project_settings = { { "id": "instanceid", "method": "POST" ... "auth_type": { "type": "Bearer", "settings": { "token": "samplehashtokenforBearer" } } ... } } ``` *Quando auth\_type {type: "*Oauth2*"}* ```javascript const project_settings = { { "id": "instanceid", "method": "POST" ... "auth_type": { "type": "Bearer", "settings": { "access_token": "samplehashtokenforBearer", "refresh_token": "", "client_id": "", "client_secret": "", "code": "", "url_callback": "http://example.com" "url_callback_encoded": "http%3A%2F%2Fexample.com" } } ... } } ``` ### BigQuery Destination (schematized) Para configurar um Google Biguery como Destino é simples basta informar o id do projeto, dataset e tabela, um e-mail de uma service account e sua private key convertida em base64. * **is\_active**: Indica se a configuração está ativa ou não. . * **id**: Identificador no formato "PROJECT\_ID.DATASET.TABLE". * **project\_id**: O ID do projeto no GCP. * **client\_email**: O e-mail da service account associado à conta de serviço que tem permissão para acessar o BigQuery no projeto. * Papéis: * role = "roles/bigquery.dataEditor" * role = "roles/bigquery.jobUser" * role = "roles/bigquery.dataEditor" * **private\_key\_base64**: A chave privada da conta de serviço codificada em base64. Essa chave é usada para autenticar a conta de serviço ao acessar o BigQuery. * **account\_id**: O ID da conta de serviço associada (service account) à configuração. * **dataset\_name**: O nome do conjunto de dados (dataset) no BigQuery onde os dados serão armazenados. * **dataset\_table**: O nome da tabela dentro do conjunto de dados onde os dados serão armazenados. Neste caso, a tabela é chamada "events". * **dataset\_location**: A localização geográfica onde o conjunto de dados está localizado no BigQuery. Isso pode afetar a latência e a conformidade regulatória. [Lista de locais](https://cloud.google.com/bigquery/docs/locations?hl=pt-br). ```json "destinations": { "bigquery": [ { "is_active": true, "id": "PROJECT_ID.agnostic.events", "project_id": "PROJECT_ID", "client_email": "ACCOUNT_ID@PROJECT_ID.iam.gserviceaccount.com", "private_key_base64": "PRIVATE_KEY_FROM_JSON_KEY_AS_BASE64", "account_id": "ACCOUNT_ID", "dataset_name": "agnostic", "dataset_table": "events", "dataset_location": "LOCATION" } ], ``` Utilize o esquema abaixo para receber os eventos *"as-is"* do Agnostic Data.
AVRO Scheme ```json [ { "name": "inserted_date", "mode": "NULLABLE", "type": "INTEGER", "description": "timestamp do insert do lado do servidor", "fields": [] }, { "name": "created", "mode": "NULLABLE", "type": "INTEGER", "description": "timestamp do evento enviado pelo cliente", "fields": [] }, { "name": "event_name", "mode": "NULLABLE", "type": "STRING", "description": "nome do evento Custom", "fields": [] }, { "name": "eid", "mode": "NULLABLE", "type": "STRING", "description": "ID do evento do sistema de fluxo pub/sub, kafka, etc", "fields": [] }, { "name": "event_type", "mode": "NULLABLE", "type": "STRING", "description": "agnostic, facebook, google, algolia, etc.", "fields": [] }, { "name": "event_name_from_type", "mode": "NULLABLE", "type": "STRING", "description": "nome original do evento em agnostic, facebook, google, etc", "fields": [] }, { "name": "scope", "mode": "NULLABLE", "type": "STRING", "description": "indicado para receber nome do projeto, quando o cliente tem vários e 1 bigquery", "fields": [] }, { "name": "event_provider", "mode": "NULLABLE", "type": "STRING", "description": "para indicar o provedor do evento (marketplace)", "fields": [] }, { "name": "app_info_version", "mode": "NULLABLE", "type": "STRING", "description": "build do aplicativo Customer", "fields": [] }, { "name": "app_package_name", "mode": "NULLABLE", "type": "STRING", "description": "e.g: com.customer.app", "fields": [] }, { "name": "relative_view", "mode": "NULLABLE", "type": "STRING", "description": "utilizado para definir caminhso relatios app/view1 ou site/urlrelativa", "fields": [] }, { "name": "action_source", "mode": "NULLABLE", "type": "STRING", "description": "identify which source the action came from", "fields": [] }, { "name": "carrier", "mode": "NULLABLE", "type": "STRING", "description": "operadora ", "fields": [] }, { "name": "session_id", "mode": "NULLABLE", "type": "STRING", "description": "session id navegacao", "fields": [] }, { "name": "user_id", "mode": "NULLABLE", "type": "STRING", "description": "id do usuário Customer", "fields": [] }, { "name": "user_pseudo_id", "mode": "NULLABLE", "type": "STRING", "description": "identificador de usuário de terceiros ou lead ainda não cadastrado", "fields": [] }, { "name": "user_phone", "mode": "NULLABLE", "type": "STRING", "description": "telefone se existir", "fields": [] }, { "name": "userToken", "mode": "NULLABLE", "type": "STRING", "description": "user token do algolia", "fields": [] }, { "name": "is_promo", "mode": "NULLABLE", "type": "STRING", "description": "se existia uma promoção relacionado ao evento", "fields": [] }, { "name": "device_id", "mode": "NULLABLE", "type": "STRING", "description": "id do device", "fields": [] }, { "name": "device_brand", "mode": "NULLABLE", "type": "STRING", "description": "marca do device", "fields": [] }, { "name": "device_resolution", "mode": "NULLABLE", "type": "STRING", "description": "resolucao do dispositivo", "fields": [] }, { "name": "device_screen_density", "mode": "NULLABLE", "type": "INTEGER", "description": "densidade da tela em inteiro x10", "fields": [] }, { "name": "device_so", "mode": "NULLABLE", "type": "STRING", "description": "sistema operacional ", "fields": [] }, { "name": "device_so_version", "mode": "NULLABLE", "type": "STRING", "description": "versao do so", "fields": [] }, { "name": "device_language", "mode": "NULLABLE", "type": "STRING", "description": "idioma", "fields": [] }, { "name": "device_model_name", "mode": "NULLABLE", "type": "STRING", "description": "e.g: iPhone 11", "fields": [] }, { "name": "device_web_browser", "mode": "NULLABLE", "type": "STRING", "description": "navegador do device ou utilizado", "fields": [] }, { "name": "device_ipaddress", "mode": "NULLABLE", "type": "STRING", "description": "endereço ipv4 ou ipv6", "fields": [] }, { "name": "device_geohash", "mode": "NULLABLE", "type": "STRING", "description": "geohash com 4 a 5 acuracidade", "fields": [] }, { "name": "device_timezone", "mode": "NULLABLE", "type": "STRING", "description": "String no formato: America/Sao_Paulo:GMT-3 ", "fields": [] }, { "name": "opened_from_type", "mode": "NULLABLE", "type": "STRING", "description": "identifica de onde o usuario abriu o app, push, dymic link ou outros", "fields": [] }, { "name": "opened_from_content", "mode": "NULLABLE", "type": "STRING", "description": "o conteudo como url, push message, etc", "fields": [] }, { "name": "rfid", "type": "RECORD", "mode": "NULLABLE", "description": "group people by regex for hash id", "fields": [ { "name": "tl", "mode": "NULLABLE", "type": "STRING", "description": "telephone number is sha256 without blank space and special characters", "fields": [] }, { "name": "ad", "mode": "NULLABLE", "type": "STRING", "description": "address id is sha256 without blank space and special characters" }, { "name": "cc", "mode": "NULLABLE", "type": "STRING", "description": "credit card id is sha256 without blank space and special characters" }, { "name": "em", "mode": "NULLABLE", "type": "STRING", "description": "email id is sha256 without blank space and special characters" } ] }, { "name": "geodata", "mode": "NULLABLE", "type": "RECORD", "description": "dados de geolocalizacao", "fields": [ { "name": "latitude", "mode": "NULLABLE", "type": "FLOAT", "description": "latitude", "fields": [] }, { "name": "longitude", "mode": "NULLABLE", "type": "FLOAT", "description": "longitude", "fields": [] }, { "name": "city", "mode": "NULLABLE", "type": "STRING", "description": "cidade", "fields": [] }, { "name": "region", "mode": "NULLABLE", "type": "STRING", "description": "regiao", "fields": [] }, { "name": "region_code", "mode": "NULLABLE", "type": "STRING", "description": "codigo da regiao", "fields": [] }, { "name": "country", "mode": "NULLABLE", "type": "STRING", "description": "pais", "fields": [] }, { "name": "country_name", "mode": "NULLABLE", "type": "STRING", "description": "nome do pais", "fields": [] }, { "name": "country_code", "mode": "NULLABLE", "type": "STRING", "description": "codigo do pais", "fields": [] }, { "name": "continent_code", "mode": "NULLABLE", "type": "STRING", "description": "codigo do continente", "fields": [] }, { "name": "postal", "mode": "NULLABLE", "type": "STRING", "description": "codigo postal", "fields": [] }, { "name": "org", "mode": "NULLABLE", "type": "STRING", "description": "organizacao", "fields": [] } ] }, { "name": "target_data", "mode": "REPEATED", "type": "RECORD", "description": "DEPRECATED: pares de valores com target_name:value_for_id. utilizados para compor uma URL ex.: api.{target_name}.com/{value_for_id}/events?name=abc", "fields": [ { "name": "key", "mode": "NULLABLE", "type": "STRING", "description": "pre-definidos nomes de chaves (key) devem ser recomendados para traduzir em um link válido da API destino", "fields": [] }, { "name": "value", "mode": "NULLABLE", "type": "STRING", "description": "para valores string para o ID do target", "fields": [] } ] }, { "name": "event_data", "mode": "REPEATED", "type": "RECORD", "description": null, "fields": [ { "name": "key", "mode": "NULLABLE", "type": "STRING", "description": null, "fields": [] }, { "name": "value", "mode": "NULLABLE", "type": "RECORD", "description": null, "fields": [ { "name": "string_value", "mode": "NULLABLE", "type": "STRING", "description": "para valores string", "fields": [] }, { "name": "int_value", "mode": "NULLABLE", "type": "INTEGER", "description": "para valores inteiros", "fields": [] }, { "name": "float_value", "mode": "NULLABLE", "type": "FLOAT", "description": "para valores decimais", "fields": [] }, { "name": "boolean_value", "mode": "NULLABLE", "type": "BOOLEAN", "description": "para verdadeiro ou falso", "fields": [] } ] } ] }, { "name": "items", "mode": "REPEATED", "type": "RECORD", "description": null, "fields": [ { "name": "item_name", "mode": "NULLABLE", "type": "STRING", "description": null, "fields": [] }, { "name": "lisn_departament", "mode": "NULLABLE", "type": "STRING", "description": null, "fields": [] }, { "name": "lisn_section", "mode": "NULLABLE", "type": "STRING", "description": null, "fields": [] }, { "name": "lisn_item", "mode": "NULLABLE", "type": "STRING", "description": null, "fields": [] }, { "name": "quantity", "mode": "NULLABLE", "type": "INTEGER", "description": null, "fields": [] }, { "name": "currency", "mode": "NULLABLE", "type": "STRING", "description": null, "fields": [] }, { "name": "value", "mode": "NULLABLE", "type": "INTEGER", "description": null, "fields": [] }, { "name": "price", "mode": "NULLABLE", "type": "FLOAT", "description": null, "fields": [] }, { "name": "index_pos", "mode": "NULLABLE", "type": "INTEGER", "description": "position", "fields": [] }, { "name": "id", "mode": "NULLABLE", "type": "STRING", "description": "FK do item", "fields": [] }, { "name": "item_id", "mode": "NULLABLE", "type": "STRING", "description": "o mesmo que id utilizado pelo Google Analytics", "fields": [] }, { "name": "coupon", "mode": "NULLABLE", "type": "STRING", "description": null, "fields": [] }, { "name": "affiliation", "mode": "NULLABLE", "type": "STRING", "description": null, "fields": [] }, { "name": "discount_value", "mode": "NULLABLE", "type": "INTEGER", "description": "valor em desconto como inteiro", "fields": [] }, { "name": "item_category", "mode": "NULLABLE", "type": "STRING", "description": null, "fields": [] }, { "name": "item_category2", "mode": "NULLABLE", "type": "STRING", "description": null, "fields": [] }, { "name": "item_list_name", "mode": "NULLABLE", "type": "STRING", "description": null, "fields": [] }, { "name": "item_list_id", "mode": "NULLABLE", "type": "STRING", "description": null, "fields": [] }, { "name": "location_id", "mode": "NULLABLE", "type": "STRING", "description": "zonas do Customer", "fields": [] }, { "name": "promotion_id", "mode": "NULLABLE", "type": "STRING", "description": "id da promocao no banco", "fields": [] }, { "name": "promotion_name", "mode": "NULLABLE", "type": "STRING", "description": "nome da promoçao", "fields": [] } ] } ] ```
### BigQuery Destination (raw changelog) Diferente do destino BigQuery esquematizado com os campos pré-definidos e modelados conforme nosso AVRO Scheme, o cliente também pode habilitar um BigQuery Destination Raw Changelog. Os dados armazenados nesta tabela são brutos, ou seja, estão no formato original em que foram capturados, sem processamento, filtragem ou agregação. Neste contexto, implica que a tabela não apenas registra eventos, mas especificamente as mudanças ou atualizações que ocorrem. Isso pode incluir informações sobre o que foi alterado, quando, e possivelmente quem fez a mudança, oferecendo um histórico detalhado de eventos que alteram o estado ou os dados dentro do sistema.
AVRO Raw Scheme ```json [ { "name": "inserted_date", "mode": "REQUIRED", "type": "INTEGER", "description": "timestamp do insert do lado do servidor", "fields": [] }, { "name": "eid", "mode": "REQUIRED", "type": "STRING", "description": "ID do evento do sistema de fluxo pub/sub, kafka, etc", "fields": [] }, { "name": "operation", "mode": "NULLABLE", "type": "STRING", "description": "CREATE, UPDATE, IMPORT, or DELETE.", "fields": [] }, { "name": "data", "mode": "NULLABLE", "type": "STRING", "description": "JSON com os dados do evento", "fields": [] }, { "name": "document_path", "mode": "NULLABLE", "type": "STRING", "description": "JSON com os dados do evento", "fields": [] } ] ```
Explorando os dados #### Dicas de processamento dos dados raw Faça a importação das bibliotecas necessárias ```python import pandas as pd import pandas_gbq as pgbq import json from pandas import json_normalize ... // conexão com o BQ ... ``` em seguida faça a consulta utilizando um controle de tempo e limite devido ao grande volume de dados. ```python # Sua consulta SQL query = """ SELECT * FROM `project_id.dataset.events_raw` WHERE inserted_date >= TIMESTAMP('2024-02-01') AND inserted_date < TIMESTAMP('2024-03-01') LIMIT 1000000 """ ``` Atribua a variável *df* para começar a manipular seus dados. ```python df = pgbq.read_gbq(query, project_id="project_id", dialect="standard") ``` Normalize o JSON ```python ## Converta data (json) do esquema firestore_export para um dataframe data = df['data'].apply(json.loads) ## normalizar o data para torna-se um dataframe df_data = pd.json_normalize(data) ``` Acesse os dados e aprenda profundamente! Veja um exemplo de exploração. ```python # Event durations counts df_data['event.duration'].value_counts() ```
## Elastic Cloud Destinations Para configurar um Elastic Cloud como Destino é simples basta informar o id do projeto, o nome do índice, url do endpoint disponível na console do elastic e a chave convertida em base64. ```json "destinations": { "elastic": [ { "is_active": true, "id": "YOUR_ID:YOUR_ACCESSKEY_PROVIDED_BY_ELASTIC_CLOUD", "index": "events", "private_key_base64": "YOUR_KEY_AS_BASE64", "url": "https://YOUR_ID_INSTANCE.brazilsouth.azure.elastic-cloud.com:9243", "event_rename": { "view_content": "view_content_v2" } } ], ``` ### Renomeando evento para um destino (elastic - consulte-nos) Existem casos de uso onde você precisará alterar o nome do evento original para um nome final desejado, por exemplo, caso um índice do elastic não possa receber mais eventos por exemplo view\_content podemos renomeá-lo para o destino Elastic utilizando **event\_rename**. Abaixo payload para configurar o Destination Elastic para renomear todos os eventos view\_content. ```json "destinations": { "elastic": [ { ... "event_rename": { "view_content": "view_content_v2" } } ], ``` ### Elastic: Renomeando um índice baseado em um evento Existem casos de uso onde você precisará alterar o nome do índice padrão para um nome final desejado, por exemplo, caso um índice do elastic não possa receber mais eventos por exemplo view\_content podemos renomeá-lo para o destino Elastic utilizando **index\_rename\_by\_event** ```json index_rename_by_event ``` Os nomes dos índices criados pelo Agnostic Data no Elastic seguem o padrão abaixo: ```javascript index_concat = `${destination.index}_${project_id}_${objectPlain.event_name}`; // events_YOUR_AGNOSTICDATA_PROJECT_ID_view_content ``` Digamos que você precise alterar de events\_YOUR\_AGNOSTICDATA\_PROJECT\_ID\_view\_content para events\_YOUR\_AGNOSTICDATA\_PROJECT\_ID\_view\_content\_v2. Siga os passos para definir o payload. Abaixo payload para configurar o Destination Elastic para renomear todos os eventos view\_content. ```json "destinations": { "elastic": [ { ... "index_rename_by_event": { "view_content": "events_new-dedicated-01_view_content_v2" } } ], ``` *** ### Google Ads (roadmap) #### Prerequisites Uma conta [Google Ads](https://support.google.com/google-ads/answer/6366720) "linkada" para uma uma Conta de Administrador do Google Ads ([Google Ads Manager account)](https://support.google.com/google-ads/answer/7459601) * Customer ID(s) - * Customer Statuses Filter - #### Principais tabelas * customer * customer\_label * campaign\_criterion * campaign\_bidding\_strategy * campaign\_label * label * ad\_group\_ad * ad\_group\_ad\_label * ad\_group --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://docs.agnosticdata.ai/agnosticdata.ai-or-documentation/fundamentals/destinations.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.