Documentazione Guida per gli sviluppatori di Target

Gestire il catalogo Recommendations tramite API

Last update: Sat Jul 20 2024 00:00:00 GMT+0000 (Coordinated Universal Time)

Creato per:

Sviluppatore

Mentre ti assicuri di soddisfare i requisiti per utilizzare l'API di Recommendations, hai imparato a generare un token di accesso utilizzando il flusso di autenticazione JWT per utilizzare le API di amministrazione Adobe Target su Adobe Developer Console.

È ora possibile utilizzare le API Recommendations per aggiungere, aggiornare o eliminare elementi nel catalogo dei consigli. Come per le altre API amministratore di Adobe Target, le API Recommendations richiedono l’autenticazione.

NOTE

Invia la richiesta IMS: JWT Generate + Auth via User Token ogni volta che devi aggiornare il token di accesso per l'autenticazione, poiché scade dopo 24 ore. Per istruzioni, consulta Configurare l'autenticazione API Adobe.

JWT3ff

Prima di continuare, ottenere la raccolta Postman di Recommendations.

Creazione e aggiornamento di elementi con l’API Save Entities

Per popolare il database di prodotti Recommendations utilizzando l'API anziché un feed di prodotto CSV o richieste Target attivate sulle pagine dei prodotti, utilizza l'API Salva entità. Questa richiesta aggiunge o aggiorna un elemento in un singolo ambiente Target. La sintassi è:

POST https://mc.adobe.io/{{TENANT_ID}}/target/recs/entities

Ad esempio, Salva entità può essere utilizzato per aggiornare gli articoli ogni volta che vengono raggiunte determinate soglie, ad esempio soglie di inventario o di prezzo, per contrassegnare tali articoli ed evitare che vengano consigliati.

Passa a Target > Setup > Hosts > CONTROL Environments per ottenere l'ID ambiente di destinazione in cui desideri aggiungere o aggiornare un elemento.
Verificare che TENANT_ID e API_KEY facciano riferimento alle variabili di ambiente Postman stabilite in precedenza. Utilizza l’immagine seguente per il confronto. Se necessario, modifica le intestazioni e il percorso nella richiesta API in modo che corrispondano a quelli nell’immagine seguente.

Immetti il codice JSON come raw in Body. Non dimenticare di specificare l'ID ambiente utilizzando la variabile environment. Nell’esempio seguente, l’ID ambiente è 6781.

SalvaEntità4.png

Di seguito è riportato un esempio di JSON che aggiunge entity.id kit2001 con valori di entità associati per un prodotto Toaster Oven nell’ambiente 6781.

code language-none

code language-none
`{ "entities": [{ "name": "Toaster Oven", "id": "kit2001", "environment": 6781, "categories": [ "housewares:appliances" ], "attributes": { "inventory": 77, "margin": 23, "message": "crashing helicopter", "pageUrl": "www.foobar.foo.com/helicopter.html", "thumbnailUrl": "www.foobar.foo.com/helicopter.jpg", "value": 19.2 } }] }`

    {
    "entities": [{
            "name": "Toaster Oven",
            "id": "kit2001",
            "environment": 6781,
            "categories": [
                "housewares:appliances"
            ],
            "attributes": {
                "inventory": 77,
                "margin": 23,
                "message": "crashing helicopter",
                "pageUrl": "www.foobar.foo.com/helicopter.html",
                "thumbnailUrl": "www.foobar.foo.com/helicopter.jpg",
               "value": 19.2
            }
        }]
    }

Fare clic su Send. Dovresti ricevere la seguente risposta.

SalvaEntità5.png

L’oggetto JSON può essere ridimensionato per inviare più prodotti. Ad esempio, questo JSON specifica due entità.

code language-none

code language-none
{ "entities": [{ "name": "Toaster Oven", "id": "kit2001", "environment": 6781, "categories": [ "housewares:appliances" ], "attributes": { "inventory": 89, "margin": 11, "message": "Toaster Oven", "pageUrl": "www.foobar.foo.com/helicopter.html", "thumbnailUrl": "www.foobar.foo.com/helicopter.jpg", "value": 102.5 } }, { "name": "Blender", "id": "kit2002", "environment": 6781, "categories": [ "housewares:appliances" ], "attributes": { "inventory": 36, "margin": 5, "message": "Blender", "pageUrl": "www.foobar.foo.com/helicopter.html", "thumbnailUrl": "www.foobar.foo.com/helicopter.jpg", "value": 54.5 } } ] }

    {
        "entities": [{
                "name": "Toaster Oven",
                "id": "kit2001",
                "environment": 6781,
                "categories": [
                    "housewares:appliances"
                ],
                "attributes": {
                    "inventory": 89,
                    "margin": 11,
                    "message": "Toaster Oven",
                    "pageUrl": "www.foobar.foo.com/helicopter.html",
                    "thumbnailUrl": "www.foobar.foo.com/helicopter.jpg",
                    "value": 102.5
                }
            },
            {
                "name": "Blender",
                "id": "kit2002",
                "environment": 6781,
                "categories": [
                    "housewares:appliances"
                ],
                "attributes": {
                    "inventory": 36,
                    "margin": 5,
                    "message": "Blender",
                    "pageUrl": "www.foobar.foo.com/helicopter.html",
                    "thumbnailUrl": "www.foobar.foo.com/helicopter.jpg",
                    "value": 54.5
                }
            }
        ]
    }

