Crear solicitudes de API

Todas las llamadas a la API de Orchestrator se realizan utilizando métodos HTTP a la URL de Orchestrator. La URL de Orchestrator tiene la siguiente sintaxis: {AutomationCloudURL}/{organizationName}/{tenantName}/orchestrator_. Recomendamos cifrar los datos que envíes a través de llamadas API usando el protocolo HTTPS.

Folder Request Headers

Para acceder a los recursos de una carpeta, cada solicitud debe contener FolderId, FolderPatho FolderKey en un encabezado HTTP. Este encabezado puede estar codificado (usando la codificación Base64 UTF-16LE) o como texto sin formato.

Supported folder header formats:

• X-UIPATH-OrganizationUnitId "FolderId"
• X-UIPATH-FolderPath-Encoded "{Encoded FolderPath value}"
• X-UIPATH-FolderPath "PlainText FolderPath value"
• X-UIPATH-FolderKey "FolderKey"

Obtaining FolderId

The FolderId can be obtained by performing a GET request to the /odata/Folders endpoint and copying the "Id" value, or from the Orchestrator URL - https://your-domain-server.com/?fid=2032&tid=8. FolderId is of type Int 64. If you change the licensing plan for your Orchestrator account (for example, from Enterprise Trial to Enterprise), the FolderId value also changes.

Obtaining FolderKey

The FolderKey can be obtained by performing a GET request to the /odata/Folders endpoint and copying the "Key" value. FolderKey is of type Unique Id/String. The FolderKey value remains the same even if you change your licensing plan.

Relative Folder Paths

Relative folder paths are supported in an X-UIPATH-FolderPath-Encoded header as follows:

• Path starting with / - starts from the root folder of the tree the ambient folder is part of
• Path starting with . - starts from the ambient folder
• Path starting with .. - starts one level up in the hierarchy for each .. in the path (e.g. ../ for one level up, ../../ for two levels up)

Ten en cuenta que no se admiten las barras diagonales finales.

Importante:

Cuando se utiliza la API de Orchestrator junto con MSXML, la respuesta "204 "Sin contenido puede generar un código de estado 1223 y provocar errores.

Nota:

El parámetro @odata.count no se emite de forma predeterminada en los resultados de la API que se originan en las actividades del flujo de trabajo y las integraciones de la API fuera de los procesos. Para incluirlo, debes añadir manualmente $count=true al punto final deseado.

Solicitudes OBTENER

GET requests are usually the simplest ones to make. They help you retrieve data and use generic OData clauses shown in the table below.

OData Clauses Reference

Clause	Propósito
$top	Limit the number of results returned
$filter	Filter results based on property conditions
$expand	Load navigation properties of the requested resource
$select	Specify a subset of resource properties to return
$orderby	Sort results by specified properties
$skip	Skip a specified number of items in results

$ top

Esta cláusula le ayuda a limitar la cantidad de datos que recupera. Tiene un límite superior que está determinado por el punto final al que está realizando llamadas y el número de recursos de este tipo que existen en sus instancias de Orchestrator.

Por ejemplo, esta solicitud {AutomationCloudURL}/{organizationName}/{tenantName}/orchestrator_/odata/odata/Environments?$top=10 devuelve los primeros 10 entornos disponibles en Community Edition de Orchestrator. Sin embargo, si solo existen 5 entornos, solo se recuperan.

$filter

Esta cláusula OData se utiliza para filtrar un recurso específico según sus propiedades.

Por ejemplo, se puede filtrar según:

• propiedades numéricas:
  • {AutomationCloudURL}/{organizationName}/{tenantName}/orchestrator_/odata/odata/Environments?$filter=Id%20eq%2015
    • solicita un entorno específico en función de su Id
• propiedades del texto:
  • {AutomationCloudURL}/{organizationName}/{tenantName}/orchestrator_/odata/odata/Environments?$filter=contains(Name,'N')&$top=10
    • devuelve los primeros 10 entornos cuyo nombre contiene la letra "N"
• propiedades Boolean:
  • {AutomationCloudURL}/{organizationName}/{tenantName}/orchestrator_/odata/odata/Processes?$filter=Title%20eq%20'test'%20%26%20IsLatestVersion%20eq%20true
    • devuelve todos los procesos que contienen la palabra "Prueba" y representan la versión más reciente
• propiedades enumerables:
  • {AutomationCloudURL}/{organizationName}/{tenantName}/orchestrator_/odata/odata/QueueItems?$filter=Priority%20eq%20'High'
    • devuelve todos los artículos en cola que tienen una prioridad Alta
• la propiedad de una propiedad:
  • {AutomationCloudURL}/{organizationName}/{tenantName}/orchestrator_/odata/odata/Jobs?$top=10$filter=Robot/MachineName%20eq%20'Documentation'
    • devuelve los primeros 10 trabajos que ejecutó cualquier robot existente en la máquina "Documentación"

Los parámetros de filtro se pueden combinar utilizando operadores lógicos "y", "o" y/o "no" y se pueden agrupar con paréntesis "()", como la siguiente solicitud:

• {AutomationCloudURL}/{organizationName}/{tenantName}/orchestrator_/odata/odata/Jobs?$top=10&$filter=Robot/MachineName eq 'LAVINIA-PC' and (not(Source eq 'Manual') or StartTime gt 2017-10-28T12:13:00.07Z) : muestra los 10 principales trabajos que se están ejecutando manualmente o después del "2017-10-28T12: 13: 00.07Z", por un Robot implementado en la máquina "LAVINIA-PC".

Problema conocido

Consultas de filtro OData $que contienen una expresión que compara un objeto complejo anidado con null no funcionan.Por ejemplo, utilizar la expresión Release ne null devuelve un error, porque Release es un objeto complejo que incluye sus propias propiedades anidadas.

En tales casos, recomendamos reemplazar el objeto complejo por un objeto simple.

Ejemplos:

• Puedes reemplazar Release ne null por ReleaseName ne null, ya que ReleaseName es un objeto simple existente.
  Nota:

  No se puede reemplazar Machine ne null por MachineName ne null, ya que MachineName no existe.

• Puedes utilizar una propiedad anidada en el objeto complejo para la comparación. Por ejemplo, Release/Name ne null puede reemplazar Release ne null, y Machine/Name ne null puede reemplazar Machine ne null.

$ expandir

Esta cláusula se utiliza para cargar completamente las propiedades de navegación del recurso solicitado.

$ seleccionar

Esta cláusula OData te permite especificar un subconjunto de propiedades del recurso que deseas que se devuelvan. Si quieres extraer varios recursos, puedes separarlos con una coma.

$ pedido por

La cláusula $orderby te permite ordenar los recursos recuperados. Al igual que con la cláusula $select , los recursos que deseas ordenar están separados por comas y se pueden ordenar en orden ascendente (asc) o descendente (desc). Si no se especifica ninguno de estos operadores, los recursos se ordenan automáticamente de manera ascendente.

$skip

Esta cláusula le permite omitir los primeros n elementos, en un filtro indicado.

Solicitudes POST

El verbo POST HTTP le ayuda a crear nuevos elementos subordinados a otros recursos. Al crear un nuevo recurso, PUBLICAR en el elemento principal y Orchestrator se encargará de asociar el nuevo recurso con el elemento principal, asignar una ID y otra información necesaria. Los datos se agregan a través del cuerpo de la solicitud y la respuesta es el objeto creado completo.

Puede agregar nuevos elementos a una cola, crear nuevos activos, entornos o procesos, asignar un revisor a una o varias transacciones fallidas y la lista continúa.

Nota:

No se pueden escapar los caracteres especiales en el cuerpo de las solicitudes POST. Para utilizar caracteres especiales, primero debes declarar el parámetro en el que los utilizas como cadena, utilizando el siguiente formato "[e-mail]": "#String". Para comprender mejor, consulta cómo se completó el parámetro Specific Content en el ejemplo a continuación.

Solicitudes PUT

PUT suele ser necesario cuando se quiere actualizar el contenido de un recurso. En general, las solicitudes se realizan a una entidad específica añadiendo su Id en la URL. Ten en cuenta que una llamada PUT reemplaza la entidad existente con el contenido de la solicitud o, si no existe en la ubicación designada, intenta crearla.

Es posible actualizar colas, entornos, unidades de organización, comentarios sobre transacciones, procesos y detalles de otros recursos.

Solicitudes PATCH

PATCH se utiliza para actualizar el contenido de una entidad existente, especificando la entidad deseada añadiendo su Id en la URL. El cuerpo de la solicitud contiene solo los contenidos que quieres cambiar. Esto se distingue de una llamada PUT que reemplaza la entidad actual con el contenido de la solicitud posterior.

Es posible utilizar una solicitud de PATCH para actualizar Máquinas, Procesos, Robots, Tenants, Usuarios (excepto la Unidad de Organización y los Roles) y las entidades de Webhooks.

Solicitudes ELIMINAR

El uso de este verbo HTTP te permite marcar un elemento especificado como eliminado en la base de datos. El recurso generalmente se indica con la ayuda de su ID en la URL a la que realiza la llamada. Una respuesta 209 debe informarle que su solicitud se ha realizado correctamente.

Es posible eliminar activos, entornos, comentarios de elementos de la cola, procesos, roles, tenants, usuarios y muchos otros.