Consultar los registros de la entidad

Consulta los registros de la entidad.

Punto final de API

POST BaseURL/EntityService/<Entity>/query

• Dependiendo de la plataforma en la nube que estés utilizando, utiliza la URL base asociada.

Solicitar encabezados.

Encabezado	Valor
Autorización	Portador <access_token>
Tipo de contenido	application/json

Nota:

Reemplaza todos los valores entre corchetes angulares <...> con sus valores de caso de uso correspondientes.

El <access_token> es el que recibió cuando autorizó la aplicación externa. Está disponible durante 1 hora; luego debes generar uno nuevo o solicitar un token de actualización.

Parámetros de consulta

Parámetro de consulta	Tipo de datos	Descripción	Valor predeterminado
nivelDeExpansión (opcional)	int32	Especifica la profundidad de los registros relacionados que se van a recuperar. El valor de este parámetro puede ser 1, 2 o 3.	2

Cuerpo de la solicitud (obligatorio)

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

El cuerpo de la solicitud del punto final query tiene los siguientes componentes:

selectedFields

Este es un componente opcional, de tipo string. Especifica la lista de campos que se devolverán para cada registro de la consulta. Si se deja vacía o si la lista de consulta está vacía, se devuelven todos los campos de registros. El valor predeterminado es null.

GrupoDeFiltro

Este es un componente obligatorio que te ayuda a establecer las propiedades de filtrado para la consulta. Combina las siguientes propiedades:

• OperadorLógico : esta es una propiedad opcional de FilterGroup , de int32. Especifica si todos los filtros y grupos de filtros se aplican a la consulta. Usa 0 para aplicar todos los filtros y grupos de filtros. Utiliza 1 para aplicar cualquiera de los filtros y grupos de filtros. El valor predeterminado es 0.

• consultaFiltro : esta es una propiedad de GrupoDeFiltros obligatoria, que te ayuda a definir la expresión de filtrado. Tiene las siguientes propiedades:

  propiedad FiltroDeConsulta	Tipo de datos	Descripción
  fieldName	string	Especifica el nombre del campo que se va a filtrar.
  operator	string	Especifica el operador de filtro. Admite lo siguiente: contains, not contains, startswith, endswith, =, !=, >, <,>=, <=, in, not in. Utiliza el operador adecuado para el tipo de campo correspondiente.
  valor	string	Especifica el valor de filtrado.

• GruposDeFiltros : esta es una propiedad GrupoDeFiltros opcional, en caso de que necesites establecer otra opción de filtrado para la consulta. Contiene todas las propiedades de FilterGroup enumeradas anteriormente.

Iniciar

Este es un componente opcional, de tipo int32. Especifica el número de registros que se omitirán antes de recuperar los registros de la consulta. Se puede utilizar junto con la propiedad de límite para implementar la paginación. Los registros están ordenados de forma ascendente por sus ID. Para modificar el orden de clasificación, utiliza la propiedad sortOptions . El valor predeterminado es 0.

limit

Este es un componente opcional, de tipo int32. Especifica el número máximo de registros que se leerán de la entidad. Se puede utilizar junto con la propiedad de inicio para implementar la paginación. El valor predeterminado es 100 y el valor máximo es 1000.

sortOptions

Este es un componente opcional que te ayuda a ordenar los registros consultados por una lista de campos. Si se deja vacío, los registros se ordenan de forma ascendente por sus ID. Combina las siguientes propiedades:

• NombreDeCampo : esta es una propiedad de OpcionesDeOrdenación obligatoria, de tipo string. Especifica el nombre del campo utilizado para ordenar los registros. El nombre debe corresponder a un campo válido y distingue entre mayúsculas y minúsculas.
• esDescendente : esta es una propiedad opcional de opcionesDeOrdenación , de tipo boolean. Establécelo en true si quieres ordenar los registros de forma descendente. El valor predeterminado es false.

Respuesta

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 del cuerpo de la respuesta

El cuerpo de respuesta del punto final query tiene los siguientes componentes:

• totalDeRecordCount : el número total de registros que coinciden con los filtros de consulta especificados.
• valor : una matriz de registros de entidad que coinciden con los filtros de consulta especificados, limitados por la propiedad de límite .

401 No autorizado

No está autenticado para acceder a Data Fabric/Data Service. Asegúrate de que tu UiPath Assistant o Robot esté conectado a una carpeta moderna en tu cuenta.

403 Forbidden

No tiene permiso para acceder a la entidad, campo o registro, o está utilizando un tipo de robot no compatible. Póngase en contacto con su administrador para obtener los permisos necesarios.

Funciones agregadas

Puedes ejecutar cálculos agregados sobre una sola entidad añadiendo las propiedades aggregates y groupBy al cuerpo de la solicitud. Los agregados devuelven valores calculados (como totales o promedios), ya sea solos o junto con valores de campo agrupados.

Solicitar cuerpo

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

Componentes de solicitud agregada

Además de las propiedades de consulta base, las consultas agregadas utilizan los siguientes componentes:

Agregación

Este es un componente opcional, de tipo matriz. Especifica las funciones de agregado que se van a aplicar. Puedes incluir un máximo de 5 agregados por consulta. Cada elemento tiene las siguientes propiedades:

propiedad de agregados	Tipo de datos	Obligatorio	Descripción
function	string	Sí	La función agregada que se aplicará. Valores admitidos: COUNT, SUM, AVG, MIN, MAX. No distingue entre mayúsculas y minúsculas.
Campo	string	Sí	El campo que se agregará. Debe ser un campo de la entidad consultada.
Alias	string	No	El nombre de la columna de resultados. Si se omite, se genera automáticamente como {FUNCTION}_{FIELD} (por ejemplo, COUNT_Id). Los alias deben ser únicos dentro de la consulta (no distinguen entre mayúsculas y minúsculas), comenzar con una letra y contener solo letras, dígitos y guiones bajos.

Agrupar por

Este es un componente opcional, de tipo matriz de string. Especifica los campos por los que agrupar los resultados. Puede incluir un máximo de 5 campos.

Cuando proporcionas tanto aggregates como un selectedFields no vacío, groupBy es obligatorio, y todos los campos de selectedFields también deben aparecer en groupBy.

Nota:

Al ordenar una consulta agregada, establece sortOptions.fieldName en un agregado alias, o en un campo que forme parte de selectedFields/groupBy.

Compatibilidad con tipos de campo

Función	Tipos de campos compatibles
RECUENTO, MÍN, MÁX	Cualquier tipo de campo, excepto campos de archivo adjunto y campos de texto multilínea (normales MULTILINE y grandes MULTILINE_MAX).
SUMA, PROMEDIO	Solo campos numéricos: INT, BIGINT, DECIMAL, FLOAT, REAL.

Límites y restricciones

• Un máximo de 5 funciones agregadas y 5 campos groupBy por consulta.
• Los agregados no se pueden combinar con expansiones (expansionLevel).
• Los agregados solo se admiten en entidades estándar (basadas en tablas). No son compatibles con entidades virtuales (fuentes de datos externas), conjuntos de opciones o entidades del sistema.
• Los agregados no se pueden aplicar a los campos de archivos adjuntos o a los campos de texto multilínea (tanto MULTILINE regulares como MULTILINE_MAX grandes). Esto se aplica a todas las funciones, incluida COUNT.
• Los filtros de permisos en el nivel de registro (nivel de fila) no se aplican a los resultados agregados: los valores agregados se calculan en todos los registros de la entidad, incluidos los registros que la persona que llama no puede leer individualmente. Los permisos de lectura a nivel de entidad y de campo se siguen aplicando; no puede agregar o agrupar por un campo que no tiene permiso para leer.

Ejemplo: recuento agrupado por un campo

Cuenta los empleados por departamento, ordenados por recuento descendente.

Solicitud:

POST BaseURL/EntityService/Employees/query

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

Respuesta:

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

Consultas multientidad (uniones)

Puedes combinar registros de entidades relacionadas en una sola consulta añadiendo la propiedad joins al cuerpo de la solicitud. Las uniones se pueden utilizar solas o junto con agregados y groupBy.

La entidad principal (izquierda) es la que está en la URL de la solicitud (<Entity>). Cada unión añade otra entidad a la consulta.

Solicitar cuerpo

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

Calificación de campo

Cuando una consulta abarca varias entidades, se refiere a los campos como EntityName.fieldName. Puedes utilizar el fieldName no calificado solo cuando es único en todas las entidades de la consulta; de lo contrario, se rechaza como ambigua. Los nombres de las entidades no distinguen entre mayúsculas y minúsculas.

Esto se aplica a selectedFields, groupBy, sortOptions.fieldName, los filtros filterGroup , aggregates.field y los valores de unión on.left/on.right . En la respuesta, los campos siempre se devuelven calificados como EntityName.fieldName.

Componentes de la solicitud de unión

Se une a

Este es un componente opcional, de tipo matriz. Especifica las entidades a unir. Puede incluir un máximo de 3 uniones. Cada elemento tiene las siguientes propiedades:

une la propiedad	Tipo de datos	Obligatorio	Descripción
Tipo	string	Sí	El tipo de unión. Valores admitidos: INNER, LEFT. No distingue entre mayúsculas y minúsculas. Todas las uniones en una sola consulta deben ser del mismo tipo; no se admite la combinación INNER y LEFT .
Entidad	string	Sí	El nombre de la entidad a la que se unirá. Cada entidad puede aparecer solo una vez y no puede ser la entidad principal (no se admiten las autouniones).
Activado	object	Sí	La condición de unión. Contiene left y right.
a.la.izquierda	string	Sí	El campo de unión en el lado izquierdo, como fieldName (si no es ambiguo) o EntityName.fieldName.
a.la.derecha	string	Sí	El campo de unión en el lado derecho, como fieldName (si no es ambiguo) o EntityName.fieldName.

Límites y restricciones

• Un máximo de 3 uniones por consulta, todas del mismo tipo (INNER o LEFT).
• Las claves de unión en ambos lados deben tener tipos compatibles (numérico con numérico, texto con texto, fecha con fecha).
• No puede unirse en: campos generados por el sistema, campos cifrados, campos de texto grandes (multilínea máx.), campos de conjunto de opciones o conjuntos de opciones múltiples, o campos de archivo (archivo adjunto). Los campos de relación se pueden utilizar como claves de unión.
• La cláusula HAVING no es compatible.
• Al combinar uniones con agregados, también se aplican las reglas de agregado y groupBy descritas en la sección Funciones de agregado .

Ejemplo: combinación izquierda con un agregado

Enumera los clientes con su recuento de pedidos, incluidos los clientes que no tienen pedidos.

Solicitud:

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 }
  ]
}

Respuesta:

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