Endpoint di scadenza del set di dati

Utilizza l'endpoint /ttl nell'API di igiene dei dati per pianificare l'eliminazione dei set di dati in Adobe Experience Platform.

La scadenza di un set di dati è un’operazione di eliminazione ritardata. Il set di dati non è protetto nel frattempo e può essere eliminato in altro modo prima della scadenza pianificata.

Prima dell’inizio dell’eliminazione, puoi annullare la scadenza o modificarne l’ora pianificata. Per riaprire una scadenza annullata, impostare una nuova scadenza.

Una volta avviata l'eliminazione, il processo di scadenza viene contrassegnato come executing e non può più essere modificato. Il set di dati può essere recuperabile per un massimo di sette giorni, ma solo tramite una richiesta manuale del servizio Adobe. Durante l’eliminazione, il data lake, Identity Service e Real-Time Customer Profile rimuovono ciascuno i contenuti del set di dati separatamente. Al termine dell'eliminazione, la scadenza viene contrassegnata come completed.

Advanced Data Lifecycle Management supporta le eliminazioni dei set di dati tramite l'endpoint di scadenza del set di dati e le eliminazioni degli ID (dati a livello di riga) tramite identità primarie tramite l'endpoint dell'ordine di lavoro. Puoi anche gestire scadenze set di dati e eliminazioni record tramite l'interfaccia utente di Experience Platform. Per ulteriori informazioni, consulta la documentazione collegata.

Introduzione

L’endpoint utilizzato in questa guida fa parte dell’API di igiene dei dati. Prima di continuare, consulta la guida API per informazioni sulle intestazioni richieste per operazioni CRUD, messaggi di errore, raccolte Postman e come leggere chiamate API di esempio.

Elenca scadenze set di dati list

È possibile elencare tutte le scadenze dei set di dati configurate per l'organizzazione effettuando una richiesta GET all'endpoint /ttl.

Filtra i risultati utilizzando i parametri di query per restituire solo le scadenze che soddisfano i criteri. Ogni risultato include lo stato e i dettagli di configurazione per ogni scadenza del set di dati.

Formato API

GET /ttl?{QUERY_PARAMETERS}

Richiesta

La richiesta seguente recupera tutte le scadenze del set di dati aggiornate prima del 1° agosto 2021 e aggiornate da ultimo da un utente il cui nome corrisponde a "Jane Doe".

curl -X GET \
  https://platform.adobe.io/data/core/hygiene/ttl?updatedToDate=2021-08-01&author=LIKE%20%25Jane%20Doe%25 \
  -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}'

Risposta

In caso di esito positivo, la risposta elenca le scadenze risultanti del set di dati. L'esempio seguente è stato troncato per motivi di spazio.

{
  "results": [
    {
      "ttlId": "SD-c9f113f2-d751-44bc-bc20-9d5ca0b6ae15",
      "datasetId": "3e9f815ae1194c65b2a4c5ea",
      "datasetName": "Acme_Profile_Engagements",
      "sandboxName": "acme-beta",
      "displayName": "Engagement Data Retention Policy",
      "description": "Scheduled expiry for Acme marketing data",
      "imsOrg": "C9D8E7F6A5B41234567890AB@AcmeOrg",
      "status": "pending",
      "expiry": "2027-01-12T17:15:31.000Z",
      "updatedAt": "2026-12-15T12:40:20.000Z",
      "updatedBy": "t.lannister@acme.com <t.lannister@acme.com> 3E9F815AE1194C65B2A4C5EA@acme.com"
    }
  ],
  "current_page": 0,
  "total_pages": 1,
  "total_count": 1
}

Cercare una scadenza del set di dati lookup

Recupera i dettagli per una specifica configurazione di scadenza del set di dati effettuando una richiesta GET con l’ID di scadenza del set di dati o l’ID del set di dati come parametro del percorso.

Formato API

GET /ttl/{ID}
GET /ttl/{ID}?include=history

Richiesta

La richiesta seguente cerca i dettagli di scadenza per il set di dati 62759f2ede9e601b63a2ee14:

curl -X GET \
  https://platform.adobe.io/data/core/hygiene/ttl/62759f2ede9e601b63a2ee14 \
  -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}'

Risposta

In caso di esito positivo, la risposta restituisce i dettagli della scadenza del set di dati.

