Consultar Registros de Entidade

Consulta registros de entidade.

Ponto de Extremidade da API

POST BaseURL/EntityService/<Entity>/query

• Dependendo da plataforma de cloud que você está usando, use a URL Base associada.

Cabeçalhos de solicitação.

Cabeçalho	Valor
Autorização	O portador <access_token>
Tipo de conteúdo	application/json

Observação:

Substitua todos os valores entre os colchetes angulares <...> por seus valores de caso de uso correspondentes.

O <access_token> é aquele que você recebeu quando autorizou o aplicativo externo. Ele fica disponível por 1 hora, então você precisa gerar um novo, ou solicitar um token de atualização.

Parâmetros de Consulta

Parâmetro de consulta	Tipo de dados	Description	Valor padrão
Expansão (opcional)	int32	Especifica a profundidade dos registros relacionados a serem recuperados. O valor deste parâmetro pode ser 1, 2 ou 3.	2

Corpo da solicitação (obrigatório)

{
  "selectedFields": [
    "string"
  ],
  "filterGroup": {
    "logicalOperator": 0,
    "queryFilters": [
      {
        "fieldName": "string",
        "operator": "string",
        "value": "string"
      }
    ],
    "filterGroups": [
    ]
  },
  "start": 0,
  "limit": 0,
  "sortOptions": [
    {
      "fieldName": "string",
      "isDescending": true
    }
  ]
}

Solicitar esquemas de corpo

O corpo da solicitação de endpoint query tem os seguintes componentes:

selectedFields

Este é um componente opcional, do tipo string. Especifica a lista dos campos a serem retornados para cada registro da consulta. Se deixado em branco ou se a lista de consulta estiver vazia, todos os campos de registro serão retornados. O valor padrão é null.

filterGroup

Este é um componente obrigatório que ajuda a definir as propriedades de filtragem para a consulta. Combina as seguintes propriedades:

• Lógica - Essa é uma propriedade opcional de GrupoDeFiltros , do tipo int32. Especifica se todos os filtros e grupos de filtros se aplicam à consulta. Use 0 para aplicar todos os filtros e grupos de filtros. Use 1 para aplicar qualquer um dos filtros e grupos de filtros. O valor padrão é 0.

• consultaFiltro - Essa é uma propriedade filtrarGrupo necessária, que ajuda você a definir a expressão de filtragem. Ele tem as seguintes propriedades:

  propriedade QueryFilter	Tipo de dados	Description
  fieldName	string	Especifica o nome do campo a ser filtrado.
  operator	string	Especifica o operador do filtro. Suporta o seguinte: contains, not contains, startswith, endswith, =, !=, >, <,>=, <=, in, not in. Use o operador adequado para o tipo de campo correspondente.
  Value	string	Especifica o valor de filtragem.

• FilterGroups - Esta é uma propriedade opcional do FilterGroup , no caso de você precisar definir outra opção de filtragem para a consulta. Ele contém todas as propriedades FilterGroup listadas acima.

Iniciar

Esse é um componente opcional, do tipo int32. Especifica o número de registros a ignorar antes de recuperar os registros da consulta. Pode ser usado junto com a propriedade limit para implementar a paginação. Os registros são ordenados em ordem crescente por seus IDs. Para modificar a ordem de classificação, use a propriedade sortOptions . O valor padrão é 0.

limit

Esse é um componente opcional, do tipo int32. Especifica o número máximo de registros a serem lidos da entidade. Pode ser usado junto com a propriedade inicial para implementar a paginação. O valor padrão é 100 e o valor máximo é 1000.

sortOptions

Este é um componente opcional, que ajuda a classificar os registros consultados por uma lista de campos. Se deixados em branco, os registros serão classificados em ordem crescente por seus IDs. Combina as seguintes propriedades:

• NomeDoCampo - Essa é uma propriedade OpçõesDeClassificação obrigatória, do tipo string. Especifica o nome do campo usado para classificar os registros. O nome deve corresponder a um campo válido e diferencia maiúsculas de minúsculas.
• estáDescendente - Esta é uma propriedade opcional sortOptions , do tipo boolean. Defina-o como true se você quiser classificar os registros em ordem decrescente. O valor padrão é false.

Resposta

200 OK

{
  "TotalRecordCount": 0,
  "Value": [
    {
      "ClosingDate": "2021-03-04",
      "CreatedBy": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "CreateTime": "2021-03-04T10:21:22.771Z",
      "Id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "Logo": {
        "Name": "string",
        "Path": "string",
        "Size": 0,
        "Type": "string"
      },
      "Name": "string",
      "Nations": 0,
      "OlymipcsVersion": 0,
      "OpeningDate": "2021-03-04",
      "UpdatedBy": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "UpdateTime": "2021-03-04T10:21:22.771Z"
    }
  ]
}

