Configurare Developer Console e Postman

In questa lezione, imposterai un progetto nella Console per sviluppatori di Adobe e scaricherai le raccolte Postman in modo da poter iniziare a utilizzare le API di Platform.

Per completare gli esercizi API in questa esercitazione, scarica l’app Postman per il tuo sistema operativo. Anche se non è necessario per utilizzare le API di Experience Platform, Postman semplifica i flussi di lavoro API e Adobe Experience Platform fornisce decine di raccolte Postman per aiutarti a eseguire le chiamate API e imparare come funzionano. Il resto di questo tutorial presuppone una certa conoscenza di lavoro di Postman. Per assistenza, fai riferimento alla documentazione Postman.

Platform è la prima API integrata. Sebbene esistano anche opzioni di interfaccia per tutte le attività principali, a un certo punto potrebbe essere utile utilizzare l’API Platform. Ad esempio, per acquisire i dati, spostare gli elementi tra le sandbox, automatizzare le attività di routine o utilizzare nuove funzionalità di Platform prima che l’interfaccia utente sia stata creata.

Al di fuori di questa esercitazione, potrebbe essere necessario utilizzare l’API Platform per architetti di dati e data engineer .

Autorizzazioni necessarie

Nella lezione Configurare le autorizzazioni , puoi impostare tutti i controlli di accesso necessari per completare la lezione.

Configurare Adobe Developer Console

  1. Crea una cartella sul computer locale denominata Luma Tutorial Assets per i file utilizzati nell’esercitazione.

  2. Apri Adobe Developer Console

  3. Accedi e conferma di essere nell'organizzazione corretta

  4. Selezionare Crea nuovo progetto nel menu Avvio rapido.

    Crea nuovo progetto

  5. Nel progetto appena creato, seleziona il pulsante Aggiungi al progetto , quindi seleziona API

    Configurazione dell’API per progetti Adobe Developer Console

  6. Filtrare l’elenco selezionando Adobe Experience Platform

  7. Nell'elenco delle API disponibili, seleziona API Experience Platform e seleziona Avanti.

    Configurazione dell’API per progetti Adobe Developer Console

  8. Per l’autenticazione da sistemi esterni come Postman, è necessaria una coppia di chiavi pubblica/privata. Per generare una nuova coppia di chiavi, selezionare Opzione 1 e premere il pulsante Genera coppia di chiavi

    Configurazione dell’API per progetti Adobe Developer Console

  9. Quando le chiavi sono pronte, potrebbe essere richiesto di scaricare le chiavi sul computer locale. Salva le chiavi inserite in config.zip nella cartella Luma Tutorial Assets. Ne avremo bisogno nel prossimo esercizio.

  10. Una volta generata la chiave, la chiave pubblica verrà aggiunta automaticamente al progetto come mostrato nella schermata . Selezionare il pulsante Avanti.

     Visualizza dopo la generazione e la selezione della chiave

  11. Seleziona il profilo di prodotto Luma Tutorial Platform e fai clic sul pulsante Salva API configurata

    Seleziona profilo prodotto

  12. Ora è stato creato il tuo progetto Console per sviluppatori .

  13. Nella sezione Prova della pagina, seleziona Scarica per Postman, quindi seleziona Account di servizio (JWT) per scaricare il file json dell'ambiente Postman . Salva la cartella service.postman_environment.json nella cartella Luma Tutorial Assets.

    Configurazione dell’API per progetti Adobe Developer Console

    NOTA

    Gli amministratori di sistema della tua organizzazione possono visualizzare il progetto come "Credenziale API" nel profilo di prodotto nell’Admin Console

    Configurazione dell’API per progetti Adobe Developer Console

Avrete notato che al progetto è stato assegnato un numero, ad esempio "Progetto 12":

  1. Seleziona il numero del progetto nella breadcrumb.

  2. Selezionare il pulsante Modifica progetto

  3. Modifica il Titolo progetto in Luma Tutorial API Project (aggiungi il tuo nome alla fine, se più persone della tua azienda stanno seguendo questa esercitazione)

  4. Selezionare il pulsante Salva

    Configurazione dell’API per progetti Adobe Developer Console

