Endpoint "privacy jobs"

Questo documento illustra come lavorare con i processi relativi alla privacy utilizzando le chiamate API. In particolare, riguarda l'uso del /job endpoint nella Privacy Service API. Prima di leggere questa guida, consulta guida introduttiva per informazioni importanti che devi conoscere per effettuare correttamente chiamate all’API, incluse le intestazioni richieste e la lettura di esempi di chiamate API.

NOTA

Se stai tentando di gestire le richieste di consenso o rinuncia dei clienti, consulta guida dell’endpoint di consenso.

Elenca tutti i processi

Puoi visualizzare un elenco di tutti i processi di privacy disponibili all’interno della tua organizzazione effettuando una richiesta GET al /jobs endpoint.

Formato API

Questo formato di richiesta utilizza un regulation parametro di query sul /jobs punto finale, quindi inizia con un punto interrogativo (?) come illustrato di seguito. La risposta è impaginata e consente di utilizzare altri parametri di query (page e size) per filtrare la risposta. È possibile separare più parametri utilizzando il simbolo commerciale (&).

GET /jobs?regulation={REGULATION}
GET /jobs?regulation={REGULATION}&page={PAGE}
GET /jobs?regulation={REGULATION}&size={SIZE}
GET /jobs?regulation={REGULATION}&page={PAGE}&size={SIZE}
Parametro Descrizione
{REGULATION} Tipo di regolamento per cui eseguire la query. I valori accettati includono:
  • apa_aus
  • ccpa
  • cpra_usa
  • gdpr
  • hipaa_usa
  • lgpd_bra
  • nzpa_nzl
  • pdpa_tha
  • vcdpa_usa

Consulta la panoramica su normative supportate per ulteriori informazioni sulle normative sulla privacy rappresentate dai valori di cui sopra.
{PAGE} Pagina di dati da visualizzare, utilizzando la numerazione basata su 0. Il valore predefinito è 0.
{SIZE} Il numero di risultati da visualizzare su ogni pagina. Il valore predefinito è 1 e il massimo è 100. Se si supera il valore massimo, l’API restituisce un errore 400 codici.

Richiesta

La richiesta seguente recupera un elenco impaginato di tutti i processi all’interno di un’organizzazione IMS, a partire dalla terza pagina con una dimensione di pagina di 50.

curl -X GET \
  https://platform.adobe.io/data/core/privacy/jobs?regulation=gdpr&page=2&size=50 \
  -H 'Authorization: Bearer {ACCESS_TOKEN}' \
  -H 'x-api-key: {API_KEY}' \
  -H 'x-gw-ims-org-id: {ORG_ID}'

Risposta

In caso di esito positivo, la risposta restituisce un elenco di processi, ciascuno dei quali contiene dettagli quali jobId. In questo esempio, la risposta conterrà un elenco di 50 processi, a partire dalla terza pagina dei risultati.

Accesso alle pagine successive

Per recuperare il successivo set di risultati in una risposta impaginata, devi effettuare un’altra chiamata API allo stesso endpoint durante l’aumento del page parametro di query per 1.

Creare un processo di privacy

Prima di creare una nuova richiesta di lavoro, devi raccogliere informazioni di identificazione sulle persone interessate a cui desideri accedere, eliminare o rinunciare alla vendita dei dati. Una volta che disponi dei dati richiesti, questi devono essere forniti nel payload di una richiesta POST al /jobs endpoint.

NOTA

Le applicazioni Adobe Experience Cloud compatibili utilizzano valori diversi per identificare le persone interessate. Consulta la guida su Applicazioni Privacy Service e Experience Cloud per ulteriori informazioni sugli identificatori richiesti per le applicazioni. Per informazioni più generali su come determinare gli ID da inviare a Privacy Service, consulta il documento su dati di identità nelle richieste di privacy.

Il Privacy Service L’API supporta due tipi di richieste di lavoro per i dati personali:

IMPORTANTE

Mentre le richieste di accesso ed eliminazione possono essere combinate come una singola chiamata API, le richieste di rinuncia devono essere effettuate separatamente.

Creare un processo di accesso/eliminazione

In questa sezione viene illustrato come effettuare una richiesta di processo di accesso/eliminazione utilizzando l’API.

Formato API

POST /jobs

Richiesta

La richiesta seguente crea una nuova richiesta di processo, configurata dagli attributi forniti nel payload come descritto di seguito.

curl -X POST \
  https://platform.adobe.io/data/core/privacy/jobs \
  -H 'Authorization: Bearer {ACCESS_TOKEN}' \
  -H 'Content-Type: application/json' \
  -H 'x-api-key: {API_KEY}' \
  -H 'x-gw-ims-org-id: {ORG_ID}' \
  -d '{
    "companyContexts": [
      {
        "namespace": "imsOrgID",
        "value": "{ORG_ID}"
      }
    ],
    "users": [
      {
        "key": "DavidSmith",
        "action": ["access"],
        "userIDs": [
          {
            "namespace": "email",
            "value": "dsmith@acme.com",
            "type": "standard"
          },
          {
            "namespace": "ECID",
            "type": "standard",
            "value":  "443636576799758681021090721276",
            "isDeletedClientSide": false
          }
        ]
      },
      {
        "key": "user12345",
        "action": ["access","delete"],
        "userIDs": [
          {
            "namespace": "email",
            "value": "ajones@acme.com",
            "type": "standard"
          },
          {
            "namespace": "loyaltyAccount",
            "value": "12AD45FE30R29",
            "type": "integrationCode"
          }
        ]
      }
    ],
    "include": ["Analytics", "AudienceManager","profileService"],
    "expandIds": false,
    "priority": "normal",
    "analyticsDeleteMethod": "anonymize",
    "mergePolicyId": 124,
    "regulation": "ccpa"
}'
Proprietà Descrizione
companyContexts (Obbligatorio) Array contenente le informazioni di autenticazione per l’organizzazione. Ogni identificatore elencato include i seguenti attributi:
  • namespace: spazio dei nomi di un identificatore.
  • value: valore dell’identificatore.
È obbligatorio che uno degli identificatori utilizza imsOrgId come namespace, con i relativi value contenente l’ID univoco per l’organizzazione IMS.

Identificatori aggiuntivi possono essere qualificatori aziendali specifici per prodotto (ad esempio, Campaign), che identificano un’integrazione con un’applicazione di Adobe appartenente alla tua organizzazione. I valori potenziali includono nomi di account, codici client, ID tenant o altri identificatori dell’applicazione.
users (Obbligatorio) Matrice contenente una raccolta di almeno un utente di cui si desidera accedere o eliminare le informazioni. È possibile fornire un massimo di 1000 ID utente in una singola richiesta. Ogni oggetto utente contiene le seguenti informazioni:
  • key: identificatore per un utente utilizzato per qualificare gli ID processo separati nei dati di risposta. È consigliabile scegliere una stringa univoca e facilmente identificabile per questo valore in modo che possa essere facilmente referenziato o cercato in un secondo momento.
  • action: array che elenca le azioni da eseguire sui dati dell’utente. A seconda delle azioni che desideri eseguire, questo array deve includere access, delete, o entrambi.
  • userIDs: raccolta di identità per l’utente. Il numero di identità che un singolo utente può avere è limitato a nove. Ogni identità è costituita da una namespace, a value, e un qualificatore dello spazio dei nomi (type). Consulta la appendice per ulteriori dettagli su queste proprietà richieste.
Per una spiegazione più dettagliata di users e userIDs, vedere guida alla risoluzione dei problemi.
include (Obbligatorio) Array di prodotti di Adobe da includere nell’elaborazione. Se questo valore manca o è vuoto, la richiesta verrà rifiutata. Includi solo i prodotti con cui l’organizzazione ha un’integrazione. Consulta la sezione su valori prodotti accettati per ulteriori informazioni, consulta l’appendice.
expandIDs Proprietà facoltativa che, se impostata su true, rappresenta un’ottimizzazione per l’elaborazione degli ID nelle applicazioni (attualmente supportato solo da Analytics). Se omesso, il valore predefinito è false.
priority Proprietà facoltativa utilizzata da Adobe Analytics che imposta la priorità per l’elaborazione delle richieste. I valori accettati sono normal e low. Se priority viene omesso, il comportamento predefinito è normal.
analyticsDeleteMethod Proprietà facoltativa che specifica come Adobe Analytics deve gestire i dati personali. Per questo attributo sono accettati due possibili valori:
  • anonymize: tutti i dati a cui fa riferimento la raccolta specificata di ID utente vengono resi anonimi. Se analyticsDeleteMethod viene omesso. Si tratta del comportamento predefinito.
  • purge: tutti i dati vengono rimossi completamente.
