I criteri di utilizzo dei dati sono regole che descrivono i tipi di azioni di marketing consentite o con cui è consentito eseguire attività sui dati all'interno di Experience Platform. L'endpoint /policies
in Policy Service API consente di gestire i criteri di utilizzo dei dati a livello di programmazione per l'organizzazione.
L'endpoint API utilizzato in questa guida fa parte dell' Policy Service API. Prima di continuare, consultare la guida introduttiva per i collegamenti alla documentazione correlata, una guida alla lettura delle chiamate API di esempio in questo documento e informazioni importanti sulle intestazioni necessarie per eseguire correttamente chiamate a qualsiasi API Experience Platform.
È possibile elencare tutti i criteri core
o custom
effettuando una richiesta di GET rispettivamente a /policies/core
o /policies/custom
.
Formato API
GET /policies/core
GET /policies/custom
Richiesta
La seguente richiesta consente di ottenere un elenco di criteri personalizzati definiti dall'organizzazione.
curl -X GET \
https://platform.adobe.io/data/foundation/dulepolicy/policies/custom \
-H 'Authorization: Bearer {ACCESS_TOKEN}' \
-H 'x-api-key: {API_KEY}' \
-H 'x-gw-ims-org-id: {IMS_ORG}' \
-H 'x-sandbox-name: {SANDBOX_NAME}'
Risposta
Una risposta corretta include un array children
che elenca i dettagli di ciascun criterio recuperato, inclusi i relativi valori id
. È possibile utilizzare il campo id
di un particolare criterio per eseguire le richieste Search, update e delete per tale criterio.
{
"_page": {
"start": "5c6dacdf685a4913dc48937c",
"count": 2
},
"_links": {
"page": {
"href": "https://platform.adobe.io/policies/custom?{?limit,start,property}",
"templated": true
}
},
"children": [
{
"name": "Export Data to Third Party",
"status": "DRAFT",
"marketingActionRefs": [
"https://platform.adobe.io/data/foundation/dulepolicy/marketingActions/custom/exportToThirdParty"
],
"description": "Conditions under which data cannot be exported to a third party",
"deny": {
"operator": "AND",
"operands": [
{
"label": "C1"
},
{
"operator": "OR",
"operands": [
{
"label": "C3"
},
{
"label": "C7"
}
]
}
]
},
"imsOrg": "{IMS_ORG}",
"created": 1550691551888,
"createdClient": "{CLIENT_ID}",
"createdUser": "{USER_ID}",
"updated": 1550701472910,
"updatedClient": "{CLIENT_ID}",
"updatedUser": "{USER_ID}",
"_links": {
"self": {
"href": "https://platform.adobe.io/data/foundation/dulepolicy/policies/custom/5c6dacdf685a4913dc48937c"
}
},
"id": "5c6dacdf685a4913dc48937c"
},
{
"name": "Combine Data",
"status": "ENABLED",
"marketingActionRefs": [
"https://platform.adobe.io/data/foundation/dulepolicy/marketingActions/custom/combineData"
],
"description": "Data that meets these conditions cannot be combined.",
"deny": {
"operator": "AND",
"operands": [
{
"label": "C3"
},
{
"label": "I1"
}
]
},
"imsOrg": "{IMS_ORG}",
"created": 1550703519823,
"createdClient": "{CLIENT_ID}",
"createdUser": "{USER_ID}",
"updated": 1550714340335,
"updatedClient": "{CLIENT_ID}",
"updatedUser": "{USER_ID}",
"_links": {
"self": {
"href": "https://platform.adobe.io/data/foundation/dulepolicy/policies/custom/5c6ddb9f5c404513dc2dc454"
}
},
"id": "5c6ddb9f5c404513dc2dc454"
}
]
}
Proprietà | Descrizione |
---|---|
_page.count |
Numero totale di criteri recuperati. |
name |
Nome visualizzato per un criterio. |
status |
Stato corrente di un criterio. Esistono tre stati possibili: DRAFT , ENABLED o DISABLED . Per impostazione predefinita, solo i criteri ENABLED partecipano alla valutazione. Per ulteriori informazioni, vedere la panoramica sulla valutazione dei criteri. |
marketingActionRefs |
Un array che elenca gli URI di tutte le azioni di marketing applicabili a un criterio. |
description |
Una descrizione facoltativa che fornisce ulteriore contesto al caso di utilizzo del criterio. |
deny |
Un oggetto che descrive le etichette di utilizzo dei dati specifiche sulle quali viene limitata l'azione di marketing associata a un criterio. Per ulteriori informazioni su questa proprietà, vedere la sezione relativa alla creazione di un criterio. |
Potete cercare un criterio specifico includendo la proprietà id
di tale criterio nel percorso di una richiesta di GET.
Formato API
GET /policies/core/{POLICY_ID}
GET /policies/custom/{POLICY_ID}
Parametro | Descrizione |
---|---|
{POLICY_ID} |
Il id del criterio da cercare. |
Richiesta
curl -X GET \
https://platform.adobe.io/data/foundation/dulepolicy/policies/custom/5c6dacdf685a4913dc48937c \
-H 'Authorization: Bearer {ACCESS_TOKEN}' \
-H 'x-api-key: {API_KEY}' \
-H 'x-gw-ims-org-id: {IMS_ORG}' \
-H 'x-sandbox-name: {SANDBOX_NAME}'
Risposta
Una risposta corretta restituisce i dettagli del criterio.
{
"name": "Export Data to Third Party",
"status": "DRAFT",
"marketingActionRefs": [
"https://platform.adobe.io/data/foundation/dulepolicy/marketingActions/custom/exportToThirdParty"
],
"description": "Conditions under which data cannot be exported to a third party",
"deny": {
"operator": "AND",
"operands": [
{
"label": "C1"
},
{
"operator": "OR",
"operands": [
{
"label": "C3"
},
{
"label": "C7"
}
]
}
]
},
"imsOrg": "{IMS_ORG}",
"created": 1550703519823,
"createdClient": "{CLIENT_ID}",
"createdUser": "{USER_ID}",
"updated": 1550714340335,
"updatedClient": "{CLIENT_ID}",
"updatedUser": "{USER_ID}",
"_links": {
"self": {
"href": "https://platform.adobe.io/data/foundation/dulepolicy/policies/custom/5c6dacdf685a4913dc48937c"
}
},
"id": "5c6dacdf685a4913dc48937c"
}
Proprietà | Descrizione |
---|---|
name |
Nome visualizzato per il criterio. |
status |
Stato corrente del criterio. Esistono tre stati possibili: DRAFT , ENABLED o DISABLED . Per impostazione predefinita, solo i criteri ENABLED partecipano alla valutazione. Per ulteriori informazioni, vedere la panoramica sulla valutazione dei criteri. |
marketingActionRefs |
Un array che elenca gli URI di tutte le azioni di marketing applicabili al criterio. |
description |
Una descrizione facoltativa che fornisce ulteriore contesto al caso di utilizzo del criterio. |
deny |
Un oggetto che descrive le etichette di utilizzo dei dati specifiche sulle quali l'azione di marketing associata al criterio non viene eseguita. Per ulteriori informazioni su questa proprietà, vedere la sezione relativa alla creazione di un criterio. |
Nell'API Policy Service, un criterio è definito dai seguenti elementi:
Per soddisfare quest'ultimo requisito, le definizioni dei criteri devono includere un'espressione booleana relativa alla presenza di etichette di utilizzo dei dati. Questa espressione è denominata espressione di criterio.
Le espressioni del criterio vengono fornite sotto forma di proprietà deny
all'interno di ogni definizione del criterio. Un esempio di semplice oggetto deny
che verifica solo la presenza di una singola etichetta avrà l'aspetto seguente:
"deny": {
"label": "C1"
}
Tuttavia, molti criteri specificano condizioni più complesse relative alla presenza di etichette di utilizzo dei dati. Per supportare questi casi di utilizzo, è anche possibile includere operazioni booleane per descrivere le espressioni dei criteri. L'oggetto policy espressione deve contenere un'etichetta o un operatore e gli operandi, ma non entrambi. A sua volta, ogni operando è anche un oggetto con espressione di criterio.
Ad esempio, per definire un criterio che impedisca l'esecuzione di un'azione di marketing sui dati in cui sono presenti etichette C1 OR (C3 AND C7)
, la proprietà deny
del criterio viene specificata come:
"deny": {
"operator": "OR",
"operands": [
{"label": "C1"},
{
"operator": "AND",
"operands": [
{"label": "C3"},
{"label": "C7"}
]
}
]
}
Proprietà | Descrizione |
---|---|
operator |
Indica la relazione condizionale tra le etichette fornite nell'array di pari livello operands . I valori accettati sono:
|
operands |
Un array di oggetti, con ciascun oggetto che rappresenta una singola etichetta o una coppia aggiuntiva di proprietà operator e operands . La presenza delle etichette e/o delle operazioni in un array operands restituisce true o false in base al valore della proprietà di pari livello operator . |
label |
Nome di un'unica etichetta di utilizzo dati applicata al criterio. |
Potete creare un nuovo criterio personalizzato effettuando una richiesta di POST all'endpoint /policies/custom
.
Formato API
POST /policies/custom
Richiesta
La richiesta seguente crea un nuovo criterio che impedisce l'esecuzione dell'azione di marketing exportToThirdParty
sui dati contenenti etichette C1 OR (C3 AND C7)
.
curl -X POST \
https://platform.adobe.io/data/foundation/dulepolicy/policies/custom \
-H 'Authorization: Bearer {ACCESS_TOKEN}' \
-H 'Content-Type: application/json' \
-H 'x-api-key: {API_KEY}' \
-H 'x-gw-ims-org-id: {IMS_ORG}' \
-H 'x-sandbox-name: {SANDBOX_NAME}' \
-d '{
"name": "Export Data to Third Party",
"status": "DRAFT",
"marketingActionRefs": [
"https://platform.adobe.io/data/foundation/dulepolicy/marketingActions/custom/exportToThirdParty"
],
"description": "Conditions under which data cannot be exported to a third party",
"deny": {
"operator": "OR",
"operands": [
{"label": "C1"},
{
"operator": "AND",
"operands": [
{"label": "C3"},
{"label": "C7"}
]
}
]
}
}'
Proprietà | Descrizione |
---|---|
name |
Nome visualizzato per il criterio. |
status |
Stato corrente del criterio. Esistono tre stati possibili: DRAFT , ENABLED o DISABLED . Per impostazione predefinita, solo i criteri ENABLED partecipano alla valutazione. Per ulteriori informazioni, vedere la panoramica sulla valutazione dei criteri. |
marketingActionRefs |
Un array che elenca gli URI di tutte le azioni di marketing applicabili al criterio. L'URI di un'azione di marketing è fornito in _links.self.href nella risposta per cercare un'azione di marketing. |
description |
Una descrizione facoltativa che fornisce ulteriore contesto al caso di utilizzo del criterio. |
deny |
L'espressione di criterio che descrive le etichette di utilizzo dei dati specifiche per le azioni di marketing associate al criterio non viene eseguita. |
Risposta
Una risposta corretta restituisce i dettagli del criterio appena creato, incluso id
. Questo valore è di sola lettura e viene assegnato automaticamente alla creazione del criterio.
{
"name": "Export Data to Third Party",
"status": "DRAFT",
"marketingActionRefs": [
"https://platform.adobe.io/data/foundation/dulepolicy/marketingActions/custom/exportToThirdParty"
],
"description": "Conditions under which data cannot be exported to a third party",
"deny": {
"operator": "OR",
"operands": [
{
"label": "C1"
},
{
"operator": "AND",
"operands": [
{
"label": "C3"
},
{
"label": "C7"
}
]
}
]
},
"imsOrg": "{IMS_ORG}",
"created": 1550691551888,
"createdClient": "{CLIENT_ID}",
"createdUser": "{USER_ID}",
"updated": 1550691551888,
"updatedClient": "{CLIENT_ID}",
"updatedUser": "{USER_ID}",
"_links": {
"self": {
"href": "https://platform.adobe.io/data/foundation/dulepolicy/policies/custom/5c6dacdf685a4913dc48937c"
}
},
"id": "5c6dacdf685a4913dc48937c"
}
È possibile aggiornare solo i criteri personalizzati. Se si desidera abilitare o disabilitare i criteri di base, consultare la sezione in aggiornamento dell'elenco dei criteri di base abilitati.
Potete aggiornare un criterio personalizzato esistente fornendo il relativo ID nel percorso di una richiesta di PUT con un payload che include il modulo aggiornato del criterio nella sua interezza. In altre parole, la richiesta PUT sostanzialmente riscrive il criterio.
Consultate la sezione sull aggiornamento di una parte di un criterio personalizzato se desiderate aggiornare solo uno o più campi per un criterio, anziché sovrascriverlo.
Formato API
PUT /policies/custom/{POLICY_ID}
Parametro | Descrizione |
---|---|
{POLICY_ID} |
Il id del criterio da aggiornare. |
Richiesta
In questo esempio, le condizioni per l'esportazione di dati a terzi sono cambiate e ora è necessario che il criterio creato neghi questa azione di marketing se sono presenti etichette di dati C1 AND C5
.
La richiesta seguente aggiorna il criterio esistente per includere la nuova espressione del criterio. Notate che, poiché questa richiesta in sostanza riscrive il criterio, tutti i campi devono essere inclusi nel payload, anche se alcuni dei relativi valori non vengono aggiornati.
curl -X PUT \
https://platform.adobe.io/data/foundation/dulepolicy/policies/custom/5c6dacdf685a4913dc48937c \
-H 'Authorization: Bearer {ACCESS_TOKEN}' \
-H 'Content-Type: application/json' \
-H 'x-api-key: {API_KEY}' \
-H 'x-gw-ims-org-id: {IMS_ORG}' \
-H 'x-sandbox-name: {SANDBOX_NAME}' \
-d '{
"name": "Export Data to Third Party",
"status": "DRAFT",
"marketingActionRefs": [
"../marketingActions/custom/exportToThirdParty"
],
"description": "Conditions under which data cannot be exported to a third party",
"deny": {
"operator": "AND",
"operands": [
{"label": "C1"},
{"label": "C5"}
]
}
}'
Proprietà | Descrizione |
---|---|
name |
Nome visualizzato per il criterio. |
status |
Stato corrente del criterio. Esistono tre stati possibili: DRAFT , ENABLED o DISABLED . Per impostazione predefinita, solo i criteri ENABLED partecipano alla valutazione. Per ulteriori informazioni, vedere la panoramica sulla valutazione dei criteri. |
marketingActionRefs |
Un array che elenca gli URI di tutte le azioni di marketing applicabili al criterio. L'URI di un'azione di marketing è fornito in _links.self.href nella risposta per cercare un'azione di marketing. |
description |
Una descrizione facoltativa che fornisce ulteriore contesto al caso di utilizzo del criterio. |
deny |
L'espressione di criterio che descrive le etichette di utilizzo dei dati specifiche per le azioni di marketing associate al criterio non viene eseguita. Per ulteriori informazioni su questa proprietà, vedere la sezione relativa alla creazione di un criterio. |
Risposta
Una risposta corretta restituisce i dettagli del criterio aggiornato.
{
"name": "Export Data to Third Party",
"status": "DRAFT",
"marketingActionRefs": [
"https://platform.adobe.io/data/foundation/dulepolicy/marketingActions/core/exportToThirdParty"
],
"description": "Conditions under which data cannot be exported to a third party",
"deny": {
"operator": "AND",
"operands": [
{
"label": "C1"
},
{
"label": "C5"
}
]
},
"imsOrg": "{IMS_ORG}",
"created": 1550691551888,
"createdClient": "{CLIENT_ID}",
"createdUser": "{USER_ID}",
"updated": 1550701472910,
"updatedClient": "{CLIENT_ID}",
"updatedUser": "{USER_ID}",
"_links": {
"self": {
"href": "https://platform.adobe.io/data/foundation/dulepolicy/policies/custom/5c6dacdf685a4913dc48937c"
}
},
"id": "5c6dacdf685a4913dc48937c"
}
È possibile aggiornare solo i criteri personalizzati. Se si desidera abilitare o disabilitare i criteri di base, consultare la sezione in aggiornamento dell'elenco dei criteri di base abilitati.
Una parte specifica di un criterio può essere aggiornata utilizzando una richiesta PATCH. A differenza delle richieste PUT che riscrivono il criterio, le richieste PATCH aggiornano solo le proprietà specificate nel corpo della richiesta. Ciò è particolarmente utile quando si desidera abilitare o disabilitare un criterio, in quanto è necessario fornire solo il percorso della proprietà appropriata (/status
) e il relativo valore (ENABLED
o DISABLED
).
I payload per le richieste PATCH seguono la formattazione della patch JSON. Per ulteriori informazioni sulla sintassi accettata, vedere la Guida di base delle API.
L'API Policy Service supporta le operazioni di patch JSON add
, remove
e replace
e consente di combinare diversi aggiornamenti in una singola chiamata, come illustrato nell'esempio seguente.
Formato API
PATCH /policies/custom/{POLICY_ID}
Parametro | Descrizione |
---|---|
{POLICY_ID} |
Il id del criterio di cui si desidera aggiornare le proprietà. |
Richiesta
La richiesta seguente utilizza due operazioni replace
per cambiare lo stato del criterio da DRAFT
a ENABLED
e per aggiornare il campo description
con una nuova descrizione.
Quando si inviano più operazioni PATCH in un'unica richiesta, queste vengono elaborate nell'ordine in cui appaiono nell'array. Se necessario, accertatevi di inviare le richieste nell'ordine corretto.
curl -X PATCH \
https://platform.adobe.io/data/foundation/dulepolicy/policies/custom/5c6dacdf685a4913dc48937c \
-H 'Authorization: Bearer {ACCESS_TOKEN}' \
-H 'Content-Type: application/json' \
-H 'x-api-key: {API_KEY}' \
-H 'x-gw-ims-org-id: {IMS_ORG}' \
-H 'x-sandbox-name: {SANDBOX_NAME}' \
-d ' [
{
"op": "replace",
"path": "/status",
"value": "ENABLED"
},
{
"op": "replace",
"path": "/description",
"value": "New policy description."
}
]'
Risposta
Una risposta corretta restituisce i dettagli del criterio aggiornato.
{
"name": "Export Data to Third Party",
"status": "ENABLED",
"marketingActionRefs": [
"https://platform.adobe.io/data/foundation/dulepolicy/marketingActions/custom/exportToThirdParty"
],
"description": "New policy description.",
"deny": {
"operator": "AND",
"operands": [
{
"label": "C1"
},
{
"operator": "OR",
"operands": [
{
"label": "C3"
},
{
"label": "C7"
}
]
}
]
},
"imsOrg": "{IMS_ORG}",
"created": 1550703519823,
"createdClient": "{CLIENT_ID}",
"createdUser": "{USER_ID}",
"updated": 1550712163182,
"updatedClient": "{CLIENT_ID}",
"updatedUser": "{USER_ID}",
"_links": {
"self": {
"href": "https://platform.adobe.io/data/foundation/dulepolicy/policies/custom/5c6dacdf685a4913dc48937c"
}
},
"id": "5c6dacdf685a4913dc48937c"
}
Potete eliminare un criterio personalizzato includendone id
nel percorso di una richiesta di DELETE.
Una volta eliminati, i criteri non possono essere recuperati. È consigliabile eseguire una richiesta di ricerca (GET) prima di visualizzare il criterio e confermare che si tratta del criterio corretto da rimuovere.
Formato API
DELETE /policies/custom/{POLICY_ID}
Parametro | Descrizione |
---|---|
{POLICY_ID} |
ID del criterio da eliminare. |
Richiesta
curl -X DELETE \
https://platform.adobe.io/data/foundation/dulepolicy/policies/custom/5c6ddb56eb60ca13dbf8b9a8 \
-H 'Authorization: Bearer {ACCESS_TOKEN}' \
-H 'x-api-key: {API_KEY}' \
-H 'x-gw-ims-org-id: {IMS_ORG}' \
-H 'x-sandbox-name: {SANDBOX_NAME}'
Risposta
Una risposta corretta restituisce lo stato HTTP 200 (OK) con un corpo vuoto.
Potete confermare l'eliminazione tentando di ricercare nuovamente (GET) il criterio. Se il criterio è stato eliminato correttamente, dovreste ricevere un errore HTTP 404 (non trovato).
Per impostazione predefinita, solo i criteri di utilizzo dei dati abilitati partecipano alla valutazione. È possibile recuperare un elenco dei criteri di base attualmente abilitati dalla propria organizzazione effettuando una richiesta di GET all'endpoint /enabledCorePolicies
.
Formato API
GET /enabledCorePolicies
Richiesta
curl -X GET \
https://platform.adobe.io/data/foundation/dulepolicy/enabledCorePolicies \
-H 'Authorization: Bearer {ACCESS_TOKEN}' \
-H 'x-api-key: {API_KEY}' \
-H 'x-gw-ims-org-id: {IMS_ORG}' \
-H 'x-sandbox-name: {SANDBOX_NAME}'
Risposta
Una risposta corretta restituisce l'elenco dei criteri di base abilitati in un array policyIds
.
{
"policyIds": [
"corepolicy_0001",
"corepolicy_0002",
"corepolicy_0003",
"corepolicy_0004",
"corepolicy_0005",
"corepolicy_0006",
"corepolicy_0007",
"corepolicy_0008"
],
"imsOrg": "{IMS_ORG}",
"created": 1529696681413,
"createdClient": "{CLIENT_ID}",
"createdUser": "{USER_ID}",
"updated": 1529697651972,
"updatedClient": "{CLIENT_ID}",
"updatedUser": "{USER_ID}",
"_links": {
"self": {
"href": "https://platform.adobe.io:443/data/foundation/dulepolicy/enabledCorePolicies"
}
}
}
Per impostazione predefinita, solo i criteri di utilizzo dei dati abilitati partecipano alla valutazione. Eseguendo una richiesta di PUT all'endpoint /enabledCorePolicies
, puoi aggiornare l'elenco dei criteri di base abilitati per la tua organizzazione utilizzando una singola chiamata.
Solo i criteri di base possono essere attivati o disattivati da questo endpoint. Per abilitare o disabilitare i criteri personalizzati, consultare la sezione relativa all'aggiornamento di una parte di un criterio ](#patch).[
Formato API
PUT /enabledCorePolicies
Richiesta
La richiesta seguente aggiorna l'elenco dei criteri di base abilitati in base agli ID forniti nel payload.
curl -X GET \
https://platform.adobe.io/data/foundation/dulepolicy/enabledCorePolicies \
-H 'Authorization: Bearer {ACCESS_TOKEN}' \
-H 'x-api-key: {API_KEY}' \
-H 'x-gw-ims-org-id: {IMS_ORG}' \
-H 'x-sandbox-name: {SANDBOX_NAME}' \
-d '{
"policyIds": [
"corepolicy_0001",
"corepolicy_0002",
"corepolicy_0007",
"corepolicy_0008"
]
}'
Proprietà | Descrizione |
---|---|
policyIds |
Elenco degli ID dei criteri di base da abilitare. Eventuali criteri di base non inclusi sono impostati sullo stato DISABLED e non parteciperanno alla valutazione. |
Risposta
Una risposta corretta restituisce l'elenco aggiornato dei criteri di base abilitati in un array policyIds
.
{
"policyIds": [
"corepolicy_0001",
"corepolicy_0002",
"corepolicy_0007",
"corepolicy_0008"
],
"imsOrg": "{IMS_ORG}",
"created": 1529696681413,
"createdClient": "{CLIENT_ID}",
"createdUser": "{USER_ID}",
"updated": 1595876052649,
"updatedClient": "{CLIENT_ID}",
"updatedUser": "{USER_ID}",
"_links": {
"self": {
"href": "https://platform.adobe.io:443/data/foundation/dulepolicy/enabledCorePolicies"
}
}
}
Una volta definiti nuovi criteri o aggiornati quelli esistenti, puoi utilizzare l'API Policy Service per testare le azioni di marketing in base a etichette o set di dati specifici e verificare se i criteri stanno generando le violazioni come previsto. Per ulteriori informazioni, vedere la guida sugli endpoint di valutazione criteri.