Endpoint processi segmento

Un processo di segmento è un processo asincrono che crea un nuovo segmento di pubblico. Fa riferimento a una definizione del segmento, nonché a qualsiasi criteri di unione che controlla in che modo Real-time Customer Profile unisce gli attributi di sovrapposizione nei frammenti di profilo. Quando un processo del segmento viene completato correttamente, potete raccogliere varie informazioni sul segmento, ad esempio eventuali errori che si sono verificati durante l'elaborazione e le dimensioni finali del pubblico.

Questa guida fornisce informazioni utili per comprendere meglio i processi dei segmenti e include chiamate API di esempio per eseguire azioni di base tramite l'API.

Introduzione

Gli endpoint utilizzati in questa guida fanno parte dell'API Adobe Experience Platform Segmentation Service. Prima di continuare, controlla la guida introduttiva per informazioni importanti che devi conoscere per effettuare correttamente le chiamate all'API, comprese le intestazioni richieste e come leggere le chiamate API di esempio.

Recuperare un elenco di processi di segmento

È possibile recuperare un elenco di tutti i processi del segmento per l'organizzazione IMS effettuando una richiesta di GET all'endpoint /segment/jobs.

Formato API

L'endpoint /segment/jobs supporta diversi parametri di query per facilitare il filtro dei risultati. Anche se questi parametri sono opzionali, il loro utilizzo è fortemente consigliato per ridurre i costi di sovraccarico. Effettuando una chiamata a questo endpoint senza parametri, tutti i processi di esportazione disponibili per la vostra organizzazione verranno recuperati. È possibile includere più parametri, separati da e-mail (&).

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

Parametri query

Parametro Descrizione Esempio
start Specifica l'offset iniziale per i processi del segmento restituiti. start=1
limit Specifica il numero di processi di segmento restituiti per pagina. limit=20
status Filtra i risultati in base allo stato. I valori supportati sono NUOVO, IN CODA, ELABORAZIONE, SUCCESSO, NON RIUSCITO, ANNULLAMENTO, ANNULLATO status=NEW
sort Ordina i processi del segmento restituiti. È scritto nel formato [attributeName]:[desc|asc]. sort=creationTime:desc
property Filtra i processi del segmento e ottiene corrispondenze esatte per il filtro specificato. Può essere scritto in uno dei seguenti formati:
  • [jsonObjectPath]==[value] - filtraggio sulla chiave dell'oggetto
  • [arrayTypeAttributeName]~[objectKey]==[value] - filtraggio all'interno dell'array
 property=segments~segmentId==workInUS

Richiesta

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}'

Risposta

Una risposta corretta restituisce lo stato HTTP 200 con un elenco di processi di segmento per l’organizzazione IMS specificata come JSON. La risposta seguente restituisce un elenco di tutti i processi del segmento riusciti per l'organizzazione IMS.

NOTA

La risposta seguente è stata troncata per lo spazio e mostrerà solo il primo processo restituito.

{
    "_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": {}
    }
}
Proprietà Descrizione
id Identificatore di sola lettura generato dal sistema per il processo del segmento.
status Lo stato corrente per il processo del segmento. I valori potenziali per lo stato includono "NEW", "PROCESSING", "ANNULLAMENTO", "ANNULLATO", "FAILED" e "SUCCESSO".
segments Un oggetto che contiene informazioni sulle definizioni del segmento restituite all'interno del processo del segmento.
segments.segment.id ID della definizione del segmento.
segments.segment.expression Un oggetto che contiene informazioni sull'espressione della definizione del segmento, scritta in PQL.
metrics Un oggetto che contiene informazioni diagnostiche sul processo del segmento.
metrics.totalTime Un oggetto che contiene informazioni sulle ore di inizio e fine del processo di segmentazione, nonché sul tempo totale impiegato.
metrics.profileSegmentationTime Un oggetto che contiene informazioni sulle ore di inizio e fine della valutazione della segmentazione, nonché sul tempo totale impiegato.
metrics.segmentProfileCounter Il numero di profili qualificati per segmento.
metrics.segmentedProfileByNamespaceCounter Il numero di profili qualificati per ogni namespace di identità per segmento.
metrics.segmentProfileByStatusCounter Il numero di profili per ogni stato. Sono supportati i tre stati seguenti:
  • "realizzato" - Il numero di nuovi profili immessi nel segmento.
  • "existing" - Il numero di profili che continuano a esistere nel segmento.
  • "uscito" - Il numero di segmenti di profilo che non esistono più nel segmento.
metrics.totalProfilesByMergePolicy Numero totale di profili uniti in base ai criteri di unione.

Crea un nuovo processo segmento

Puoi creare un nuovo processo per segmenti effettuando una richiesta di POST all'endpoint /segment/jobs e includendo nel corpo l'ID della definizione del segmento da cui desideri creare una nuova audience.