mergePolicyId Quando si eseguono richieste di privacy per Real-Time Customer Profile (profileService), puoi facoltativamente fornire l’ID della specifica criterio di unione che desideri utilizzare per l’unione di ID. Specificando un criterio di unione, le richieste di privacy possono includere informazioni sui segmenti quando si restituiscono dati su un cliente. È possibile specificare un solo criterio di unione per richiesta. Se non viene fornito alcun criterio di unione, le informazioni di segmentazione non vengono incluse nella risposta.
regulation (Obbligatorio) Il regolamento per il lavoro sulla privacy. Sono accettati i seguenti valori:
  • apa_aus
  • ccpa
  • cpra_usa
  • gdpr
  • hipaa_usa
  • lgpd_bra
  • nzpa_nzl
  • pdpa_tha
  • vcdpa_usa

Consulta la panoramica su normative supportate per ulteriori informazioni sulle normative sulla privacy rappresentate dai valori di cui sopra.

Risposta

In caso di esito positivo, la risposta restituisce i dettagli dei nuovi processi creati.

{
    "jobs": [
        {
            "jobId": "6fc09b53-c24f-4a6c-9ca2-c6076b0842b6",
            "customer": {
                "user": {
                    "key": "DavidSmith",
                    "action": [
                        "access"
                    ]
                }
            }
        },
        {
            "jobId": "6fc09b53-c24f-4a6c-9ca2-c6076be029f3",
            "customer": {
                "user": {
                    "key": "user12345",
                    "action": [
                        "access"
                    ]
                }
            }
        },
        {
            "jobId": "6fc09b53-c24f-4a6c-9ca2-c6076bd023j1",
            "customer": {
                "user": {
                    "key": "user12345",
                    "action": [
                        "delete"
                    ]
                }
            }
        }
    ],
    "requestStatus": 1,
    "totalRecords": 3
}
Proprietà Descrizione
jobId ID univoco di sola lettura generato dal sistema per un processo. Questo valore viene utilizzato nel passaggio successivo della ricerca di un processo specifico.

Dopo aver inviato correttamente la richiesta del processo, è possibile procedere al passaggio successivo di verifica dello stato del processo.

Controllare lo stato di un processo

È possibile recuperare informazioni su un job specifico, ad esempio il relativo stato di elaborazione corrente, includendo jobId nel percorso di una richiesta GET al /jobs endpoint.

IMPORTANTE

I dati per i processi creati in precedenza sono disponibili per il recupero solo entro 30 giorni dalla data di completamento del processo.

Formato API

GET /jobs/{JOB_ID}
Parametro Descrizione
{JOB_ID} ID del processo che desideri cercare. Questo ID viene restituito in jobId in risposte API per creazione di un processo e elenco di tutti i processi.

Richiesta

La richiesta seguente recupera i dettagli del processo il cui jobId viene fornito nel percorso della richiesta.

curl -X GET \
  https://platform.adobe.io/data/core/privacy/jobs/6fc09b53-c24f-4a6c-9ca2-c6076b0842b6 \
  -H 'Authorization: Bearer {ACCESS_TOKEN}' \
  -H 'x-api-key: {API_KEY}' \
  -H 'x-gw-ims-org-id: {ORG_ID}'

Risposta

In caso di esito positivo, la risposta restituisce i dettagli del processo specificato.

