SFMC Tips #347: Marketing Cloud Next, ricerca CMS con REST API

Con il rilascio della nuova funzionalità Winter ’27 per Marketing Cloud Next Growth & Advanced Edition, ora è possibile utilizzare le REST API per gestire i contenuti memorizzati nei CMS workspace.

Con questa Connect REST API è possibile eseguire principalmente le seguenti operazioni sui contenuti.

• Create
• Update
• Search

I canali di contenuto supportati includono i seguenti.

• Email
• SMS
• WhatsApp
• Mobile App

Oltre ai messaggi per ciascun canale, tramite l’API è possibile gestire anche contenuti come i seguenti.

• Video Content
• Content Block
• Tracked Link
• Form

Questo rende possibile recuperare, creare e aggiornare i contenuti di Marketing Cloud Next da sistemi esterni o da applicazioni proprietarie, automatizzando parte della gestione dei contenuti.

Quando ho saputo che questa funzionalità sarebbe stata rilasciata, la prima cosa che ho voluto provare è stata creare una funzione per cercare del testo all’interno del corpo dei contenuti.

Questa volta, quindi, vorrei creare un Lightning Web Component (LWC) utilizzando questa REST API.

*Per sicurezza, questo strumento è configurato come Read Only e utilizza esclusivamente richieste GET.

Aggiungendo l’LWC creato come tab in Marketing Cloud Next, ad esempio, è possibile eseguire da Salesforce operazioni come le seguenti.

Ricercare testo specifico contenuto nel corpo di un’email

• Campagna Winter ’27
• Preference Center

Ricercare contenuti che contengono un URL specifico

• Vecchio URL della landing page
• URL di test
• URL relativo a un dominio specifico

Ricercare codice AMPscript o Handlebars

• ContentBlockBykey
• getContentBlock
• Content Key specifica

Ricercare stringhe presenti anche all’interno dei Reusable Content Block

• Ricerca anche delle stringhe contenute nei Content Block non memorizzati direttamente nel corpo dell’email

Durante la ricerca, è inoltre possibile restringere il target utilizzando le seguenti condizioni.

Marketing Workspace

Content Type

• Email
• Email Template
• Email Content Block
• SMS
• WhatsApp
• In-App Message
• Tracked Link
• Form
• Image
• Video
• Document
• Landing Page, ecc.

Status

• All
• Published
• Revised
• Draft

Ad esempio, è possibile eseguire ricerche come:

• Cercare solo le email pubblicate per verificare se rimane un vecchio URL
• Controllare solo le email in bozza per verificare se rimane example.com
• Restringere la ricerca ai Content Block e verificare quali contengono un testo specifico

Inoltre, apertura del contenuto target dai risultati di ricerca tramite il pulsante “View” consente di verificare:

• Content Body JSON
• HTML grezzo
• Controlli QA (qualità) semplici
• Elenco dei link

I risultati della ricerca mostrano anche:

• Content Type
• Status
• Data ultima modifica
• Content Key

Questo rende più semplice identificare quale contenuto corrisponde alla ricerca.

Inoltre, lo strumento mostra il numero di API Request utilizzate, permettendo di usare lo strumento tenendo sotto controllo il consumo di REST API.

Informazioni sulle API Request

In questa ricerca, i dettagli del contenuto target vengono recuperati tramite la REST API in modo da poter verificare anche il corpo del contenuto. Per questo motivo, vengono consumate API Request di Salesforce in base al numero di elementi di contenuto ricercati.

Per questa ragione, i risultati della ricerca mostrano il numero di API Request utilizzate per quella specifica ricerca, come indicato di seguito.

Matches: 2
Content Scanned: 52
API Requests Used: 58

API Requests Used corrisponde al numero effettivo di chiamate API al CMS avvenute durante quel processo di ricerca.

Ad esempio, se c’è una grande quantità di contenuti da ricercare, o se un’email fa riferimento a Reusable Content Block, è necessario recuperare ulteriori dettagli sui contenuti, e quindi il numero di API Request aumenta di conseguenza.

Non si tratta di consumo di crediti come i Message Credits o i Data 360 Credits. Viene invece trattato come utilizzo di API Request dell’org Salesforce.

Se si effettuano ricerche frequenti su una grande quantità di contenuti, è opportuno considerare anche l’utilizzo complessivo delle API dell’org.

In Salesforce Enterprise Edition, per le licenze utente Salesforce standard, l’allocazione base è di 1.000 API Request per licenza ogni 24 ore. Inoltre, l’org dispone di un’allocazione base di 100.000 API Request, quindi il limite giornaliero per Enterprise Edition si calcola approssimativamente come segue.

100.000
 +
Numero di licenze Salesforce × 1.000
 +
Add-on API Call acquistato

Ad esempio, per un’org Enterprise Edition con 50 licenze utente Salesforce:

100.000 + (50 × 1.000)
= 150.000 API Request / 24 ore

Questa è una stima indicativa.

È possibile verificare l’utilizzo delle API Request per l’intera org Salesforce da [Setup] → [Company Information] → [API Requests, Last 24 Hours]. Qui è possibile controllare l’utilizzo delle ultime 24 ore e il limite API dell’org.

Passaggi di configurazione

Poiché questa implementazione avverrà tramite Agentforce Vibes, consiglio di provare prima l’implementazione in una Sandbox o SDO. Agentforce Vibes non è disponibile negli ambienti di produzione o nei Trailhead Playground, quindi non è possibile implementarla nello stesso modo in questi contesti.

0. Preparazione

1. Prima di tutto, scaricare localmente il seguente file ZIP.

2. Aprire Agentforce Vibes.

3. Una volta aperto Agentforce Vibes, trascinare il file ZIP nell’area evidenziata in rosso qui sotto.

4. Il file ZIP viene ora memorizzato come mostrato di seguito.

5. Successivamente, aprire il terminale dal menu.

6. Copiare e incollare le due righe di comando seguenti esattamente come sono nel terminale, tutte insieme, e premere Invio.

unzip MCN_Content_Utility_ReadOnly_v4_9.zip
bash mcn-content-utility/install.sh

7. Questo esegue le seguenti operazioni.

• Estrazione del file ZIP
• Deploy dei metadati MCN Content Utility
• Esecuzione del test Apex MCNContentUtilityControllerTest
• Assegnazione del permission set MCN_Content_Utility all’utente corrente

Attendere il completamento del processo: se tutto va a buon fine fino alla fine, è tutto ok.

1. Apertura di External Client App Manager

Successivamente, nella Quick Find del Setup, cercare e aprire External Client App Manager, e fare clic su New External Client App.

2. Informazioni di base

Inserire i seguenti valori.

• External Client App Name
  MCN Content Utility
• API Name
  MCN_Content_Utility
• Contact Email
  Il proprio indirizzo email (questo non implica che verrà inviata alcuna email specifica)
• Distribution State
  Local

3. API (Enable OAuth Settings)

Successivamente, attivare Enable OAuth.

Per il Callback URL, configurare temporaneamente il seguente URL.

https://login.salesforce.com/services/oauth2/callback

Si tratta anche dell’URL che Salesforce utilizza generalmente negli esempi di verifica OAuth per gli External Client App. Questo valore verrà modificato successivamente.

Aggiungere inoltre i seguenti due elementi da Available OAuth Scopes.

• Manage user data via APIs (api)
• Perform requests at any time (refresh_token, offline_access)

Il loro scopo in questo caso è il seguente.

• api → Per invocare la Connect REST API
• refresh_token / offline_access → Per continuare a utilizzarla dalla Named Credential senza dover effettuare nuovamente il login ogni volta

4. Security

Infine, in Security, attivare di nuovo le seguenti due impostazioni e salvare.

• Require secret for Web Server Flow
• Require secret for Refresh Token Flow

5. Verifica di Consumer Key e Consumer Secret

Dopo il salvataggio, fare clic su Consumer Key and Secret dalla tab Settings.

※ È richiesto il login come amministratore.

I seguenti valori ottenuti qui:

• Consumer Key
• Consumer Secret

verranno utilizzati nell’External Auth Identity Provider che creeremo tra poco, quindi lasciare aperta questa schermata.

6. Creazione di un External Auth Identity Provider

Nella Quick Find del Setup, cercare Named Credentials, quindi fare clic su New dalla tab External Auth Identity Providers.

Configurare come segue.

• Label
  MCN Content Utility Salesforce OAuth
• Name
  MCN_Content_Utility_Salesforce_OAuth
• Authentication Protocol
  OAuth 2.0
• Authentication Flow Type
  Authorization Code (Browser Flow)
• Client ID
  La Consumer Key verificata in precedenza
• Client Secret
  La Consumer Secret verificata in precedenza
• Pass client credentials in request body
  Off
• Use Proof Key for Code Exchange (PKCE) Extension
  On

Per Identity Provider URL, utilizzare l’URL My Domain dell’org Salesforce stessa.

Ad esempio, se è:

https://<Your-My-Domain>.my.salesforce.com

allora configurare quanto segue.

Authorize Endpoint URL

https://<Your-My-Domain>.my.salesforce.com/services/oauth2/authorize

Token Endpoint URL

https://<Your-My-Domain>.my.salesforce.com/services/oauth2/token

User Info Endpoint URL

https://<Your-My-Domain>.my.salesforce.com/services/oauth2/userinfo

Dopo aver configurato, salvare.

7. Impostazione del Callback URL nell’External Client App

Quando si salva l’External Auth Identity Provider, Salesforce genera un Callback URL.

Copiare questo URL.

Successivamente, andare su:

External Client App Manager → MCN Content Utility → tab Settings

e sostituire l’URL configurato temporaneamente:

https://login.salesforce.com/services/oauth2/callback

con il Callback URL appena ottenuto, e salvare.

Assicurarsi di fare clic sul pulsante Save. In caso contrario, l’autenticazione OAuth nel Passaggio 12 non funzionerà.

8. Creazione di una External Credential

Successivamente, aprire Named Credentials nel Setup, quindi fare clic su New dalla tab External Credentials.

Configurare come segue.

• Label
  MCN Content Utility OAuth
• Name
  MCN_Content_Utility_OAuth
• Authentication Protocol
  OAuth 2.0
• Authentication Flow Type
  Browser Flow
• Scope
  api refresh_token
• Identity Provider
  External Auth Identity Provider
• External Auth Identity Provider
  MCN Content Utility Salesforce OAuth

Dopo aver configurato, salvare.

9. Creazione di un Named Principal

Dopo il salvataggio, scorrere fino alla sezione Principals e fare clic su New.

Questa volta, per semplificare la verifica, utilizzeremo un Named Principal che condivide un’unica autenticazione.

• Parameter Name
  MCNContentUtility
• Sequence Number
  1
• Identity Type
  Named Principal

Salvare.

10. Concessione dell’accesso al Principal dal Permission Set

In realtà, durante l’installazione dello ZIP iniziale, il seguente permission set:

• MCN_Content_Utility

è stato assegnato all’utente corrente.

Aggiungeremo a questo permission set anche l’accesso all’External Credential Principal appena creato.

Dal Setup, aprire:

Permission Sets → MCN Content Utility → External Credential Principal Access

e fare clic su Edit.

Selezionare la voce seguente mostrata sotto Available External Credential Principals:

• MCN_Content_Utility_OAuth — MCNContentUtility

e salvare.

11. Creazione di una Named Credential

Aprire nuovamente Setup → Named Credentials, quindi fare clic su New dalla tab Named Credentials.

Configurare come segue.

• Label
  MCN Content API
• Name
  MCN_Content_API
• URL
  URL My Domain
  Esempio: https://na1772662003452.my.salesforce.com/
• External Credential
  MCN Content Utility OAuth
• Generate Authorization Header
  On

Assicurarsi qui che Name sia impostato su MCN_Content_API.

Questo perché l’Apex distribuito in questa occasione fa riferimento alla Named Credential utilizzando il nome: callout:MCN_Content_API

12. Autenticazione OAuth

Successivamente, aprire:

Named Credentials → External Credentials → MCN Content Utility OAuth

Nella sezione Principals, per:

• MCNContentUtility

fare clic su Authenticate dal menu delle azioni.

Quando appare la schermata di login Salesforce, effettuare il login come l’utente Salesforce a cui si vuole consentire l’accesso all’API in questa occasione, e concedere l’accesso.

※ Questa autenticazione OAuth verrà eseguita una sola volta da un amministratore.

Se completata correttamente, l’OAuth Token viene memorizzato nell’External Credential.

13. Creazione di un Lightning Component Tab

A questo punto, tutto è pronto per invocare l’API.

Successivamente, rendiamo l’LWC distribuito in questa occasione accessibile da Marketing Cloud Next.

Nel Setup, cercare e aprire Tabs, quindi scorrere fino a Lightning Component Tabs. Fare clic su New e configurare come segue.

• Lightning Component
  c:mcnContentUtility
• Tab Label
  Content Utility
• Tab Style
  Any

Dopo aver configurato, salvare.