Formato API

POST /segment/jobs

Richiesta

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",
  }
]'
Proprietà Descrizione
segmentId L’ID della definizione del segmento per cui desiderate creare un processo di segmento. Queste definizioni di segmento possono appartenere a criteri di unione diversi. Ulteriori informazioni sulle definizioni dei segmenti sono disponibili nella guida alla definizione dell'endpoint .

Risposta

Una risposta corretta restituisce lo stato HTTP 200 con i dettagli del processo del segmento appena creato.

{
    "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
}
Proprietà Descrizione
id Identificatore di sola lettura generato dal sistema per il processo di segmento appena creato.
status Lo stato corrente per il processo del segmento. Poiché il processo del segmento viene creato di recente, lo stato sarà sempre "NEW".
segments Un oggetto che contiene informazioni sulle definizioni di segmento per le quali il processo di segmento è in esecuzione.
segments.segment.id ID della definizione del segmento fornita.
segments.segment.expression Un oggetto che contiene informazioni sull'espressione della definizione del segmento, scritta in PQL.

Recuperare un processo segmento specifico

Potete recuperare informazioni dettagliate su un processo di segmento specifico effettuando una richiesta di GET all'endpoint /segment/jobs e fornendo l'ID del processo di segmento che desiderate recuperare nel percorso della richiesta.

Formato API

GET /segment/jobs/{SEGMENT_JOB_ID}
Proprietà Descrizione
{SEGMENT_JOB_ID} Il valore id del processo del segmento da recuperare.

Richiesta

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}'

Risposta

Una risposta corretta restituisce lo stato HTTP 200 con informazioni dettagliate sul processo del segmento specificato.

{
    "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
}
Proprietà Descrizione
id Identificatore di sola lettura generato dal sistema per il processo del segmento.
status Lo stato corrente per il processo del segmento. I valori potenziali per lo stato includono "NEW", "PROCESSING", "ANNULLAMENTO", "ANNULLATO", "FAILED" e "SUCCESSO".
segments Un oggetto che contiene informazioni sulle definizioni del segmento restituite all'interno del processo del segmento.
segments.segment.id ID della definizione del segmento.
segments.segment.expression Un oggetto che contiene informazioni sull'espressione della definizione del segmento, scritta in PQL.
metrics Un oggetto che contiene informazioni diagnostiche sul processo del segmento.

Recupero in blocco dei processi del segmento

Potete recuperare informazioni dettagliate su più processi di segmento eseguendo una richiesta POST all'endpoint /segment/jobs/bulk-get e fornendo i valori id dei processi di segmento nel corpo della richiesta.

Formato API

POST /segment/jobs/bulk-get

Richiesta

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"
            }
        ]
    }'

Risposta

Una risposta corretta restituisce lo stato HTTP 207 con i processi di segmento richiesti.

NOTA

La risposta seguente è stata troncata per lo spazio, mostrando solo dettagli parziali di ciascun processo del segmento. La risposta completa elenca tutti i dettagli per i processi del segmento richiesti.

{
    "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
        }
    }
}
Proprietà Descrizione
id Identificatore di sola lettura generato dal sistema per il processo del segmento.
status Lo stato corrente per il processo del segmento. I valori potenziali per lo stato includono "NEW", "PROCESSING", "ANNULLAMENTO", "ANNULLATO", "FAILED" e "SUCCESSO".
segments Un oggetto che contiene informazioni sulle definizioni del segmento restituite all'interno del processo del segmento.
segments.segment.id ID della definizione del segmento.
segments.segment.expression Un oggetto che contiene informazioni sull'espressione della definizione del segmento, scritta in PQL.

Annullare o eliminare un processo di segmento specifico

Potete eliminare un processo di segmento specifico eseguendo una richiesta di DELETE all'endpoint /segment/jobs e fornendo l'ID del processo di segmento da eliminare nel percorso della richiesta.

NOTA

La risposta API alla richiesta di eliminazione è immediata. Tuttavia, l'eliminazione effettiva del processo del segmento è asincrona. In altre parole, esiste una differenza di tempo tra quando viene effettuata la richiesta di eliminazione al processo del segmento e quando viene applicata.

Formato API

DELETE /segment/jobs/{SEGMENT_JOB_ID}
Proprietà Descrizione
{SEGMENT_JOB_ID} Il valore id del processo del segmento da eliminare.

Richiesta

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}'

Risposta

Una risposta corretta restituisce lo stato HTTP 204 con le seguenti informazioni.

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

Passaggi successivi

Dopo aver letto questa guida è ora possibile comprendere meglio come funzionano i processi di segmento.

In questa pagina

Adobe Summit Banner

A virtual event April 27-28.

Expand your skills and get inspired.

Register for free
Adobe Summit Banner

A virtual event April 27-28.

Expand your skills and get inspired.

Register for free