7.7 API de serviço de Query

Objetivo

  • Use a API de serviço de Query para gerenciar modelos de query e agendamentos de query

Contexto

Neste exercício, você executará chamadas de API para gerenciar modelos de query e agendamentos de query usando uma coleção Postman. Você definirá modelos de query, executará query regulares e query CTAS. Um query CTAS (criar tabela como query selecionado) armazena seu conjunto de dados explícito. Enquanto os query regulares são armazenados em um conjunto de dados implícito (ou gerado pelo sistema), que é normalmente exportado no formato de arquivo de parquet.

Documentação

API de serviço de Query 7.7.1

A API de serviço de Query permite gerenciar query não interativos em relação ao lago de dados da Adobe Experience Platform.

Não interativo significa que uma solicitação para executar um query não resultará em uma resposta imediata. O query será processado e seus resultados serão armazenados em um CTAS implícito ou explícito: criar tabela como selecionar) conjunto de dados.

7.7.2 Query de amostra

Como query de exemplo, você usará o primeiro query listado em 7.3 - Query, query, query… e análise de churn:

Quantas visualizações de produtos temos diariamente?

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

Abra o Postman no seu computador. Como parte do Módulo 3, você criou um ambiente Postman e importou uma coleção Postman. Siga as instruções em Exercise 3.3.3 caso ainda não tenha feito isso.

Como parte da coleção do Postman importada, você verá uma pasta 3. Serviço de query. Se você não vir essa pasta, baixe novamente a coleção do Postman e importe novamente essa coleção no Postman, conforme instruído em Exercise 3.3.3.

QS

OBSERVAÇÃO

Neste momento, somente a pasta 1. Query contém solicitações. Outras solicitações serão adicionadas em um estágio de camada.

Abra essa pasta e conheça as chamadas da API de serviço de Query para executar, monitorar e baixar o conjunto de resultados do query.

Uma chamada de POST para [/query/query] com a seguinte carga acionará a execução do query;

7.7.3.1 Criar Query

Clique na solicitação chamada 1.1 QS - Create Query e vá para Headers. Você verá isso:

Segmentação

Vamos focar neste campo de cabeçalho:

Chave Valor
x-sandbox-name --module7sandbox--
OBSERVAÇÃO

É necessário especificar o nome da caixa de proteção do Adobe Experience Platform que você está usando. O campo de cabeçalho x-sandbox-name deve ser --module7sandbox--.

Vá para a seção Body desta solicitação. No Corpo desta solicitação, você verá o seguinte:

Segmentação

{
    "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"
}

Atenção: atualize a variável name na solicitação abaixo substituindo ldap por seu ldap específico.

Depois de adicionar seu ldap específico, o Corpo deve ser semelhante a este:

{
    "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"
}
OBSERVAÇÃO

A tecla dbName no corpo JSON acima refere-se à caixa de proteção usada na sua instância do Adobe Experience Platform. Se você estiver usando a caixa de proteção PROD, o dbName deverá ser prod:all, se você usar outra caixa de proteção como, por exemplo, module7, o dbName deverá ser igual a module7:all.

Em seguida, clique no botão azul Enviar para criar o segmento e visualização os resultados.

Segmentação

Quando a solicitação de POST for bem-sucedida, retornará a seguinte resposta:

{
    "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\"}"
        }
    }
}

O estado atual do query é SUBMITTED, uma vez executado, o estado se tornará SUCCESS.

Você também pode pesquisar query enviados pela interface do usuário do Adobe Experience Platform, abrir Adobe Experience Platform, navegar até Query, Log e selecionar seu query:

Segmentação

7.7.3.2 Obter Query

Clique na solicitação chamada 1.2 QS - Obter Query e vá para Cabeçalhos. Você verá isso:

Segmentação

Vamos focar neste campo de cabeçalho:

Chave Valor
x-sandbox-name --module7sandbox--
OBSERVAÇÃO

É necessário especificar o nome da caixa de proteção do Adobe Experience Platform que você está usando. O campo de cabeçalho x-sandbox-name deve ser --module7sandbox--.

Vá para Params. Você verá isso:

Segmentação

O parâmetro orderby permite que você especifique uma ordem de classificação com base na propriedade created. Observe o sinal de '-' na frente da criação, o que significa que a ordem na qual a lista de query é retornada usará a data criada na ordem decrescente. Seu query deve estar no topo da lista.

Em seguida, clique no botão azul Enviar para criar o segmento e visualização os resultados.

Segmentação

Quando bem-sucedida, a solicitação retornará uma resposta semelhante à apresentada abaixo. O state da resposta pode ser SUBMITTED, IN_PROGRESS ou SUCCESS. Pode levar vários minutos até que o query tenha um estado SUCCESS. Você pode repetir o envio desta solicitação várias vezes, até que você veja o estado 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 o estado for SUCCESS, continue com a próxima solicitação.

7.7.3.3 Obter status do Query

Clique na solicitação chamada 1.3 QS - Obter status do Query e vá para Cabeçalhos. Você verá isso:

Segmentação

Vamos focar neste campo de cabeçalho:

Chave Valor
x-sandbox-name --module7sandbox--
OBSERVAÇÃO

É necessário especificar o nome da caixa de proteção do Adobe Experience Platform que você está usando. O campo de cabeçalho x-sandbox-name deve ser --module7sandbox--.

Em seguida, clique no botão azul Enviar para criar o segmento e visualização os resultados.

Segmentação

Quando bem-sucedida, a solicitação retornará uma resposta semelhante à apresentada abaixo.

{
    "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 um query atingir o estado SUCCESS, a resposta também indicará o número de linhas recuperadas pelo query por meio da propriedade rowCount. Em nosso exemplo, 10 linhas são retornadas pelo query. Vamos ver na próxima seção como podemos recuperar as 10 linhas.

7.7.3.4 Obter resultado do Query

A resposta SUCCESS acima inclui uma propriedade referreferred_datasets, que aponta para o conjunto de dados implícito que armazena o resultado do query. Para obter acesso ao resultado, usamos sua propriedade href ou id.

Clique na solicitação chamada 1.4 QS - Obter resultado do Query e vá para Cabeçalhos. Você verá isso:

Segmentação

Vamos focar neste campo de cabeçalho:

Chave Valor
x-sandbox-name --module7sandbox--
OBSERVAÇÃO

É necessário especificar o nome da caixa de proteção do Adobe Experience Platform que você está usando. O campo de cabeçalho x-sandbox-name deve ser --module7sandbox--.

Em seguida, clique no botão azul Enviar para criar o segmento e visualização os resultados.

Segmentação

A resposta desta solicitação apontará para os arquivos do conjunto de dados:

{
    "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"
        }
    }
}
OBSERVAÇÃO

Mais exercícios serão adicionados em breve para ajudá-lo a interagir com a API de serviço de Query.

Próxima etapa: Resumo e benefícios

Voltar ao módulo 7

Voltar para todos os módulos

Nesta página