Esquema do corpo da resposta

O corpo da resposta do endpoint query tem os seguintes componentes:

• ContagemDeRegistrostotal - O número total de registros correspondentes aos filtros de consulta especificados.
• valor - Uma matriz de registros de entidade correspondentes aos filtros de consulta especificados, limitados pela propriedade limit .

401 não autorizado

Você não tem autenticação para acessar o Data Fabric/Data Service. Verifique se seu Assistant ou Robô está conectado a uma pasta moderna em sua conta.

403 Forbidden

Você não tem permissão para acessar a entidade, o campo ou o registro, ou está usando um tipo de robô incompatível. Ou entre em contato com o administrador para obter as permissões necessárias.

Agregar funções

Você pode executar cálculos agregados em uma única entidade adicionando as propriedades aggregates e groupBy ao corpo da solicitação. As agregações retornam valores computados (como totais ou médias), por conta própria ou ao lado de valores de campo agrupados.

Corpo da Solicitação

{
  "selectedFields": [
    "Department"
  ],
  "aggregates": [
    {
      "function": "COUNT",
      "field": "Id",
      "alias": "EmployeeCount"
    }
  ],
  "groupBy": [
    "Department"
  ],
  "filterGroup": {
    "logicalOperator": 0,
    "queryFilters": [
      {
        "fieldName": "Status",
        "operator": "=",
        "value": "Active"
      }
    ]
  },
  "sortOptions": [
    {
      "fieldName": "EmployeeCount",
      "isDescending": true
    }
  ],
  "start": 0,
  "limit": 100
}

Agregar componentes de solicitação

Além das propriedades de consulta base, as consultas agregadas usam os seguintes componentes:

Agregados

Esse é um componente opcional, do tipo array. Especifica as funções agregadas a serem aplicadas. Você pode incluir no máximo cinco agregações por consulta. Cada item tem as seguintes propriedades:

propriedade de agregações	Tipo de dados	Required	Description
function	string	Sim	A função agregada a ser aplicada. Valores suportados: COUNT, SUM, AVG, MIN, MAX. Sem distinção entre maiúsculas e minúsculas.
Campo	string	Sim	O campo a ser agregado. Deve ser um campo da entidade consultada.
Alias	string	Não	O nome da coluna de resultado. Se omitido, ele é gerado automaticamente como {FUNCTION}_{FIELD} (por exemplo, COUNT_Id). Os alias devem ser exclusivos dentro da consulta (sem diferenciação entre maiúsculas e minúsculas), começar com uma letra e conter apenas letras, dígitos e sublinhados.

Agrupar por

Esse é um componente opcional, do tipo array de string. Especifica os campos pelos quais os resultados serão agrupados. É possível incluir no máximo cinco campos.

Quando você fornece aggregates e um selectedFields não vazio, groupBy é necessário e todo campo em selectedFields também deve aparecer em groupBy.

Observação:

Ao classificar uma consulta agregada, defina sortOptions.fieldName para um alias agregado ou para um campo que faça parte de selectedFields/groupBy.

Suporte ao tipo de campo

Função	Tipos de campos compatíveis
Contagem, Mín, Máx	Qualquer tipo de campo, exceto campos de anexo e campos de texto multilinhas (regular MULTILINE e grande MULTILINE_MAX).
SOMA, AVG	Apenas campos numéricos: INT, BIGINT, DECIMAL, FLOAT, REAL.

Limites e restrições

• Um máximo de cinco funções agregadas e cinco campos groupBy por consulta.
• Os agregados não podem ser combinados com expansões (expansionLevel).
• Os agregados são compatíveis apenas com entidades padrão (baseadas em tabela). Eles não são compatíveis com entidades virtuais (origens de dados externas), conjuntos de escolhas ou entidades do sistema.
• Os agregados não podem ser aplicados a campos de anexo ou a campos de texto multilinhas (tanto MULTILINE regulares quanto MULTILINE_MAX grandes). Isso se aplica a todas as funções, incluindo COUNT.
• Os filtros de permissão no nível do registro (nível de linha) não são aplicados a resultados agregados: os valores agregados são calculados em todos os registros na entidade, incluindo registros que o chamador não pode ler individualmente. As permissões de leitura no nível da entidade e no nível do campo ainda são aplicadas; não é possível agregar ou agrupar por um campo que você não tem permissão para ler.

Exemplo: contagem agrupada por um campo

Contagens de funcionários por departamento, ordenados por contagem decrescente.

Solicitação:

POST BaseURL/EntityService/Employees/query

