Endpoint di gestione sandbox

Le sandbox in Adobe Experience Platform forniscono ambienti di sviluppo isolati che consentono di testare le funzioni, eseguire esperimenti e creare configurazioni personalizzate senza influire sull’ambiente di produzione. La /sandboxes punto finale Sandbox L’API ti consente di gestire in modo programmatico le sandbox in Platform.

Introduzione

L’endpoint API utilizzato in questa guida fa parte del Sandbox API. Prima di continuare, controlla la guida introduttiva per i collegamenti alla documentazione correlata, una guida alla lettura delle chiamate API di esempio in questo documento e importanti informazioni sulle intestazioni richieste necessarie per effettuare correttamente le chiamate a qualsiasi API di Experience Platform.

Recupera un elenco di sandbox

Puoi elencare tutte le sandbox appartenenti alla tua organizzazione IMS (attive o meno), effettuando una richiesta GET al /sandboxes punto finale.

Formato API

GET /sandboxes?{QUERY_PARAMS}
Parametro Descrizione
{QUERY_PARAMS} Parametri di query opzionali per filtrare i risultati in base a. Vedi la sezione su parametri di query per ulteriori informazioni.

Richiesta

curl -X GET \
  https://platform.adobe.io/data/foundation/sandbox-management/sandboxes?&limit=4&offset=1 \
  -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}'

Risposta

Una risposta corretta restituisce un elenco di sandbox appartenenti all’organizzazione, inclusi dettagli quali name, title, statee type.

{
    "sandboxes": [
        {
            "name": "prod",
            "title": "Production",
            "state": "active",
            "type": "production",
            "region": "VA7",
            "isDefault": true,
            "eTag": 2,
            "createdDate": "2019-09-04 04:57:24",
            "lastModifiedDate": "2019-09-04 04:57:24",
            "createdBy": "{USER_ID}",
            "modifiedBy": "{USER_ID}"
        },
        {
            "name": "dev",
            "title": "Development",
            "state": "active",
            "type": "development",
            "region": "VA7",
            "isDefault": false,
            "eTag": 1,
            "createdDate": "2019-09-03 22:27:48",
            "lastModifiedDate": "2019-09-03 22:27:48",
            "createdBy": "{USER_ID}",
            "modifiedBy": "{USER_ID}"
        },
        {
            "name": "stage",
            "title": "Staging",
            "state": "active",
            "type": "development",
            "region": "VA7",
            "isDefault": false,
            "eTag": 1,
            "createdDate": "2019-09-03 22:27:48",
            "lastModifiedDate": "2019-09-03 22:27:48",
            "createdBy": "{USER_ID}",
            "modifiedBy": "{USER_ID}"
        },
        {
            "name": "dev-2",
            "title": "Development 2",
            "state": "creating",
            "type": "development",
            "region": "VA7",
            "isDefault": false,
            "eTag": 1,
            "createdDate": "2019-09-07 10:16:02",
            "lastModifiedDate": "2019-09-07 10:16:02",
            "createdBy": "{USER_ID}",
            "modifiedBy": "{USER_ID}"
        }
    ],
    "_page": {
        "limit": 4,
        "count": 4
    },
    "_links": {
        "next": {
            "href": "https://platform.adobe.io:443/data/foundation/sandbox-management/sandboxes/?limit={limit}&offset={offset}",
            "templated": true
        },
        "prev": {
            "href": "https://platform.adobe.io:443/data/foundation/sandbox-management/sandboxes?offset=0&limit=1",
            "templated": null
        },
        "page": {
            "href": "https://platform.adobe.io:443/data/foundation/sandbox-management/sandboxes?offset=1&limit=1",
            "templated": null
        }
    }
}
Proprietà Descrizione
name Nome della sandbox. Questa proprietà viene utilizzata a scopo di ricerca nelle chiamate API.
title Nome visualizzato della sandbox.
state Lo stato di elaborazione corrente della sandbox. Lo stato di una sandbox può essere uno dei seguenti:
  • creating: La sandbox è stata creata, ma viene comunque fornita dal sistema.
  • active: La sandbox viene creata e attiva.
  • failed: A causa di un errore, il sistema non è in grado di eseguire il provisioning della sandbox ed è disabilitato.
  • deleted: La sandbox è stata disabilitata manualmente.
type Il tipo di sandbox. Gli attuali tipi di sandbox supportati includono development e production.
isDefault Proprietà booleana che indica se questa sandbox è la sandbox di produzione predefinita per l’organizzazione.
eTag Identificatore per una versione specifica della sandbox. Utilizzato per il controllo delle versioni e l’efficienza del caching, questo valore viene aggiornato ogni volta che viene apportata una modifica alla sandbox.

Cercare una sandbox

