Documentação Experience Platform Guia do Serviço de consulta

Endpoint de consultas

Last update: Wed Feb 28 2024 00:00:00 GMT+0000 (Coordinated Universal Time)

Tópicos:
Queries

Criado para:

Developer

Exemplos de chamadas de API

As seções a seguir abordam as chamadas que podem ser feitas usando o /queries endpoint na variável Query Service API. Cada chamada inclui o formato da API geral, uma solicitação de amostra mostrando os cabeçalhos necessários e uma resposta de amostra.

Recuperar uma lista de consultas

Você pode recuperar uma lista de todas as consultas para sua organização fazendo uma solicitação GET para /queries terminal.

Formato da API

GET /queries
GET /queries?{QUERY_PARAMETERS}

{QUERY_PARAMETERS}: (Opcional) Parâmetros adicionados ao caminho da solicitação que configuram os resultados retornados na resposta. Vários parâmetros podem ser incluídos, separados por "E" comercial (&). Os parâmetros disponíveis estão listados abaixo.

Parâmetros de consulta

Veja a seguir uma lista de parâmetros de consulta disponíveis para consultas de listagem. Todos esses parâmetros são opcionais. Fazer uma chamada para esse endpoint sem parâmetros recuperará todas as consultas disponíveis para sua organização.

Parâmetro

Descrição

orderby

Especifica o campo pelo qual ordenar resultados. Os campos compatíveis são created e updated. Por exemplo, orderby=created Os resultados serão classificados por criados em ordem crescente. Adicionar um - antes de criar (orderby=-created) classificará os itens por criados em ordem decrescente.

limit

Especifica o limite de tamanho de página para controlar o número de resultados incluídos em uma página. (Valor padrão: 20)

start

Especifique um carimbo de data e hora no formato ISO para ordenar os resultados. Se nenhuma data de início for especificada, a chamada à API retornará primeiro a consulta criada mais antiga e, em seguida, continuará a listar os resultados mais recentes.
Os carimbos de data e hora ISO permitem diferentes níveis de granularidade na data e hora. Os carimbos de data e hora ISO básicos têm o formato de: 2020-09-07 para expressar a data em 7 de setembro de 2020. Um exemplo mais complexo seria escrito como 2022-11-05T08:15:30-05:00 e corresponde a 5 de novembro de 2022, 8:15:30 da manhã, Hora Padrão do Leste dos EUA. Um fuso horário pode ser fornecido com um deslocamento UTC e é indicado pelo sufixo "Z" (2020-01-01T01:01:01Z). Se nenhum fuso horário for fornecido, o padrão será zero.

property

Filtrar resultados com base em campos. Os filtros deve ser escapado por HTML. As vírgulas são usadas para combinar vários conjuntos de filtros. Os campos compatíveis são created, updated, state, e id. A lista de operadores compatíveis é > (maior que), < (menor que), >= (maior que ou igual a), <= (menor que ou igual a), == (igual a), != (diferente de) e ~ (contém). Por exemplo, id==6ebd9c2d-494d-425a-aa91-24033f3abeec retornará todas as consultas com a ID especificada.

excludeSoftDeleted

Indica se uma consulta que foi excluída por software deve ser incluída. Por exemplo, excludeSoftDeleted=false irá include consultas excluídas por software. (Booleano, valor padrão: verdadeiro)

excludeHidden

Indica se as consultas não orientadas por usuário devem ser exibidas. Se este valor for definido como falso, include consultas não orientadas por usuários, como definições de CURSOR, FETCH ou consultas de metadados. (Booleano, valor padrão: verdadeiro)

isPrevLink

A variável isPrevLink O parâmetro de consulta é usado para paginação. Os resultados da chamada de API são classificados usando seus created carimbo de data e hora e o orderby propriedade. Ao navegar pelas páginas de resultados, isPrevLink está definido como verdadeiro ao retroceder a paginação. Inverte a ordem da consulta. Consulte os links "próximo" e "anterior" como exemplos.

Solicitação

A solicitação a seguir recupera a consulta mais recente criada para sua organização.

curl -X GET https://platform.adobe.io/data/foundation/query/queries?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}'

Resposta

Uma resposta bem-sucedida retorna o status HTTP 200 com uma lista de consultas para a organização especificada como JSON. A resposta a seguir retorna a consulta mais recente criada para sua organização.

{
    "queries": [
        {
            "isInsertInto": false,
            "request": {
                "dbName": "prod:all",
                "sql": "SELECT *\nFROM\n  accounts\nLIMIT 10\n"
            },
            "state": "SUCCESS",
            "rowCount": 0,
            "errors": [],
            "isCTAS": false,
            "version": 1,
            "id": "9957bd7f-2244-4fd5-91bc-077d7df1d8e5",
            "elapsedTime": 28,
            "updated": "2019-12-06T22:00:17.390Z",
            "client": "Adobe Query Service UI",
            "userId": "{USER_ID}",
            "created": "2019-12-06T22:00:17.362Z",
            "_links": {
                "self": {
                    "href": "https://platform.adobe.io/data/foundation/query/queries/9957bd7f-2244-4fd5-91bc-077d7df1d8e5",
                    "method": "GET"
                },
                "soft_delete": {
                    "href": "https://platform.adobe.io/data/foundation/query/queries/9957bd7f-2244-4fd5-91bc-077d7df1d8e5",
                    "method": "PATCH",
                    "body": "{ \"op\": \"soft_delete\"}"
                },
                "referenced_datasets": [
                    {
                        "id": "5b2bdd32230d4401de87397c",
                        "href": "https://platform.adobe.io/data/foundation/catalog/dataSets/5b2bdd32230d4401de87397c"
                    }
                ]
            }
        }
    ],
    "_page": {
        "orderby": "-created",
        "start": "2019-12-06T22:00:17.362Z",
        "next": "2019-08-01T00:14:21.748Z",
        "count": 1
    },
    "_links": {
        "next": {
            "href": "https://platform.adobe.io/data/foundation/query/queries?orderby=-created&start=2019-08-01T00:14:21.748Z"
        },
        "prev": {
            "href": "https://platform.adobe.io/data/foundation/query/queries?orderby=-created&start=2019-12-06T22:00:17.362Z&isPrevLink=true"
        }
    },
    "version": 1
}

Criar uma consulta

Você pode criar uma nova consulta fazendo uma solicitação POST para o /queries terminal.

Formato da API

POST /queries

Solicitação

A solicitação a seguir cria uma nova consulta, com uma instrução SQL fornecida na carga:

curl -X POST https://platform.adobe.io/data/foundation/query/queries \
 -H 'Authorization: Bearer {ACCESS_TOKEN}' \
 -H 'Content-Type: application/json' \
 -H 'x-gw-ims-org-id: {ORG_ID}' \
 -H 'x-api-key: {API_KEY}' \
 -H 'x-sandbox-name: {SANDBOX_NAME}' \
 -d '{
        "dbName": "prod:all",
        "sql": "SELECT account_balance FROM user_data WHERE user_id='$user_id';",
        "queryParameters": {
            user_id : {USER_ID}
            }
        "name": "Sample Query",
        "description": "Sample Description"
    }

O exemplo de solicitação abaixo cria uma nova consulta usando uma ID de modelo de consulta existente.

curl -X POST https://platform.adobe.io/data/foundation/query/queries \
 -H 'Authorization: Bearer {ACCESS_TOKEN}' \
 -H 'Content-Type: application/json' \
 -H 'x-gw-ims-org-id: {ORG_ID}' \
 -H 'x-api-key: {API_KEY}' \
 -H 'x-sandbox-name: {SANDBOX_NAME}' \
 -d '{
        "dbName": "prod:all",
        "templateID": "f7cb5155-29da-4b95-8131-8c5deadfbe7f",
        "name": "Sample Query",
        "description": "Sample Description"
    }

Propriedade

Descrição

dbName

O nome do banco de dados para o qual você está criando uma consulta SQL.

sql

A consulta SQL que você deseja criar.

name

O nome da sua consulta SQL.

description

A descrição da sua consulta SQL.

queryParameters

Um par de valores chave para substituir quaisquer valores parametrizados na instrução SQL. É apenas obrigatório se você está usando substituições de parâmetros no SQL fornecido. Nenhuma verificação de tipo de valor será feita nesses pares de valores principais.

templateId

O identificador exclusivo de uma consulta pré-existente. Você pode fornecer isso em vez de uma instrução SQL.

insertIntoParameters

(Opcional) Se essa propriedade for definida, essa consulta será convertida em uma consulta INSERT INTO.

ctasParameters

(Opcional) Se esta propriedade for definida, esta consulta será convertida em uma consulta CTAS.

Resposta

Uma resposta bem-sucedida retorna o status HTTP 202 (Aceito) com detalhes da consulta recém-criada. Quando a ativação da consulta for concluída e ela for executada com êxito, a variável state mudará de SUBMITTED para SUCCESS.