Imposta Postman

  1. Scarica e installa Postman

  2. Apri Postman e importa il file di ambiente json scaricato, service.postman_environment.json
    Ambiente di importazione di Adobe Developer Console

  3. In Postman, seleziona l’ambiente nel menu a discesa in alto a destra e seleziona l’icona eye per visualizzare le variabili di ambiente. Le variabili ACCESS_TOKEN, PRIVATE_KEY e JWT_TOKEN sono vuote:

    Configurazione dell’API per progetti Adobe Developer Console

Aggiorna nome ambiente

Poiché il nome esportato dell’ambiente da Developer Console viene generato in modo casuale, assegnagli un nome più descrittivo in modo da non confondere gli ambienti in un secondo momento quando inizi a lavorare sull’implementazione effettiva di Platform:

  1. Con la schermata delle variabili di ambiente ancora aperta, seleziona Modifica in alto a destra

  2. Aggiorna Nome ambiente a Luma Tutorial

  3. Lascia aperta la modalità Gestisci ambienti in modalità di modifica, poiché la modificheremo ulteriormente nel passaggio successivo

    Aggiorna il nome dell'ambiente Postman

Aggiungi la chiave privata

Ora è il momento di aggiungere il valore PRIVATE_KEY all’ambiente Postman

  1. Estrai il file config.zip scaricato che è stato generato nell’esercizio precedente durante la creazione del progetto Console per sviluppatori. Questo file zip contiene due file:
    • private.key
    • certificate_pub.crt
  2. Apri il file private.key in un editor di testo e copia il contenuto.
  3. In Postman, sul modale Gestisci ambienti > Modifica ancora aperto dall'ultimo esercizio, incolla i valori copiati davanti alle colonne PRIVATE_KEY in Valore iniziale e Valore corrente.
  4. Selezionare il pulsante Aggiorna per salvare PRIVATE_KEY e il nome dell'ambiente aggiornato.
    Chiave privata incollata in Postman

Aggiungi i token JWT e Access

Adobe fornisce un set completo di raccolte Postman per aiutarti a esplorare le API di Experience Platform. Queste raccolte si trovano nell' repository GitHub di Adobe Experience Platform Postman Samples. Aggiungi ai segnalibri questo repository in quanto lo utilizzi più volte durante questo tutorial e successivamente durante l'implementazione di Experience Platform per la tua azienda.

La prima raccolta funziona con le API Adobe Identity Management Service (IMS). È un modo conveniente per popolare i JWT_TOKEN e ACCESS_TOKEN da Postman destinati a casi d'uso non di produzione, ad esempio per completare questa esercitazione nella sandbox. In alternativa, puoi generare il token JWT all’interno di Adobe Developer Console. Tuttavia, poiché scade regolarmente, l’utilizzo di questa raccolta consente di aggiornarla senza dover rivisitare nuovamente Adobe Developer Console durante il completamento di questa esercitazione.

AVVERTENZA

Come indicato in Adobe Identity Management Service APIs README, i metodi di generazione indicati sono adatti per uso non di produzione. La firma locale carica una libreria JavaScript da un host di terze parti e la firma remota invia la chiave privata a un servizio Web di proprietà e gestito da Adobe. Sebbene Adobe non memorizzi questa chiave privata, le chiavi di produzione non devono mai essere condivise con nessuno.

Per generare i token:

  1. Scarica la raccolta di generazione token di accesso alla Console per sviluppatori nella cartella Luma Tutorial Assets

  2. Importa la raccolta in Postman

  3. Seleziona la richiesta IMS: JWT Genera + Auth tramite User Token e seleziona Invia

    Richiedere i token

  4. Le JWT_TOKEN e ACCESS_TOKEN vengono compilate automaticamente nelle variabili di ambiente di Postman.

    Postman

Aggiungere il nome della sandbox e l’ID tenant

Le variabili SANDBOX_NAME e TENANT_ID e CONTAINER_ID non vengono fornite nell’esportazione dell’ambiente da Adobe Developer Console, pertanto vengono aggiunte manualmente:

  1. In Postman, apri il modale Variabili di ambiente

  2. Seleziona il collegamento Modifica a destra del nome dell'ambiente

  3. Nel Aggiungi nuovo campo variabile, immetti SANDBOX_NAME

  4. In entrambi i campi di valore, immetti luma-tutorial, il nome assegnato alla sandbox nella lezione precedente. Se hai usato un nome diverso per la sandbox, ad esempio luma-tutorial-ignatiusjreilly, assicurati di utilizzare tale valore.

  5. Nel Aggiungi nuovo campo variabile, immetti TENANT_ID

  6. Passa al browser web e cerca l’ID tenant della tua azienda andando all’interfaccia di Experience Platform ed estraendo la parte dell’URL dopo il simbolo @. Ad esempio, il mio ID tenant è techmarketingdemos ma il tuo è diverso:

    Ottenimento dell’ID tenant dall’URL dell’interfaccia di Platform

  7. Copia questo valore e torna alla schermata Postman Manage Environments (Gestisci ambienti)

  8. Incolla l’ID tenant in entrambi i campi del valore

  9. Nel Aggiungi nuovo campo variabile, immetti CONTAINER_ID

  10. Inserisci global in entrambi i campi del valore

    NOTA

    CONTAINER_ID è un campo il cui valore viene modificato più volte durante l’esercitazione. Quando si utilizza global, l’API interagisce con gli elementi forniti da Adobe nel tuo account Platform. Quando si utilizza tenant, l’API interagisce con i propri elementi personalizzati.

  11. Seleziona il pulsante Aggiorna per salvare le variabili

    I campi SANDBOX_NAME, TENANT_ID e CONTAINER_ID sono stati aggiunti come variabili di ambiente

Ora puoi chiudere la finestra modale Gestisci ambienti .

Effettuare una chiamata API Platform

Ora confermiamo di aver configurato tutto correttamente effettuando una chiamata API.

Apri l’altro gruppo di raccolte di Experienci Platform Postman in GitHub, il experience-platform-postman-amples. Ci sono molte raccolte in questa pagina, relative a varie funzioni di Platform.

Scarichiamo le raccolte in base alle esigenze per questa esercitazione. Questo archivio GitHub ti sarà utile dopo questa esercitazione quando inizi a implementare Platform per la tua azienda, pertanto ti consigliamo vivamente di segnalarlo nei segnalibri.

Ora, effettuiamo la nostra prima chiamata API:

  1. Scarica la raccolta API del Registro di sistema dello schema nella cartella Luma Tutorial Assets
  2. Importa in Postman
  3. Apri API del Registro di sistema dello schema > Classi > Elenca tutte le classi nel contenitore specificato
  4. Osserva le schede Parametri e Intestazioni e osserva come includono alcune delle variabili di ambiente immesse in precedenza.
  5. Seleziona il campo Intestazioni > Accetta valore e modificalo in application/vnd.adobe.xed-id+json. Le API del Registro di sistema dello schema richiedono uno dei valori di intestazione Accept specificati che forniscono formati diversi nella risposta.
  6. Seleziona Invia per effettuare la tua prima chiamata API Platform.

Speriamo di avere una risposta 200 OK di successo contenente un elenco delle classi XDM standard disponibili nella sandbox, come illustrato di seguito.

Prima chiamata API in Postman

Se la chiamata non è riuscita, effettua il debug utilizzando i dettagli della risposta dell’errore nella chiamata API e controlla i passaggi precedenti. Se ti trovi bloccato, chiedi aiuto nel Forum della community o utilizza il collegamento a destra di questa pagina per "Segnala un problema".

Risorse aggiuntive

Con le autorizzazioni Platform, la sandbox e la configurazione di Postman, sei pronto a modellare i dati in schemas!

In questa pagina