DocumentationExperience PlatformGuide des connecteurs source

Filtrez les données au niveau de la ligne d’une source à l’aide de la méthode Flow Service API

Last update: Tue Nov 14 2023 00:00:00 GMT+0000 (Coordinated Universal Time)

Créé pour :

  • Développeur
IMPORTANT
La prise en charge du filtrage des données au niveau des lignes n’est actuellement disponible que pour les sources suivantes :

Ce tutoriel décrit les étapes à suivre pour filtrer les données au niveau de la ligne pour une source à l’aide de la variable Flow Service API.

Prise en main

Ce tutoriel nécessite une compréhension du fonctionnement des composants suivants d’Adobe Experience Platform :

  • Sources: Experience Platformpermet d’ingérer des données provenant de diverses sources tout en vous offrant la possibilité de structurer, d’étiqueter et d’améliorer les données entrantes à l’aide des services Platform.
  • Sandbox : Experience Platform fournit des sandbox virtuels qui divisent une instance Platform unique en environnements virtuels distincts pour favoriser le développement et l’évolution d’applications d’expérience digitale.

Utiliser les API Platform

Pour plus d’informations sur la manière d’effectuer des appels vers les API Platform, consultez le guide Prise en main des API Platform.

Filtrage des données source

Les étapes suivantes décrivent les étapes à suivre pour filtrer les données au niveau de la ligne pour votre source.

Recherche des spécifications de connexion

Avant de pouvoir utiliser l’API pour filtrer les données au niveau des lignes d’une source, vous devez d’abord récupérer les détails de spécification de connexion de votre source afin de déterminer les opérateurs et la langue pris en charge par une source spécifique.

Pour récupérer la spécification de connexion d’une source donnée, envoyez une requête GET à la fonction /connectionSpecs point d’entrée du Flow Service API tout en fournissant le nom de propriété de votre source dans le cadre de vos paramètres de requête.

Format d’API

GET /connectionSpecs/{QUERY_PARAMS}
Paramètre
Description
{QUERY_PARAMS}
Paramètres de requête facultatifs selon lesquels filtrer les résultats. Vous pouvez récupérer la variable Google BigQuery spécification de connexion en appliquant la name propriété et spécification "google-big-query" dans votre recherche.

Requête

La requête suivante récupère les spécifications de connexion pour 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}'

Réponse

Une réponse réussie renvoie les spécifications de connexion pour Google BigQuery, y compris des informations sur le langage de requête et les opérateurs logiques pris en charge.

NOTE
La réponse de l’API ci-dessous est tronquée pour des raisons de concision.
"attributes": {
  "filterAtSource": {
    "enabled": true,
    "queryLanguage": "SQL",
    "logicalOperators": [
      "and",
      "or",
      "not"
    ],
    "comparisonOperators": [
      "=",
      "!=",
      "<",
      "<=",
      ">",
      ">=",
      "like",
      "in"
    ],
    "columnNameEscapeChar": "`",
    "valueEscapeChar": "'"
  }
Propriété
Description
attributes.filterAtSource.enabled
Détermine si la source interrogée prend en charge le filtrage des données au niveau de la ligne.
attributes.filterAtSource.queryLanguage
Détermine le langage de requête pris en charge par la source interrogée.
attributes.filterAtSource.logicalOperators
Détermine les opérateurs logiques que vous pouvez utiliser pour filtrer les données au niveau de la ligne pour votre source.
attributes.filterAtSource.comparisonOperators
Détermine les opérateurs de comparaison que vous pouvez utiliser pour filtrer les données au niveau de la ligne pour votre source. Pour plus d’informations sur les opérateurs de comparaison, reportez-vous au tableau ci-dessous.
attributes.filterAtSource.columnNameEscapeChar
Détermine le caractère à utiliser pour échapper les colonnes.
attributes.filterAtSource.valueEscapeChar
Détermine la manière dont les valeurs seront entourées lors de l’écriture d’une requête SQL.

Opérateurs de comparaison

Opérateur
Description
==
Filtre selon si la propriété est égale à la valeur fournie.
!=
Filtre selon si la propriété n’est pas égale à la valeur fournie.
<
Filtre selon si la propriété est inférieure à la valeur fournie.
>
Filtre selon si la propriété est supérieure ou non à la valeur fournie.
<=
Filtre selon si la propriété est inférieure ou égale à la valeur fournie.
>=
Filtre selon si la propriété est supérieure ou égale à la valeur fournie.
like
Filtre en utilisant dans une WHERE pour rechercher un modèle spécifié.
in
Filtre selon si la propriété se trouve dans une plage spécifiée.

Définition des conditions de filtrage pour l’ingestion

Une fois que vous avez identifié les opérateurs logiques et le langage de requête pris en charge par votre source, vous pouvez utiliser le langage de requête de profil (PQL) pour spécifier les conditions de filtrage à appliquer à vos données source.

Dans l’exemple ci-dessous, les conditions sont appliquées uniquement à la sélection des données qui correspondent aux valeurs fournies pour les types de noeuds répertoriés en tant que paramètres.

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

Prévisualiser vos données

Vous pouvez prévisualiser vos données en adressant une requête de GET au /explore point d’entrée du Flow Service API lors de la fourniture filters dans les paramètres de requête et en spécifiant vos conditions d’entrée PQL dans Base64.

Format d’API

GET /connections/{BASE_CONNECTION_ID}/explore?objectType=table&object={TABLE_PATH}&preview=true&filters={FILTERS}
Paramètre
Description
{BASE_CONNECTION_ID}
L’identifiant de connexion de base de votre source.
{TABLE_PATH}
La propriété path de la table que vous souhaitez inspecter.
{FILTERS}
Vos conditions de filtrage PQL codées dans Base64.

Requête

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}'

Réponse

Une requête réussie renvoie la réponse suivante.

{
  "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"
    }
  ]
}

Créer une connexion source pour les données filtrées

Pour créer une connexion source et ingérer des données filtrées, envoyez une requête de POST à la variable /sourceConnections point de terminaison tout en fournissant vos conditions de filtrage dans le cadre de vos paramètres de corps.

Format d’API

POST /sourceConnections

Requête

La requête suivante crée une connexion source pour ingérer des données à partir de test1.fasTestTable where 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"
      }
    }'

Réponse

Une réponse réussie renvoie l’identifiant unique (id) de la nouvelle connexion source.

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

Annexe

Cette section fournit d’autres exemples de payloads différents pour le filtrage.

Conditions uniques

Vous pouvez omettre la fnApply pour les scénarios qui ne nécessitent qu’une seule condition.

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

En utilisant la variable in operator

Consultez l’exemple de payload ci-dessous pour obtenir un exemple de l’opérateur 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"
            ]
          }
        ]
      }
    ]
  }
}

En utilisant la variable isNull operator

Consultez l’exemple de payload ci-dessous pour obtenir un exemple de l’opérateur isNull.

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

En utilisant la variable NOT operator

Consultez l’exemple de payload ci-dessous pour obtenir un exemple de l’opérateur NOT.

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

Exemple avec conditions imbriquées

Consultez l’exemple de payload ci-dessous pour obtenir un exemple de conditions imbriquées complexes.

{
  "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