Show Menu
TÓPICOS×

Configurar um conjunto de dados para Profile e Identity Service usando APIs

Este tutorial aborda o processo de ativação de um conjunto de dados para uso em Real-time Customer Profile e Identity Service, detalhado nas seguintes etapas:
  1. Ative um conjunto de dados para uso em Real-time Customer Profile, usando uma das duas opções:

Introdução

Este tutorial requer uma compreensão funcional dos vários serviços de Adobe Experience Platform envolvidos no gerenciamento de conjuntos de dados Profilehabilitados. Antes de iniciar este tutorial, reveja a documentação dos seguintes Platform serviços relacionados:
  • Real-time Customer Profile : Fornece um perfil unificado e em tempo real para o consumidor, com base em dados agregados de várias fontes.
  • Identity Service : Habilita Real-time Customer Profile a união de identidades de fontes de dados diferentes em Platformque estão sendo ingeridas.
  • 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 Platform organiza os dados de experiência do cliente.
As seções a seguir fornecem informações adicionais que você precisará saber para fazer chamadas com êxito para as APIs da Platform.

Lendo chamadas de exemplo da API

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 JSON de amostra retornado em respostas de API também é fornecido. Para obter informações sobre as convenções usadas na documentação para chamadas de API de amostra, consulte a seção sobre como ler chamadas de API de exemplo no guia de Experience Platform solução de problemas.

Reunir valores para cabeçalhos necessários

Para fazer chamadas para Platform APIs, você deve primeiro concluir o tutorial de autenticação. A conclusão do tutorial de autenticação fornece os valores para cada um dos cabeçalhos necessários em todas as chamadas de Experience Platform API, como mostrado abaixo:
  • Autorização: Portador {ACCESS_TOKEN}
  • x-api-key: {API_KEY}
  • x-gw-ims-org-id: {IMS_ORG}
Todas as solicitações que contêm uma carga (POST, PUT, PATCH) exigem um cabeçalho adicional:
  • Tipo de conteúdo: application/json
Todos os recursos em Experience Platform são isolados para caixas de proteção virtuais específicas. Todas as solicitações para Platform APIs exigem um cabeçalho que especifique o nome da caixa de proteção em que a operação ocorrerá. Para obter mais informações sobre caixas de proteção em Platform, consulte a documentação de visão geral da caixa de proteção.
  • x-sandbox-name: {SANDBOX_NAME}

Criar um conjunto de dados habilitado para Profile e Identity

Você pode ativar um conjunto de dados para Real-time Customer Profile e imediatamente Identity Service após a criação ou em qualquer ponto depois que o conjunto de dados for criado. Se você deseja ativar um conjunto de dados que já foi criado, siga as etapas para configurar um conjunto de dados existente encontrado posteriormente neste documento. Para criar um novo conjunto de dados, é necessário saber a ID de um schema XDM existente habilitado para o Perfil do cliente em tempo real. Para obter informações sobre como procurar ou criar um schema habilitado para Perfis, consulte o tutorial sobre como criar um schema usando a API do Registro do Schema. A chamada a seguir para a API Catalog ativa um conjunto de dados para Profile e Identity Service.
Formato da API
POST /dataSets

Solicitação
Ao incluir unifiedProfile e unifiedIdentity em tags no corpo da solicitação, o conjunto de dados será imediatamente ativado para Profile e Identity Service, respectivamente. Os valores dessas tags devem ser uma matriz que contenha a string "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: {IMS_ORG}' \
  -H 'x-sandbox-name: {SANDBOX_NAME}' \
  -d '{
    "fileDescription" : {
    "persisted": true,
        "containerFormat": "parquet",
        "format": "parquet"
    },
    "fields":[],
    "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"]
    }
  }'

Propriedade
Descrição
schemaRef.id
A ID do schema Profile-ativado no qual o conjunto de dados será baseado.
{TENANT_ID}
A namespace dentro da qual Schema Registry contém recursos pertencentes à sua Organização IMS. Consulte a seção TENANT_ID do guia do Schema Registry desenvolvedor para obter mais informações.
Resposta
Uma resposta bem-sucedida mostra uma matriz que contém a ID do conjunto de dados recém-criado na forma de "@/dataSets/{DATASET_ID}" . Depois de criar e ativar um conjunto de dados com êxito, siga para as etapas para carregar os dados .
[
    "@/dataSets/5b020a27e7040801dedbf46e"
] 

Configurar um conjunto de dados existente

As etapas a seguir abordam como ativar um conjunto de dados criado anteriormente para Real-time Customer Profile e Identity Service. Se você já tiver criado um conjunto de dados habilitado para Perfis, siga para as etapas para assimilar dados .

Verificar se o conjunto de dados está ativado

Usando a Catalog API, 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}

Parâmetro
Descrição
{DATASET_ID}
A ID de um conjunto de dados que você deseja inspecionar.
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: {IMS_ORG}' \
  -H 'x-sandbox-name: {SANDBOX_NAME}'