{
    "ttlId": "SD-c8c75921-2416-4be7-9cfd-9ab01de66c5f",
    "datasetId": "62759f2ede9e601b63a2ee14",
    "datasetName": "XtVRwq9-38734",
    "sandboxName": "prod",
    "displayName": "Delete Acme Data before 2025",
    "description": "The Acme information in this dataset is licensed for our use through the end of 2024.",
    "imsOrg": "885737B25DC460C50A49411B@AdobeOrg",
    "status": "pending",
    "expiry": "2035-09-25T00:00:00Z",
    "updatedAt": "2025-05-01T19:00:55.000Z",
    "updatedBy": "Jane Doe <jdoe@adobe.com> 77A51F696282E48C0A494 012@64d18d6361fae88d49412d.e",
}

Tag di scadenza del catalogo

Quando si utilizza l'API catalogo per cercare i dettagli del set di dati, se il set di dati ha una scadenza attiva verrà elencato in tags.adobe/hygiene/ttl.

Il seguente JSON mostra una risposta Catalog API troncata per un set di dati con valore di scadenza 32503680000000. Il tag codifica la scadenza come il numero di millisecondi trascorsi dall’epoca Unix.

{
  "63212313c308d51b997858ba": {
    "name": "Test Dataset",
    "description": "A piecrust promise, made to be broken",
    "imsOrg": "0FCC747E56F59C747F000101@AdobeOrg",
    "sandboxId": "8dc51b90-d0f9-11e9-b164-ed6a398c8b35",
    "tags": {
      "adobe/hygiene/ttl": [ "32503680000000" ],
      ...
    },
    ...
  }
}

Creare una scadenza del set di dati create

Crea una nuova configurazione di scadenza del set di dati per definire quando scadrà un set di dati e se sarà idoneo per l’eliminazione.
Fornisci l’ID del set di dati, la data di scadenza o la data-ora (nel formato ISO 8601), un nome visualizzato e (facoltativamente) una descrizione.

Per creare una scadenza del set di dati, invia una richiesta POST come mostrato di seguito.

Formato API

POST /ttl

Richiesta

curl -X POST \
  https://platform.adobe.io/data/core/hygiene/ttl \
  -H 'Authorization: Bearer {ACCESS_TOKEN}' \
  -H 'x-gw-ims-org-id: {ORG_ID}' \
  -H 'x-api-key: {API_KEY}' \
  -H 'x-sandbox-name: {SANDBOX_NAME}' \
  -H 'Content-Type: application/json' \
  -d '{
        "datasetId": "3e9f815ae1194c65b2a4c5ea",
        "expiry": "2030-12-31",
        "displayName": "Expiry rule for Acme customers",
        "description": "Set expiration for Acme customer dataset"
      }'

Risposta

In caso di esito positivo, la risposta restituisce lo stato HTTP 201 (Creato) e la nuova configurazione di scadenza del set di dati.

{
  "ttlId": "SD-2aaf113e-3f17-4321-bf29-a2c51152b042",
  "datasetId": "3e9f815ae1194c65b2a4c5ea",
  "datasetName": "Acme_Customer_Data",
  "sandboxName": "acme-prod",
  "displayName": "Expiry rule for Acme customers",
  "description": "Set expiration for Acme customer dataset",
  "imsOrg": "{ORG_ID}",
  "status": "pending",
  "expiry": "2030-12-31T00:00:00Z",
  "updatedAt": "2025-01-02T10:35:45.000Z",
  "updatedBy": "s.stark@acme.com <s.stark@acme.com> 3E9F815AE1194C65B2A4C5EA@acme.com"
}

Se per il set di dati esiste già una scadenza, si verifica uno stato HTTP 400 (richiesta non valida). Lo stato HTTP 404 (Non trovato) si verifica se non esiste un set di dati o se non si dispone dell’accesso al set di dati.

Aggiornare una configurazione di scadenza del set di dati update

Per aggiornare una configurazione di scadenza di un set di dati esistente, effettuare una richiesta PUT a /ttl/DATASET_EXPIRATION_ID. È possibile aggiornare solo i campi displayName, description e expiry della configurazione. Gli aggiornamenti sono consentiti solo quando lo stato di scadenza è pending.

Formato API

PUT /ttl/{DATASET_EXPIRATION_ID}

Richiesta

