データセットの有効期限エンドポイント
Data Hygiene APIの/ttl エンドポイントを使用して、Adobe Experience Platformのデータセットを削除するタイミングをスケジュールします。
データセットの有効期限は、遅延削除操作です。 データセットは暫定的に保護されず、スケジュールされた有効期限の前に他の方法で削除される可能性があります。
削除を開始する前に、有効期限をキャンセルしたり、スケジュールされた時間を変更したりできます。 キャンセルされた有効期限を再度開くには、新しい有効期限を設定します。
削除が開始されると、有効期限ジョブはexecutingとしてマークされ、変更できなくなります。 このデータセットは、最大7日間回復可能ですが、手動でのAdobe サービスリクエストによってのみ可能です。 削除中、データレイク、ID サービス、リアルタイム顧客プロファイルは、それぞれデータセットの内容を個別に削除します。 削除が完了すると、有効期限はcompletedとしてマークされます。
高度なデータライフサイクル管理では、データセットの有効期限エンドポイントを介したデータセットの削除と、workorder エンドポイント を介したプライマリ IDを使用したIDの削除(行レベルのデータ)をサポートしています。 また、Experience Platform UIを使用して、 データセットの有効期限および レコードの削除を管理することもできます。 詳しくは、リンクされたドキュメントを参照してください。
はじめに
このガイドで使用するエンドポイントは、Data Hygiene API の一部です。続行する前に、CRUD操作に必要なヘッダー、エラーメッセージ、Postman コレクション、サンプル API呼び出しの読み取り方法について、API ガイド を確認してください。
x-sandbox-name: {SANDBOX_NAME} ヘッダーを使用する必要があります。データセット有効期限のリスト list
/ttl エンドポイントに対してGET リクエストを行うことで、組織に設定されたすべてのデータセット有効期限を一覧表示できます。
クエリパラメーターを使用して結果をフィルタリングし、条件を満たす有効期限のみを返します。 各結果には、各データセットの有効期限のステータスと設定の詳細が含まれます。
API 形式
GET /ttl?{QUERY_PARAMETERS}
{QUERY_PARAMETERS}& 文字で区切られた複数のパラメーターを含む、オプションのクエリパラメーターのリスト。共通のパラメーターには、ページネーション用の limit および page があります。サポートされているクエリパラメーターの完全なリストについては、付録セクション サポートされているクエリパラメーターの完全なリストを参照してください。 最も一般的に使用されるパラメーターは、以下に含まれています。また、付録にも含まれています。authorLIKE %john%)。datasetIddatasetNamestatuspending、executing、cancelled、completed。expiryDatelimitpageリクエスト
次のリクエストは、2021年8月1日より前に更新され、名前が「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}'
応答
応答が成功すると、結果のデータセット有効期限がリスト表示されます。次の例は、スペースを節約するために省略されています。
ttlIdは{DATASET_EXPIRATION_ID}とも呼ばれます。 どちらも、データセットの有効期限の一意の識別子を参照します。{
"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
}
resultsttlIddatasetIddatasetNamesandboxNamedisplayNamedescriptionimsOrgstatuspending、executing、cancelled、completedのいずれか。expiryupdatedAtupdatedBycurrent_pagetotal_pagestotal_countデータセット有効期限の検索 lookup
データセットの有効期限IDまたはデータセット IDをパスパラメーターとして使用してGET リクエストを行うことで、特定のデータセットの有効期限の設定の詳細を取得します。
SD-xxxxxx-xxxx)またはデータセット IDをパスに指定できます。 応答のttlIdは、データセットの有効期限の一意の識別子です。API 形式
GET /ttl/{ID}
GET /ttl/{ID}?include=history
{ID}includehistoryに設定されている場合、応答には、設定の変更イベントを含むhistory配列が含まれます。リクエスト
次のリクエストでは、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}'
応答
応答が成功すると、データセット有効期限の詳細が返されます。
{
"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",
}
ttlIddatasetIddatasetNamesandboxNamedisplayNamedescriptionimsOrgstatusいずれかの:
pending、executing、cancelled、completed。expiryupdatedAtupdatedByカタログの有効期限タグ
Catalog API を使用してデータセットの詳細を検索するには、データセットにアクティブな有効期限がある場合は、そのデータセットが tags.adobe/hygiene/ttl の下に表示されます。
次のJSONは、有効期限が32503680000000のデータセットに対する切り捨てられたカタログ API応答を示しています。 タグは、有効期限を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" ],
...
},
...
}
}
データセット有効期限の作成 create
新しいデータセット有効期限の設定を作成して、データセットがいつ期限切れになり、削除の対象になるかを定義します。
データセット ID、有効期限または日時(ISO 8601形式)、表示名、および(オプションで)説明を入力します。
データセットの有効期限を作成するには、次に示すようにPOST リクエストを送信します。
API 形式
POST /ttl
リクエスト
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"
}'
datasetIdexpiry必須。 ISO 8601形式の有効期限の日時。 これにより、システム内のデータの有効期間が定義されます。 日付のみが指定されている場合、デフォルトはUTCの午前0時(00:00:00Z)になります。 有効期限は、今後24時間以上である必要があります。
メモ:
- データセットの有効期限が既に存在する場合、リクエストは失敗します。
displayNamedescription応答
応答が成功すると、HTTP 201 (作成済み)ステータスと新しいデータセット有効期限の設定が返されます。
{
"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"
}
ttlIddatasetIddatasetNamesandboxNamedisplayNamedescriptionimsOrgstatusいずれかの:
pending、executing、cancelled、completed。expiryupdatedAtupdatedByデータセットの有効期限が既に存在する場合、400 (不正なリクエスト) HTTP ステータスが発生します。 404 (見つかりません) HTTP ステータスは、そのようなデータセットが存在しないか、データセットにアクセスできない場合に発生します。
データセットの有効期限の設定を更新する update
既存のデータセット有効期限の設定を更新するには、PUT リクエストを/ttl/DATASET_EXPIRATION_IDに行います。 設定のdisplayName、descriptionおよびexpiry フィールドのみを更新できます。 更新は、有効期限ステータスがpendingの場合にのみ許可されます。
expiry フィールドには、日付(YYYY-MM-DD)または日時(YYYY-MM-DDTHHSSZ)を入力できます。 日付のみが指定された場合、システムはその日の午前0時UTC (00:00:00Z)を使用します。 有効期限は、今後24時間以上である必要があります。API 形式
PUT /ttl/{DATASET_EXPIRATION_ID}
{DATASET_EXPIRATION_ID}ttlIdと呼ばれます。リクエスト
次のリクエストは、データセットの有効期限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"
}'
displayNamedescriptionexpiry応答
応答が成功すると、HTTP ステータス 200 (OK)と更新されたデータセット有効期限の設定が返されます。
{
"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"
}
ttlIddatasetIddatasetNamesandboxNamedisplayNamedescriptionimsOrgstatusいずれかの:
pending、executing、cancelled、completed。expiryupdatedAtupdatedByこのようなデータセットの有効期限が存在しない場合、応答が失敗すると、404 (見つかりません) HTTP ステータスが返されます。
データセット有効期限のキャンセル delete
保留中のデータセットの有効期限の設定をキャンセルするには、/ttl/{ID}に対してDELETE リクエストを行います。
pending ステータスのデータセット有効期限のみです。 既にexecuting、completedまたはcancelledにある有効期限をキャンセルしようとすると、HTTP 400 (不正なリクエスト)が返されます。API 形式
DELETE /ttl/{ID}
{ID}リクエスト
次のリクエストでは、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}'
応答
応答が成功すると、HTTP ステータス 200 (OK)とキャンセルされたデータセットの有効期限の設定が返されます。 有効期限のstatus属性が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"
}
ttlIddatasetIddatasetNamesandboxNamedisplayNamedescriptionimsOrgstatusいずれかの:
pending、executing、cancelled、completed。expiryupdatedAtupdatedBy400 (不正なリクエスト)応答の例
有効期限がexecuting、completed、またはcancelledの設定を持つデータセットをキャンセルしようとすると、400 エラーが発生します。
{
"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
}
]
}
completedまたはcancelledにあるデータセットの有効期限をキャンセルしようとすると、404 エラーが発生します。付録
承認されたクエリパラメーター query-params
次の表では、データセット有効期限をリスト表示する際に使用できるクエリパラメーターを説明します。
description、displayNameおよびdatasetNameのパラメーターには、すべてLIKE値で検索する機能が含まれています。 つまり、「Name1」という文字列を検索すると、「Name123」、「Name183」、「DisplayName1234」という名前のスケジュールされたデータセットの有効期限を見つけることができます。authorauthor クエリパラメーターを使用して、データセットの有効期限を最近更新したユーザーを検索します。 作成後に更新が行われていない場合は、有効期限の元の作成者と一致します。 このパラメーターは、created_by フィールドが検索文字列に対応する有効期限と一致します。検索文字列が
LIKEまたはNOT LIKEで始まる場合、残りはSQL検索パターンとして扱われます。 それ以外の場合は、検索文字列全体が、created_by フィールドのコンテンツ全体に完全に一致する必要があるリテラル文字列として扱われます。author=LIKE %john%, author=John Q. PublicdatasetIddatasetId=62b3925ff20f8e1b990a7434datasetNamedatasetName=Acmedescriptiondescription=Handle expiration of Acme information through the end of 2024.displayNamedisplayName=License ExpiryexecutedDate/executedFromDate/executedToDateexecutedDate=2023-02-05T19:34:40.383615ZexpiryDate2024-01-01expiryToDate または expiryFromDateexpiryFromDate=2099-01-01&expiryToDate=2100-01-01limitlimit=50orderByorderBy クエリパラメーターは、APIによって返される結果の並べ替え順序を指定します。 ASC (昇順)またはDESC (降順)の1つ以上のフィールドに基づいてデータを配置する場合に使用します。 ASCとDESCをそれぞれ表すには、「+」または「 – 」プレフィックスを使用します。 次の値を使用できます:displayName、description、datasetName、id、updatedBy、updatedAt、expiry、status。-datasetNameorgIdx-gw-ims-org-id ヘッダーの値となり、リクエストがサービストークンを提供しない限り無視されます。orgId=885737B25DC460C50A49411B@AdobeOrgpagepage=3sandboxNamex-sandbox-name ヘッダーにあるサンドボックス名です。sandboxName=* を使用して、すべてのサンドボックスからデータセット有効期限を含めます。sandboxName=dev1search指定された文字列が有効期限IDと完全に一致するか、次のいずれかのフィールドに contained が含まれている場合、有効期限に一致します:
- 作成者
- 表示名
- description
- 表示名
- データセット名
search=TESTINGstatusstatus=pending,cancelledttlIdttlID=SD-c8c75921-2416-4be7-9cfd-9ab01de66c5fupdatedDate2024-01-01updatedToDate または updatedFromDate有効期限は、作成時、キャンセル時、実行時を含め、編集されるたびに更新されたと見なされます。
updatedDate=2022-01-01