Habilitar um conjunto de dados para Profile e Identity Service usando APIs
Este tutorial aborda o processo de habilitação de um conjunto de dados para uso em Real-Time Customer Profile e Identity Service, detalhado nas seguintes etapas:
-
Habilite um conjunto de dados para uso em Real-Time Customer Profile, usando uma das duas opções:
-
Confirmar assimilação de dados pelo Perfil de Cliente em Tempo Real
Introdução
Este tutorial requer uma compreensão funcional de vários serviços da Adobe Experience Platform envolvidos no gerenciamento de conjuntos de dados habilitados para perfis. Antes de iniciar este tutorial, reveja a documentação desses serviços Platform relacionados:
- Real-Time Customer Profile: Fornece um perfil de consumidor unificado em tempo real com base em dados agregados de várias fontes.
- Identity Service: Habilita Real-Time Customer Profile unindo identidades de diferentes fontes de dados que estão sendo assimiladas em Platform.
- Catalog Service: uma API RESTful que permite criar conjuntos de dados e configurá-los para Real-Time Customer Profile e Identity Service.
- Experience Data Model (XDM): a estrutura padronizada pela qual o Platform organiza os dados de experiência do cliente.
As seções a seguir fornecem as informações adicionais que você precisará saber para fazer chamadas com êxito para as APIs da plataforma.
Leitura de chamadas de API de amostra
Este tutorial fornece exemplos de chamadas de API para demonstrar como formatar suas solicitações. Isso inclui caminhos, cabeçalhos necessários e conteúdos de solicitação formatados corretamente. Também fornece exemplos de JSON retornado nas respostas da API. 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 guia de solução de problemas Experience Platform.
Coletar valores para cabeçalhos necessários
Para fazer chamadas para APIs do Platform, primeiro complete o tutorial de autenticação. Concluir o tutorial de autenticação fornece os valores para cada um dos cabeçalhos necessários em todas as chamadas de API da Experience Platform, conforme mostrado abaixo:
Authorization: Bearer {ACCESS_TOKEN}x-api-key: {API_KEY}x-gw-ims-org-id: {ORG_ID}
Todas as solicitações que contêm uma carga (POST, PUT, PATCH) exigem um cabeçalho Content-Type adicional. O valor correto desse cabeçalho é mostrado nas solicitações de exemplo, quando necessário.
Todos os recursos em Experience Platform estão isolados em sandboxes virtuais específicas. Todas as solicitações para APIs Platform exigem um cabeçalho x-sandbox-name que especifique o nome da sandbox em que a operação ocorrerá. Para obter mais informações sobre sandboxes em Platform, consulte a documentação de visão geral da sandbox.
Criar um conjunto de dados habilitado para Perfil e Identidade create-a-dataset-enabled-for-profile-and-identity
Você pode ativar um conjunto de dados para o Perfil do cliente em tempo real e o Serviço de identidade imediatamente após a criação ou em qualquer momento após a criação do conjunto de dados. Se você quiser habilitar um conjunto de dados que já foi criado, siga as etapas para configurar um conjunto de dados existente localizado posteriormente neste documento.
Para criar um conjunto de dados habilitado para o Perfil, você pode usar uma solicitação POST para o ponto de extremidade /dataSets.
Formato da API
POST /dataSets
Solicitação
Ao incluir unifiedProfile e unifiedIdentity em tags no corpo da solicitação, o conjunto de dados será habilitado imediatamente para Profile e Identity Service, respectivamente. Os valores dessas marcas devem ser uma matriz contendo a cadeia de caracteres "enabled:true".
curl -X POST \
https://platform.adobe.io/data/foundation/catalog/dataSets \
-H 'Content-Type: application/json' \
-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}' \
-d '{
"schemaRef": {
"id": "https://ns.adobe.com/{TENANT_ID}/schemas/31670881463308a46f7d2cb09762715",
"contentType": "application/vnd.adobe.xed-full-notext+json; version=1"
},
"tags": {
"unifiedProfile": ["enabled:true"],
"unifiedIdentity": ["enabled:true"]
}
}'
schemaRef.id{TENANT_ID}Resposta
Uma resposta bem-sucedida mostra uma matriz contendo a ID do conjunto de dados recém-criado na forma de "@/dataSets/{DATASET_ID}". Depois de criar e habilitar com êxito um conjunto de dados, prossiga para as etapas para carregar dados.
[
"@/dataSets/5b020a27e7040801dedbf46e"
]
Configurar um conjunto de dados existente configure-an-existing-dataset
As etapas a seguir abordam como habilitar um conjunto de dados criado anteriormente para Real-Time Customer Profile e Identity Service. Se você já criou um conjunto de dados habilitado para perfil, prossiga para as etapas para assimilar dados.
Verificar se o conjunto de dados está habilitado check-if-the-dataset-is-enabled
Usando a API Catalog, você pode inspecionar um conjunto de dados existente para determinar se ele está habilitado para uso em Real-Time Customer Profile e Identity Service. A chamada a seguir recupera os detalhes de um conjunto de dados por ID.
Formato da API
GET /dataSets/{DATASET_ID}
{DATASET_ID}Solicitação
curl -X GET \
'https://platform.adobe.io/data/foundation/catalog/dataSets/5b020a27e7040801dedbf46e' \
-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
{
"5b020a27e7040801dedbf46e": {
"name": "Commission Program Events DataSet",
"imsOrg": "{ORG_ID}",
"tags": {
"adobe/pqs/table": [
"unifiedprofileingestiontesteventsdataset"
],
"unifiedProfile": [
"enabled:true"
],
"unifiedIdentity": [
"enabled:true"
]
},
"version": "1.0.1",
"created": 1536536917382,
"updated": 1539793978215,
"createdClient": "{CLIENT_CREATED}",
"createdUser": "{CREATED_BY}",
"updatedUser": "{CREATED_BY}",
"viewId": "5b020a27e7040801dedbf46f",
"files": "@/dataSetFiles?dataSetId=5b020a27e7040801dedbf46e",
"schema": "@/xdms/context/experienceevent",
"schemaRef": {
"id": "https://ns.adobe.com/xdm/context/experienceevent",
"contentType": "application/vnd.adobe.xed+json"
}
}
}
Na propriedade tags, você pode ver que unifiedProfile e unifiedIdentity estão ambos presentes com o valor enabled:true. Portanto, Real-Time Customer Profile e Identity Service estão habilitados para este conjunto de dados, respectivamente.
Ativar o conjunto de dados enable-the-dataset
Se o conjunto de dados existente não tiver sido habilitado para Profile ou Identity Service, você poderá habilitá-lo fazendo uma solicitação PATCH usando a ID do conjunto de dados.
Formato da API
PATCH /dataSets/{DATASET_ID}
{DATASET_ID}Solicitação
curl -X PATCH \
https://platform.adobe.io/data/foundation/catalog/dataSets/5b020a27e7040801dedbf46e \
-H 'Content-Type:application/json-patch+json' \
-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}' \
-d '[
{ "op": "add", "path": "/tags/unifiedProfile", "value": ["enabled:true"] },
{ "op": "add", "path": "/tags/unifiedIdentity", "value": ["enabled:true"] }
]'
O corpo da solicitação inclui de path a dois tipos de marcas, unifiedProfile e unifiedIdentity. Os value de cada um são matrizes que contêm a cadeia de caracteres enabled:true.
Resposta
Uma solicitação PATCH bem-sucedida retorna o Status HTTP 200 (OK) e uma matriz contendo a ID do conjunto de dados atualizado. Essa ID deve corresponder à enviada na solicitação PATCH. As marcas unifiedProfile e unifiedIdentity foram adicionadas e o conjunto de dados está habilitado para uso pelos serviços de Perfil e Identidade.
[
"@/dataSets/5b020a27e7040801dedbf46e"
]
Assimilar dados no conjunto de dados ingest-data-into-the-dataset
Real-Time Customer Profile e Identity Service consomem dados XDM enquanto estão sendo assimilados em um conjunto de dados. Para obter instruções sobre como carregar dados em um conjunto de dados, consulte o tutorial sobre criação de um conjunto de dados usando APIs. Ao planejar quais dados enviar para seu conjunto de dados habilitado para Profile, considere as seguintes práticas recomendadas:
- Inclua todos os dados que deseja usar como critérios de segmentação.
- Inclua quantos identificadores você puder verificar a partir dos dados do perfil para maximizar seu gráfico de identidade. Isso permite que o Identity Service compile identidades em conjuntos de dados com mais eficiência.
Confirmar assimilação de dados por Real-Time Customer Profile confirm-data-ingest-by-real-time-customer-profile
Ao fazer upload de dados para um novo conjunto de dados pela primeira vez ou como parte de um processo que envolve um novo ETL ou fonte de dados, é recomendável verificar cuidadosamente os dados para garantir que tenham sido carregados conforme esperado. Usando a API de Acesso Real-Time Customer Profile, você pode recuperar dados em lote conforme eles são carregados em um conjunto de dados. Se você não conseguir recuperar nenhuma das entidades esperadas, seu conjunto de dados pode não estar habilitado para Real-Time Customer Profile. Depois de confirmar que o conjunto de dados foi ativado, verifique se o formato de dados de origem e os identificadores atendem às suas expectativas. Para obter instruções detalhadas sobre como usar a API Real-Time Customer Profile para acessar dados do Profile, consulte o manual de ponto de extremidade de entidades, também conhecido como API "Profile Access".
Confirmar assimilação de dados pelo Serviço de identidade confirm-data-ingest-by-identity-service
Cada fragmento de dados assimilado que contém mais de uma identidade cria um link em seu gráfico de identidade privado. Para obter mais informações sobre gráficos de identidade e acessar dados de identidade, comece lendo a visão geral do Serviço de identidade.