Ponto de extremidade de expiração do conjunto de dados

Use o ponto de extremidade /ttl na API de higiene de dados para agendar quando os conjuntos de dados na Adobe Experience Platform devem ser excluídos.

A expiração de um conjunto de dados é uma operação de exclusão atrasada. O conjunto de dados não é protegido enquanto isso e pode ser excluído por outros meios antes da expiração programada.

Antes de começar a exclusão, você pode cancelar a expiração ou alterar o horário agendado. Para reabrir uma expiração cancelada, defina uma nova expiração.

Depois que a exclusão começar, o trabalho de expiração será marcado como executing e não poderá mais ser modificado. O conjunto de dados pode ser recuperado por até sete dias, mas somente por meio de uma solicitação de serviço manual da Adobe. Durante a exclusão, o data lake, o Serviço de identidade e o Perfil do cliente em tempo real removem separadamente o conteúdo do conjunto de dados. Quando a exclusão for concluída, a expiração será marcada como completed.

O Gerenciamento avançado do ciclo de vida dos dados suporta exclusões de conjuntos de dados por meio do ponto de extremidade de expiração do conjunto de dados e exclusões de ID (dados em nível de linha) usando identidades primárias por meio do ponto de extremidade da ordem de trabalho. Também é possível gerenciar expirações do conjunto de dados e exclusões de registros por meio da interface do usuário do Experience Platform. Consulte a documentação vinculada para obter mais informações.

Introdução

O endpoint usado neste guia faz parte da API de higiene de dados. Antes de continuar, consulte o Guia de API para obter informações sobre cabeçalhos necessários para operações CRUD, mensagens de erro, coleções do Postman e como ler chamadas de API de exemplo.

Listar expirações do conjunto de dados list

Você pode listar todas as expirações de conjunto de dados configuradas para sua organização fazendo uma solicitação GET para o ponto de extremidade /ttl.

Filtrar resultados usando parâmetros de consulta para retornar somente as expirações que atendem aos seus critérios. Cada resultado inclui detalhes de status e configuração para cada expiração do conjunto de dados.

Formato da API

GET /ttl?{QUERY_PARAMETERS}

Solicitação

A solicitação a seguir recupera todas as expirações do conjunto de dados atualizadas antes de 1º de agosto de 2021 e atualizadas pela última vez por um usuário cujo nome corresponda 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}'

Resposta

Uma resposta bem-sucedida lista as expirações do conjunto de dados resultantes. O exemplo a seguir foi truncado por questões de espaço.

{
  "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
}

Pesquisar uma expiração de conjunto de dados lookup

Recupere os detalhes de uma configuração específica de expiração do conjunto de dados fazendo uma solicitação do GET com a ID de expiração do conjunto de dados ou a ID do conjunto de dados como o parâmetro de caminho.

Formato da API

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

Solicitação

A solicitação a seguir pesquisa os detalhes de expiração do conjunto de dados 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}'

Resposta

Uma resposta bem-sucedida retorna os detalhes da expiração do conjunto de dados.

{
    "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",
}

Tags de expiração de catálogo

Ao usar a API do catálogo para pesquisar detalhes do conjunto de dados, se o conjunto de dados tiver uma expiração ativa, ele será listado em tags.adobe/hygiene/ttl.

O JSON a seguir mostra uma resposta de API de catálogo truncada para um conjunto de dados com um valor de expiração de 32503680000000. A tag codifica a expiração como o número de milissegundos desde a época do 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" ],
      ...
    },
    ...
  }
}

Criar uma expiração de conjunto de dados create

Crie uma nova configuração de expiração do conjunto de dados para definir quando um conjunto de dados expirará e estará qualificado para exclusão.
Forneça a ID do conjunto de dados, a data de expiração ou a data-hora (no formato ISO 8601), um nome de exibição e (opcionalmente) uma descrição.

Para criar uma expiração do conjunto de dados, envie uma solicitação POST, como mostrado abaixo.

Formato da API

POST /ttl

Solicitação

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

Resposta

Uma resposta bem-sucedida retorna um status HTTP 201 (Criado) e a nova configuração de expiração do conjunto de dados.

{
  "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"
}

Um status HTTP 400 (Solicitação inválida) ocorre se a expiração de um conjunto de dados já existir para o conjunto de dados. Um status HTTP 404 (Não encontrado) ocorre se esse conjunto de dados não existir ou se você não tiver acesso ao conjunto de dados.

Atualizar uma configuração de expiração do conjunto de dados update

Para atualizar uma configuração de expiração de conjunto de dados existente, faça uma solicitação PUT para /ttl/DATASET_EXPIRATION_ID. Você só pode atualizar os campos displayName, description e expiry da configuração. Atualizações só são permitidas quando o status de expiração é pending.

Formato da API

PUT /ttl/{DATASET_EXPIRATION_ID}

Solicitação

A solicitação a seguir atualiza a expiração, o nome de exibição e a descrição da expiração do conjunto de dados 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"
      }'

Resposta

Uma resposta bem-sucedida retorna o status HTTP 200 (OK) e a configuração de expiração do conjunto de dados atualizada.

{
  "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"
}

Uma resposta sem sucesso retornará um status HTTP 404 (Não encontrado) se essa expiração de conjunto de dados não existir.

Cancelar a expiração de um conjunto de dados delete

Cancele uma configuração de expiração pendente do conjunto de dados fazendo uma solicitação DELETE para /ttl/{ID}.

Formato da API

DELETE /ttl/{ID}

Solicitação

A solicitação a seguir cancela uma expiração do conjunto de dados com a 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}'

Resposta

Uma resposta bem-sucedida retorna o status HTTP 200 (OK) e a configuração de expiração do conjunto de dados cancelado. Observe que o atributo status da expiração está definido como 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"
}

Exemplo de resposta 400 (Solicitação inválida)

Erro 400 ao tentar cancelar um conjunto de dados com uma configuração de expiração de executing, completed ou 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
    }
  ]
}

Apêndice

Parâmetros de consulta aceitos query-params

A tabela a seguir descreve os parâmetros de consulta disponíveis ao listar expirações do conjunto de dados: