Documentazione Experience Platform Guida di Query Service

Endpoint "query templates"

Last update: Tue Jul 16 2024 00:00:00 GMT+0000 (Coordinated Universal Time)

Argomenti:
Query

Creato per:

Sviluppatore

Chiamate API di esempio

Le sezioni seguenti descrivono le varie chiamate API che è possibile effettuare utilizzando l'API Query Service. Ogni chiamata include il formato API generale, una richiesta di esempio che mostra le intestazioni richieste e una risposta di esempio.

Per informazioni sulla creazione di modelli tramite l'interfaccia utente di Experience Platform, vedere la documentazione dei modelli di query dell'interfaccia utente.

Recuperare un elenco di modelli di query

Per recuperare un elenco di tutti i modelli di query per l'organizzazione, eseguire una richiesta GET all'endpoint /query-templates.

Formato API

GET /query-templates
GET /query-templates?{QUERY_PARAMETERS}

Proprietà

Descrizione

{QUERY_PARAMETERS}

(Facoltativo) Parametri aggiunti al percorso della richiesta che configurano i risultati restituiti nella risposta. È possibile includere più parametri, separati da e commerciali (&). I parametri disponibili sono elencati di seguito.

Parametri query

Di seguito è riportato un elenco dei parametri di query disponibili per l'elenco dei modelli di query. Tutti questi parametri sono facoltativi. Effettuando una chiamata a questo endpoint senza parametri, verranno recuperati tutti i modelli di query disponibili per la tua organizzazione.

Parametro

Descrizione

orderby

Specifica il campo in base al quale ordinare i risultati. I campi supportati sono created e updated. Ad esempio, orderby=created ordinerà i risultati in base alla creazione in ordine crescente. L'aggiunta di un - prima della creazione (orderby=-created) ordinerà gli elementi in base alla creazione in ordine decrescente.

limit

Specifica il limite di dimensioni della pagina per controllare il numero di risultati inclusi in una pagina. (Valore predefinito: 20)

start

Specifica una marca temporale in formato ISO per ordinare i risultati. Se non viene specificata alcuna data di inizio, la chiamata API restituirà prima i modelli creati più datati, quindi continuerà a elencare i risultati più recenti.
Le marche temporali ISO consentono diversi livelli di granularità in data e ora. I timestamp ISO di base assumono il formato di: 2020-09-07 per esprimere la data 7 settembre 2020. Un esempio più complesso verrebbe scritto come 2022-11-05T08:15:30-05:00 e corrisponde al 5 novembre 2022, 8:15:30, ora standard orientale USA. È possibile fornire un fuso orario con scostamento UTC ed è indicato dal suffisso "Z" (2020-01-01T01:01:01Z). Se non viene fornito alcun fuso orario, per impostazione predefinita viene impostato su zero.

property

Filtra i risultati in base ai campi. I filtri devono avere escape HTML. Le virgole vengono utilizzate per combinare più set di filtri. I campi supportati sono name e userId. L'unico operatore supportato è == (uguale a). Ad esempio, name==my_template restituirà tutti i modelli di query con il nome my_template.

Richiesta

La richiesta seguente recupera il modello di query più recente creato per la tua organizzazione.

curl -X GET https://platform.adobe.io/data/foundation/query/query-templates?limit=1
 -H 'Authorization: Bearer {ACCESS_TOKEN}' \
 -H 'x-gw-ims-org-id: {ORG_ID}' \
 -H 'x-api-key: {API_KEY}' \
 -H 'x-sandbox-name: {SANDBOX_NAME}'

Risposta

In caso di esito positivo, la risposta restituisce lo stato HTTP 200 con un elenco di modelli di query per l’organizzazione specificata. La risposta seguente restituisce l’ultimo modello di query creato per la tua organizzazione.

{
    "templates": [
        {
            "sql": "SELECT *\nFROM\n  accounts\nLIMIT 10\n",
            "name": "Test",
            "id": "f7cb5155-29da-4b95-8131-8c5deadfbe7f",
            "updated": "2019-11-21T21:50:01.469Z",
            "userId": "{USER_ID}",
            "created": "2019-11-21T21:50:01.469Z",
            "_links": {
                "self": {
                    "href": "https://platform.adobe.io/data/foundation/query/query-templates/f7cb5155-29da-4b95-8131-8c5deadfbe7f",
                    "method": "GET"
                },
                "delete": {
                    "href": "https://platform.adobe.io/data/foundation/query/query-templates/f7cb5155-29da-4b95-8131-8c5deadfbe7f",
                    "method": "DELETE"
                },
                "update": {
                    "href": "https://platform.adobe.io/data/foundation/query/query-templates/f7cb5155-29da-4b95-8131-8c5deadfbe7f",
                    "method": "PUT",
                    "body": "{\"sql\": \"new sql \", \"name\": \"new name\"}"
                }
            }
        }
    ],
    "_page": {
        "orderby": "-created",
        "start": "2019-11-21T21:50:01.469Z",
        "next": "2019-11-21T21:50:01.469Z",
        "count": 1
    },
    "_links": {
        "next": {
            "href": "https://platform.adobe.io/data/foundation/query/query-templates?orderby=-created&start=2019-11-21T21:50:01.469Z"
        },
        "prev": {
            "href": "https://platform.adobe.io/data/foundation/query/query-templates?orderby=-created&start=2019-11-21T21:50:01.469Z&isPrevLink=true"
        }
    },
    "version": 1
}

NOTE

È possibile utilizzare il valore di _links.delete per eliminare il modello di query.

Creare un modello di query

È possibile creare un modello di query effettuando una richiesta POST all'endpoint /query-templates.

Formato API

POST /query-templates

Richiesta

curl -X POST https://platform.adobe.io/data/foundation/query/query-templates
 -H 'Authorization: Bearer {ACCESS_TOKEN}' \
 -H 'x-gw-ims-org-id: {ORG_ID}' \
 -H 'x-api-key: {API_KEY}' \
 -H 'x-sandbox-name: {SANDBOX_NAME}'
 -d '{
        "sql": "SELECT account_balance FROM user_data WHERE user_id='$user_id';",
        "name": "Sample query template",
        "queryParameters": {
            user_id : {USER_ID}
            }
    }'

Proprietà

Descrizione

sql

La query SQL da creare. È possibile utilizzare SQL standard o un parametro sostitutivo. Per utilizzare una sostituzione dei parametri nel codice SQL, è necessario anteporre la chiave del parametro a $. Ad esempio, $key, e forniscono i parametri utilizzati in SQL come coppie di valori chiave JSON nel campo queryParameters. I valori qui passati saranno i parametri predefiniti utilizzati nel modello. Se desideri ignorare questi parametri, devi sostituirli nella richiesta POST.

name

Nome del modello di query.

queryParameters

Associazione di valori chiave per sostituire eventuali valori con parametri nell'istruzione SQL. È necessario solo se si stanno utilizzando sostituzioni di parametri all'interno del codice SQL fornito. Su queste coppie chiave-valore non verrà eseguito alcun controllo del tipo di valore.

Risposta

In caso di esito positivo, la risposta restituisce lo stato HTTP 202 (Accettato) con i dettagli del modello di query appena creato.

{
    "sql": "SELECT account_balance FROM user_data WHERE user_id='$user_id';",
    "name": "Sample query template",
    "id": "0094d000-9062-4e6a-8fdb-05606805f08f",
    "updated": "2020-01-09T00:20:09.670Z",
    "userId": "{USER_ID}",
    "created": "2020-01-09T00:20:09.670Z",
    "_links": {
        "self": {
            "href": "https://platform.adobe.io/data/foundation/query/query-templates/0094d000-9062-4e6a-8fdb-05606805f08f",
            "method": "GET"
        },
        "delete": {
            "href": "https://platform.adobe.io/data/foundation/query/query-templates/0094d000-9062-4e6a-8fdb-05606805f08f",
            "method": "DELETE"
        },
        "update": {
            "href": "https://platform.adobe.io/data/foundation/query/query-templates/0094d000-9062-4e6a-8fdb-05606805f08f",
            "method": "PUT",
            "body": "{\"sql\": \"new sql \", \"name\": \"new name\"}"
        }
    }
}

NOTE

È possibile utilizzare il valore di _links.delete per eliminare il modello di query.

Recuperare un modello di query specificato

È possibile recuperare un modello di query specifico effettuando una richiesta di GET all'endpoint /query-templates/{TEMPLATE_ID} e fornendo l'ID del modello di query nel percorso della richiesta.

Formato API

GET /query-templates/{TEMPLATE_ID}

Proprietà

Descrizione

{TEMPLATE_ID}

Valore id del modello di query che si desidera recuperare.

Richiesta

curl -X GET https://platform.adobe.io/data/foundation/query/query-templates/0094d000-9062-4e6a-8fdb-05606805f08f
 -H 'Authorization: Bearer {ACCESS_TOKEN}' \
 -H 'x-gw-ims-org-id: {ORG_ID}' \
 -H 'x-api-key: {API_KEY}' \
 -H 'x-sandbox-name: {SANDBOX_NAME}'

Risposta

In caso di esito positivo, la risposta restituisce lo stato HTTP 200 con i dettagli del modello di query specificato.

{
    "sql": "SELECT * FROM accounts;",
    "name": "Sample query template",
    "id": "0094d000-9062-4e6a-8fdb-05606805f08f",
    "updated": "2020-01-09T00:20:09.670Z",
    "userId": "A5A562D15E1645480A495CE1@techacct.adobe.com",
    "created": "2020-01-09T00:20:09.670Z",
    "_links": {
        "self": {
            "href": "https://platform.adobe.io/data/foundation/query/query-templates/0094d000-9062-4e6a-8fdb-05606805f08f",
            "method": "GET"
        },
        "delete": {
            "href": "https://platform.adobe.io/data/foundation/query/query-templates/0094d000-9062-4e6a-8fdb-05606805f08f",
            "method": "DELETE"
        },
        "update": {
            "href": "https://platform.adobe.io/data/foundation/query/query-templates/0094d000-9062-4e6a-8fdb-05606805f08f",
            "method": "PUT",
            "body": "{\"sql\": \"new sql \", \"name\": \"new name\"}"
        }
    }
}

NOTE

È possibile utilizzare il valore di _links.delete per eliminare il modello di query.

Aggiornare un modello di query specificato

È possibile aggiornare un modello di query specifico effettuando una richiesta PUT all'endpoint /query-templates/{TEMPLATE_ID} e fornendo l'ID del modello di query nel percorso della richiesta.

Formato API

PUT /query-templates/{TEMPLATE_ID}

Proprietà

Descrizione

{TEMPLATE_ID}

Valore id del modello di query che si desidera recuperare.

Richiesta

NOTE

La richiesta PUT richiede la compilazione sia del campo sql che del campo name e sovrascrive il contenuto corrente del modello di query.

curl -X PUT https://platform.adobe.io/data/foundation/query/query-templates/0094d000-9062-4e6a-8fdb-05606805f08f
 -H 'Authorization: Bearer {ACCESS_TOKEN}' \
 -H 'x-gw-ims-org-id: {ORG_ID}' \
 -H 'x-api-key: {API_KEY}' \
 -H 'x-sandbox-name: {SANDBOX_NAME}'
 -d '{
    "sql": "SELECT account_balance FROM user_data WHERE user_id='$user_id';",
    "name": "Sample query template",
    "queryParameters": {
            user_id : {USER_ID}
        }
    }'

Proprietà

Descrizione

sql

name

Nome del modello di query.

queryParameters

Risposta

In caso di esito positivo, la risposta restituisce lo stato HTTP 202 (Accepted) con le informazioni aggiornate per il modello di query specificato.

{
    "sql": "SELECT * FROM accounts LIMIT 20;",
    "name": "Sample query template",
    "id": "0094d000-9062-4e6a-8fdb-05606805f08f",
    "updated": "2020-01-09T00:29:20.028Z",
    "lastUpdatedBy": "{USER_ID}",
    "userId": "{USER_ID}",
    "created": "2020-01-09T00:20:09.670Z",
    "_links": {
        "self": {
            "href": "https://platform.adobe.io/data/foundation/query/query_templates/0094d000-9062-4e6a-8fdb-05606805f08f",
            "method": "GET"
        },
        "delete": {
            "href": "https://platform.adobe.io/data/foundation/query/query_templates/0094d000-9062-4e6a-8fdb-05606805f08f",
            "method": "DELETE"
        },
        "update": {
            "href": "https://platform.adobe.io/data/foundation/query/query_templates/0094d000-9062-4e6a-8fdb-05606805f08f",
            "method": "PUT",
            "body": "{\"sql\": \"new sql \", \"name\": \"new name\"}"
        }
    }
}

NOTE

È possibile utilizzare il valore di _links.delete per eliminare il modello di query.

Eliminare un modello di query specificato

È possibile eliminare un modello di query specifico effettuando una richiesta DELETE a /query-templates/{TEMPLATE_ID} e fornendo l'ID del modello di query nel percorso della richiesta.

Formato API

DELETE /query-templates/{TEMPLATE_ID}

Proprietà

Descrizione

{TEMPLATE_ID}

Valore id del modello di query che si desidera recuperare.

Richiesta

curl -X DELETE https://platform.adobe.io/data/foundation/query/query-templates/0094d000-9062-4e6a-8fdb-05606805f08f
 -H 'Authorization: Bearer {ACCESS_TOKEN}' \
 -H 'x-gw-ims-org-id: {ORG_ID}' \
 -H 'x-api-key: {API_KEY}' \
 -H 'x-sandbox-name: {SANDBOX_NAME}'

Risposta

In caso di esito positivo, la risposta restituisce lo stato HTTP 202 (Accepted) con il seguente messaggio.

{
    "message": "Deleted",
    "statusCode": 202
}

recommendation-more-help

ccf2b369-4031-483f-af63-a93b5ae5e3fb