Resposta
{
    "5b020a27e7040801dedbf46e": {
        "name": "Commission Program Events DataSet",
        "imsOrg": "{IMS_ORG}",
        "tags": {
            "adobe/pqs/table": [
                "unifiedprofileingestiontesteventsdataset"
            ],
            "unifiedProfile": [
                "enabled:true"
            ],
            "unifiedIdentity": [
                "enabled:true"
            ]
        },
        "lastBatchId": "6dcd9128a1c84e6aa5177641165e18e4",
        "lastBatchStatus": "success",
        "dule": {},
        "statsCache": {
            "startDate": null,
            "endDate": null
        },
        "namespace": "ACP",
        "state": "DRAFT",
        "version": "1.0.1",
        "created": 1536536917382,
        "updated": 1539793978215,
        "createdClient": "{CLIENT_CREATED}",
        "createdUser": "{CREATED_BY}",
        "updatedUser": "{CREATED_BY}",
        "viewId": "5b020a27e7040801dedbf46f",
        "status": "enabled",
        "fileDescription": {
            "persisted": true,
            "containerFormat": "parquet",
            "format": "parquet"
        },
        "transforms": "@/dataSets/5b020a27e7040801dedbf46e/views/5b020a27e7040801dedbf46f/transforms",
        "files": "@/dataSets/5b020a27e7040801dedbf46e/views/5b020a27e7040801dedbf46f/files",
        "schema": "@/xdms/context/experienceevent",
        "schemaMetadata": {
            "primaryKey": [],
            "delta": [],
            "dule": [],
            "gdpr": []
        },
        "schemaRef": {
            "id": "https://ns.adobe.com/xdm/context/experienceevent",
            "contentType": "application/vnd.adobe.xed+json"
        }
    }
}

Sob a tags propriedade, você pode ver isso unifiedProfile e unifiedIdentity ambos estão presentes com o valor enabled:true . Portanto, Real-time Customer Profile e Identity Service são ativados para esse conjunto de dados, respectivamente.

Ativar o conjunto de dados

Se o conjunto de dados existente não tiver sido ativado para Profile ou Identity Service, você poderá ativá-lo fazendo uma solicitação PATCH usando a ID do conjunto de dados.
Formato da API
PATCH /dataSets/{DATASET_ID}

Parâmetro
Descrição
{DATASET_ID}
A ID de um conjunto de dados que você deseja atualizar.
Solicitação
curl -X PATCH \
  https://platform.adobe.io/data/foundation/catalog/dataSets/5b020a27e7040801dedbf46e \
  -H 'Content-Type: application/json' \
  -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}' \
  -d '{
    "tags" : {
        "unifiedProfile": ["enabled:true"],
        "unifiedIdentity": ["enabled:true"]
    }
  }'

O corpo da solicitação inclui uma tags propriedade, que contém duas subpropriedades: "unifiedProfile" e "unifiedIdentity" . Os valores dessas subpropriedades são arrays que contêm a string "enabled:true" .
Resposta Uma solicitação PATCH bem-sucedida retorna o Status HTTP 200 (OK) e uma matriz que contém a ID do conjunto de dados atualizado. Essa ID deve corresponder àquela enviada na solicitação PATCH. As tags "unifiedProfile" e "unifiedIdentity" foram adicionadas e o conjunto de dados está habilitado para uso pelos serviços de Perfil e identidade.
[
    "@/dataSets/5b020a27e7040801dedbf46e"
]

Inserir dados no conjunto de dados

Os dados XDM são Real-time Customer Profile e Identity Service consomem conforme são ingeridos em um conjunto de dados. Para obter instruções sobre como carregar dados em um conjunto de dados, consulte o tutorial sobre como criar um conjunto de dados usando APIs . Ao planejar quais dados serão enviados para seu conjunto de dados Profilehabilitado, considere as seguintes práticas recomendadas:
  • Inclua todos os dados que você deseja usar como critérios de segmento de audiência.
  • Inclua quantos identificadores você puder determinar a partir dos dados do perfil para maximizar seu gráfico de identidade. Isso permite Identity Service costurar identidades em conjuntos de dados de forma mais eficaz.

Confirmar a assimilação de dados por 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 eles tenham sido carregados conforme esperado. Usando a API Real-time Customer Profile de acesso, é possível recuperar dados em lote à medida que 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 e os identificadores dos dados de origem suportam suas expectativas. Para obter instruções detalhadas sobre como usar a Real-time Customer Profile API para acessar Profile os dados, siga o guia de endpoint das entidades, também conhecido como "Profile Access API".

Confirmar a assimilação de dados pelo Serviço de Identidade

Cada fragmento de dados ingerido que contém mais de uma identidade cria um link no gráfico de identidade particular. Para obter mais informações sobre gráficos de identidade e dados de identidade de acesso, comece lendo a visão geral do Serviço de identidade.