Ora tocca a te! Utilizza l'API Save Entities per aggiungere i seguenti elementi al catalogo. Utilizza il JSON di esempio riportato sopra come punto di partenza. Sarà necessario estendere il JSON per includere altre entità.

Sembra che gli ultimi due elementi non appartengano. Ispezioniamoli utilizzando l'API Get Entity e, se necessario, eliminiamoli utilizzando l'API Delete Entities.

Ottenere i dettagli dell’elemento con l’API Get Entity

Per recuperare i dettagli di un elemento esistente, utilizzare Ottieni API entità. La sintassi è:

GET https://mc.adobe.io/{{TENANT_ID}}/target/recs/entities/[entity.id]

I dettagli di entità possono essere recuperati solo per una singola entità alla volta. È possibile utilizzare Ottieni entità per confermare gli aggiornamenti apportati nel catalogo come previsto o per controllare in altro modo il contenuto del catalogo.

Nella richiesta API, specifica l'ID entità utilizzando la variabile entityId. L’esempio seguente restituisce i dettagli per l’entità il cui entityId=kit2004.
Verificare che TENANT_ID e API_KEY facciano riferimento alle variabili di ambiente Postman stabilite in precedenza. Utilizza l’immagine seguente per il confronto. Se necessario, modifica le intestazioni e il percorso nella richiesta API in modo che corrispondano a quelli nell’immagine seguente.

Invia la richiesta.

GetEntity3
Se ricevi un errore che indica che l’entità non è stata trovata, come mostrato nell’esempio precedente, verifica di inviare la richiesta all’ambiente Target corretto.

note note
NOTE
Se non viene specificato alcun ambiente in modo esplicito, Get Entity tenta di ottenere l'entità solo dall'ambiente predefinito. Se desideri effettuare il pull da un ambiente diverso da quello predefinito, devi specificare l’ID ambiente.

Se necessario, aggiungi il parametro environmentId e invia nuovamente la richiesta.
Invia un'altra richiesta Get Entity, questa volta per controllare l'entità il cui entityId=kit2005.

Supponiamo di decidere che queste entità devono essere rimosse dal catalogo. Utilizzare l'API Delete Entities.

Eliminazione di elementi con l’API Elimina entità

Per rimuovere elementi dal catalogo, utilizzare l'API Elimina entità. La sintassi è:

DELETE https://mc.adobe.io/{{TENANT_ID}}/target/recs/entities?ids=[comma-delimited-entity-ids]&environment=[environmentId]

WARNING

L’API Elimina entità elimina le entità a cui si fa riferimento dagli ID specificati. Se non viene fornito alcun ID di entità, vengono eliminate tutte le entità nell’ambiente specificato. Se non viene fornito alcun ID ambiente, le entità verranno eliminate da tutti gli ambienti. Usalo con cautela!

Passa a Target > Setup > Hosts > Environments per ottenere l'ID ambiente di destinazione da cui desideri eliminare gli elementi.
Nella richiesta API, specifica gli ID entità delle entità da eliminare, utilizzando la sintassi &ids=[comma-delimited-entity-ids] (un parametro di query). Quando si eliminano più entità, separa gli ID utilizzando le virgole.
Specificare l'ID ambiente utilizzando la sintassi &environment=[environmentId]. In caso contrario, le entità verranno eliminate in tutti gli ambienti.
Verificare che TENANT_ID e API_KEY facciano riferimento alle variabili di ambiente Postman stabilite in precedenza. Utilizza l’immagine seguente per il confronto. Se necessario, modifica le intestazioni e il percorso nella richiesta API in modo che corrispondano a quelli nell’immagine seguente.
Invia la richiesta.
Verificare i risultati utilizzando Get Entity, che a questo punto dovrebbe indicare che non è possibile trovare le entità eliminate.

Congratulazioni! Ora puoi utilizzare le API di Recommendations per creare, aggiornare, eliminare e ottenere dettagli sulle entità nel catalogo. Nella sezione successiva verrà illustrato come gestire i criteri personalizzati.

<!— Avanti "Gestisci criteri personalizzati" > —>

recommendation-more-help

6906415f-169c-422b-89d3-7118e147c4e3