Questo articolo spiega come utilizzare l'endpoint Create content dell'API di SMARTFENSE per creare in modo automatizzato contenuti propri della sua organizzazione. Include i requisiti, la struttura della richiesta, la gestione delle immagini e i codici di risposta.
Cosa permette di fare questo endpoint?
L'endpoint Create content crea un contenuto dell'organizzazione a partire dallo stesso JSON utilizzato per caricare i contenuti predefiniti.
Attualmente accetta i seguenti tipi di contenuto:
- Newsletter
- Momenti educativi
- Phishing
- Ransomware
- Moduli interattivi
- Esami
- Sondaggi
- Corsi
Il tipo di contenuto viene definito nel percorso della richiesta. Il contenuto viene salvato come contenuto proprio dell'organizzazione ed è disponibile per essere utilizzato nelle campagne.
Importante: il contenuto viene creato solo nelle lingue incluse nel JSON. Tali lingue devono essere attive nell'organizzazione. L'API non traduce i testi.
Prerequisiti
- Disporre di un'applicazione registrata in Configuración > Integraciones > Aplicaciones registradas, con il relativo Client ID e Client Secret.
- Assegnare all'applicazione l'ambito (scope)
write_contents_create(Creare contenuti). - Utilizzare uno dei flussi OAuth 2.0 supportati: Authorization code o Client credentials.
- Conoscere l'identificativo del catalogo dell'applicazione in cui verrà salvato il contenuto.
Per maggiori informazioni su come registrare un'applicazione e ottenere il token di accesso, consulti l'articolo Integración de APIs en SMARTFENSE.
Endpoint
POST https://tenant.takesecurity.com/api/v1/contents/{content_type}Sostituisca tenant con il sottodominio della sua istanza di SMARTFENSE.
Intestazioni obbligatorie:
Authorization: Bearer <access_token>Content-Type: application/json
Parametro di percorso
| Parametro | Tipo | Obbligatorio | Descrizione |
|---|---|---|---|
content_type | string | Sì | Tipo di contenuto da creare. Determina lo schema del corpo della richiesta. |
Consulti i valori esatti di
content_typenella sezione Contenidos > Create content della documentazione ufficiale dell'API, disponibile all'indirizzohttps://tenant.takesecurity.com/api/schema/redoc/.
Struttura del corpo della richiesta
Il corpo della richiesta varia in base al tipo di contenuto. La documentazione lo presenta come One of con i seguenti schemi:
- NewsletterContentRequest
- TeachableContentRequest
- PhishingContentRequest
- RansomwareContentRequest
- TrainingContentRequest
- ExamContentRequest
- SurveyContentRequest
- CourseContentRequest
I campi comuni sono i seguenti:
| Campo | Tipo | Obbligatorio | Descrizione |
|---|---|---|---|
active | boolean | No | Definisce se il contenuto viene creato attivo (disponibile per le campagne) o inattivo (per rivederlo e attivarlo dalla piattaforma). Valore predefinito: true. |
difficulty | string | Sì | Difficoltà del contenuto: low, medium o high. |
compliance_mappings | array of objects | No | Clausole delle normative predefinite attivate dall'organizzazione. Ogni oggetto include normative_id e normative_clause_id. |
categories | array of integers | No | Identificativi delle categorie predefinite. |
themes | array of integers | No | Identificativi dei temi predefiniti. |
tags | array of integers | No | Identificativi delle etichette predefinite. |
catalog_id | integer | Sì | Catalogo in cui viene salvato il contenuto. |
estimated_minutes | integer (>= 0) | Sì | Minuti stimati di lettura. |
presentation_image_url | string | No | Immagine di presentazione. Può essere un file della piattaforma (predefinito o dell'organizzazione) o un indirizzo https. |
content | object | Sì | Testi di ciascuna lingua, identificati dal relativo codice (ad esempio, es-ar). |
Categorie, temi, etichette e normative devono essere predefiniti e disponibili per l'organizzazione. Il contenuto può essere salvato solo in un catalogo dell'applicazione.
Esempio di richiesta (newsletter)
{
"active": false,
"difficulty": "medium",
"compliance_mappings": [
{ "normative_id": 0, "normative_clause_id": 0 }
],
"categories": [0],
"themes": [0],
"tags": [0],
"catalog_id": 0,
"estimated_minutes": 5,
"presentation_image_url": "https://www.esempio.com/immagine.png",
"content": {
"es-ar": { }
}
}Sostituisca i valori
0con gli identificativi reali della sua organizzazione. La struttura interna di ciascuna lingua all'interno dicontentdipende dal tipo di contenuto. Per newsletter e momenti educativi corrisponde allo schema EmailTextsRequest. Consulti il dettaglio di ciascuno schema nella documentazione ufficiale dell'API.
Gestione delle immagini
Le immagini possono essere indicate in due modi:
- File della piattaforma: un file predefinito o proprio dell'organizzazione.
- Indirizzo https: un URL sulla porta 443 di un server pubblico.
Quando utilizza un indirizzo https, la piattaforma scarica l'immagine durante la stessa richiesta, prima di creare il contenuto. L'immagine viene salvata come immagine dell'organizzazione, come se fosse stata caricata dalla schermata. In questo modo, il contenuto non dipende dal sito di origine.
Se lo stesso indirizzo compare in più campi o lingue, viene scaricato una sola volta.
Limiti delle immagini
| Limite | Valore |
|---|---|
| Formati accettati | PNG, JPEG e GIF |
| Dimensione massima per immagine | 4 MB |
| Pixel massimi | 25 milioni |
| Fotogrammi massimi (GIF) | 100 |
| Indirizzi per contenuto | Fino a 10 |
| Reindirizzamenti per indirizzo | Fino a 3 |
| Tempo massimo di download | 12 secondi (tutti i download) |
Importante: se un'immagine non può essere scaricata, la risposta indica il campo interessato e il contenuto non viene creato.
Risposta positiva
Se la richiesta è corretta, l'API risponde con il codice 201 e il seguente corpo:
{
"content_code": "string",
"content_type": "string",
"name": "string"
}| Campo | Descrizione |
|---|---|
content_code | Codice del contenuto. È il valore che riceve l'API di scrittura delle campagne per assegnare il contenuto a una campagna. |
content_type | Tipo di contenuto, come nel percorso. |
name | Nome del contenuto. |
Conservi il content_code. Le servirà per assegnare il contenuto a una campagna tramite l'API.
Codici di errore
| Codice | Significato |
|---|---|
| 400 | Il JSON non è valido o fa riferimento a qualcosa che l'organizzazione non può utilizzare. La risposta indica quale campo e perché. |
| 405 | L'API non crea ancora contenuti di quel tipo. |
| 429 | L'applicazione ha superato il numero di richieste consentite al minuto, oppure ci sono troppi download di immagini in corso. L'intestazione Retry-After indica quanti secondi attendere prima di riprovare. |
💡 Buone pratiche
- Crei i contenuti con
"active": falseper rivederli nella piattaforma prima di utilizzarli nelle campagne. - Assegni all'applicazione solo lo scope write_contents_create se la sua unica funzione è creare contenuti.
- Verifichi che le lingue del JSON siano attive nell'organizzazione prima di inviare la richiesta.
- Ospiti le immagini su server pubblici stabili e con tempi di risposta rapidi, per non superare il limite di 12 secondi.
- Ottimizzi il peso delle immagini prima di inviarle per evitare rifiuti dovuti alla dimensione.
- In caso di errore 429, rispetti il tempo indicato in Retry-After prima di riprovare.
- Registri il content_code di ogni contenuto creato per automatizzare in seguito la creazione delle campagne.