Criação de solicitações de API

Todas as chamadas de API do Orchestrator são feitas usando métodos HTTP para a URL do Orchestrator. A URL do Orchestrator tem a seguinte sintaxe: {AutomationCloudURL}/{organizationName}/{tenantName}/orchestrator_. Recomenda-se criptografar os dados que você envia por meio de chamadas de APIs, usando o protocolo HTTPS.

Folder Request Headers

Para acessar recursos em uma pasta, cada solicitação deve conter FolderId, FolderPathou FolderKey em um cabeçalho HTTP. Este cabeçalho pode ser codificado (usando a codificação Base64 UTF-16LE) ou texto simples.

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)

Observe que barras ao final não são aceitas.

Importante:

Ao usar a API do Orchestrator em conjunto com o MSXML, a resposta 204 Sem conteúdo pode resultar em um Código de status 1223 e causar erros.

Observação:

O parâmetro @odata.count não é exibido por padrão em resultados de API originários de atividades de fluxo de trabalho e integrações de API fora dos processos. Para incluí-lo, você deve adicionar manualmente $count=true ao ponto de extremidade desejado.

Solicitações GET

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	Finalidade
$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

$topo

Esta cláusula ajuda a limitar a quantidade de dados recuperados. Ele tem um limite máximo que é determinado pelo terminal para o qual você está fazendo chamadas e o número desses recursos existentes em suas instâncias do orquestrador.

Por exemplo, esta solicitação {AutomationCloudURL}/{organizationName}/{tenantName}/orchestrator_/odata/odata/Environments?$top=10 retorna os 10 primeiros ambientes disponíveis no Community Edition do Orchestrator. No entanto, se existirem apenas 5 ambientes, apenas esses serão recuperados.

$filter

Esta cláusula OData é usada para filtrar um recurso específico de acordo com suas propriedades.

Por exemplo, pode-se filtrar de acordo com:

• propriedades numéricas:
  • {AutomationCloudURL}/{organizationName}/{tenantName}/orchestrator_/odata/odata/Environments?$filter=Id%20eq%2015
    • solicita um ambiente específico com base em seu ID
• Propriedades do texto:
  • {AutomationCloudURL}/{organizationName}/{tenantName}/orchestrator_/odata/odata/Environments?$filter=contains(Name,'N')&$top=10
    • retorna os primeiros 10 ambientes cujo nome contém a letra "N"
• propriedades booleanas:
  • {AutomationCloudURL}/{organizationName}/{tenantName}/orchestrator_/odata/odata/Processes?$filter=Title%20eq%20'test'%20%26%20IsLatestVersion%20eq%20true
    • retorna todos os processos que contêm a palavra "teste" e representam a versão mais recente
• propriedades enumeráveis:
  • {AutomationCloudURL}/{organizationName}/{tenantName}/orchestrator_/odata/odata/QueueItems?$filter=Priority%20eq%20'High'
    • retorna todos os itens da fila que têm prioridade alta
• a propriedade de uma propriedade:
  • {AutomationCloudURL}/{organizationName}/{tenantName}/orchestrator_/odata/odata/Jobs?$top=10$filter=Robot/MachineName%20eq%20'Documentation'
    • retorna os 10 primeiros trabalhos que qualquer robô existente na máquina "Documentação" executou

Os parâmetros de filtro podem ser combinados usando operadores lógicos "and", "or" e/ou "and/or". Além disso, podem ser agrupados com parênteses "()", como na seguinte solicitação:

• {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) - exibe os 10 principais trabalhos que estão sendo executados manualmente ou após "2017-10-28T12:13:00.07Z", por um robô implantado na máquina "LAVINIA-PC".

Problema conhecido

Consultas do OData $filter que contêm uma expressão que compara um objeto complexo aninhado a null não funcionam.Por exemplo, o uso da expressão Release ne null retorna um erro, porque Release é um objeto complexo que inclui suas próprias propriedades aninhadas.

Nesses casos, recomendamos substituir o objeto complexo por um objeto simples.

Exemplos:

• Você pode substituir Release ne nullpor ReleaseName ne null, pois ReleaseNameé um objeto simples existente.
  Observação:

  Você não pode substituir Machine ne null por MachineName ne null, pois MachineName não existe.

• Você pode usar uma propriedade aninhada no objeto complexo para comparação. Por exemplo, Release/Name ne nullpode substituir Release ne null, e Machine/Name ne nullpode substituir Machine ne null.

$expandir

Esta cláusula é usada para carregar totalmente as propriedades de navegação do recurso solicitado.

$selecionar

Essa cláusula OData permite que você especifique um subconjunto de propriedades de recurso que deseja retornar. Se você deseja extrair vários recursos, pode separá-los usando uma vírgula.

$orderby

A cláusula $orderby permite que você classifique os recursos recuperados. Assim como na cláusula $select , os recursos que você deseja classificar são separados por vírgulas e podem ser classificados em ordem crescente (asc) ou decrescente (desc). Se nenhum desses operadores for especificado, os recursos serão classificados automaticamente em ordem crescente.

$skip

Esta cláusula permite pular o primeiro n número de itens, em um filtro indicado.

Solicitações POST

O verbo POST HTTP ajuda você a criar novos itens, subordinados a outros recursos. Ao criar um novo recurso, faça um POST para o pai e o Orchestrator se encarrega de associar o novo recurso ao pai, atribuindo um ID e outras informações necessárias. Os dados são adicionados através do corpo da requisição, e a resposta é todo o objeto criado.

Você pode adicionar novos itens a uma fila, criar novos ativos, ambientes ou processos, atribuir um revisor a uma ou várias transações com falha e a lista continua.

Observação:

Caracteres especiais não podem ser escapados no corpo de solicitações POST. Para usar caracteres especiais, você precisa primeiro declarar como string o parâmetro em que eles são usados, utilizando o seguinte formato "[e-mail]": "#String". Para entender melhor, consulte como o parâmetro Specific Content foi preenchido no exemplo abaixo.

Solicitações PUT

PUT geralmente é necessário quando você deseja atualizar o conteúdo de um recurso. Em geral, as solicitações são feitas para uma entidade específica adicionando seu Id na URL. Observe que uma chamada PUT substitui a entidade existente pelo conteúdo da solicitação ou, se não existir nenhuma no local designado, tenta criá-la.

É possível atualizar filas, ambientes, unidades de organização, comentários sobre transações, detalhes de processos e outros recursos.

Solicitações PATCH

O PATCH é usado para atualizar o conteúdo de uma entidade existente, com a entidade desejada especificada adicionando Id ao URL. O corpo da solicitação contém apenas o conteúdo que você deseja alterar. Isso é diferente de uma chamada PUT que substitui a entidade atual pelo conteúdo da solicitação subsequente.

É possível usar uma solicitação PATCH para atualizar as entidades Máquinas, Processos, Robôs, Locatários, Usuários (exceto Unidade Organizacional e Funções) e Webhooks.

Solicitações DELETE

O uso desse verbo HTTP permite marcar um item especificado como excluído no banco de dados. O recurso geralmente é indicado com a ajuda de seu Id na URL para a qual você faz a chamada. Uma resposta 204 deve informar que sua solicitação foi bem-sucedida.

É possível excluir ativos, ambientes, comentários de itens de fila, processos, funções, inquilinos, usuários e muitos outros.