Ponto de extremidade de trabalhos de segmento

Um trabalho de segmento é um processo assíncrono que cria um novo segmento de público-alvo. Ele faz referência a uma definição de segmento, bem como a qualquer política de mesclagem controlando como Real-time Customer Profile mescla atributos sobrepostos nos fragmentos de perfil. Quando um trabalho de segmento é concluído com êxito, você pode coletar várias informações sobre o segmento, como erros que possam ter ocorrido durante o processamento e o tamanho final do público-alvo.

Este guia fornece informações para ajudá-lo a entender melhor as tarefas do segmento e inclui exemplos de chamadas de API para executar ações básicas usando a API.

Introdução

Os endpoints usados neste guia fazem parte da API Adobe Experience Platform Segmentation Service. Antes de continuar, reveja o guia de introdução para obter informações importantes que você precisa saber para fazer chamadas para a API com êxito, incluindo cabeçalhos necessários e como ler chamadas de API de exemplo.

Recuperar uma lista de tarefas de segmento

Você pode recuperar uma lista de todas as tarefas de segmento para sua Organização IMS fazendo uma solicitação de GET para o endpoint /segment/jobs.

Formato da API

O ponto de extremidade /segment/jobs oferece suporte a vários parâmetros de consulta para ajudar a filtrar os resultados. Embora esses parâmetros sejam opcionais, seu uso é altamente recomendado para ajudar a reduzir a sobrecarga cara. Efetuar uma chamada para esse endpoint sem parâmetros recuperará todos os trabalhos de exportação disponíveis para sua organização. Vários parâmetros podem ser incluídos, separados por "E" comercial (&).

GET /segment/jobs
GET /segment/jobs?{QUERY_PARAMETERS}

Parâmetros de consulta

Parâmetro Descrição Exemplo
start Especifica o deslocamento inicial dos trabalhos de segmento retornados. start=1
limit Especifica o número de trabalhos de segmento retornados por página. limit=20
status Filtra os resultados com base no status . Os valores suportados são NOVO, FILEIRADO, PROCESSAMENTO, BEM-SUCEDIDO, FALHA, CANCELAMENTO, CANCELADO status=NEW
sort Encomende os trabalhos do segmento retornados. É gravado no formato [attributeName]:[desc|asc]. sort=creationTime:desc
property Filtra os trabalhos do segmento e obtém correspondências exatas para o filtro fornecido. Ele pode ser escrito em um dos seguintes formatos:
  • [jsonObjectPath]==[value] - filtragem na chave de objeto
  • [arrayTypeAttributeName]~[objectKey]==[value] - filtragem dentro da matriz
 property=segments~segmentId==workInUS

Solicitação

curl -X GET https://platform.adobe.io/data/core/ups/segment/jobs?status=SUCCEEDED \
 -H 'Authorization: Bearer {ACCESS_TOKEN}' \
 -H 'x-gw-ims-org-id: {IMS_ORG}' \
 -H 'x-api-key: {API_KEY}' \
 -H 'x-sandbox-name: {SANDBOX_NAME}'

Resposta

Uma resposta bem-sucedida retorna o status HTTP 200 com uma lista de tarefas de segmento para a organização IMS especificada como JSON. A resposta a seguir retorna uma lista de todos os trabalhos de segmento bem-sucedidos da organização IMS.

OBSERVAÇÃO

A resposta a seguir foi truncada para espaço e mostrará apenas o primeiro trabalho retornado.

