Avaliar eventos em tempo quase real com a segmentação de transmissão

Segmentação de transmissão ativada Adobe Experience Platform O permite que os clientes façam a segmentação em tempo quase real, concentrando-se na riqueza de dados. Com a segmentação por transmissão, a qualificação de segmentos agora acontece à medida que os dados de transmissão chegam ao Platform, reduzindo a necessidade de agendar e executar trabalhos de segmentação. Com esse recurso, a maioria das regras de segmento agora pode ser avaliada à medida que os dados são passados para Platform, o que significa que a associação do segmento será mantida atualizada sem executar trabalhos de segmentação programados.

Introdução

Este guia do desenvolvedor requer uma compreensão funcional dos vários Adobe Experience Platform serviços envolvidos com a segmentação por transmissão. Antes de iniciar este tutorial, revise a documentação dos seguintes serviços:

As seções a seguir fornecem informações adicionais que você precisará saber para fazer chamadas com êxito para o Platform APIs.

Leitura de chamadas de API de amostra

Este guia do desenvolvedor 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 Experience Platform guia de solução de problemas.

Coletar valores para cabeçalhos necessários

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 todas as chamadas de API da Experience Platform, conforme mostrado abaixo:

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á:

Todas as solicitações que contêm um conteúdo (POST, PUT, PATCH) exigem um cabeçalho adicional:

Cabeçalhos adicionais podem ser necessários para concluir solicitações específicas. Os cabeçalhos corretos são mostrados em cada um dos exemplos deste documento. Preste atenção especial às solicitações de amostra para garantir que todos os cabeçalhos necessários sejam incluídos.

Tipos de consulta habilitados para segmentação de transmissão query-types

Para que uma definição de segmento seja avaliada usando a segmentação por transmissão, o query deve estar em conformidade com as diretrizes a seguir.

Uma definição de segmento não ser ativado para segmentação por transmissão nos seguintes cenários:

Observe que as seguintes diretrizes se aplicam ao fazer a segmentação por transmissão:

Se uma definição de segmento for modificada para não atender mais aos critérios de segmentação por transmissão, a definição de segmento mudará automaticamente de "Transmissão" para "Lote".

Além disso, a desqualificação de segmentos, semelhante à qualificação de segmentos, acontece em tempo real. Como resultado, se um perfil não se qualificar mais para uma definição de segmento, ele será imediatamente desqualificado. Por exemplo, se a definição do segmento solicitar "Todos os usuários que compraram sapatos vermelhos nas últimas três horas", após três horas, todos os perfis que se qualificaram inicialmente para a definição do segmento serão desqualificados.

Recuperar todas as definições de segmento habilitadas para segmentação por transmissão

É possível recuperar uma lista de todas as definições de segmento que estão habilitadas para segmentação por transmissão na organização fazendo uma solicitação GET para a /segment/definitions terminal.

Formato da API

Para recuperar definições de segmento com transmissão ativada, você deve incluir o parâmetro de consulta evaluationInfo.continuous.enabled=true no caminho da solicitação.

GET /segment/definitions?evaluationInfo.continuous.enabled=true

Solicitação

curl -X GET \
  'https://platform.adobe.io/data/core/ups/segment/definitions?evaluationInfo.continuous.enabled=true' \
  -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}'

Resposta

Uma resposta bem-sucedida retorna uma matriz de definições de segmento na organização que estão habilitadas para segmentação por transmissão.

{
    "segments": [
        {
            "id": "15063cb-2da8-4851-a2e2-bf59ddd2f004",
            "schema": {
                "name": "_xdm.context.profile"
            },
            "ttlInDays": 30,
            "imsOrgId": "{ORG_ID}",
            "sandbox": {
                "sandboxId": "",
                "sandboxName": "",
                "type": "production",
                "default": true
            },
            "name": " People who are NOT on their homepage ",
            "expression": {
                "type": "PQL",
                "format": "pql/text",
                "value": "select var1 from xEvent where var1._experience.analytics.endUser.firstWeb.webPageDetails.isHomePage = false"
            },
            "evaluationInfo": {
                "batch": {
                    "enabled": false
                },
                "continuous": {
                    "enabled": true
                },
                "synchronous": {
                    "enabled": false
                }
            },
            "creationTime": 1572029711000,
            "updateEpoch": 1572029712000,
            "updateTime": 1572029712000
        },
        {
            "id": "f15063cb-2da8-4851-a2e2-bf59ddd2f004",
            "schema": {
                "name": "_xdm.context.profile"
            },
            "ttlInDays": 30,
            "imsOrgId": "{ORG_ID}",
            "sandbox": {
                "sandboxId": "",
                "sandboxName": "",
                "type": "production",
                "default": true
            },
            "name": "Homepage_continuous",
            "description": "People who are on their homepage - continuous",
            "expression": {
                "type": "PQL",
                "format": "pql/text",
                "value": "select var1 from xEvent where var1._experience.analytics.endUser.firstWeb.webPageDetails.isHomePage = true"
            },
            "evaluationInfo": {
                "batch": {
                    "enabled": true
                },
                "continuous": {
                    "enabled": true
                },
                "synchronous": {
                    "enabled": false
                }
            },
            "creationTime": 1572021085000,
            "updateEpoch": 1572021086000,
            "updateTime": 1572021086000
        }
    ],
    "page": {
        "totalCount": 2,
        "totalPages": 1,
        "sortField": "creationTime",
        "sort": "desc",
        "pageSize": 2,
        "limit": 100
    },
    "link": {}
}

