文档 Experience Platform Privacy Service 指南

隐私作业端点

Last update: Fri Nov 08 2024 00:00:00 GMT+0000 (Coordinated Universal Time)

主题：

创建对象：

开发人员

本文档介绍如何使用API调用处理隐私作业。具体来说，它涵盖Privacy Service API中/job端点的使用。在阅读本指南之前，请参阅入门指南以了解成功调用API所需了解的重要信息，包括所需的标头以及如何阅读示例API调用。

NOTE

如果您尝试管理客户的同意或选择退出请求，请参阅同意端点指南。

列出所有作业 list

通过向/jobs端点发出GET请求，可查看组织内所有可用隐私作业的列表。

API格式

此请求格式在/jobs端点上使用regulation查询参数，因此它以问号(?)开头，如下所示。在列出资源时，Privacy ServiceAPI最多返回1000个作业并分页响应。使用其他查询参数（page、size和日期筛选器）筛选响应。可以使用&符号(&)分隔多个参数。

TIP

使用其他查询参数进一步筛选特定查询的结果。例如，您可以使用status、fromDate和toDate查询参数来发现给定时间段内提交的隐私作业数量及其状态。

GET /jobs?regulation={REGULATION}
GET /jobs?regulation={REGULATION}&page={PAGE}
GET /jobs?regulation={REGULATION}&size={SIZE}
GET /jobs?regulation={REGULATION}&page={PAGE}&size={SIZE}
GET /jobs?regulation={REGULATION}&fromDate={FROMDATE}&toDate={TODATE}&status={STATUS}

参数

描述

{REGULATION}

要查询的法规类型。接受的值包括：

apa_aus
ccpa
cpa_usa
cpra_usa
ctdpa_usa
dpdpa
fdbr_usa
gdpr
hipaa_usa
icdpa_usa
lgpd_bra
mcdpa_usa
mhmda_usa
ndpa_usa
nhpa_usa
njdpa_usa
nzpa_nzl
ocpa_usa
pdpa_tha
ql25
tdpsa_usa
ucpa_usa
vcdpa_usa

有关上述值表示的隐私法规的更多信息，请参阅支持的法规概述。

{PAGE}

要显示的数据页面，使用基于0的编号。默认值为 0。

{SIZE}

每页上显示的结果数。默认值为100，最大值为1000。超过最大值会导致API返回400代码错误。

{status}

默认行为是包括所有状态。如果指定状态类型，则请求将仅返回与该状态类型匹配的隐私作业。接受的值包括：

processing
complete
error

{toDate}

此参数将结果限制为指定日期之前处理的结果。从发出请求之日起，系统回顾时间可达45天。但是，范围不能超过30天。
它接受YYYY-MM-DD格式。您提供的日期将解释为以格林威治标准时间(GMT)表示的终止日期。
如果未提供此参数（以及相应的fromDate），则默认行为将返回过去七天中返回数据的作业。如果您使用toDate，则还必须使用fromDate查询参数。如果不同时使用这两个参数，调用将返回400错误。

{fromDate}

此参数将结果限制为指定日期后处理的结果。从发出请求之日起，系统回顾时间可达45天。但是，范围不能超过30天。
它接受YYYY-MM-DD格式。您提供的日期将解释为以格林威治标准时间(GMT)表示的请求来源日期。
如果未提供此参数（以及相应的toDate），则默认行为将返回过去七天中返回数据的作业。如果您使用fromDate，则还必须使用toDate查询参数。如果不同时使用这两个参数，调用将返回400错误。

{filterDate}

此参数将结果限制为指定日期处理的结果。它接受YYYY-MM-DD格式。系统可以回顾过去45天。

请求

以下请求检索组织内所有作业的分页列表，从页面大小为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}'

响应

成功的响应将返回作业列表，每个作业都包含详细信息，如其jobId。在此示例中，响应将包含一个50个作业的列表，从结果的第三页开始。

访问后续页面

要在分页响应中获取下一组结果，您必须对同一端点进行另一个API调用，同时将page查询参数增加1。

创建隐私作业 create-job

IMPORTANT

Privacy Service仅适用于数据主体和消费者权利请求。不支持或允许将Privacy Service用于数据清理或维护。 Adobe有及时履行这些义务的法律义务。因此，不允许对Privacy Service进行负载测试，因为它是仅用于生产的环境，并会创建有效隐私请求的不必要积压。

现已设定每日硬性上传限制，以防止滥用服务。发现滥用系统的用户将禁用其对该服务的访问权限。随后将与他们举行一次会议，讨论他们的行动并讨论可接受的Privacy Service用途。

在创建新的作业请求之前，必须首先收集有关要访问、删除或选择退出销售其数据的数据主体的标识信息。获得所需数据后，必须在POST请求的有效负载中将其提供给/jobs端点。

NOTE

兼容的Adobe Experience Cloud应用程序使用不同的值来标识数据主体。有关应用程序所需标识符的更多信息，请参阅Privacy Service和Experience Cloud应用程序指南。有关确定将哪些ID发送到Privacy Service的更一般的指导，请参阅隐私请求🔗中有关身份数据的文档。

Privacy Service API支持两种针对个人数据的作业请求：

访问和/或删除：访问（读取）或删除个人数据。
选择退出销售：将个人数据标记为不出售。

IMPORTANT

虽然访问和删除请求可以作为单个API调用进行组合，但必须单独发出选择退出请求。

创建访问/删除作业 access-delete

此部分演示了如何使用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: {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",
    "mergePolicyId": 124,
    "regulation": "ccpa"
}'

属性

描述

companyContexts （必需）

包含您组织的身份验证信息的数组。列出的每个标识符都包含以下属性：

namespace：标识符的命名空间。
value：标识符的值。

必需，其中一个标识符使用imsOrgId作为其namespace，其value包含您组织的唯一ID。

其他标识符可以是产品特定的公司限定符（例如，Campaign），用于标识与属于您组织的Adobe应用程序的集成。潜在值包括帐户名称、客户端代码、租户ID或其他应用程序标识符。

users （必需）

一个数组，其中包含您要访问或删除其信息的至少一个用户的集合。单个请求最多可提供1000个用户。每个用户对象包含以下信息：

key：用于限定响应数据中各个作业ID的用户的标识符。最好为此值选择一个唯一的、易于识别的字符串，以便稍后可以轻松引用或查找。
action：一个数组，列出了要对用户数据执行的所需操作。根据您要执行的操作，此数组必须包括access和/或delete。
userIDs：用户的标识集合。单个用户可以拥有的身份数限制为9个。每个标识都包含namespace、value和命名空间限定符(type)。有关这些所需属性的更多详细信息，请参阅附录。

有关users和userIDs的更详细说明，请参阅疑难解答指南。

include （必需）

要包含在处理中的一系列Adobe产品。如果此值缺失或为空，则将拒绝请求。仅包括您的组织与之集成的产品。有关详细信息，请参阅附录中有关接受的产品值的部分。

expandIDs

一个可选属性，当设置为true时，表示对处理应用程序中的ID进行优化（当前仅受Analytics支持）。如果忽略，此值将默认为false。

priority

Adobe Analytics使用的一个可选属性，用于设置处理请求的优先级。接受的值包括 normal 和 low。如果忽略priority，则默认行为是normal。

mergePolicyId

对实时客户个人资料(profileService)发出隐私请求时，您可以选择提供要用于ID拼接的特定合并策略的ID。通过指定合并策略，隐私请求可以在返回客户数据时包含受众信息。每个请求只能指定一个合并策略。如果未提供合并策略，则响应中不包含分段信息。

regulation （必需）

隐私工作的法规。接受以下值：

apa_aus
ccpa
cpra_usa
gdpr
hipaa_usa
lgpd_bra
nzpa_nzl
pdpa_tha
vcdpa_usa

有关上述值表示的隐私法规的更多信息，请参阅支持的法规概述。

响应

成功的响应将返回新创建的作业的详细信息。

{
    "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。此值将在查找特定作业的下一个步骤中使用。

成功提交作业请求后，您可以继续下一步操作检查作业状态。

检查作业的状态 check-status

通过在/jobs终结点的GET请求路径中包含特定作业的jobId，您可以检索有关该作业的信息，例如其当前处理状态。

IMPORTANT

以前创建的作业的数据只能在作业完成日期后的30天内进行检索。

API格式

GET /jobs/{JOB_ID}

参数

描述

{JOB_ID}

要查找的作业的ID。在针对创建作业和列出所有作业的成功的API响应中，此ID在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: {ORG_ID}'

响应

成功的响应将返回指定作业的详细信息。

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

对于某些状态，某些产品可能返回提供responseMsgDetail未涵盖的其他信息的results对象。

downloadURL

如果作业的状态为complete，则此属性会提供一个URL以将作业结果下载为ZIP文件。在作业完成后60天内可下载此文件。

作业状态类别 status-categories

下表列出了不同的可能作业状态类别及其相应含义：

状态类别

含义

complete

作业已完成，并（如果需要）从每个应用程序上传文件。

processing

应用程序已确认该作业，当前正在处理。

submitted

作业将提交给每个适用的应用程序。

error

处理作业时出现问题 — 通过检索各个作业详细信息可能会获得更具体的信息。

NOTE

如果提交的作业具有仍在处理的依赖子作业，则该作业可能仍处于processing状态。

后续步骤

您现在知道如何使用Privacy Service API创建和监视隐私作业。有关如何使用用户界面执行相同任务的信息，请参阅Privacy ServiceUI概述。

recommendation-more-help

9cbf7061-a312-49f7-aaf8-a10885d53580