Este tutorial ajudará você a começar a usar APIs de assimilação de streaming, parte da Adobe Experience Platform Data Ingestion Service APIs.
Este tutorial requer um conhecimento prático de vários serviços da Adobe Experience Platform. Antes de iniciar este tutorial, reveja a documentação dos seguintes serviços:
{TENANT_ID}
, que aparece em chamadas em todo este tutorial, bem como saber como criar esquemas, que são usados na criação de um conjunto de dados para assimilação.Para obter informações sobre como fazer chamadas para APIs da plataforma com êxito, consulte o guia em introdução às APIs do Platform.
Para criar um conjunto de dados, primeiro será necessário criar um novo esquema que implemente o XDM Individual Profile classe . Para obter mais informações sobre como criar schemas, leia o Guia do desenvolvedor da API da API do Registro de Schema.
Formato da API
POST /schemaregistry/tenant/schemas
Solicitação
curl -X POST https://platform.adobe.io/data/foundation/schemaregistry/tenant/schemas \
-H 'Authorization: Bearer {ACCESS_TOKEN}' \
-H 'Content-Type: application/json' \
-H 'x-api-key: {API_KEY}' \
-H 'x-gw-ims-org-id: {ORG_ID}' \
-H 'x-sandbox-name: {SANDBOX_NAME}' \
-d '{
"type": "object",
"title": "Sample schema",
"description": "Sample description",
"allOf": [
{
"$ref": "https://ns.adobe.com/xdm/context/profile"
},
{
"$ref": "https://ns.adobe.com/xdm/context/profile-person-details"
},
{
"$ref": "https://ns.adobe.com/xdm/context/profile-work-details"
}
],
"meta:immutableTags": [
"union"
]
}'
Propriedade | Descrição |
---|---|
title |
O nome que deseja usar para o esquema. Este nome deve ser exclusivo. |
description |
Uma descrição significativa para o esquema que você está criando. |
meta:immutableTags |
Neste exemplo, a variável union é usada para persistir seus dados em Real-time Customer Profile. |
Resposta
Uma resposta bem-sucedida retorna o status HTTP 201 com detalhes do esquema recém-criado.
{
"$id": "https://ns.adobe.com/{TENANT_ID}/schemas/{SCHEMA_ID}",
"meta:altId": "_{TENANT_ID}.schemas.{SCHEMA_ID}",
"meta:resourceType": "schemas",
"version": "1.0",
"type": "object",
"title": "Sample schema",
"description": "Sample description",
"allOf": [
{
"$ref": "https://ns.adobe.com/xdm/context/profile"
},
{
"$ref": "https://ns.adobe.com/xdm/context/profile-person-details"
},
{
"$ref": "https://ns.adobe.com/xdm/context/profile-work-details"
}
],
"meta:class": "https://ns.adobe.com/xdm/context/profile",
"meta:abstract": false,
"meta:extensible": false,
"meta:extends": [
"https://ns.adobe.com/xdm/context/profile",
"https://ns.adobe.com/xdm/data/record",
"https://ns.adobe.com/xdm/cpmtext/identitymap",
"https://ns.adobe.com/xdm/common/extensible",
"https://ns.adobe.com/xdm/common/auditable",
"https://ns.adobe.com/xdm/context/profile-person-details",
"https://ns.adobe.com/xdm/context/profile-work-details"
],
"meta:immutableTags": [
"union"
],
"meta:containerId": "tenant",
"imsOrg": "{ORG_ID}",
"meta:xdmType": "object",
"meta:registryMetadata": {
"repo:createDate": 1551376506996,
"repo:lastModifiedDate": 1551376506996,
"xdm:createdClientId": "{CLIENT_ID}",
"xdm:repositoryCreatedBy": "{CREATED_BY}"
}
}
Propriedade | Descrição |
---|---|
{TENANT_ID} |
Essa ID é usada para garantir que os recursos criados sejam namespacados corretamente e estejam contidos na Organização IMS. Para obter mais informações sobre o ID do locatário, leia a guia do Registro de esquema. |
Por favor, tome nota da $id
bem como version
, já que ambos serão usados ao criar seu conjunto de dados.
Em seguida, adicione um descritor de identidade ao schema criado acima, usando o atributo de endereço de email de trabalho como o identificador principal. Isso resultará em duas alterações:
O endereço de email de trabalho se tornará um campo obrigatório. Isso significa que as mensagens enviadas sem esse campo falharão na validação e não serão assimiladas.
Real-time Customer Profile O usará o endereço de email como um identificador para ajudar a unir mais informações sobre esse indivíduo.
curl -X POST https://platform.adobe.io/data/foundation/schemaregistry/tenant/descriptors \
-H 'Authorization: Bearer {ACCESS_TOKEN}' \
-H 'Content-Type: application/json' \
-H 'x-api-key: {API_KEY}' \
-H 'x-gw-ims-org-id: {ORG_ID}' \
-H 'x-sandbox-name: {SANDBOX_NAME}' \
-d '{
"@type":"xdm:descriptorIdentity",
"xdm:sourceProperty":"/workEmail/address",
"xdm:property":"xdm:code",
"xdm:isPrimary":true,
"xdm:namespace":"Email",
"xdm:sourceSchema":"{SCHEMA_REF_ID}",
"xdm:sourceVersion":1
}
Propriedade | Descrição |
---|---|
{SCHEMA_REF_ID} |
O $id que você recebeu anteriormente ao compor o schema. Deve ser algo como isto: "https://ns.adobe.com/{TENANT_ID}/schemas/{SCHEMA_ID}" |
Códigos de namespace de identidade
Certifique-se de que os códigos sejam válidos - o exemplo acima usa "email" que é um namespace de identidade padrão. Outros namespaces de identidade padrão comumente usados podem ser encontrados no Perguntas frequentes sobre o serviço de identidade.
Se quiser criar um namespace personalizado, siga as etapas descritas na visão geral do namespace de identidade.
Resposta
Uma resposta bem-sucedida retorna o status HTTP 201 com informações sobre o descritor de identidade primário recém-criado para o esquema.
{
"xdm:property": "xdm:code",
"xdm:sourceSchema": "https://ns.adobe.com/{TENANT_ID}/schemas/{SCHEMA_ID}",
"xdm:namespace": "Email",
"@type": "xdm:descriptorIdentity",
"xdm:sourceVersion": 1,
"xdm:isPrimary": true,
"xdm:sourceProperty": "/workEmail/address",
"@id": "17aaebfa382ce8fc0a40d3e43870b6470aab894e1c368d16",
"meta:containerId": "tenant",
"version": "1",
"imsOrg": "{ORG_ID}"
}
Depois de criar o esquema, será necessário criar um conjunto de dados para assimilar dados de registro.
Esse conjunto de dados será ativado para Real-time Customer Profile e Identity Service.
Formato da API
POST /catalog/dataSets
Solicitação
curl -X POST https://platform.adobe.io/data/foundation/catalog/dataSets \
-H 'Authorization: Bearer {ACCESS_TOKEN}' \
-H 'Content-Type: application/json' \
-H 'x-api-key: {API_KEY}' \
-H 'x-gw-ims-org-id: {ORG_ID}' \
-H 'x-sandbox-name: {SANDBOX_NAME}' \
-d ' {
"name": "Dataset name",
"description": "Dataset description",
"schemaRef": {
"id": "https://ns.adobe.com/{TENANT_ID}/schemas/{SCHEMA_ID},
"contentType": "application/vnd.adobe.xed-full+json;version=1"
},
"tags": {
"unifiedIdentity": ["enabled:true"],
"unifiedProfile": ["enabled:true"]
}
}'
Resposta
Uma resposta bem-sucedida retorna o status HTTP 201 e uma matriz contendo a ID do conjunto de dados recém-criado no formato @/dataSets/{DATASET_ID}
.
[
"@/dataSets/5e30d7986c0cc218a85cee65
]
Depois de criar o esquema e o conjunto de dados, você pode criar uma conexão de transmissão
Para obter mais informações sobre como criar uma conexão de transmissão, leia o tutorial criar uma conexão de transmissão.
Com o conjunto de dados e a conexão de transmissão no lugar, você pode assimilar registros JSON formatados em XDM para assimilar dados de registro no Platform.
Formato da API
POST /collection/{CONNECTION_ID}?syncValidation=true
Parâmetro | Descrição |
---|---|
{CONNECTION_ID} |
O inletId valor da conexão de transmissão criada anteriormente. |
syncValidation |
Um parâmetro de consulta opcional destinado a fins de desenvolvimento. Se estiver definido como true , ele pode ser usado para feedback imediato para determinar se a solicitação foi enviada com êxito. Por padrão, esse valor é definido como false . Observe que, se você definir este parâmetro de consulta como true que a taxa de solicitação será limitada a 60 vezes por minuto CONNECTION_ID . |
Solicitação
A inserção de dados de registro em uma conexão de transmissão pode ser feita com ou sem o nome de origem.
A solicitação de exemplo abaixo assimila um registro com um nome de origem ausente no Platform. Se um registro não tiver o nome de origem, ele adicionará a ID de origem da definição de conexão de transmissão.
A chamada de API a seguir faz not exigir cabeçalhos de autenticação.
curl -X POST https://dcs.adobedc.net/collection/{CONNECTION_ID}?syncValidation=true \
-H "Cache-Control: no-cache" \
-H "Content-Type: application/json" \
-d '{
"header": {
"schemaRef": {
"id": "https://ns.adobe.com/{TENANT_ID}/schemas/{SCHEMA_ID}",
"contentType": "application/vnd.adobe.xed-full+json;version=1"
},
"imsOrgId": "{ORG_ID}",
"datasetId": "{DATASET_ID}",
"flowId": "{FLOW_ID}",
},
"body": {
"xdmMeta": {
"schemaRef": {
"id": "https://ns.adobe.com/{TENANT_ID}/schemas/{SCHEMA_ID}",
"contentType": "application/vnd.adobe.xed-full+json;version=1"
}
},
"xdmEntity": {
"person": {
"name": {
"firstName": "Jane",
"middleName": "F",
"lastName": "Doe"
},
"birthDate": "1969-03-14",
"gender": "female"
},
"workEmail": {
"primary": true,
"address": "janedoe@example.com",
"type": "work",
"status": "active"
}
}
}
}'
Se você quiser incluir um nome de origem, o exemplo a seguir mostra como incluí-lo.
"header": {
"schemaRef": {
"id": "https://ns.adobe.com/{TENANT_ID}/schemas/{SCHEMA_ID}",
"contentType": "application/vnd.adobe.xed-full+json;version=1"
},
"imsOrgId": "{ORG_ID}",
"datasetId": "{DATASET_ID}",
"source": {
"name": "Sample source name"
}
}
Resposta
Uma resposta bem-sucedida retorna o status HTTP 200 com detalhes da nova transmissão Profile.
{
"inletId": "{CONNECTION_ID}",
"xactionId": "1584479347507:2153:240",
"receivedTimeMs": 1584479347507,
"syncValidation": {
"status": "pass"
}
}
Propriedade | Descrição |
---|---|
{CONNECTION_ID} |
A ID da conexão de transmissão criada anteriormente. |
xactionId |
Um identificador exclusivo gerou no lado do servidor para o registro que você acabou de enviar. Essa ID ajuda o Adobe a rastrear o ciclo de vida desse registro em vários sistemas e com a depuração. |
receivedTimeMs |
Um carimbo de data e hora (época em milissegundos) que mostra a hora em que a solicitação foi recebida. |
syncValidation.status |
Como o parâmetro de consulta syncValidation=true for adicionado, esse valor será exibido. Se a validação tiver êxito, o status será pass . |
Para validar os registros assimilados anteriormente, você pode usar o Profile Access API para recuperar os dados do registro.
Se a ID da política de mesclagem não estiver definida e a variável schema.name
ou relatedSchema.name
é _xdm.context.profile
, Profile Access buscará all identidades relacionadas.
Formato da API
GET /access/entities
GET /access/entities?{QUERY_PARAMETERS}
GET /access/entities?schema.name=_xdm.context.profile&entityId=janedoe@example.com&entityIdNS=email
Parâmetro | Descrição |
---|---|
schema.name |
Obrigatório. O nome do schema que você está acessando. |
entityId |
A ID da entidade. Se fornecido, você também deve fornecer o namespace da entidade. |
entityIdNS |
O namespace da ID que você está tentando recuperar. |
Solicitação
Você pode revisar os dados de registro assimilados anteriormente com a seguinte solicitação do GET.
curl -X GET 'https://platform.adobe.io/data/core/ups/access/entities?schema.name=_xdm.context.profile&entityId=janedoe@example.com&entityIdNS=email'\
-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 o status HTTP 200 com detalhes das entidades solicitadas. Como você pode ver, esse é o mesmo registro que foi assimilado com êxito anteriormente.
{
"BVrqzwVv7o2p3naHvnsWpqZXv3KJgA": {
"entityId": "BVrqzwVv7o2p3naHvnsWpqZXv3KJgA",
"mergePolicy": {
"id": "e161dae9-52f0-4c7f-b264-dc43dd903d56"
},
"sources": [
"5e30d7986c0cc218a85cee65"
],
"tags": [
"1580346827274:2478:215"
],
"identityGraph": [
"BVrqzwVv7o2p3naHvnsWpqZXv3KJgA"
],
"entity": {
"person": {
"name": {
"lastName": "Doe",
"middleName": "F",
"firstName": "Jane"
},
"gender": "female",
"birthDate": "1969-03-14"
},
"workEmail": {
"type": "work",
"address": "janedoe@example.com",
"status": "active",
"primary": true
},
"identityMap": {
"email": [
{
"id": "janedoe@example.com"
}
]
}
},
"lastModifiedAt": "2020-01-30T01:13:59Z"
}
}
Ao ler este documento, agora você entende como assimilar dados de registro no Platform usando conexões de transmissão. Você pode tentar fazer mais chamadas com valores diferentes e recuperar os valores atualizados. Além disso, você pode começar a monitorar os dados assimilados por meio de Platform IU. Para obter mais informações, leia o monitoramento da ingestão de dados guia.
Para obter mais informações sobre a assimilação de streaming em geral, leia o visão geral da assimilação de streaming.