Puoi cercare un singolo sandbox effettuando una richiesta GET che include i name nel percorso della richiesta.

Formato API

GET /sandboxes/{SANDBOX_NAME}
Parametro Descrizione
{SANDBOX_NAME} La name della sandbox che si desidera cercare.

Richiesta

La richiesta seguente recupera una sandbox denominata "dev-2".

curl -X GET \
  https://platform.adobe.io/data/foundation/sandbox-management/sandboxes/dev-2 \
  -H 'Authorization: Bearer {ACCESS_TOKEN}' \
  -H 'x-api-key: {API_KEY}' \
  -H 'x-gw-ims-org-id: {ORG_ID}' \

Risposta

Una risposta corretta restituisce i dettagli della sandbox, inclusa la relativa name, title, statee type.

{
    "name": "dev-2",
    "title": "Development 2",
    "state": "creating",
    "type": "development",
    "region": "VA7",
    "isDefault": false,
    "eTag": 1,
    "createdDate": "2019-09-07 10:16:02",
    "lastModifiedDate": "2019-09-07 10:16:02",
    "createdBy": "{USER_ID}",
    "modifiedBy": "{USER_ID}"
}
Proprietà Descrizione
name Nome della sandbox. Questa proprietà viene utilizzata a scopo di ricerca nelle chiamate API.
title Nome visualizzato della sandbox.
state Lo stato di elaborazione corrente della sandbox. Lo stato di una sandbox può essere uno dei seguenti:
  • creazione: La sandbox è stata creata, ma viene comunque fornita dal sistema.
  • attivo: La sandbox viene creata e attiva.
  • fallito: A causa di un errore, il sistema non è in grado di eseguire il provisioning della sandbox ed è disabilitato.
  • cancellato: La sandbox è stata disabilitata manualmente.
type Il tipo di sandbox. Gli attuali tipi di sandbox supportati includono: development e production.
isDefault Proprietà booleana che indica se questa sandbox è la sandbox predefinita per l’organizzazione. In genere si tratta della sandbox di produzione.
eTag Identificatore per una versione specifica della sandbox. Utilizzato per il controllo delle versioni e l’efficienza del caching, questo valore viene aggiornato ogni volta che viene apportata una modifica alla sandbox.

Creare una sandbox

NOTA

Quando crei una nuova sandbox, devi prima aggiungerla al tuo profilo di prodotto in Adobe Admin Console prima di iniziare a utilizzare la nuova sandbox. Consulta la documentazione su gestione delle autorizzazioni per un profilo di prodotto per informazioni su come eseguire il provisioning di una sandbox a un profilo di prodotto.

Puoi creare una nuova sandbox di sviluppo o produzione effettuando una richiesta di POST al /sandboxes punto finale.

Creare una sandbox di sviluppo

Per creare una sandbox di sviluppo, devi fornire un type attributo con valore di development nel payload della richiesta.

Formato API

POST /sandboxes

Richiesta

La seguente richiesta crea una nuova sandbox di sviluppo denominata "acme-dev".

curl -X POST \
  https://platform.adobe.io/data/foundation/sandbox-management/sandboxes \
  -H 'Authorization: Bearer {ACCESS_TOKEN}' \
  -H 'x-api-key: {API_KEY}' \
  -H 'x-gw-ims-org-id: {ORG_ID}' \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "acme-dev",
    "title": "Acme Business Group dev",
    "type": "development"
  }'
Proprietà Descrizione
name Identificatore che verrà utilizzato per accedere alla sandbox nelle richieste future. Questo valore deve essere univoco e la best practice prevede di renderlo il più descrittivo possibile. Questo valore non può contenere spazi o caratteri speciali.
title Un nome leggibile dall’utente utilizzato a scopo di visualizzazione nell’interfaccia utente di Platform.
type Tipo di sandbox da creare. Per una sandbox non di produzione, questo valore deve essere development.

Risposta

Una risposta corretta restituisce i dettagli della nuova sandbox creata, mostrando che la relativa state è "creazione".

{
    "name": "acme-dev",
    "title": "Acme Business Group dev",
    "state": "creating",
    "type": "development",
    "region": "VA7"
}
NOTA

Le sandbox richiedono circa 30 secondi per essere fornite dal sistema, dopo di che il loro state diventerà "attivo" o "non riuscito".

Creare una sandbox di produzione

Per creare una sandbox di produzione, devi fornire un type attributo con valore di production nel payload della richiesta.

Formato API

POST /sandboxes

Richiesta

La seguente richiesta crea una nuova sandbox di produzione denominata "acme".

