Documentação Experience Platform Guia dos conectores de origem

Filtrar dados em nível de linha para uma origem usando o Flow Service API

Last update: Tue Jun 20 2023 00:00:00 GMT+0000 (Coordinated Universal Time)

Tópicos:
Sources

Criado para:

Developer

IMPORTANT

Atualmente, o suporte para filtragem de dados em nível de linha está disponível apenas para as seguintes fontes:

Este tutorial fornece etapas sobre como filtrar dados no nível de linha de uma origem usando o Flow Service API.

Introdução

Este tutorial requer que você tenha uma compreensão funcional dos seguintes componentes do Adobe Experience Platform:

Origens: Experience Platform O permite que os dados sejam assimilados de várias fontes e, ao mesmo tempo, fornece a capacidade de estruturar, rotular e aprimorar os dados recebidos usando o Platform serviços.
Sandboxes: Experience Platform O fornece sandboxes virtuais que particionam uma única Platform em ambientes virtuais separados para ajudar a desenvolver aplicativos de experiência digital.

Uso de APIs da plataforma

Para obter informações sobre como fazer chamadas para APIs da Platform com êxito, consulte o manual em introdução às APIs da Platform.

Filtrar dados de origem

As etapas a seguir descrevem as etapas a serem seguidas para filtrar os dados no nível de linha para sua origem.

Pesquisar especificações de conexão

Antes de usar a API para filtrar dados em nível de linha para uma origem, primeiro você deve recuperar os detalhes de especificação da conexão da origem para determinar os operadores e o idioma compatíveis com uma origem específica.

Para recuperar a especificação de conexão de uma determinada origem, faça uma solicitação GET ao /connectionSpecs endpoint do Flow Service ao fornecer o nome da propriedade da fonte como parte dos parâmetros de consulta.

Formato da API

GET /connectionSpecs/{QUERY_PARAMS}

Parâmetro

Descrição

{QUERY_PARAMS}

Os parâmetros de consulta opcionais para filtrar os resultados. Você pode recuperar a variável Google BigQuery especificação de conexão aplicando o name propriedade e especificação "google-big-query" em sua pesquisa.

Solicitação

A solicitação a seguir recupera especificações de conexão para Google BigQuery.

curl -X GET \
  'https://platform.adobe.io/data/foundation/flowservice/connectionSpecs?property=name=="google-big-query"' \
  -H 'Authorization: Bearer {ACCESS_TOKEN}' \
  -H 'x-api-key: {API_KEY}' \
  -H 'x-gw-ims-org-id: {ORG_ID}' \
  -H 'x-sandbox-name: {SANDBOX_NAME}'

Resposta

Uma resposta bem-sucedida retorna as especificações de conexão para Google BigQuery, incluindo informações sobre a linguagem de consulta e os operadores lógicos compatíveis.

NOTE

A resposta da API abaixo está truncada por motivos de brevidade.