{
    "_page": {
        "totalCount": 14,
        "pageSize": 14
    },
    "children": [
        {
            "id": "b31aed3d-b3b1-4613-98c6-7d3846e8d48f",
            "imsOrgId": "E95186D65A28ABF00A495D82@AdobeOrg",
            "sandbox": {
                "sandboxId": "28e74200-e3de-11e9-8f5d-7f27416c5f0d",
                "sandboxName": "prod",
                "type": "production",
                "default": true
            },
            "profileInstanceId": "ups",
            "source": "scheduler",
            "status": "SUCCEEDED",
            "batchId": "678f53bc-e21d-4c47-a7ec-5ad0064f8e4c",
            "computeJobId": 8811,
            "computeGatewayJobId": "9ea97b25-a0f5-410e-ae87-b2d85e58f399",
            "segments": [
                {
                    "segmentId": "30230300-ccf1-48ad-8012-c5563a007069",
                    "segment": {
                        "id": "30230300-ccf1-48ad-8012-c5563a007069",
                        "expression": {
                            "type": "PQL",
                            "format": "pql/json",
                            "value": "{PQL_EXPRESSION}"
                        },
                        "mergePolicyId": "25c548a0-ca7f-4dcd-81d5-997642f178b9",
                        "mergePolicy": {
                            "id": "25c548a0-ca7f-4dcd-81d5-997642f178b9",
                            "version": 1
                        }
                    }
                }
            ],
            "metrics": {
                "totalTime": {
                    "startTimeInMs": 1573203617195,
                    "endTimeInMs": 1573204395655,
                    "totalTimeInMs": 778460
                },
                "profileSegmentationTime": {
                    "startTimeInMs": 1573204266727,
                    "endTimeInMs": 1573204395655,
                    "totalTimeInMs": 128928
                },
                "totalProfiles":13146432,
                "segmentedProfileCounter":{
                    "94509dba-7387-452f-addc-5d8d979f6ae8":1033
                },
                "segmentedProfileByNamespaceCounter":{
                    "94509dba-7387-452f-addc-5d8d979f6ae8":{
                        "tenantiduserobjid":1033,
                        "campaign_profile_mscom_mkt_prod2":1033
                    }
                },
                "segmentedProfileByStatusCounter":{
                    "94509dba-7387-452f-addc-5d8d979f6ae8":{
                        "exited":144646,
                        "existing":10,
                        "realized":2056
                    }
                },
                "totalProfilesByMergePolicy":{
                    "25c548a0-ca7f-4dcd-81d5-997642f178b9":13146432
                }
            },
            "requestId": "4e538382-dbd8-449e-988a-4ac639ebe72b-1573203600264",
            "schema": {
                "name": "_xdm.context.profile"
            },
            "properties": {
                "scheduleId": "4e538382-dbd8-449e-988a-4ac639ebe72b",
                "runId": "e6c1308d-0d4b-4246-b2eb-43697b50a149"
            },
            "_links": {
                "cancel": {
                    "href": "/segment/jobs/b31aed3d-b3b1-4613-98c6-7d3846e8d48f",
                    "method": "DELETE"
                },
                "checkStatus": {
                    "href": "/segment/jobs/b31aed3d-b3b1-4613-98c6-7d3846e8d48f",
                    "method": "GET"
                }
            },
            "updateTime": 1573204395000,
            "creationTime": 1573203600535,
            "updateEpoch": 1573204395
        }
    ],
    "_links": {
        "next": {}
    }
}
Propriedade Descrição
id Um identificador somente leitura gerado pelo sistema para o trabalho do segmento.
status O status atual do trabalho do segmento. Os valores potenciais para o status incluem "NOVO", "PROCESSAMENTO", "CANCELAMENTO", "CANCELADO", "FALHADO" e "SUCEDIDO".
segments Um objeto que contém informações sobre as definições de segmento retornadas no trabalho de segmento.
segments.segment.id A ID da definição de segmento.
segments.segment.expression Um objeto que contém informações sobre a expressão da definição de segmento, escrita em PQL.
metrics Um objeto que contém informações de diagnóstico sobre o trabalho do segmento.
metrics.totalTime Um objeto que contém informações sobre os horários em que o trabalho de segmentação foi iniciado e encerrado, bem como o tempo total gasto.
metrics.profileSegmentationTime Um objeto que contém informações sobre os horários em que a avaliação de segmentação foi iniciada e finalizada, bem como o tempo total gasto.
metrics.segmentProfileCounter O número de perfis qualificados por segmento.
metrics.segmentedProfileByNamespaceCounter O número de perfis qualificados para cada namespace de identidade com base em segmento.
metrics.segmentProfileByStatusCounter A contagem de perfis para cada status. Os três status a seguir são suportados:
  • "percebido" - o número de novos perfis que entraram no segmento.
  • "existente" - o número de perfis que continuam a existir no segmento.
  • "encerrado" - O número de segmentos de perfil que não existem mais no segmento.
metrics.totalProfilesByMergePolicy O número total de perfis mesclados com base em políticas de mesclagem.