{
    "jobId": "6fc09b53-c24f-4a6c-9ca2-c6076b0842b6",
    "requestId": "15700479082313109RX-899",
    "userKey": "David Smith",
    "action": "access",
    "status": "complete",
    "submittedBy": "{ACCOUNT_ID}",
    "createdDate": "10/02/2019 08:25 PM GMT",
    "lastModifiedDate": "10/02/2019 08:25 PM GMT",
    "userIds": [
        {
            "namespace": "email",
            "value": "dsmith@acme.com",
            "type": "standard",
            "namespaceId": 6,
            "isDeletedClientSide": false
        },
        {
            "namespace": "ECID",
            "value": "1123A4D5690B32A",
            "type": "standard",
            "namespaceId": 4,
            "isDeletedClientSide": false
        }
    ],
    "productResponses": [
        {
            "product": "Analytics",
            "retryCount": 0,
            "processedDate": "10/02/2019 08:25 PM GMT",
            "productStatusResponse": {
                "status": "complete",
                "message": "Success",
                "responseMsgCode": "PRVCY-6000-200",
                "responseMsgDetail": "Finished successfully."
            }
        },
        {
            "product": "Profile",
            "retryCount": 0,
            "processedDate": "10/02/2019 08:25 PM GMT",
            "productStatusResponse": {
                "status": "complete",
                "message": "Success",
                "responseMsgCode": "PRVCY-6000-200",
                "responseMsgDetail": "Success dataSetIds = [5dbb87aad37beb18a96feb61], Failed dataSetIds = []"
            }
        },
        {
            "product": "AudienceManager",
            "retryCount": 0,
            "processedDate": "10/02/2019 08:25 PM GMT",
            "productStatusResponse": {
                "status": "complete",
                "message": "Success",
                "responseMsgCode": "PRVCY-6054-200",
                "responseMsgDetail": "PARTIALLY COMPLETED- Data not found for some requests, check results for more info.",
                "results": {
                  "processed": ["1123A4D5690B32A"],
                  "ignored": ["dsmith@acme.com"]
                }
            }
        }
    ],
    "downloadURL": "http://...",
    "regulation": "ccpa"
}
Proprietà Descrizione
productStatusResponse Ogni oggetto all'interno del productResponses contiene informazioni sullo stato corrente del processo rispetto a un Experience Cloud applicazione.
productStatusResponse.status Categoria di stato corrente del processo. Consulta la tabella seguente per un elenco di categorie di stato disponibili e il significato corrispondente.
productStatusResponse.message Lo stato specifico del processo, corrispondente alla categoria di stato.
productStatusResponse.responseMsgCode Un codice standard per i messaggi di risposta del prodotto ricevuti da Privacy Service. I dettagli del messaggio sono forniti in responseMsgDetail.
productStatusResponse.responseMsgDetail Una spiegazione più dettagliata dello stato del processo. I messaggi con stati simili possono variare tra i prodotti.
productStatusResponse.results Per alcuni stati, alcuni prodotti possono restituire un results oggetto che fornisce informazioni aggiuntive non coperte responseMsgDetail.
downloadURL Se lo stato del processo è complete, questo attributo fornisce un URL per scaricare i risultati del processo come file ZIP. Questo file è disponibile per il download per 60 giorni dopo il completamento del processo.

Categorie stato processo

Nella tabella seguente sono elencate le diverse categorie possibili di stato dei job e il relativo significato:

Categoria di stato Significato
complete Il processo è completo e (se necessario) i file vengono caricati da ogni applicazione.
processing Le applicazioni hanno riconosciuto il job e sono in fase di elaborazione.
submitted Il processo viene inviato a ogni candidatura applicabile.
error Si è verificato un errore nell’elaborazione del processo. Per ottenere informazioni più specifiche, è possibile recuperare i dettagli dei singoli processi.
NOTA

Un processo inviato potrebbe rimanere in un processing stato se il processo figlio dipendente è ancora in elaborazione.

Passaggi successivi

Ora sai come creare e monitorare i processi relativi alla privacy utilizzando Privacy Service API. Per informazioni su come eseguire le stesse attività utilizzando l'interfaccia utente, vedere Panoramica dell’interfaccia utente di Privacy Service.

In questa pagina