La richiesta seguente aggiorna la scadenza, il nome visualizzato e la descrizione per la scadenza del set di dati SD-c1f902aa-57cb-412e-bb2b-c70b8e1a5f45:

curl -X PUT \
  https://platform.adobe.io/data/core/hygiene/ttl/SD-c1f902aa-57cb-412e-bb2b-c70b8e1a5f45 \
  -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}' \
  -H 'Content-Type: application/json' \
  -d '{
        "displayName": "Customer Dataset Expiry Rule",
        "description": "Updated description for Acme customer dataset",
        "expiry": "2031-06-15"
      }'

Risposta

In caso di esito positivo, la risposta restituisce lo stato HTTP 200 (OK) e la configurazione di scadenza del set di dati aggiornata.

{
  "ttlId": "SD-c1f902aa-57cb-412e-bb2b-c70b8e1a5f45",
  "datasetId": "3e9f815ae1194c65b2a4c5ea",
  "datasetName": "Acme_Customer_Data",
  "sandboxName": "acme-prod",
  "displayName": "Customer Dataset Expiry Rule",
  "description": "Updated description for Acme customer dataset",
  "imsOrg": "C9D8E7F6A5B41234567890AB@AcmeOrg",
  "status": "pending",
  "expiry": "2031-06-15T00:00:00Z",
  "updatedAt": "2031-05-01T14:11:12.000Z",
  "updatedBy": "b.tarth@acme.com <b.tarth@acme.com> 3E9F815AE1194C65B2A4C5EA@acme.com"
}

In caso di esito negativo, la risposta restituisce lo stato HTTP 404 (Non trovato) se non esiste una scadenza del set di dati.

Annullare la scadenza di un set di dati delete

Annullare una configurazione di scadenza di un set di dati in sospeso effettuando una richiesta DELETE a /ttl/{ID}.

Formato API

DELETE /ttl/{ID}

Richiesta

La richiesta seguente annulla la scadenza di un set di dati con ID SD-d4a7d918-283b-41fd-bfe1-4e730a613d21:

curl -X DELETE \
  https://platform.adobe.io/data/core/hygiene/ttl/SD-d4a7d918-283b-41fd-bfe1-4e730a613d21 \
  -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}'

Risposta

In caso di esito positivo, la risposta restituisce lo stato HTTP 200 (OK) e la configurazione della scadenza del set di dati annullata. L'attributo status della scadenza non è impostato su cancelled.

{
  "ttlId": "SD-d4a7d918-283b-41fd-bfe1-4e730a613d21",
  "datasetId": "5a9e2c68d3b24f03b55a91ce",
  "datasetName": "Acme_Customer_Data",
  "sandboxName": "acme-prod",
  "displayName": "Customer Dataset Expiry Rule",
  "description": "Cancelled expiry configuration for Acme customer dataset",
  "imsOrg": "C9D8E7F6A5B41234567890AB@AcmeOrg",
  "status": "cancelled",
  "expiry": "2032-02-28T00:00:00Z",
  "updatedAt": "2032-01-15T08:27:31.000Z",
  "updatedBy": "s.clegane@acme.com <s.clegane@acme.com> 5A9E2C68D3B24F03B55A91CE@acme.com"
}

Esempio di risposta 400 (richiesta non valida)

Errore 400 durante il tentativo di annullare un set di dati con una configurazione di scadenza executing, completed o cancelled.

{
  "type": "http://ns.adobe.com/aep/errors/HYGN-3102-400",
  "title": "The requested dataset already has an existing expiration. Additional detail: A TTL already exists for datasetId=686e9ca25ef7462aefe72c93",
  "status": 400,
  "report": {
    "tenantInfo": {
      "sandboxName": "prod",
      "sandboxId": "not-applicable",
      "imsOrgId": "{IMS_ORG_ID}"
    },
    "additionalContext": {
      "Invoking Client ID": "acp_privacy_hygiene"
    }
  },
  "error-chain": [
    {
      "serviceId": "HYGN",
      "errorCode": "HYGN-3102-400",
      "invokingServiceId": "acp_privacy_hygiene",
      "unixTimeStampMs": 1754408150394
    }
  ]
}

Appendice

Parametri di query accettati query-params

La tabella seguente illustra i parametri di query disponibili quando si elencano le scadenze dei set di dati: