7.7 API di Query Service

Obiettivo

  • Utilizzare l'API di Query Service per gestire i modelli di query e le pianificazioni di query

Contesto

In questo esercizio eseguirete chiamate API per gestire i modelli di query e le pianificazioni di query utilizzando una raccolta Postman. Definirete modelli di query, eseguirete query regolari e query CTAS. Una query CTAS (create una tabella come query di selezione) memorizza il set di risultati in un set di dati esplicito. Anche se le query regolari sono memorizzate in un dataset implicito (o generato dal sistema), solitamente esportato in formato parquet.

Documentazione

7.7.1 API di Query Service

L'API di Query Service consente di gestire le query non interattive nel lago dati Adobe Experience Platform.

Non interattivo significa che una richiesta di esecuzione di una query non darà luogo a una risposta immediata. La query verrà elaborata e il relativo set di risultati verrà memorizzato in modo implicito o esplicito (CTAS: crea tabella come set di dati selezionato).

7.7.2 Esempio di query

Come query di esempio si utilizzerà la prima query elencata in 7.3 - Query, query, query… e churn analysis:

Quante visualizzazioni di prodotto abbiamo quotidianamente?

SQL

select date_format( timestamp , 'yyyy-MM-dd') AS Day,
       count(*) AS productViews
from   demo_system_event_dataset_for_website_global_v1_1
where  --aepTenantId--.demoEnvironment.brandName IN ('Luma Telco', 'Citi Signal')
and eventType = 'commerce.productViews'
group by Day
limit 10;

7.7.3 Query

Apri Postman sul tuo computer. Come parte del Modulo 3, avete creato un ambiente Postman e importato una raccolta Postman. Seguire le istruzioni riportate in Esercizio 3.3.3 nel caso in cui non lo abbiate ancora fatto.

Come parte della raccolta Postman che avete importato, vedrete una cartella 3. Servizio query. Se non trovi questa cartella, scarica di nuovo la raccolta Postman e reimporta la raccolta in Postman come indicato in Esercizio 3.3.3.

QS

NOTA

Al momento, solo la cartella 1. Le query contengono richieste. Altre richieste verranno aggiunte in una fase del livello.

Aprite la cartella e conoscete le chiamate API di Query Service per eseguire, monitorare e scaricare il set di risultati della query.

Una chiamata POST a [/query/query/query] con il payload seguente attiverà l'esecuzione della query;

7.7.3.1 Crea query

Fate clic sulla richiesta denominata 1.1 QS - Create Query e andate a Intestazioni. Vedrete questo:

Segmentazione

Concentriamoci su questo campo di intestazione:

Chiave Valore
x-sandbox-name --module7sandbox--
NOTA

Dovete specificare il nome della sandbox Adobe Experience Platform in uso. Il campo di intestazione x-sandbox-name deve essere --module7sandbox--.

Andate alla sezione Body della richiesta. In Body di questa richiesta, sono disponibili le seguenti informazioni:

Segmentazione

{
    "name" : "ldap - QS API demo - Citi Signal - Product Views Per Day",
	"description": "ldap - QS API demo - Citi Signal - Product Views Per Day",
	"dbName": "module7:all",
	"sql": "select date_format( timestamp , 'yyyy-MM-dd') AS Day, count(*) AS productViews from demo_system_event_dataset_for_website_global_v1_1 where _experienceplatform.demoEnvironment.brandName IN ('Luma Telco', 'Citi Signal') and eventType = 'commerce.productViews' group by Day limit 10"
}

Attenzione: aggiornare la variabile name nella richiesta seguente sostituendo ldap con il ldap specifico.

Dopo aver aggiunto il ldap specifico, il corpo deve essere simile al seguente:

{
    "name" : "vangeluw - QS API demo - Citi Signal - Product Views Per Day",
	"description": "vangeluw - QS API demo - Citi Signal - Product Views Per Day",
	"dbName": "module7:all",
	"sql": "select date_format( timestamp , 'yyyy-MM-dd') AS Day, count(*) AS productViews from demo_system_event_dataset_for_website_global_v1_1 where _experienceplatform.demoEnvironment.brandName IN ('Luma Telco', 'Citi Signal') and eventType = 'commerce.productViews' group by Day limit 10"
}
NOTA

La chiave dbName nel corpo JSON di cui sopra fa riferimento alla sandbox utilizzata nell'istanza di Adobe Experience Platform. Se si utilizza la sandbox di PROD, dbName deve essere prod:all, se si utilizza un'altra sandbox come ad esempio module7, dbName deve essere uguale a module7:all.

Fare clic sul pulsante blu Invia per creare il segmento e visualizzare i risultati.

Segmentazione

In caso di esito positivo, la richiesta POST restituirà la seguente risposta:

{
    "isInsertInto": false,
    "request": {
        "dbName": "module7:all",
        "sql": "select date_format( timestamp , 'yyyy-MM-dd') AS Day, count(*) AS productViews from demo_system_event_dataset_for_website_global_v1_1 where _experienceplatform.demoEnvironment.brandName IN ('Luma Telco', 'Citi Signal') and eventType = 'commerce.productViews' group by Day limit 10",
        "name": "vangeluw - QS API demo - Citi Signal - Product Views Per Day",
        "description": "vangeluw - QS API demo - Citi Signal - Product Views Per Day"
    },
    "clientId": "5a143b5ae4aa4631a1f3b09cd051333f",
    "state": "SUBMITTED",
    "rowCount": 0,
    "errors": [],
    "isCTAS": false,
    "version": 1,
    "id": "8f0d7f25-f7aa-493b-9792-290f884a7e5b",
    "elapsedTime": 0,
    "updated": "2021-01-20T13:23:13.951Z",
    "client": "API",
    "userId": "A3392DB95FFF08EE0A495E87@techacct.adobe.com",
    "created": "2021-01-20T13:23:13.951Z",
    "_links": {
        "self": {
            "href": "https://platform-va7.adobe.io/data/foundation/query/queries/8f0d7f25-f7aa-493b-9792-290f884a7e5b",
            "method": "GET"
        },
        "soft_delete": {
            "href": "https://platform-va7.adobe.io/data/foundation/query/queries/8f0d7f25-f7aa-493b-9792-290f884a7e5b",
            "method": "PATCH",
            "body": "{ \"op\": \"soft_delete\"}"
        },
        "cancel": {
            "href": "https://platform-va7.adobe.io/data/foundation/query/queries/8f0d7f25-f7aa-493b-9792-290f884a7e5b",
            "method": "PATCH",
            "body": "{ \"op\": \"cancel\"}"
        }
    }
}

L'attuale stato della query è INVIATO, una volta eseguito il relativo stato diventerà SUCCESS.

È inoltre possibile consultare le query inviate tramite l'interfaccia utente di Adobe Experience Platform, aprire Adobe Experience Platform, passare a Query, Log e selezionare la query:

Segmentazione

7.7.3.2 Ottenere le query

Fare clic sulla richiesta denominata 1.2 QS - Get Queries e passare a Headers. Vedrete questo:

Segmentazione

Concentriamoci su questo campo di intestazione:

Chiave Valore
x-sandbox-name --module7sandbox--
NOTA

Dovete specificare il nome della sandbox Adobe Experience Platform in uso. Il campo di intestazione x-sandbox-name deve essere --module7sandbox--.

Vai a Params. Vedrete questo:

Segmentazione

Il parametro order by consente di specificare un ordinamento basato sulla proprietà created. Osservate l'accesso '-' davanti alla creazione, il che significa che l'ordine in cui viene restituito l'elenco di query utilizzerà la data creata nell'ordine decrescente. La query deve essere in cima all'elenco.

Fare clic sul pulsante blu Invia per creare il segmento e visualizzare i risultati.

Segmentazione

In caso di esito positivo, la richiesta restituirà una risposta simile a quella riportata di seguito. Lo stato della risposta può essere INVIATO, IN_PROGRESS o SUCCESSO. Potrebbero essere necessari alcuni minuti prima che la query abbia uno stato SUCCESS. È possibile ripetere l'invio di questa richiesta più volte, fino a visualizzare lo stato SUCCESS.

{
    "queries": [
        {
            "isInsertInto": false,
            "request": {
                "dbName": "module7:all",
                "sql": "select date_format( timestamp , 'yyyy-MM-dd') AS Day, count(*) AS productViews from demo_system_event_dataset_for_website_global_v1_1 where _experienceplatform.demoEnvironment.brandName IN ('Luma Telco', 'Citi Signal') and eventType = 'commerce.productViews' group by Day limit 10",
                "name": "vangeluw - QS API demo - Citi Signal - Product Views Per Day",
                "description": "vangeluw - QS API demo - Citi Signal - Product Views Per Day"
            },
            "clientId": "5a143b5ae4aa4631a1f3b09cd051333f",
            "state": "SUCCESS",
            "rowCount": 1,
            "errors": [],
            "isCTAS": false,
            "version": 1,
            "id": "8f0d7f25-f7aa-493b-9792-290f884a7e5b",
            "elapsedTime": 217481,
            "updated": "2021-01-20T13:26:51.432Z",
            "client": "API",
            "userId": "A3392DB95FFF08EE0A495E87@techacct.adobe.com",
            "created": "2021-01-20T13:23:13.951Z",
            "_links": {
                "self": {
                    "href": "https://platform-va7.adobe.io/data/foundation/query/queries/8f0d7f25-f7aa-493b-9792-290f884a7e5b",
                    "method": "GET"
                },
                "soft_delete": {
                    "href": "https://platform-va7.adobe.io/data/foundation/query/queries/8f0d7f25-f7aa-493b-9792-290f884a7e5b",
                    "method": "PATCH",
                    "body": "{ \"op\": \"soft_delete\"}"
                },
                "referenced_datasets": [
                    {
                        "id": "60080ace62c49a19490c5870",
                        "href": "https://platform-va7.adobe.io/data/foundation/catalog/dataSets/60080ace62c49a19490c5870"
                    }
                ]
            }
        }
     ]
    },
    "version": 1
}

Quando lo stato è SUCCESS, proseguire con la richiesta successiva.

7.7.3.3 Ottenere lo stato della query

Fare clic sulla richiesta denominata 1.3 QS - Get Query Status e passare a Headers. Vedrete questo:

Segmentazione

Concentriamoci su questo campo di intestazione:

Chiave Valore
x-sandbox-name --module7sandbox--
NOTA

Dovete specificare il nome della sandbox Adobe Experience Platform in uso. Il campo di intestazione x-sandbox-name deve essere --module7sandbox--.

Fare clic sul pulsante blu Invia per creare il segmento e visualizzare i risultati.

Segmentazione

In caso di esito positivo, la richiesta restituirà una risposta simile a quella riportata di seguito.

{
    "isInsertInto": false,
    "request": {
        "dbName": "module7:all",
        "sql": "select date_format( timestamp , 'yyyy-MM-dd') AS Day, count(*) AS productViews from demo_system_event_dataset_for_website_global_v1_1 where _experienceplatform.demoEnvironment.brandName IN ('Luma Telco', 'Citi Signal') and eventType = 'commerce.productViews' group by Day limit 10",
        "name": "vangeluw - QS API demo - Citi Signal - Product Views Per Day",
        "description": "vangeluw - QS API demo - Citi Signal - Product Views Per Day"
    },
    "clientId": "5a143b5ae4aa4631a1f3b09cd051333f",
    "state": "SUCCESS",
    "rowCount": 1,
    "errors": [],
    "isCTAS": false,
    "version": 1,
    "id": "8f0d7f25-f7aa-493b-9792-290f884a7e5b",
    "elapsedTime": 217481,
    "updated": "2021-01-20T13:26:51.432Z",
    "client": "API",
    "userId": "A3392DB95FFF08EE0A495E87@techacct.adobe.com",
    "created": "2021-01-20T13:23:13.951Z",
    "_links": {
        "self": {
            "href": "https://platform-va7.adobe.io/data/foundation/query/queries/8f0d7f25-f7aa-493b-9792-290f884a7e5b",
            "method": "GET"
        },
        "soft_delete": {
            "href": "https://platform-va7.adobe.io/data/foundation/query/queries/8f0d7f25-f7aa-493b-9792-290f884a7e5b",
            "method": "PATCH",
            "body": "{ \"op\": \"soft_delete\"}"
        },
        "referenced_datasets": [
            {
                "id": "60080ace62c49a19490c5870",
                "href": "https://platform-va7.adobe.io/data/foundation/catalog/dataSets/60080ace62c49a19490c5870"
            }
        ]
    }
}

Quando una query raggiunge lo stato di SUCCESS, la risposta indica anche il numero di righe recuperate dalla query tramite la proprietà rowCount. Nel nostro esempio, 10 righe vengono restituite dalla query. Vediamo nella sezione successiva come recuperare le 10 righe.

7.7.3.4 Recupero dei risultati della query

La risposta SUCCESS sopra include una proprietà referenziated_datasets che punta al dataset implicito che memorizza il risultato della query. Per accedere al risultato, utilizzeremo la relativa proprietà href o id.

Fare clic sulla richiesta denominata 1.4 QS - Ottieni risultato query e passare a Intestazioni. Vedrete questo:

Segmentazione

Concentriamoci su questo campo di intestazione:

Chiave Valore
x-sandbox-name --module7sandbox--
NOTA

Dovete specificare il nome della sandbox Adobe Experience Platform in uso. Il campo di intestazione x-sandbox-name deve essere --module7sandbox--.

Fare clic sul pulsante blu Invia per creare il segmento e visualizzare i risultati.

Segmentazione

La risposta di questa richiesta punta ai file di set di dati:

{
    "60080ace62c49a19490c5870": {
        "name": "Demo System - Event Dataset for Website (Global v1.1)",
        "description": "Demo System - Event Dataset for Website (Global v1.1)",
        "enableErrorDiagnostics": false,
        "tags": {
            "adobe/siphon/partition/definition": [
                "day(timestamp, _ACP_DATE)",
                "identity(_ACP_BATCHID)"
            ],
            "aep/siphon/partitions": [
                "_ACP_DATE",
                "_ACP_BATCHID"
            ],
            "acp_granular_plugin_validation_flags": [
                "identity:enabled",
                "profile:enabled"
            ],
            "adobe/siphon/buffered-promotion-recency": [
                "live"
            ],
            "adobe/siphon/use-buffered-promotion": [
                "true"
            ],
            "adobe/pqs/table": [
                "demo_system_event_dataset_for_website_global_v1_1"
            ],
            "aep/siphon/expire-snapshot-timestamp": [
                "1611141272703"
            ],
            "acp_granular_validation_flags": [
                "requiredFieldCheck:enabled"
            ],
            "acp_validationContext": [
                "enabled"
            ],
            "adobe/siphon/table/format": [
                "iceberg"
            ],
            "unifiedProfile": [
                "enabled:true",
                "enabledAt:2021-01-20 10:49:51"
            ],
            "unifiedIdentity": [
                "enabled:true"
            ]
        },
        "namespace": "ACP",
        "state": "DRAFT",
        "imsOrg": "907075E95BF479EC0A495C73@AdobeOrg",
        "sandboxId": "62cd9f38-8529-4b05-8d9f-388529db0540",
        "lastBatchId": "01EWFQZ15XRNNB1FPKPW5ETRVP",
        "lastBatchStatus": "success",
        "lastSuccessfulBatch": "01EWFQZ15XRNNB1FPKPW5ETRVP",
        "version": "1.0.6",
        "created": 1611139790698,
        "updated": 1611149266031,
        "createdClient": "750e24ee855b4ac18ccc4f4817f96ee1",
        "createdUser": "3A260B485E909A170A495E76@techacct.adobe.com",
        "updatedUser": "acp_foundation_dataTracker@AdobeID",
        "viewId": "60080ace62c49a19490c5871",
        "fileDescription": {
            "persisted": true,
            "containerFormat": "parquet",
            "format": "parquet"
        },
        "files": "@/dataSets/60080ace62c49a19490c5870/views/60080ace62c49a19490c5871/files",
        "schemaMetadata": {
            "delta": [],
            "gdpr": []
        },
        "schemaRef": {
            "id": "https://ns.adobe.com/experienceplatform/schemas/d9b88a044ad96154637965a97ed63c7b20bdf2ab3b4f642e",
            "contentType": "application/vnd.adobe.xed-full+json;version=1"
        }
    }
}
NOTA

Presto verranno aggiunti ulteriori esercizi per consentirvi di interagire con l'API del servizio di query.

Passaggio successivo: Riepilogo e vantaggi

Torna al modulo 7

Torna a tutti i moduli

In questa pagina