Este tutorial aborda as etapas para impor a conformidade do uso de dados para o Real-Time Customer Profile segmentos de público usando APIs.
Este tutorial requer um entendimento prático dos seguintes componentes do Adobe Experience Platform:
As seções a seguir fornecem informações adicionais que você precisará saber para fazer chamadas com êxito para o Platform APIs.
Este tutorial fornece exemplos de chamadas de API para demonstrar como formatar suas solicitações. Isso inclui caminhos, cabeçalhos necessários e cargas de solicitação formatadas corretamente. O exemplo de JSON retornado nas respostas da API também é fornecido. Para obter informações sobre as convenções usadas na documentação para chamadas de API de exemplo, consulte a seção sobre como ler chamadas de API de exemplo no Experience Platform guia de solução de problemas.
Para fazer chamadas para Platform APIs, primeiro conclua o tutorial de autenticação. Concluir o tutorial de autenticação fornece os valores para cada um dos cabeçalhos necessários em todos os Experience Platform Chamadas de API, conforme mostrado abaixo:
{ACCESS_TOKEN}
{API_KEY}
{ORG_ID}
Todos os recursos em Experience Platform são isolados em sandboxes virtuais específicas. Todas as solicitações para Platform As APIs exigem um cabeçalho que especifique o nome da sandbox em que a operação ocorrerá:
{SANDBOX_NAME}
Para obter mais informações sobre sandboxes no Platform, consulte o documentação de visão geral da sandbox.
Todas as solicitações que contêm uma carga (POST, PUT, PATCH) exigem um cabeçalho adicional:
Esse fluxo de trabalho começa acessando um segmento de público-alvo conhecido. Segmentos ativados para uso no Real-Time Customer Profile contêm uma ID de política de mesclagem na definição de segmento. Essa política de mesclagem contém informações sobre quais conjuntos de dados devem ser incluídos no segmento, que por sua vez contém quaisquer rótulos de uso de dados aplicáveis.
Usar o Segmentation , você pode pesquisar uma definição de segmento por sua ID para encontrar a política de mesclagem associada.
Formato da API
GET /segment/definitions/{SEGMENT_DEFINITION_ID}
Propriedade | Descrição |
---|---|
{SEGMENT_DEFINITION_ID} |
A ID da definição de segmento que você deseja pesquisar. |
Solicitação
curl -X GET \
https://platform.adobe.io/data/core/ups/segment/definitions/24379cae-726a-4987-b7b9-79c32cddb5c1 \
-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 os detalhes da definição de segmento.
{
"id": "24379cae-726a-4987-b7b9-79c32cddb5c1",
"schema": {
"name": "_xdm.context.profile"
},
"ttlInDays": 90,
"imsOrgId": "{ORG_ID}",
"name": "Cart abandons in CA",
"description": "",
"expression": {
"type": "PQL",
"format": "pql/text",
"value": "homeAddress.countryISO = 'US'"
},
"mergePolicyId": "2b43d78d-0ad4-4c1e-ac2d-574c09b01119",
"evaluationInfo": {
"batch": {
"enabled": true
},
"continuous": {
"enabled": false
},
"synchronous": {
"enabled": false
}
},
"creationTime": 1556094486000,
"updateEpoch": 1556094486000,
"updateTime": 1556094486000
}
}
Propriedade | Descrição |
---|---|
mergePolicyId |
A ID da política de mesclagem usada para a definição do segmento. Isso será usado na próxima etapa. |
As políticas de mesclagem contêm informações sobre os conjuntos de dados de origem, que por sua vez contêm rótulos de uso de dados. Você pode pesquisar os detalhes de uma política de mesclagem fornecendo a ID da política de mesclagem em uma solicitação do GET para o Profile API. Mais informações sobre políticas de mesclagem podem ser encontradas no manual de ponto de extremidade das políticas de mesclagem.
Formato da API
GET /config/mergePolicies/{MERGE_POLICY_ID}
Propriedade | Descrição |
---|---|
{MERGE_POLICY_ID} |
A ID da política de mesclagem obtida no etapa anterior. |
Solicitação
curl -X GET \
https://platform.adobe.io/data/core/ups/config/mergePolicies/2b43d78d-0ad4-4c1e-ac2d-574c09b01119 \
-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 os detalhes da política de mesclagem.
{
"id": "2b43d78d-0ad4-4c1e-ac2d-574c09b01119",
"imsOrgId": "{ORG_ID}",
"schema": {
"name": "_xdm.context.profile"
},
"version": 1,
"identityGraph": {
"type": "none"
},
"attributeMerge": {
"type":"dataSetPrecedence",
"data": {
"order": ["5b95b155419ec801e6eee780", "5b7c86968f7b6501e21ba9df"]
}
},
"default": false,
"updateEpoch": 1551127597
}
Propriedade | Descrição |
---|---|
schema.name |
O nome do esquema associado à política de mesclagem. |
attributeMerge.type |
O tipo de configuração de precedência de dados para a política de mesclagem. Se o valor for dataSetPrecedence , os conjuntos de dados associados a esta política de mesclagem são listados em attributeMerge > data > order . Se o valor for timestampOrdered , todos os conjuntos de dados associados ao esquema referenciado no schema.name são usados pela política de mesclagem. |
attributeMerge.data.order |
Se a variável attributeMerge.type é dataSetPrecedence , esse atributo será uma matriz que contém as IDs dos conjuntos de dados usados por essa política de mesclagem. Essas IDs são usadas na próxima etapa. |
Essa etapa pressupõe que você tenha pelo menos uma política de uso de dados ativa que impeça que ações de marketing específicas sejam executadas em dados que contenham determinados rótulos. Se você não tiver políticas de uso aplicáveis aos conjuntos de dados que estão sendo avaliados, siga as tutorial de criação de política para criar um antes de continuar com esta etapa.
Depois de obter as IDs dos conjuntos de dados de origem da política de mesclagem, você poderá usar o API de serviço de política avaliar esses conjuntos de dados em relação a ações de marketing específicas para verificar violações de política de uso de dados.
Para avaliar os conjuntos de dados, você deve fornecer o nome da ação de marketing no caminho de uma solicitação POST, além de fornecer as IDs do conjunto de dados no corpo da solicitação, como mostrado no exemplo abaixo.
Formato da API
POST /marketingActions/core/{MARKETING_ACTION_NAME}/constraints
POST /marketingActions/custom/{MARKETING_ACTION_NAME}/constraints
Parâmetro | Descrição |
---|---|
{MARKETING_ACTION_NAME} |
O nome da ação de marketing associada à política de uso de dados pela qual você está avaliando os conjuntos de dados. Dependendo se a política foi definida pelo Adobe ou por sua organização, é necessário usar /marketingActions/core ou /marketingActions/custom , respectivamente. |
Solicitação
A solicitação a seguir testa o exportToThirdParty
ação de marketing contra conjuntos de dados obtidos no etapa anterior. A carga da solicitação é uma matriz que contém as IDs de cada conjunto de dados.
curl -X POST \
https://platform.adobe.io/data/foundation/dulepolicy/marketingActions/custom/exportToThirdParty/constraints
-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 '[
{
"entityType": "dataSet",
"entityId": "5b95b155419ec801e6eee780"
},
{
"entityType": "dataSet",
"entityId": "5b7c86968f7b6501e21ba9df"
}
]'
Propriedade | Descrição |
---|---|
entityType |
Cada item na matriz de carga útil deve indicar o tipo de entidade que está sendo definido. Para esse caso de uso, o valor sempre será "dataSet". |
entityID |
Cada item na matriz de carga deve fornecer a ID exclusiva para um conjunto de dados. |
Resposta
Uma resposta bem-sucedida retorna o URI da ação de marketing, os rótulos de uso de dados coletados dos conjuntos de dados fornecidos e uma lista de quaisquer políticas de uso de dados que foram violadas como resultado do teste da ação com esses rótulos. Neste exemplo, a política "Exportar dados para terceiros" é mostrada na variável violatedPolicies
, indicando que a ação de marketing acionou uma violação de política.
{
"timestamp": 1556324277895,
"clientId": "{CLIENT_ID}",
"userId": "{USER_ID}",
"imsOrg": "{ORG_ID}",
"marketingActionRef": "https://platform.adobe.io:443/data/foundation/dulepolicy/marketingActions/custom/exportToThirdParty",
"duleLabels": [
"C1",
"C2",
"C4",
"C5"
],
"discoveredLabels": [
{
"entityType": "dataSet",
"entityId": "5b95b155419ec801e6eee780",
"dataSetLabels": {
"connection": {
"labels": []
},
"dataSet": {
"labels": [
"C5"
]
},
"fields": [
{
"labels": [
"C2",
],
"path": "/properties/_customer"
},
{
"labels": [
"C5"
],
"path": "/properties/geoUnit"
},
{
"labels": [
"C1"
],
"path": "/properties/identityMap"
}
]
}
},
{
"entityType": "dataSet",
"entityId": "5b7c86968f7b6501e21ba9df",
"dataSetLabels": {
"connection": {
"labels": []
},
"dataSet": {
"labels": [
"C5"
]
},
"fields": [
{
"labels": [
"C5"
],
"path": "/properties/createdByBatchID"
},
{
"labels": [
"C5"
],
"path": "/properties/faxPhone"
}
]
}
}
],
"violatedPolicies": [
{
"name": "Export Data to Third Party",
"status": "ENABLED",
"marketingActionRefs": [
"https://platform-stage.adobe.io:443/data/foundation/dulepolicy/marketingActions/custom/exportToThirdParty"
],
"description": "Conditions under which data cannot be exported to a third party",
"deny": {
"operator": "OR",
"operands": [
{
"label": "C1"
},
{
"operator": "AND",
"operands": [
{
"label": "C3"
},
{
"label": "C7"
}
]
}
]
},
"imsOrg": "{ORG_ID}",
"created": 1565651746693,
"createdClient": "{CREATED_CLIENT}",
"createdUser": "{CREATED_USER",
"updated": 1565723012139,
"updatedClient": "{UPDATED_CLIENT}",
"updatedUser": "{UPDATED_USER}",
"_links": {
"self": {
"href": "https://platform-stage.adobe.io/data/foundation/dulepolicy/policies/custom/5d51f322e553c814e67af1a3"
}
},
"id": "5d51f322e553c814e67af1a3"
}
]
}
Propriedade | Descrição |
---|---|
duleLabels |
Uma lista de rótulos de uso de dados que foram extraídos dos conjuntos de dados fornecidos. |
discoveredLabels |
Uma lista dos conjuntos de dados fornecidos na carga da solicitação, exibindo os rótulos de nível de conjunto de dados e de nível de campo encontrados em cada um. |
violatedPolicies |
Uma matriz que lista quaisquer políticas de uso de dados que foram violadas ao testar a ação de marketing (especificada em marketingActionRef ) em relação ao duleLabels . |
Usando os dados retornados na resposta da API, você pode configurar protocolos no aplicativo de experiência para aplicar adequadamente as violações de política quando elas ocorrerem.
Se o seu segmento de público-alvo não passar na avaliação, você poderá ajustar os dados incluídos no segmento por meio de um dos dois métodos descritos abaixo.
Atualizar a política de mesclagem de uma definição de segmento ajustará os conjuntos de dados e campos que serão incluídos quando o trabalho do segmento for executado. Consulte a seção sobre atualização de uma política de mesclagem existente no tutorial de política de mesclagem de API para obter mais informações.
Ao exportar um segmento para um conjunto de dados usando o Segmentation você pode filtrar os dados incluídos na exportação usando a variável fields
parâmetro. Quaisquer campos de dados adicionados a esse parâmetro serão incluídos na exportação, enquanto todos os outros campos de dados serão excluídos.
Considere um segmento que tenha campos de dados chamados "A", "B" e "C". Se desejar exportar apenas o campo "C", a variável fields
O parâmetro conteria apenas o campo "C". Ao fazer isso, os campos "A" e "B" seriam excluídos ao exportar o segmento.
Consulte a seção sobre exportação de um segmento no tutorial de segmentação para obter mais informações.
Ao seguir este tutorial, você pesquisou os rótulos de uso de dados associados a um segmento de público-alvo e os testou quanto a violações de política em relação a ações de marketing específicas. Para obter mais informações sobre a governança de dados em Experience Platform, leia a visão geral para Governança de dados.