Cartelle
Creato per:
- Amministratore
Le cartelle sono la risorsa organizzativa principale in Marketo e ogni altro tipo di risorsa ha almeno una cartella come elemento principale. Questa cartella principale può essere una cartella puramente organizzativa o un programma con una relazione funzionale con altri tipi di risorse e può anche essere l’elemento principale di altre risorse. Le cartelle possono essere create, interrogate, aggiornate ed eliminate tramite l’API, e consentono inoltre di recuperare un elenco dei relativi contenuti. Anche se i programmi possono essere restituiti tramite l'esecuzione di query sull'API delle cartelle, la creazione, l'aggiornamento e l'eliminazione dei programmi devono essere eseguiti tramite l'API dei programmi.
Query
La query delle cartelle segue i tipi di query standard per le risorse di per ID, per nome e esplorazione.
Per ID
GET /rest/asset/v1/folder/{id}.json?type=Folder
{
"success": true,
"warnings": [],
"errors": [],
"requestId": "1241b#14e21ca814a",
"result": [
{
"name": "Social Media",
"description": null,
"createdAt": "2011-03-04T17:01:32Z+0000",
"updatedAt": "2011-03-04T17:01:32Z+0000",
"url": null,
"folderId": {
"id": 341,
"type": "Folder"
},
"folderType": "Email",
"parent": {
"id": 11,
"type": "Folder"
},
"path": "/Design Studio/Default/Emails/Social Media",
"isArchive": false,
"isSystem": false,
"accessZoneId": 1,
"workspace": "Default",
"id": 341
}
]
}
Il parametro di tipo è obbligatorio e deve essere uno tra "Folder" (Cartella) o "Program" (Programma). Il tipo determina se la ricerca nella cartella viene eseguita in base a un ID cartella o a un ID programma. Per questo endpoint, nell'array dei risultati viene restituito un solo record. Osserva il parametro folderType nella risposta. Questo può indicare molti tipi diversi di cartelle. Le cartelle Attività di Marketo dispongono di un tipo Cartella di marketing o Programma, che può contenere diversi tipi di risorse, mentre le cartelle di Design Studio hanno un tipo corrispondente al tipo di risorsa che possono contenere. Ad esempio, una cartella con folderType impostato su "E-mail" può contenere solo e-mail o altre sottocartelle, che possono avere folderType impostato su E-mail o Modello e-mail. I tipi possono includere:
- Modello e-mail
- Pagina di destinazione
- Modello per pagina di destinazione
- Frammento
- File
Per nome
È consentita anche la query per nome. L'endpoint di query per nome presenta il nome come unico parametro obbligatorio. Name esegue una corrispondenza esatta di stringa con il campo name delle cartelle nell’istanza e restituisce i risultati per ogni cartella che corrisponde a tale nome. Inoltre, dispone dei parametri di query facoltativi "type", che possono essere Folder o Program (Cartella o Programma), "root" (Radice) l’ID della cartella da cercare, oppure "workspace" il nome dell’area di lavoro in cui eseguire la ricerca. Se è impostato il parametro root, è necessario impostare anche il parametro type.
GET /rest/asset/v1/folder/byName.json?name=Test%2010%20-%20deverly
{
"success": true,
"warnings": [],
"errors": [],
"requestId": "19#14e1f2f3688",
"result": [
{
"name": "Test 10 - deverly",
"description": "This is a test",
"createdAt": "2015-06-23T06:27:04Z+0000",
"updatedAt": "2015-06-23T06:27:04Z+0000",
"url": "https://app-abm.marketo.com/#MF1070A1",
"folderId": {
"id": 454,
"type": "FOLDER"
},
"folderType": "Marketing Folder",
"parent": {
"id": 416,
"type": "FOLDER"
},
"path": "/Marketing Activities/Default/Marketing Programs - deverly/Test 10 - deverly",
"isArchive": false,
"isSystem": false,
"accessZoneId": 1,
"workspace": "Default",
"id": 454
}
]
}
Durante la ricerca per nome, è importante notare che sia Marketing Activities che Design Studio sono cartelle principali proprie, e possono quindi essere recuperate per nome e utilizzate per scorrere il resto della gerarchia di cartelle in un’istanza di destinazione.
Sfogliare
Le cartelle possono anche essere recuperate in blocco. Il parametro "root" può essere utilizzato per specificare la cartella principale in cui verrà eseguita la query e viene formattato come oggetto JSON incorporato come valore per il parametro di query. La radice ha due membri:
- id: l’ID della cartella o del programma.
- tipo: cartella o programma, a seconda del tipo di cartella principale da browser.
Se la cartella principale non è nota o l’obiettivo è quello di recuperare tutte le cartelle in una determinata area, è possibile specificarla come area "Marketing Activities", "Design Studio" o "Lead Database". È possibile recuperare gli ID per ciascuno di questi elementi tramite l'API Get Folder By Name e specificando il nome dell'area desiderata.
Come altri endpoint per il recupero di risorse in blocco, offset e maxReturn sono parametri facoltativi per il paging. Altri parametri facoltativi sono:
- workSpace: il nome dell’area di lavoro a cui applicare il filtro.
- maxDepth: il numero massimo di livelli da attraversare nella gerarchia di cartelle. Se è impostato su 0, viene restituita solo la cartella specificata nella directory principale. Se non viene specificato, il valore predefinito è 2.
GET /rest/asset/v1/folders.json?root={"id":14,"type":"Folder"}
{
"success": true,
"warnings": [],
"errors": [],
"requestId": "9bd8#14e1f49047c",
"result": [
{
"name": "Marketing Activities",
"description": "Root node for the Marketing Activities app area",
"createdAt": "2010-03-27T18:27:45Z+0000",
"updatedAt": "2010-03-27T18:27:45Z+0000",
"url": null,
"folderId": {
"id": 14,
"type": "Folder"
},
"folderType": "Zone",
"parent": null,
"path": "/Marketing Activities",
"isArchive": false,
"isSystem": true,
"accessZoneId": 1,
"workspace": "Default",
"id": 14
},
{
"name": "Default",
"description": "Root node of the Marketing activities Default",
"createdAt": "2010-03-27T18:27:45Z+0000",
"updatedAt": "2010-03-27T18:27:45Z+0000",
"url": null,
"folderId": {
"id": 15,
"type": "Folder"
},
"folderType": "Zone",
"parent": {
"id": 14,
"type": "Folder"
},
"path": "/Marketing Activities/Default",
"isArchive": false,
"isSystem": true,
"accessZoneId": 1,
"workspace": "Default",
"id": 15
},
{
"name": "Archive",
"description": "",
"createdAt": "2010-03-27T18:28:17Z+0000",
"updatedAt": "2010-03-27T18:28:17Z+0000",
"url": "https://app-abm.marketo.com/#MF157A1",
"folderId": {
"id": 310,
"type": "Folder"
},
"folderType": "Marketing Folder",
"parent": {
"id": 15,
"type": "Folder"
},
"path": "/Marketing Activities/Default/Archive",
"isArchive": false,
"isSystem": false,
"accessZoneId": 1,
"workspace": "Default",
"id": 310
}
]
}
Struttura di risposta
Gran parte della struttura di risposta delle cartelle è auto-esplicativa, ma alcuni campi meritano di essere annotati singolarmente. folderId e i campi padre sono oggetti JSON che includono l'ID esplicito e il tipo della cartella stessa. Questo tipo viene utilizzato dall’API nelle query, nei parametri radice e padre per garantire una corretta distinzione tra i tipi di cartelle Folder e Program. folderType riflette l'utilizzo della cartella, che può essere "Cartella marketing", "Programma", "E-mail", "Modello e-mail", Pagina di destinazione, Modello pagina di destinazione", "Snippet", "Immagine", "Zona" o "File". I tipi Cartella di marketing e Programma indicano che sono presenti nelle Attività di marketing e possono contenere più tipi di risorse. Gli altri tipi indicano che possono contenere solo quel tipo di risorsa, le sottocartelle e la versione modello di quel tipo, se applicabile. Il tipo Zone rappresenta le cartelle a livello principale presenti in Attività di marketing.
Il percorso di una cartella mostra la relativa gerarchia nella struttura ad albero delle cartelle, simile a un percorso in stile Unix. La prima voce nel percorso sarà sempre Marketing Activities (Attività di marketing) o Design Studio. Se l’istanza di destinazione dispone di workspace, la seconda voce nel percorso sarà il nome del workspace proprietario. Il campo url mostra l'URL esplicito della risorsa nell'istanza designata. Questo non è un collegamento universale e per funzionare correttamente deve essere autenticato come utente. isSystem indica se la cartella è di sistema. Se questa opzione è impostata su true, la cartella stessa è di sola lettura, anche se le cartelle possono essere create come elementi secondari.
Crea e aggiorna
La creazione di cartelle è semplice e viene eseguita con un'applicazione/x-www-form-urlencoded POST che dispone di due parametri obbligatori, "name", una stringa e "parent", l'elemento padre in cui creare la cartella, ovvero un oggetto JSON incorporato con due membri, ID e tipo, Folder o Program, a seconda del tipo della cartella di destinazione. Facoltativamente, è possibile includere anche "description", una stringa, che può contenere fino a 2000 caratteri.
POST /rest/asset/v1/folders.json
Content-Type: application/x-www-form-urlencoded
parent={"id":416,"type":"Folder"}&name=Test 10 - deverly&description=This is a test
{
"success": true,
"warnings": [],
"errors": [],
"requestId": "111be#14e1f193e31",
"result": [
{
"name": "Test 10 - deverly",
"description": "This is a test",
"createdAt": "2015-06-23T06:27:04Z+0000",
"updatedAt": "2015-06-23T06:27:04Z+0000",
"url": "https://app-abm.marketo.com/#MF1070A1",
"folderId": {
"id": 454,
"type": "FOLDER"
},
"folderType": "Marketing Folder",
"parent": {
"id": 416,
"type": "FOLDER"
},
"path": "/Marketing Activities/Default/Test 10 - deverly",
"isArchive": false,
"isSystem": false,
"accessZoneId": 1,
"workspace": "Default",
"id": 454
}
]
}
Gli aggiornamenti alle cartelle vengono effettuati tramite un endpoint separato e descrizione, nome e isArchive sono parametri facoltativi per l'aggiornamento. Se isArchive viene modificato da un aggiornamento, la cartella verrà archiviata, se viene modificato in true, o non archiviata, se viene modificato in false, nell'interfaccia utente di Marketo. I programmi non possono essere aggiornati con questa API.
POST /rest/asset/v1/folder/{id}.json
Content-Type: application/x-www-form-urlencoded
type=Folder&description=This is a test (update 01)
{
"success": true,
"warnings": [],
"errors": [],
"requestId": "c5b2#14e1f3954bf",
"result": [
{
"name": "Learning - deverly",
"description": "This is a test (update 01)",
"createdAt": "2015-03-17T00:17:02Z+0000",
"updatedAt": "2015-06-23T07:02:07Z+0000",
"url": "https://app-abm.marketo.com/#MF1044A1",
"folderId": {
"id": 407,
"type": "FOLDER"
},
"folderType": "Marketing Folder",
"parent": {
"id": 15,
"type": "FOLDER"
},
"path": "/Marketing Activities/Default/Learning - deverly",
"isArchive": false,
"isSystem": false,
"accessZoneId": 1,
"workspace": "Default",
"id": 407
}
]
}
Elimina
Le eliminazioni possono essere eseguite su singole cartelle se vuote, ovvero se non contengono risorse o sottocartelle. Se una cartella è di tipo Program o il campo isSystem è impostato su true, non può essere eliminata con questa API.
POST /rest/asset/v1/folder/{id}/delete.json
{
"success": true,
"warnings": [],
"errors": [],
"requestId": "4180#14e1f3fc017",
"result": [
{
"id": 453
}
]
}