Criar uma definição de segmento habilitado para streaming

Uma definição de segmento será ativada automaticamente por transmissão se corresponder a uma das tipos de segmentação de transmissão listados acima.

Formato da API

POST /segment/definitions

Solicitação

curl -X POST \
  https://platform.adobe.io/data/core/ups/segment/definitions \
  -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 '{
    "schema": {
        "name": "_xdm.context.profile"
    },
    "ttlInDays": 30,
    "name": "Homepage_continuous",
    "description": "People who are on their homepage - continuous",
    "expression": {
        "type": "PQL",
        "format": "pql/text",
        "value": "select var1 from xEvent where var1._experience.analytics.endUser.firstWeb.webPageDetails.isHomePage = true"
    },
    "evaluationInfo": {
        "batch": {
            "enabled": false
        },
        "continuous": {
            "enabled": true
        },
        "synchronous": {
            "enabled": false
        }
    }
}'

Resposta

Uma resposta bem-sucedida retorna os detalhes da definição de segmento habilitado para streaming recém-criada.

{
    "id": "f15063cb-2da8-4851-a2e2-bf59ddd2f004",
    "schema": {
        "name": "_xdm.context.profile"
    },
    "ttlInDays": 30,
    "imsOrgId": "{ORG_ID}",
    "sandbox": {
        "sandboxId": "{SANDBOX_ID}",
        "sandboxName": "{SANDBOX_NAME}",
        "type": "production",
        "default": true
    },
    "name": "Homepage_continuous",
    "description": "People who are on their homepage - continuous",
    "expression": {
        "type": "PQL",
        "format": "pql/text",
        "value": "select var1 from xEvent where var1._experience.analytics.endUser.firstWeb.webPageDetails.isHomePage = true"
    },
    "evaluationInfo": {
        "batch": {
            "enabled": false
        },
        "continuous": {
            "enabled": true,
                   },
        "synchronous": {
            "enabled": false
        }
    },
    "creationTime": 1572021085000,
    "updateEpoch": 1572021086000,
    "updateTime": 1572021086000
}

Ativar avaliação programada enable-scheduled-segmentation

Quando a avaliação de transmissão tiver sido habilitada, uma linha de base deverá ser criada (depois disso, a definição do segmento sempre estará atualizada). A avaliação programada (também conhecida como segmentação programada) deve ser ativada primeiro para que o sistema execute automaticamente a linha de base. Com a segmentação programada, sua organização pode seguir uma programação recorrente para executar automaticamente trabalhos de exportação para avaliar as definições de segmento.

Criar um agendamento

Ao fazer uma solicitação POST para o /config/schedules você pode criar um agendamento e incluir a hora específica em que o agendamento deve ser acionado.

Formato da API

POST /config/schedules

Solicitação

A solicitação a seguir cria um novo agendamento com base nas especificações fornecidas no payload.

curl -X POST \
  https://platform.adobe.io/data/core/ups/config/schedules \
  -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 '{
        "name": "{SCHEDULE_NAME}",
        "type": "batch_segmentation",
        "properties": {
            "segments": ["*"]
        },
        "schedule": "0 0 1 * * ?",
        "state": "inactive"
        }'

Resposta

Uma resposta bem-sucedida retorna os detalhes do agendamento recém-criado.

{
    "id": "cd585edf-962d-420d-94ad-3be03e619ac2",
    "imsOrgId": "{ORG_ID}",
    "sandbox": {
        "sandboxId": "e7e17720-c5bb-11e9-aafb-87c71c35cac8",
        "sandboxName": "prod",
        "type": "production",
        "default": true
    },
    "name": "{SCHEDULE_NAME}",
    "state": "inactive",
    "type": "batch_segmentation",
    "schedule": "0 0 1 * * ?",
    "properties": {
        "segments": [
            "*"
        ]
    },
    "createEpoch": 1568267948,
    "updateEpoch": 1568267948
}