{
    "isInsertInto": false,
    "request": {
        "dbName": "prod:all",
        "sql": "SELECT * FROM accounts;",
        "name": "Sample Query",
        "description": "Sample Description"
    },
    "state": "SUBMITTED",
    "rowCount": 0,
    "errors": [],
    "isCTAS": false,
    "version": 1,
    "id": "4d64cd49-cf8f-463a-a182-54bccb9954fc",
    "elapsedTime": 0,
    "updated": "2020-01-08T21:47:46.865Z",
    "client": "API",
    "userId": "{USER_ID}",
    "created": "2020-01-08T21:47:46.865Z",
    "_links": {
        "self": {
            "href": "https://platform.adobe.io/data/foundation/query/queries/4d64cd49-cf8f-463a-a182-54bccb9954fc",
            "method": "GET"
        },
        "soft_delete": {
            "href": "https://platform.adobe.io/data/foundation/query/queries/4d64cd49-cf8f-463a-a182-54bccb9954fc",
            "method": "PATCH",
            "body": "{ \"op\": \"soft_delete\"}"
        },
        "cancel": {
            "href": "https://platform.adobe.io/data/foundation/query/queries/4d64cd49-cf8f-463a-a182-54bccb9954fc",
            "method": "PATCH",
            "body": "{ \"op\": \"cancel\"}"
        }
    }
}

NOTE

Você pode usar o valor de _links.cancel para cancelar a consulta criada.

Recuperar uma consulta por ID

Você pode recuperar informações detalhadas sobre uma consulta específica fazendo uma solicitação GET ao /queries endpoint e fornecimento do query id no caminho da solicitação.

Formato da API

GET /queries/{QUERY_ID}

Propriedade

Descrição

{QUERY_ID}

A variável id valor da consulta que você deseja recuperar.

Solicitação

curl -X GET https://platform.adobe.io/data/foundation/query/queries/4d64cd49-cf8f-463a-a182-54bccb9954fc \
 -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}'

Resposta

Uma resposta bem-sucedida retorna o status HTTP 200 com informações detalhadas sobre a consulta especificada.

{
    "isInsertInto": false,
    "request": {
        "dbName": "prod:all",
        "sql": "SELECT * FROM accounts;",
        "name": "Sample Query",
        "description": "Sample Description"
    },
    "state": "SUBMITTED",
    "rowCount": 0,
    "errors": [],
    "isCTAS": false,
    "version": 1,
    "id": "4d64cd49-cf8f-463a-a182-54bccb9954fc",
    "elapsedTime": 0,
    "updated": "2020-01-08T21:47:46.865Z",
    "client": "API",
    "userId": "{USER_ID}",
    "created": "2020-01-08T21:47:46.865Z",
    "_links": {
        "self": {
            "href": "https://platform.adobe.io/data/foundation/query/queries/4d64cd49-cf8f-463a-a182-54bccb9954fc",
            "method": "GET"
        },
        "soft_delete": {
            "href": "https://platform.adobe.io/data/foundation/query/queries/4d64cd49-cf8f-463a-a182-54bccb9954fc",
            "method": "PATCH",
            "body": "{ \"op\": \"soft_delete\"}"
        },
        "cancel": {
            "href": "https://platform.adobe.io/data/foundation/query/queries/4d64cd49-cf8f-463a-a182-54bccb9954fc",
            "method": "PATCH",
            "body": "{ \"op\": \"cancel\"}"
        }
    }
}

NOTE

Você pode usar o valor de _links.cancel para cancelar a consulta criada.

Cancelar ou excluir uma consulta por software

Você pode solicitar o cancelamento ou a exclusão reversível de uma consulta especificada fazendo uma solicitação PATCH para o /queries endpoint e fornecimento do query id no caminho da solicitação.

Formato da API

PATCH /queries/{QUERY_ID}

Parâmetro

Descrição

{QUERY_ID}

A variável id valor da consulta na qual você deseja executar a operação.

Solicitação

Essa solicitação de API usa a sintaxe do patch de JSON para sua carga. Para obter mais informações sobre como o Patch JSON funciona, leia o documento Fundamentos da API.

curl -X PATCH https://platform.adobe.io/data/foundation/query/queries/4d64cd49-cf8f-463a-a182-54bccb9954fc \
 -H 'Authorization: Bearer {ACCESS_TOKEN}' \
 -H 'Content-Type: application/json',
 -H 'x-gw-ims-org-id: {ORG_ID}' \
 -H 'x-api-key: {API_KEY}' \
 -H 'x-sandbox-name: {SANDBOX_NAME}'
 -d '{
   "op": "cancel"
 }'

Propriedade

Descrição

op

O tipo de operação a ser executada no recurso. Os valores aceitos são cancel e soft_delete. Para cancelar a consulta, você deve definir o parâmetro op com o valor cancel . Observe que a operação de exclusão reversível impede que a consulta seja retornada em solicitações GET, mas não a exclui do sistema.

Resposta

Uma resposta bem-sucedida retorna o status HTTP 202 (Aceito) com a seguinte mensagem:

{
    "message": "Query cancel request received",
    "statusCode": 202
}

recommendation-more-help

ccf2b369-4031-483f-af63-a93b5ae5e3fb