Criar um novo trabalho de segmento

Você pode criar um novo trabalho de segmento fazendo uma solicitação POST para o endpoint /segment/jobs e incluindo no corpo a ID da definição de segmento da qual deseja criar um novo público-alvo.

Formato da API

POST /segment/jobs

Solicitação

curl -X POST https://platform.adobe.io/data/core/ups/segment/jobs \
 -H 'Authorization: Bearer {ACCESS_TOKEN}' \
 -H 'Content-Type: application/json' \
 -H 'x-gw-ims-org-id: {IMS_ORG}' \
 -H 'x-api-key: {API_KEY}' \
 -H 'x-sandbox-name: {SANDBOX_NAME}' \
 -d '
[
  {
    "segmentId": "4afe34ae-8c98-4513-8a1d-67ccaa54bc05",
  }
]'
Propriedade Descrição
segmentId A ID da definição de segmento para a qual você deseja criar um trabalho de segmento. Essas definições de segmento podem pertencer a diferentes políticas de mesclagem. Mais informações sobre definições de segmento podem ser encontradas no guia de ponto de extremidade de definição de segmento.

Resposta

Uma resposta bem-sucedida retorna o status HTTP 200 com detalhes do seu trabalho de segmento recém-criado.

{
    "id": "d3b4a50d-dfea-43eb-9fca-557ea53771fd",
    "imsOrgId": "{IMS_ORG}",
    "sandbox": {
        "sandboxId": "28e74200-e3de-11e9-8f5d-7f27416c5f0d",
        "sandboxName": "prod",
        "type": "production",
        "default": true
    },
    "profileInstanceId": "ups",
    "source": "api",
    "status": "NEW",
    "segments": [
        {
            "segmentId": "4afe34ae-8c98-4513-8a1d-67ccaa54bc05",
            "segment": {
                "id": "4afe34ae-8c98-4513-8a1d-67ccaa54bc05",
                "expression": {
                    "type": "PQL",
                    "format": "pql/text",
                    "value": "workAddress.country = \"US\""
                },
                "mergePolicyId": "e161dae9-52f0-4c7f-b264-dc43dd903d56",
                "mergePolicy": {
                    "id": "e161dae9-52f0-4c7f-b264-dc43dd903d56",
                    "version": 1
                }
            }
        }
    ],
    "requestId": "Hw1jdAHeuWHVKVxcAPFrLCbbjkriDl9v",
    "schema": {
        "name": "_xdm.context.profile"
    },
    "_links": {
        "cancel": {
            "href": "/segment/jobs/d3b4a50d-dfea-43eb-9fca-557ea53771fd",
            "method": "DELETE"
        },
        "checkStatus": {
            "href": "/segment/jobs/d3b4a50d-dfea-43eb-9fca-557ea53771fd",
            "method": "GET"
        }
    },
    "updateTime": 1579304260000,
    "creationTime": 1579304260897,
    "updateEpoch": 1579304260
}
Propriedade Descrição
id Um identificador somente leitura gerado pelo sistema para o trabalho de segmento recém-criado.
status O status atual do trabalho do segmento. Como o trabalho do segmento é criado recentemente, o status sempre será "NOVO".
segments Um objeto que contém informações sobre as definições de segmento para as quais esse trabalho de segmento está sendo executado.
segments.segment.id A ID da definição de segmento fornecida.
segments.segment.expression Um objeto que contém informações sobre a expressão da definição de segmento, escrita em PQL.

Recuperar um trabalho de segmento específico

Você pode recuperar informações detalhadas sobre um trabalho de segmento específico fazendo uma solicitação de GET para o terminal /segment/jobs e fornecendo a ID do trabalho de segmento que deseja recuperar no caminho da solicitação.

Formato da API

GET /segment/jobs/{SEGMENT_JOB_ID}
Propriedade Descrição
{SEGMENT_JOB_ID} O valor id do trabalho de segmento que você deseja recuperar.

Solicitação

curl -X GET https://platform.adobe.io/data/core/ups/segment/jobs/d3b4a50d-dfea-43eb-9fca-557ea53771fd \
 -H 'Authorization: Bearer {ACCESS_TOKEN}' \
 -H 'x-gw-ims-org-id: {IMS_ORG}' \
 -H 'x-api-key: {API_KEY}' \
 -H 'x-sandbox-name: {SANDBOX_NAME}'

Resposta

Uma resposta bem-sucedida retorna o status HTTP 200 com informações detalhadas sobre o trabalho do segmento especificado.

{
    "id": "d3b4a50d-dfea-43eb-9fca-557ea53771fd",
    "imsOrgId": "{IMS_ORG}",
    "sandbox": {
        "sandboxId": "28e74200-e3de-11e9-8f5d-7f27416c5f0d",
        "sandboxName": "prod",
        "type": "production",
        "default": true
    },
    "profileInstanceId": "ups",
    "source": "api",
    "status": "SUCCEEDED",
    "batchId": "651fc109-3963-48d2-aa98-9e3cc2003bac",
    "computeJobId": 39312,
    "computeGatewayJobId": "a0099ab6-11ab-4c2b-a0ea-6162e16806bd",
    "segments": [
        {
            "segmentId": "4afe34ae-8c98-4513-8a1d-67ccaa54bc05",
            "segment": {
                "id": "4afe34ae-8c98-4513-8a1d-67ccaa54bc05",
                "expression": {
                    "type": "PQL",
                    "format": "pql/text",
                    "value": "workAddress.country = \"US\""
                },
                "mergePolicyId": "e161dae9-52f0-4c7f-b264-dc43dd903d56",
                "mergePolicy": {
                    "id": "e161dae9-52f0-4c7f-b264-dc43dd903d56",
                    "version": 1
                }
            }
        }
    ],
    "metrics": {
        "totalTime": {
            "startTimeInMs": 1579304313411
        },
        "profileSegmentationTime": {}
    },
    "requestId": "Hw1jdAHeuWHVKVxcAPFrLCbbjkriDl9v",
    "schema": {
        "name": "_xdm.context.profile"
    },
    "_links": {
        "cancel": {
            "href": "/segment/jobs/d3b4a50d-dfea-43eb-9fca-557ea53771fd",
            "method": "DELETE"
        },
        "checkStatus": {
            "href": "/segment/jobs/d3b4a50d-dfea-43eb-9fca-557ea53771fd",
            "method": "GET"
        }
    },
    "updateTime": 1579304339000,
    "creationTime": 1579304260897,
    "updateEpoch": 1579304339
}
Propriedade Descrição
id Um identificador somente leitura gerado pelo sistema para o trabalho do segmento.
status O status atual do trabalho do segmento. Os valores potenciais para o status incluem "NOVO", "PROCESSAMENTO", "CANCELAMENTO", "CANCELADO", "FALHADO" e "SUCEDIDO".
segments Um objeto que contém informações sobre as definições de segmento retornadas no trabalho de segmento.
segments.segment.id A ID da definição de segmento.
segments.segment.expression Um objeto que contém informações sobre a expressão da definição de segmento, escrita em PQL.
metrics Um objeto que contém informações de diagnóstico sobre o trabalho do segmento.

Recuperar trabalhos de segmento em massa

Você pode recuperar informações detalhadas sobre vários trabalhos de segmento, fazendo uma solicitação de POST para o terminal /segment/jobs/bulk-get e fornecendo os valores id dos trabalhos de segmento no corpo da solicitação.

Formato da API

POST /segment/jobs/bulk-get

Solicitação

curl -X POST https://platform.adobe.io/data/core/ups/segment/jobs/bulk-get \
  -H 'Authorization: Bearer {ACCESS_TOKEN}' \
  -H 'Content-Type: application/json' \
  -H 'x-gw-ims-org-id: {IMS_ORG}' \
  -H 'x-api-key: {API_KEY}' \
  -H 'x-sandbox-name: {SANDBOX_NAME}' \
  -d '{
        "ids": [
            {
                "id": "cc3419d3-0389-47f1-b174-fead6b3c830d"
            },
            {
                "id": "c527dc3f-07fe-4b96-be4e-23f38e734ff8"
            }
        ]
    }'

Resposta

Uma resposta bem-sucedida retorna o status HTTP 207 com os trabalhos de segmento solicitados.

OBSERVAÇÃO

A resposta a seguir foi truncada para o espaço, mostrando apenas detalhes parciais de cada tarefa de segmento. A resposta completa listará os detalhes completos dos trabalhos do segmento solicitados.

{
    "results": {
        "cc3419d3-0389-47f1-b174-fead6b3c830d": {
            "id": "cc3419d3-0389-47f1-b174-fead6b3c830d",
            "imsOrgId": "{IMS_ORG}",
            "status": "SUCCEEDED",
            "segments": [
                {
                    "segmentId": "30230300-ccf1-48ad-8012-c5563a007069",
                    "segment": {
                        "id": "30230300-ccf1-48ad-8012-c5563a007069",
                        "expression": {
                            "type": "PQL",
                            "format": "pql/json",
                            "value": "{PQL_EXPRESSION}"
                        },
                        "mergePolicyId": "b83185bb-0bc6-489c-9363-0075eb30b4c8",
                        "mergePolicy": {
                            "id": "b83185bb-0bc6-489c-9363-0075eb30b4c8",
                            "version": 1
                        }
                    }
                }
            ],
            "updateTime": 1573204395000,
            "creationTime": 1573203600535,
            "updateEpoch": 1573204395
        },
        "c527dc3f-07fe-4b96-be4e-23f38e734ff8": {
            "id": "c527dc3f-07fe-4b96-be4e-23f38e734ff8",
            "imsOrgId": "{IMS_ORG}",
            "status": "SUCCEEDED",
            "segments": [
                {
                    "segmentId": "4afe34ae-8c98-4513-8a1d-67ccaa54bc05",
                    "segment": {
                        "id": "4afe34ae-8c98-4513-8a1d-67ccaa54bc05",
                        "expression": {
                            "type": "PQL",
                            "format": "pql/json",
                            "value": "{PQL_EXPRESSION}"
                        },
                        "mergePolicyId": "b83185bb-0bc6-489c-9363-0075eb30b4c8",
                        "mergePolicy": {
                            "id": "b83185bb-0bc6-489c-9363-0075eb30b4c8",
                            "version": 1
                        }
                    }
                }
            ],
            "updateTime": 1573204395000,
            "creationTime": 1573203600535,
            "updateEpoch": 1573204395
        }
    }
}
Propriedade Descrição
id Um identificador somente leitura gerado pelo sistema para o trabalho do segmento.
status O status atual do trabalho do segmento. Os valores potenciais para o status incluem "NOVO", "PROCESSAMENTO", "CANCELAMENTO", "CANCELADO", "FALHADO" e "SUCEDIDO".
segments Um objeto que contém informações sobre as definições de segmento retornadas no trabalho de segmento.
segments.segment.id A ID da definição de segmento.
segments.segment.expression Um objeto que contém informações sobre a expressão da definição de segmento, escrita em PQL.

Cancelar ou excluir um trabalho de segmento específico

Você pode excluir um trabalho de segmento específico fazendo uma solicitação de DELETE ao terminal /segment/jobs e fornecendo a ID do trabalho de segmento que deseja excluir no caminho da solicitação.

OBSERVAÇÃO

A resposta da API à solicitação de exclusão é imediata. No entanto, a exclusão real do trabalho do segmento é assíncrona. Em outras palavras, há uma diferença de tempo entre quando a solicitação de exclusão para o trabalho do segmento é feita e quando ela é aplicada.

Formato da API

DELETE /segment/jobs/{SEGMENT_JOB_ID}
Propriedade Descrição
{SEGMENT_JOB_ID} O valor id do trabalho de segmento que você deseja excluir.

Solicitação

curl -X DELETE https://platform.adobe.io/data/core/ups/segment/jobs/d3b4a50d-dfea-43eb-9fca-557ea53771fd \
 -H 'Authorization: Bearer {ACCESS_TOKEN}' \
 -H 'x-gw-ims-org-id: {IMS_ORG}' \
 -H 'x-api-key: {API_KEY}' \
 -H 'x-sandbox-name: {SANDBOX_NAME}'

Resposta

Uma resposta bem-sucedida retorna o status HTTP 204 com as seguintes informações.

{
    "status": true,
    "message": "Segment job with id 'd3b4a50d-dfea-43eb-9fca-557ea53771fd' has been marked for cancelling"
}

Próximas etapas

Após a leitura deste guia, você tem uma melhor compreensão de como as tarefas do segmento funcionam.

Nesta página