curl -X POST \
  https://platform.adobe.io/data/foundation/sandbox-management/sandboxes \
  -H 'Authorization: Bearer {ACCESS_TOKEN}' \
  -H 'x-api-key: {API_KEY}' \
  -H 'x-gw-ims-org-id: {ORG_ID}' \
  -H `Accept: application/json` \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "acme",
    "title": "Acme Business Group",
    "type": "production"
}'
Proprietà Descrizione
name Identificatore che verrà utilizzato per accedere alla sandbox nelle richieste future. Questo valore deve essere univoco e la best practice prevede di renderlo il più descrittivo possibile. Questo valore non può contenere spazi o caratteri speciali.
title Un nome leggibile dall’utente utilizzato a scopo di visualizzazione nell’interfaccia utente di Platform.
type Tipo di sandbox da creare. Per una sandbox di produzione, questo valore deve essere production.

Risposta

Una risposta corretta restituisce i dettagli della nuova sandbox creata, mostrando che la relativa state è "creazione".

{
    "name": "acme",
    "title": "Acme Business Group",
    "state": "creating",
    "type": "production",
    "region": "VA7"
}
NOTA

Le sandbox richiedono circa 30 secondi per essere fornite dal sistema, dopo di che il loro state diventerà "attivo" o "non riuscito".

Aggiornare una sandbox

È possibile aggiornare uno o più campi in una sandbox effettuando una richiesta di PATCH che include i name nel percorso della richiesta e nella proprietà da aggiornare nel payload della richiesta.

NOTA

Attualmente solo una sandbox title può essere aggiornata.

Formato API

PATCH /sandboxes/{SANDBOX_NAME}
Parametro Descrizione
{SANDBOX_NAME} La name della sandbox che si desidera aggiornare.

Richiesta

La seguente richiesta aggiorna il title della sandbox denominata "acme".

curl -X PATCH \
  https://platform.adobe.io/data/foundation/sandbox-management/sandboxes/acme \
  -H 'Authorization: Bearer {ACCESS_TOKEN}' \
  -H 'x-api-key: {API_KEY}' \
  -H 'x-gw-ims-org-id: {ORG_ID}' \
  -H 'Content-Type: application/json'
  -d '{
    "title": "Acme Business Group prod"
  }'

Risposta

Una risposta corretta restituisce lo stato HTTP 200 (OK) con i dettagli della sandbox appena aggiornata.

{
    "name": "acme",
    "title": "Acme Business Group prod",
    "state": "active",
    "type": "production",
    "region": "VA7"
}

Reimpostare una sandbox

Le sandbox hanno una funzione di "reimpostazione di fabbrica" che elimina tutte le risorse non predefinite da una sandbox. Puoi reimpostare una sandbox effettuando una richiesta di PUT che include le sandbox di name nel percorso della richiesta.

Formato API

PUT /sandboxes/{SANDBOX_NAME}
Parametro Descrizione
{SANDBOX_NAME} La name della sandbox che si desidera reimpostare.
validationOnly Un parametro facoltativo che consente di eseguire un controllo pre-volo sull’operazione di ripristino della sandbox senza effettuare la richiesta effettiva. Imposta questo parametro su validationOnly=true per verificare se la sandbox che stai per reimpostare contiene dati di condivisione di segmenti, Adobe Analytics, Adobe Audience Manager o.

Richiesta

La richiesta seguente reimposta una sandbox denominata "acme-dev".

curl -X PUT \
  https://platform.adobe.io/data/foundation/sandbox-management/sandboxes/acme-dev?validationOnly=true \
  -H 'Authorization: Bearer {ACCESS_TOKEN}' \
  -H 'x-api-key: {API_KEY}' \
  -H 'x-gw-ims-org-id: {ORG_ID}' \
  -H 'Content-Type: application/json'
  -d '{
    "action": "reset"
  }'
Proprietà Descrizione
action Questo parametro deve essere fornito nel payload della richiesta con un valore di "reset" per reimpostare la sandbox.

Risposta

NOTA

Una volta reimpostata la sandbox, il sistema impiega circa 30 secondi per effettuare il provisioning.

Una risposta corretta restituisce i dettagli della sandbox aggiornata, mostrando che state è "reimpostazione".

{
    "id": "d8184350-dbf5-11e9-875f-6bf1873fec16",
    "name": "acme-dev",
    "title": "Acme Business Group dev",
    "state": "resetting",
    "type": "development",
    "region": "VA7"
}

La sandbox di produzione predefinita e tutte le sandbox di produzione create dall’utente non possono essere reimpostate se il grafico di identità ospitato al suo interno viene utilizzato anche da Adobe Analytics per Analisi multidispositivo (CDA) o se il grafico di identità ospitato al suo interno viene utilizzato anche da Adobe Audience Manager per Destinazioni basate su persone (PBD) funzionalità.

Di seguito è riportato un elenco di possibili eccezioni che potrebbero impedire la reimpostazione di una sandbox:

{
    "status": 400,
    "title": "Sandbox `{SANDBOX_NAME}` cannot be reset. The identity graph hosted in this sandbox is also being used by Adobe Analytics for the Cross Device Analytics (CDA) feature.",
    "type": "http://ns.adobe.com/aep/errors/SMS-2074-400"
},
{
    "status": 400,
    "title": "Sandbox `{SANDBOX_NAME}` cannot be reset. The identity graph hosted in this sandbox is also being used by Adobe Audience Manager for the People Based Destinations (PBD) feature.",
    "type": "http://ns.adobe.com/aep/errors/SMS-2075-400"
},
{
    "status": 400,
    "title": "Sandbox `{SANDBOX_NAME}` cannot be reset. The identity graph hosted in this sandbox is also being used by Adobe Audience Manager for the People Based Destinations (PBD) feature, as well by Adobe Analytics for the Cross Device Analytics (CDA) feature.",
    "type": "http://ns.adobe.com/aep/errors/SMS-2076-400"
},
{
    "status": 400,
    "title": "Warning: Sandbox `{SANDBOX_NAME}` is used for bi-directional segment sharing with Adobe Audience Manager or Audience Core Service.",
    "type": "http://ns.adobe.com/aep/errors/SMS-2077-400"
}

Puoi procedere alla reimpostazione di una sandbox di produzione utilizzata per la condivisione di segmenti bidirezionale con Audience Manager o Audience Core Service aggiungendo la ignoreWarnings alla richiesta.

Formato API

PUT /sandboxes/{SANDBOX_NAME}?ignoreWarnings=true
Parametro Descrizione
{SANDBOX_NAME} La name della sandbox che si desidera reimpostare.
ignoreWarnings Un parametro opzionale che consente di saltare il controllo di convalida e forzare la reimpostazione di una sandbox di produzione utilizzata per la condivisione di segmenti bidirezionale con Audience Manager o Audience Core Service. Questo parametro non può essere applicato a una sandbox di produzione predefinita.

Richiesta

La richiesta seguente reimposta una sandbox di produzione denominata "acme".

curl -X PUT \
  https://platform.adobe.io/data/foundation/sandbox-management/sandboxes/acme?ignoreWarnings=true \
  -H 'Authorization: Bearer {ACCESS_TOKEN}' \
  -H 'x-api-key: {API_KEY}' \
  -H 'x-gw-ims-org-id: {ORG_ID}' \
  -H 'Content-Type: application/json'
  -d '{
    "action": "reset"
  }'

Risposta

Una risposta corretta restituisce i dettagli della sandbox aggiornata, mostrando che state è "reimpostazione".

{
    "id": "d8184350-dbf5-11e9-875f-6bf1873fec16",
    "name": "acme",
    "title": "Acme Business Group prod",
    "state": "resetting",
    "type": "production",
    "region": "VA7"
}

Eliminare una sandbox

IMPORTANTE

Impossibile eliminare la sandbox di produzione predefinita.

È possibile eliminare una sandbox effettuando una richiesta di DELETE che include le sandbox di name nel percorso della richiesta.

NOTA

L’esecuzione di questa chiamata API aggiorna la sandbox di status su "cancellato" e lo disattiva. Le richieste GET possono ancora recuperare i dettagli della sandbox dopo che è stata eliminata.

Formato API

DELETE /sandboxes/{SANDBOX_NAME}
Parametro Descrizione
{SANDBOX_NAME} La name della sandbox da eliminare.
validationOnly Un parametro facoltativo che consente di eseguire un controllo pre-volo sull’operazione di eliminazione della sandbox senza effettuare la richiesta effettiva. Imposta questo parametro su validationOnly=true per verificare se la sandbox che stai per reimpostare contiene dati di condivisione di segmenti, Adobe Analytics, Adobe Audience Manager o.
ignoreWarnings Un parametro opzionale che consente di saltare il controllo di convalida e forzare l’eliminazione di una sandbox di produzione creata dall’utente utilizzata per la condivisione di segmenti bidirezionali con Audience Manager o Audience Core Service. Questo parametro non può essere applicato a una sandbox di produzione predefinita.

Richiesta

La richiesta seguente elimina una sandbox di produzione denominata "acme".

curl -X DELETE \
  https://platform.adobe.io/data/foundation/sandbox-management/sandboxes/acme?ignoreWarnings=true \
  -H 'Authorization: Bearer {ACCESS_TOKEN}' \
  -H 'x-api-key: {API_KEY}' \
  -H 'x-gw-ims-org-id: {ORG_ID}'

Risposta

Una risposta corretta restituisce i dettagli aggiornati della sandbox, indicando che la relativa state è "cancellato".

{
    "name": "acme",
    "title": "Acme Business Group prod",
    "state": "deleted",
    "type": "development",
    "region": "VA7"
}

In questa pagina