{
  "selectedFields": ["Department"],
  "aggregates": [
    { "function": "COUNT", "field": "Id", "alias": "EmployeeCount" }
  ],
  "groupBy": ["Department"],
  "sortOptions": [
    { "fieldName": "EmployeeCount", "isDescending": true }
  ]
}

Resposta:

{
  "TotalRecordCount": 3,
  "Value": [
    { "Department": "Engineering", "EmployeeCount": 150 },
    { "Department": "Sales", "EmployeeCount": 80 },
    { "Department": "HR", "EmployeeCount": 20 }
  ]
}

Consultas de várias entidades ( junções)

Você pode combinar registros de entidades relacionadas em uma única consulta adicionando a propriedade joins ao corpo da solicitação. As junções podem ser usadas por conta própria ou em conjunto com agregados e groupBy.

A entidade principal (esquerda) é aquela na URL da solicitação (<Entity>). Cada junção adiciona outra entidade à consulta.

Corpo da Solicitação

{
  "selectedFields": [
    "Employees.Name",
    "Departments.Name"
  ],
  "joins": [
    {
      "type": "INNER",
      "entity": "Departments",
      "on": {
        "left": "Employees.DepartmentId",
        "right": "Departments.Id"
      }
    }
  ],
  "sortOptions": [
    {
      "fieldName": "Employees.Name",
      "isDescending": false
    }
  ],
  "start": 0,
  "limit": 100
}

Qualificação do campo

Quando uma consulta abrange várias entidades, consulte os campos como EntityName.fieldName. Você pode usar o não qualificado fieldName somente quando ele for exclusivo em todas as entidades na consulta; caso contrário, será rejeitada como ambígua. Os nomes das entidades não diferenciam maiúsculas de minúsculas.

Isso se aplica a selectedFields, groupBy, sortOptions.fieldName, aos filtros filterGroup , aggregates.field, e aos valores de junção on.left/on.right . Na resposta, os campos são sempre retornados qualificados como EntityName.fieldName.

Componentes de solicitação de associação

Adesões

Esse é um componente opcional, do tipo array. Especifica as entidades a serem associadas. É possível incluir no máximo três junções. Cada item tem as seguintes propriedades:

propriedade de associação	Tipo de dados	Required	Description
Tipo	string	Sim	O tipo de associação. Valores aceitos: INNER, LEFT. Sem distinção entre maiúsculas e minúsculas. Todas as junções em uma única consulta devem ser do mesmo tipo; a mistura INNER e LEFT não é suportada.
Entidade	string	Sim	O nome da entidade na qual ingressar. Cada entidade pode aparecer apenas uma vez e não pode ser a entidade principal (as junções automáticas não são compatíveis).
ativada	object	Sim	A condição de associação. Contém left e right.
à esquerda	string	Sim	O campo de junção no lado esquerdo, como fieldName (se inequívoco) ou EntityName.fieldName.
à direita	string	Sim	O campo de junção no lado direito, como fieldName (se inequívoco) ou EntityName.fieldName.

Limites e restrições

• Um máximo de três junções por consulta, todas do mesmo tipo (INNER ou LEFT).
• As chaves de junção em ambos os lado devem ter tipos compatíveis (numérico com numérico, texto com texto, data com data).
• Você não pode unir em: campos gerados pelo sistema, campos criptografados, campos de texto grandes (máximo de multilinha), campos de conjunto de escolha ou conjunto de múltipla escolha ou campos de arquivo (anexo). Campos de relacionamento podem ser usados como chaves de junção.
• A cláusula HAVING não é compatível.
• Ao combinar junções com agregados, as regras agregadas e groupBy descritas na seção Funções agregadas também se aplicam.

Exemplo: junção à esquerda com uma agregação

Lista os clientes com sua contagem de pedidos, incluindo os que não têm pedidos.

Solicitação:

POST BaseURL/EntityService/Customers/query

{
  "selectedFields": ["Customers.Id", "Customers.Name"],
  "aggregates": [
    { "function": "COUNT", "field": "Orders.Id", "alias": "OrderCount" }
  ],
  "joins": [
    {
      "type": "LEFT",
      "entity": "Orders",
      "on": { "left": "Customers.Id", "right": "Orders.CustomerId" }
    }
  ],
  "groupBy": ["Customers.Id", "Customers.Name"],
  "sortOptions": [
    { "fieldName": "OrderCount", "isDescending": true }
  ]
}

Resposta:

{
  "TotalRecordCount": 3,
  "Value": [
    { "Customers.Id": "C-001", "Customers.Name": "Acme Corp", "OrderCount": 12 },
    { "Customers.Id": "C-002", "Customers.Name": "Globex", "OrderCount": 3 },
    { "Customers.Id": "C-003", "Customers.Name": "Initech", "OrderCount": 0 }
  ]
}