Ativar um agendamento

Por padrão, um agendamento fica inativo quando criado, a menos que state propriedade está definida como active no corpo da solicitação create (POST). Você pode habilitar um agendamento (defina o state para active) fazendo um pedido PATCH ao /config/schedules e incluindo a ID do agendamento no caminho.

Formato da API

POST /config/schedules/{SCHEDULE_ID}

Solicitação

A solicitação a seguir usa Formatação de patch de JSON para atualizar a state da programação para active.

curl -X POST \
  https://platform.adobe.io/data/core/ups/config/schedules/cd585edf-962d-420d-94ad-3be03e619ac2 \
  -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 '[
        {
          "op": "add",
          "path": "/state",
          "value": "active"
        }
      ]'

Resposta

Uma atualização bem-sucedida retorna um corpo de resposta vazio e um Status HTTP 204 (Sem conteúdo).

A mesma operação pode ser usada para desativar um agendamento substituindo o "valor" na solicitação anterior por "inativo".

Próximas etapas

Agora que você ativou definições de segmento novas e existentes para segmentação por transmissão e ativou a segmentação agendada para desenvolver uma linha de base e executar avaliações recorrentes, é possível começar a criar definições de segmento com transmissão ativada para sua organização.

Para saber como executar ações semelhantes e trabalhar com definições de segmento usando a interface do usuário do Adobe Experience Platform, visite o Guia do usuário do Construtor de segmentos.

Apêndice

A seção a seguir lista as perguntas frequentes relacionadas à segmentação de transmissão:

A "desqualificação" da segmentação por transmissão também ocorre em tempo real?

Para a maioria das instâncias, a desqualificação da segmentação por transmissão ocorre em tempo real. No entanto, as definições de segmento de transmissão que usam segmentos de segmentos não não desqualificar em tempo real, em vez de desqualificar após 24 horas.

Em quais dados a segmentação por transmissão funciona?

A segmentação de streaming funciona em todos os dados que foram assimilados usando uma fonte de streaming. Os segmentos assimilados usando uma origem em lote serão avaliados à noite, mesmo que se qualifiquem para segmentação por transmissão. Os eventos transmitidos para o sistema com um carimbo de data e hora com mais de 24 horas serão processados na tarefa em lote subsequente.

Como as definições de segmento são definidas como segmentação em lote ou por transmissão?

Uma definição de segmento é definida como segmentação em lote ou por transmissão com base em uma combinação de tipo de consulta e duração do histórico de eventos. Uma lista de quais definições de segmento serão avaliadas como um segmento de transmissão pode ser encontrada na seção tipos de consulta de segmentação de transmissão.

Observe que se um segmento contiver ambos um inSegment e uma cadeia direta de evento único, não pode se qualificar para segmentação por transmissão. Se quiser que essa definição de segmento se qualifique para segmentação por transmissão, você deve tornar a cadeia de evento único direta sua própria definição de segmento.

Por que o número de definições de segmento "total qualificado" continua aumentando, enquanto o número em "Últimos X dias" permanece em zero na seção de detalhes de definição do segmento?

O número total de definições de segmento qualificado é obtido do trabalho diário de segmentação, que inclui públicos qualificados para definições de segmento em lote e de transmissão. Esse valor é mostrado para definições de segmento em lote e de transmissão.

O número abaixo de "Últimos X dias" somente inclui públicos qualificados na segmentação por transmissão e somente aumenta se você tiver transmitido dados para o sistema e contar para essa definição de transmissão. Este valor é somente exibido para definições de segmento de transmissão. Como resultado, esse valor maio exibir como 0 para definições de segmento em lote.

Como resultado, se você vir que o número em "Últimos X dias" é zero e o gráfico de linhas também está relatando zero, você não todos os perfis transmitidos para o sistema que se qualificariam para essa definição de segmento.

Quanto tempo leva para uma definição de segmento ficar disponível?

Leva até uma hora para uma definição de segmento estar disponível.

Existem limitações para os dados que estão sendo transmitidos?

Para que os dados transmitidos sejam usados na segmentação por transmissão, há deve deve ser o espaçamento entre os eventos transmitidos. Se muitos eventos forem transmitidos no mesmo segundo, a Platform tratará esses eventos como dados gerados pelo bot e eles serão descartados. Como prática recomendada, você deve pelo menos cinco segundos entre os dados do evento para garantir que os dados sejam usados corretamente.