"attributes": {
  "filterAtSource": {
    "enabled": true,
    "queryLanguage": "SQL",
    "logicalOperators": [
      "and",
      "or",
      "not"
    ],
    "comparisonOperators": [
      "=",
      "!=",
      "<",
      "<=",
      ">",
      ">=",
      "like",
      "in"
    ],
    "columnNameEscapeChar": "`",
    "valueEscapeChar": "'"
  }

Propriedade

Descrição

attributes.filterAtSource.enabled

Determina se a origem consultada oferece suporte à filtragem de dados em nível de linha.

attributes.filterAtSource.queryLanguage

Determina o idioma da consulta que a fonte consultada aceita.

attributes.filterAtSource.logicalOperators

Determina os operadores lógicos que você pode usar para filtrar dados em nível de linha para a origem.

attributes.filterAtSource.comparisonOperators

Determina operadores de comparação que você pode usar para filtrar dados em nível de linha para sua origem. Consulte a tabela abaixo para obter mais informações sobre operadores de comparação.

attributes.filterAtSource.columnNameEscapeChar

Determina o caractere a ser usado para colunas de escape.

attributes.filterAtSource.valueEscapeChar

Determina como os valores serão cercados ao gravar uma consulta SQL.

Operadores de comparação

Operador

Descrição

==

Define se a propriedade é igual ao valor fornecido.

!=

Define se a propriedade não é igual ao valor fornecido.

<

Define se a propriedade é menor que o valor fornecido.

>

Filtra especificando se a propriedade é maior que o valor fornecido.

<=

Filtra se a propriedade é menor ou igual ao valor fornecido.

>=

Filtra se a propriedade é maior ou igual ao valor fornecido.

like

Filtros sendo usados em um WHERE para procurar um padrão especificado.

in

Define se a propriedade está dentro de um intervalo especificado.

Especificar condições de filtragem para assimilação

Depois de identificar os operadores lógicos e o idioma de consulta que sua origem aceita, você pode usar o Idioma de consulta de perfil (PQL) para especificar as condições de filtragem que deseja aplicar aos dados de origem.

No exemplo abaixo, as condições são aplicadas apenas a dados de seleção que sejam iguais aos valores fornecidos para os tipos de nó listados como parâmetros.

{
  "type": "PQL",
  "format": "pql/json",
  "value": {
    "nodeType": "fnApply",
    "fnName": "=",
    "params": [
      {
        "nodeType": "fieldLookup",
        "fieldName": "city"
      },
      {
        "nodeType": "literal",
        "value": "DDN"
      }
    ]
  }
}

Pré-visualizar seus dados

Você pode visualizar seus dados fazendo uma solicitação GET para o /explore endpoint do Flow Service API ao fornecer filters como parte dos parâmetros de consulta e especificando as condições de entrada de PQL em Base64.

Formato da API

GET /connections/{BASE_CONNECTION_ID}/explore?objectType=table&object={TABLE_PATH}&preview=true&filters={FILTERS}

Parâmetro

Descrição

{BASE_CONNECTION_ID}

A ID de conexão básica da sua origem.

{TABLE_PATH}

A propriedade de caminho da tabela que você deseja inspecionar.

{FILTERS}

As condições do filtro PQL estão codificadas em Base64.

Solicitação

curl -X GET \
  'https://platform.adobe.io/data/foundation/flowservice/connections/89d1459e-3cd0-4069-acb3-68f240db4eeb/explore?objectType=table&object=TESTFAS.FASTABLE&preview=true&filters=ewogICJ0eXBlIjogIlBRTCIsCiAgImZvcm1hdCI6ICJwcWwvanNvbiIsCiAgInZhbHVlIjogewogICAgIm5vZGVUeXBlIjogImZuQXBwbHkiLAogICAgImZuTmFtZSI6ICJhbmQiLAogICAgInBhcmFtcyI6IFsKICAgICAgewogICAgICAgICJub2RlVHlwZSI6ICJmbkFwcGx5IiwKICAgICAgICAiZm5OYW1lIjogImxpa2UiLAogICAgICAgICJwYXJhbXMiOiBbCiAgICAgICAgICB7CiAgICAgICAgICAgICJub2RlVHlwZSI6ICJmaWVsZExvb2t1cCIsCiAgICAgICAgICAgICJmaWVsZE5hbWUiOiAiY2l0eSIKICAgICAgICAgIH0sCiAgICAgICAgICB7CiAgICAgICAgICAgICJub2RlVHlwZSI6ICJsaXRlcmFsIiwKICAgICAgICAgICAgInZhbHVlIjogIk0lIgogICAgICAgICAgfQogICAgICAgIF0KICAgICAgfQogICAgXQogIH0KfQ==\' \
  -H 'Authorization: Bearer {ACCESS_TOKEN}' \
  -H 'x-api-key: {API_KEY}' \
  -H 'x-gw-ims-org-id: {IMS_ORG}' \
  -H 'x-sandbox-name: {SANDBOX_NAME}'

Resposta

Uma solicitação bem-sucedida retorna a seguinte resposta.

{
  "format": "flat",
  "schema": {
    "columns": [
      {
        "name": "FIRSTNAME",
        "type": "string",
        "xdm": {
          "type": "string"
        }
      },
      {
        "name": "LASTNAME",
        "type": "string",
        "xdm": {
          "type": "string"
        }
      },
      {
        "name": "CITY",
        "type": "string",
        "xdm": {
          "type": "string"
        }
      },
      {
        "name": "AGE",
        "type": "string",
        "xdm": {
          "type": "string"
        }
      },
      {
        "name": "HEIGHT",
        "type": "string",
        "xdm": {
          "type": "string"
        }
      },
      {
        "name": "ISEMPLOYED",
        "type": "boolean",
        "xdm": {
          "type": "boolean"
        }
      },
      {
        "name": "POSTG",
        "type": "boolean",
        "xdm": {
          "type": "boolean"
        }
      },
      {
        "name": "LATITUDE",
        "type": "double",
        "xdm": {
          "type": "number"
        }
      },
      {
        "name": "LONGITUDE",
        "type": "double",
        "xdm": {
          "type": "number"
        }
      },
      {
        "name": "JOINEDDATE",
        "type": "string",
        "meta:xdmType": "date-time",
        "xdm": {
          "type": "string",
          "format": "date-time"
        }
      },
      {
        "name": "CREATEDAT",
        "type": "string",
        "meta:xdmType": "date-time",
        "xdm": {
          "type": "string",
          "format": "date-time"
        }
      },
      {
        "name": "CREATEDATTS",
        "type": "string",
        "meta:xdmType": "date-time",
        "xdm": {
          "type": "string",
          "format": "date-time"
        }
      }
    ]
  },
 "data": [
    {
        "CITY": "MZN",
        "LASTNAME": "Jain",
        "JOINEDDATE": "2022-06-22T00:00:00",
        "LONGITUDE": 1000.222,
        "CREATEDAT": "2022-06-22T17:19:33",
        "FIRSTNAME": "Shivam",
        "POSTG": true,
        "HEIGHT": "169",
        "CREATEDATTS": "2022-06-22T17:19:33",
        "ISEMPLOYED": true,
        "LATITUDE": 2000.89,
        "AGE": "25"
    },
    {
        "CITY": "MUM",
        "LASTNAME": "Kreet",
        "JOINEDDATE": "2022-09-07T00:00:00",
        "LONGITUDE": 10500.01,
        "CREATEDAT": "2022-09-07T17:19:33",
        "FIRSTNAME": "Rakul",
        "POSTG": true,
        "HEIGHT": "155",
        "CREATEDATTS": "2022-09-07T17:19:33",
        "ISEMPLOYED": false,
        "LATITUDE": 2500.89,
        "AGE": "42"
    },
    {
        "CITY": "MAN",
        "LASTNAME": "Lee",
        "JOINEDDATE": "2022-09-14T00:00:00",
        "LONGITUDE": 1000.222,
        "CREATEDAT": "2022-09-14T05:02:33",
        "FIRSTNAME": "Denzel",
        "POSTG": true,
        "HEIGHT": "185",
        "CREATEDATTS": "2022-09-14T05:02:33",
        "ISEMPLOYED": true,
        "LATITUDE": 123.89,
        "AGE": "16"
    }
  ]
}

Criar uma conexão de origem para dados filtrados

Para criar uma conexão de origem e assimilar dados filtrados, faça uma solicitação POST para o /sourceConnections ao fornecer as condições de filtragem como parte dos parâmetros do corpo.

Formato da API

POST /sourceConnections

Solicitação

A solicitação a seguir cria uma conexão de origem para assimilar dados de test1.fasTestTable onde city = DDN.

curl -X POST \
  'https://platform.adobe.io/data/foundation/flowservice/sourceConnections' \
  -H 'Authorization: Bearer {ACCESS_TOKEN}' \
  -H 'x-api-key: {API_KEY}' \
  -H 'x-gw-ims-org-id: {ORG_ID}' \
  -H 'x-sandbox-name: {SANDBOX_NAME}' \
  -H 'Content-Type: application/json' \
  -d '{
      "name": "BigQuery Source Connection",
      "description": "Source Connection for Filter test",
      "baseConnectionId": "89d1459e-3cd0-4069-acb3-68f240db4eeb",
      "data": {
        "format": "tabular"
      },
      "params": {
        "tableName": "test1.fasTestTable",
        "filters": {
          "type": "PQL",
          "format": "pql/json",
          "value": {
            "nodeType": "fnApply",
            "fnName": "=",
            "params": [
              {
                "nodeType": "fieldLookup",
                "fieldName": "city"
              },
              {
                "nodeType": "literal",
                "value": "DDN"
              }
            ]
          }
        }
      },
      "connectionSpec": {
        "id": "3c9b37f8-13a6-43d8-bad3-b863b941fedd",
        "version": "1.0"
      }
    }'

