Saltar para o conteúdo
Verificado

Consultar dados através da API

A referência completa do data_module, as formas de filtro e ordenação do dbs_read e o que dbs_delete e dbs_restore realmente alteram.

Seis métodos do data_module cobrem uma tabela de ponta a ponta: os mesmos seis que a grelha de uma tabela chama, no Studio e no separador Dados do dashboard, e os mesmos que uma app em execução chama através de xu.dbs_* (veja JavaScript Framework). Com uma chave de API da conta são acessíveis diretamente, veja Consultar e escrever dados da app para um percurso prático de dbs_read / dbs_create com corpos de pedido e de resposta. Esta página é a referência dos outros quatro e das opções de filtro, ordenação e arquivo que o dbs_read aceita.

Métodos

Todos recebem table_id, o _id do próprio nó da tabela, nunca o seu nome de apresentação, e toda a escrita passa pelas mesmas conversões de tipo de campo descritas em Tabelas e campos.

Atualizar uma linha

POST/cpi/dbs_update
admin

DBS Update

Replaces the data of an existing record, identified by row_id, in the specified app table.

table_data é fundido nos dados existentes da linha por id de campo, só os campos que incluir são alterados, todos os outros campos que a linha já tem ficam como estavam. Envie apenas os campos que pretende alterar, não é preciso ler primeiro a linha para preservar o resto.

Eliminar e restaurar linhas

POST/cpi/dbs_delete
admin

DBS Delete

Soft-deletes (or permanently deletes when 'permanent' is set) the listed record IDs from an app table.

POST/cpi/dbs_restore
admin

DBS Restore

Restores previously soft-deleted records, identified by their IDs, in the specified app table.

dbs_delete sem permanent não remove a linha, passa-a para arquivada, o mesmo estado em que uma linha fica quando alguém a arquiva na grelha. Uma linha arquivada deixa de aparecer num dbs_read normal, mas continua a existir e continua a contar para o valor de arquivadas de get_table_counts, e o dbs_restore volta a pô-la logo no estado anterior. permanent: true salta o passo de arquivo e elimina a linha de vez, o que o dbs_restore não pode desfazer.

Arquivo de linha, não de tabela

Este é o estado active/archived da própria linha, definido com dbs_delete e dbs_restore e lido de volta com o indicador archived do dbs_read. Não tem relação com o arquivo de uma tabela inteira como nó do Studio, tratado em Tabelas e campos.

Contar linhas

POST/cpi/get_table_counts
admin

Get Table Counts

Returns the number of records in a table: active records, or archived records when archived is true.

Devolve o número de linhas ativas e arquivadas de uma tabela, os mesmos valores que o dbs_read já anexa à sua própria resposta como total_table_count, úteis por si só quando quer uma contagem sem percorrer linhas para a obter.

Filtrar uma leitura

O campo query do dbs_read é um objeto com chave por id de campo, cada valor a indicar um tipo de filtro e um operador:

json
{
  "query": {
    "STU_Campus": { "filterType": "text", "type": "equals", "filter": "Downtown" },
    "STU_Age": { "filterType": "number", "type": "greaterThanOrEqual", "filter": 18 }
  }
}

Todos os campos indicados em query são combinados com os outros com AND. Um único campo também pode ter a sua própria lista de conditions com um operator OR ou AND entre elas, para "este campo corresponde a qualquer um destes":

json
{
  "query": {
    "STU_Campus": {
      "operator": "OR",
      "conditions": [
        { "filterType": "text", "type": "equals", "filter": "Downtown" },
        { "filterType": "text", "type": "equals", "filter": "Uptown" }
      ]
    }
  }
}

Ordenar e paginar

sortModel é uma lista de pares { colId, sort } (sort é asc ou desc), aplicados pela ordem indicada numa ordenação por várias colunas. from e to são um intervalo de linhas (from o deslocamento, to - from o tamanho da página), ambos opcionais; omita-os e obtém a página predefinida da tabela.

Erros que vale a pena conhecer

Aplicam-se a todos os seis métodos acima, não apenas a uma escrita: