隱私權工作端點

本檔案涵蓋如何使用API呼叫的隱私權工作。 具體來說,它涵蓋Privacy Service API中/job端點的使用。 在閱讀本指南之前,請參閱快速入門章節,以取得成功呼叫API所需的重要資訊,包括必要的標題和如何讀取範例API呼叫。

注意

如果您嘗試管理客戶的同意或選擇退出請求,請參閱同意端點指南

列出所有作業

您可以向/jobs端點提出GET請求,以檢視組織內所有可用隱私權工作的清單。

API格式

此請求格式在/jobs端點上使用regulation查詢參數,因此它以問號(?)開頭,如下所示。 回應會編頁,讓您使用其他查詢參數(pagesize)來篩選回應。 您可以使用&符號(&)來分隔多個參數。

GET /jobs?regulation={REGULATION}
GET /jobs?regulation={REGULATION}&page={PAGE}
GET /jobs?regulation={REGULATION}&size={SIZE}
GET /jobs?regulation={REGULATION}&page={PAGE}&size={SIZE}
參數 說明
{REGULATION} 要查詢的規則類型。 接受的值包括:
  • gdpr (歐盟)
  • ccpa (加州)
  • lgpd_bra (巴西)
  • nzpa_nzl (紐西蘭)
  • pdpa_tha (泰國)
{PAGE} 要顯示的資料頁,使用基於0的編號。 預設值為 0
{SIZE} 每個頁面上要顯示的結果數。 預設值為1 ,最大值為100。 超過最大值會導致API傳回400碼錯誤。

要求

下列請求會從頁面大小為50的第三頁開始,擷取IMS組織內所有工作的編頁清單。

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: {IMS_ORG}'

回應

成功的響應返回作業清單,每個作業都包含詳細資訊,如jobId。 在此範例中,回應將包含50個工作的清單,從結果的第三頁開始。

存取後續頁面

若要在編頁回應中擷取下一組結果,您必須對相同端點進行另一個API呼叫,同時將page查詢參數增加1。

建立隱私權工作

在建立新工作請求之前,您必須先收集您要存取、刪除或選擇退出銷售之資料主體的相關識別資訊。 在您取得所需資料後,必須在/jobs端點之POST要求的裝載中提供該資料。

注意

相容的Adobe Experience Cloud應用程式使用不同的值來識別資料主體。 有關應用程式所需標識符的詳細資訊,請參閱Privacy Service和Experience Cloud應用程式上的指南。 如需決定要傳送至Privacy Service的ID的更一般指引,請參閱隱私權要求中關於身分資料的檔案

Privacy Service API支援兩種個人資料的工作要求:

重要

雖然存取和刪除請求可合併為單一API呼叫,但必須個別提出退出請求。

建立訪問/刪除作業

本節說明如何使用API進行存取/刪除工作請求。

API格式

POST /jobs

要求

下列請求會建立新的工作請求,由裝載中提供的屬性設定,如下所述。

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: {IMS_ORG}' \
  -d '{
    "companyContexts": [
      {
        "namespace": "imsOrgID",
        "value": "{IMS_ORG}"
      }
    ],
    "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"],
    "expandIds": false,
    "priority": "normal",
    "analyticsDeleteMethod": "anonymize",
    "regulation": "ccpa"
}'
屬性 說明
companyContexts (必填) 包含貴組織驗證資訊的陣列。 每個列出的識別碼都包含下列屬性:
  • namespace:識別碼的名稱空間。
  • value:識別碼的值。
其中一個識別碼使用imsOrgId作為namespace,其value包含IMS組織的唯一ID,這是​required

其他識別碼可以是特定於產品的公司限定詞(例如 Campaign),用於標識與屬於您組織的Adobe應用程式的整合。潛在值包括帳戶名稱、用戶端代碼、租用戶ID或其他應用程式識別碼。
users (必填) 包含至少一個用戶集合的陣列,您希望訪問或刪除其資訊。 在單一請求中最多可提供1000個使用者ID。 每個用戶對象都包含以下資訊:
  • key:用於用戶的標識符,用於限定響應資料中的單獨作業ID。為此值選擇唯一、可輕鬆識別的字串是最佳實務,以便日後輕鬆參考或查閱。
  • action:列出對用戶資料採取所需操作的陣列。根據您要執行的操作,此陣列必須包括accessdelete或兩者。
  • userIDs:使用者身分的集合。單一使用者可擁有的身分數目限制為9。 每個身分都由namespacevalue和命名空間限定詞(type)組成。 如需這些必要屬性的詳細資訊,請參閱附錄
如需usersuserIDs的詳細說明,請參閱疑難排解指南
include (必填) 要包含在您處理中的一系列Adobe產品。 如果此值遺失或空白,則會拒絕請求。 僅包含貴組織已整合的產品。 如需詳細資訊,請參閱附錄中接受的產品值一節。
expandIDs 當設為true時,此選用屬性代表處理應用程式中ID的最佳化(目前僅Analytics支援)。 若省略,此值預設為false
priority Adobe Analytics使用的可選屬性,可設定處理請求的優先順序。 接受的值為normallow。 如果省略priority,則預設行為為normal
analyticsDeleteMethod 可選屬性,指定Adobe Analytics如何處理個人資料。 此屬性接受兩個可能的值:
  • anonymize:指定使用者ID集合所參考的所有資料都會設為匿名。如果省略analyticsDeleteMethod,則此為預設行為。
  • purge:所有資料都會完全移除。
regulation (必填) 隱私權工作的法規。 接受下列值:
  • gdpr (歐盟)
  • ccpa (加州)
  • lgpd_bra (巴西)
  • nzpa_nzl (紐西蘭)
  • pdpa_tha (泰國)

回應

成功的回應會傳回新建立之工作的詳細資料。

{
    "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
}
屬性 說明
jobId 作業的唯讀唯一系統產生的ID。 此值用於查找特定作業的下一步。

成功提交作業請求後,您可以繼續下一步檢查作業狀態

檢查作業的狀態

通過將特定作業的jobId包含在到/jobs端點的GET請求路徑中,可以檢索有關該作業的資訊,如其當前處理狀態。

重要

先前建立的作業的資料僅在作業完成日期的30天內可供檢索。

API格式

GET /jobs/{JOB_ID}
參數 說明
{JOB_ID} 您要查詢的工作ID。 此ID在建立工作列出所有工作的成功API回應中傳回在jobId下。

要求

以下請求將檢索在請求路徑中提供jobId的作業的詳細資訊。

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: {IMS_ORG}'

回應

成功的回應會傳回指定工作的詳細資料。

{
    "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"
}
屬性 說明
productStatusResponse productResponses陣列中的每個對象都包含有關特定Experience Cloud應用程式的作業當前狀態的資訊。
productStatusResponse.status 作業的當前狀態類別。 有關可用狀態類別及其對應含義的清單,請參見下表。
productStatusResponse.message 作業的特定狀態,對應於狀態類別。
productStatusResponse.responseMsgCode Privacy Service收到之產品回應訊息的標準程式碼。 消息的詳細資訊在responseMsgDetail下提供。
productStatusResponse.responseMsgDetail 對工作狀態的更詳細說明。 類似狀態的訊息可能會因產品而異。
productStatusResponse.results 對於某些狀態,某些產品可能會傳回results物件,提供responseMsgDetail未涵蓋的其他資訊。
downloadURL 如果作業的狀態為complete,此屬性會提供URL,以ZIP檔案形式下載作業結果。 此檔案可在工作完成後60天內下載。

作業狀態類別

下表列出了不同的可能作業狀態類別及其對應含義:

狀態類別 意義
complete 工作已完成,而且(如果需要)檔案會從每個應用程式上傳。
processing 應用程式已確認作業,並且正在處理。
submitted 工作會提交至每個適用的應用程式。
error 處理作業時發生故障——檢索單個作業詳細資訊可以獲得更具體的資訊。
注意

如果提交的作業具有仍在處理的從屬子作業,則該作業可能仍處於processing狀態。

後續步驟

您現在知道如何使用Privacy Service API來建立和監控隱私權工作。 有關如何使用用戶介面執行相同任務的資訊,請參閱Privacy ServiceUI概述

本頁內容