Resposta

Uma resposta bem-sucedida retorna o identificador exclusivo (id) da conexão de origem recém-criada.

{
    "id": "b7581b59-c603-4df1-a689-d23d7ac440f3",
    "etag": "\"ef05d265-0000-0200-0000-6019e0080000\""
}

Apêndice

Esta seção fornece mais exemplos de diferentes payloads para filtragem.

Condições peculiares

É possível omitir o fnApply para cenários que exigem apenas uma condição.

{
  "type": "PQL",
  "format": "pql/json",
  "value": {
    "nodeType": "fnApply",
    "fnName": "like",
    "params": [
      {
        "nodeType": "fieldLookup",
        "fieldName": "firstname"
      },
      {
        "nodeType": "literal",
        "value": "%s"
      }
    ]
  }
}

Usar o `in` operador

Consulte a carga de exemplo abaixo para obter um exemplo do operador in.

{
  "type": "PQL",
  "format": "pql/json",
  "value": {
    "nodeType": "fnApply",
    "fnName": "and",
    "params": [
      {
        "nodeType": "fnApply",
        "fnName": "in",
        "params": [
          {
            "nodeType": "fieldLookup",
            "fieldName": "firstname"
          },
          {
            "nodeType": "literal",
            "value": [
              "Ramen",
              "John"
            ]
          }
        ]
      }
    ]
  }
}

Usar o `isNull` operador

Consulte a carga de exemplo abaixo para obter um exemplo do operador isNull.

{
  "type": "PQL",
  "format": "pql/json",
  "value": {
    "nodeType": "fnApply",
    "fnName": "isNull",
    "params": [
      {
        "nodeType": "fieldLookup",
        "fieldName": "complaint_type"
      }
    ]
  }
}

Usar o `NOT` operador

Consulte a carga de exemplo abaixo para obter um exemplo do operador NOT.

{
  "type": "PQL",
  "format": "pql/json",
  "value": {
    "nodeType": "fnApply",
    "fnName": "NOT",
    "params": [
      {
        "nodeType": "fnApply",
        "fnName": "isNull",
        "params": [
          {
            "nodeType": "fieldLookup",
            "fieldName": "complaint_type"
          }
        ]
      }
    ]
  }
}

Exemplo com condições aninhadas

Consulte a carga de amostra abaixo para obter um exemplo de condições aninhadas complexas.

{
  "type": "PQL",
  "format": "pql/json",
  "value": {
    "nodeType": "fnApply",
    "fnName": "and",
    "params": [
      {
        "nodeType": "fnApply",
        "fnName": ">=",
        "params": [
          {
            "nodeType": "fieldLookup",
            "fieldName": "age"
          },
          {
            "nodeType": "literal",
            "value": 20
          }
        ]
      },
      {
        "nodeType": "fnApply",
        "fnName": "<=",
        "params": [
          {
            "nodeType": "fieldLookup",
            "fieldName": "age"
          },
          {
            "nodeType": "literal",
            "value": 30
          }
        ]
      },
      {
        "nodeType": "fnApply",
        "fnName": "or",
        "params": [
          {
            "nodeType": "fnApply",
            "fnName": "!=",
            "params": [
              {
                "nodeType": "fieldLookup",
                "fieldName": "city"
              },
              {
                "nodeType": "literal",
                "value": "PUD"
              }
            ]
          },
          {
            "nodeType": "fnApply",
            "fnName": "=",
            "params": [
              {
                "nodeType": "fieldLookup",
                "fieldName": "joinedDate"
              },
              {
                "nodeType": "literal",
                "value": "2020-04-22"
              }
            ]
          }
        ]
      }
    ]
  }
}

recommendation-more-help

337b99bb-92fb-42ae-b6b7-c7042161d089

Filtrar dados em nível de linha para uma origem usando o Flow Service API

Introdução

Uso de APIs da plataforma

Filtrar dados de origem

Pesquisar especificações de conexão

Operadores de comparação

Especificar condições de filtragem para assimilação

Pré-visualizar seus dados

Criar uma conexão de origem para dados filtrados

Apêndice

Condições peculiares

Usar o in operador

Usar o isNull operador

Usar o NOT operador

Exemplo com condições aninhadas

Usar o `in` operador

Usar o `isNull` operador

Usar o `NOT` operador