Poiché l’LWC utilizzato in questa occasione ha configurato il target lightning__Tab, può essere utilizzato come Lightning Component Tab.

14. Aggiunta di Content Utility alla Marketing App

Tornare alla Marketing app in Marketing Cloud Next.

Fare clic sull’icona a forma di matita sul lato destro della barra di navigazione in alto nella schermata.

Fare clic su Add More Items, cercare:

• Content Utility

e aggiungerlo.

15. Test di connessione

Infine, aprire la tab Content Utility e verificarla.

Prima di tutto, selezionare il Workspace. Nel caso di un SDO, si tratta di Content Workspace for Marketing Cloud.

Successivamente, Content Type è impostato di default su Email. Avrebbe potuto essere All, ma in un ambiente con una grande quantità di contenuti, verrebbero cercati anche contenuti non necessari. Consiglio di configurare sempre questa impostazione in base allo scopo desiderato.

Per Status, ci possono essere casi in cui non si desidera che appaiano nei risultati bozze non necessarie (Draft), quindi al momento è possibile filtrare solo per contenuti pubblicati (Published).

È anche possibile verificare un elenco di contenuti in stato Revised. In tal caso, eseguire la ricerca lasciando vuoto il campo di testo di ricerca.

Questa volta, ogni ricerca è limitata di default a “100 elementi.”

Ad esempio, se ci fossero 10.000 elementi di contenuto CMS, ricercarli tutti consumerebbe pesantemente le API Request.

Per le org con una grande quantità di contenuti, è anche possibile cercare fino a 1.000 elementi contemporaneamente.

Infine, inserendo una parola chiave presente nel corpo del contenuto, come del testo o un URL, nel campo di testo di ricerca, è possibile ricercare i contenuti CMS.

Dai risultati della ricerca, è anche possibile navigare verso ciascun elemento di contenuto. Facendo clic su View, la pagina scorre automaticamente verso il basso, consentendo di verificare il Content Body, la qualità, i link e altre informazioni.

Conclusione

Con questo meccanismo, poiché il contenuto di ciascun elemento target deve essere recuperato e verificato uno alla volta, un certo numero di API Request verrà inevitabilmente consumato.

Pertanto, in un ambiente con una quantità di contenuti molto elevata, è importante restringere il più possibile il target della ricerca.

In particolare, ritengo che Content Type dovrebbe sempre essere restrittivo quando si utilizza questo strumento.

In questo strumento, il valore predefinito è Email. Tuttavia, ad esempio, se Content Type è impostato su All, diventano oggetto di ricerca non solo le email, ma anche immagini, video, documenti e altri contenuti.

Se si desidera cercare solo il corpo delle email ma vengono recuperati anche questi altri elementi di contenuto, potrebbero essere consumate API Request non necessarie.

Creando e testando effettivamente questo strumento, ho scoperto che, sebbene sia comodo, in base a come viene utilizzato bisogna prestare attenzione anche al consumo di API Request.

Detto ciò, piuttosto che eseguire questo tipo di ricerca molte volte ogni giorno, penso che verrà utilizzato principalmente quando necessario, ad esempio quando si desidera:

• Trovare un URL specifico all’interno di contenuti passati
• Verificare le email che utilizzano una stringa specifica
• Controllare solo i contenuti in stato Revised

Inoltre, poiché questo strumento utilizza un permission set per controllare chi può utilizzarlo, penso che sia sufficientemente pratico se gestito in modo tale che solo gli utenti consapevoli del consumo di API Request siano autorizzati a usarlo.

All’inizio intendevo creare un semplice strumento di ricerca CMS, ma testandolo effettivamente tramite la REST API ho scoperto anche vari aspetti da considerare, come il fatto che la ricerca standard non può cercare tutto il corpo dei contenuti, i riferimenti ai Content Block e il consumo di API Request.

In conclusione, questo si è rivelato un argomento con parecchi punti a cui prestare attenzione, ma spero che i risultati di questa verifica possano essere utili anche a chi sta cercando di creare uno strumento simile utilizzando la REST API di Marketing Cloud Next.

È tutto per questa volta.

Restate collegati per altri consigli su Salesforce Marketing Cloud! 😎

Nobuyuki Watanabe

---

Tradotto e adattato da SFMC Tips #347 : Marketing Cloud Next: Search CMS Content with REST API di Nobuyuki Watanabe (@marketingcloudtips), pubblicato originariamente su Medium. Traduzione autorizzata dall’autore.