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: https://{yourDomain}/{organizationName}/{tenantName}/orchestrator_ . Recomenda-se criptografar os dados que você envia por meio de chamadas de APIs, usando o protocolo HTTPS.

Importante:

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.

Por exemplo:

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

O FolderId pode ser obtido executando uma solicitação GET para o ponto de extremidade /odata/Folders e copiando o valor “Id”, ou a partir do URL do Orchestrator — https://your-domain-server.com/?fid=2032&tid=8. FolderId é do tipo Int 64.

O FolderKey pode ser obtido executando uma solicitação GET para o terminal /odata/Folders e copiando o valor "Chave". FolderKey é do tipo ID/String Exclusivo.

Se você alterar o plano de licenciamento de sua conta do Orchestrator (por exemplo, de Enterprise Trial para Enterprise), o valor FolderId também mudará, enquanto o valor FolderKey permanecerá o mesmo.

Os caminhos de pastas relativos são suportados em um cabeçalho X-UIPATH-FolderPath-Encoded, da seguinte forma:

• Caminho que começa com / - começa na pasta root da árvore da qual a pasta Ambiente faz parte.
• Caminho que começa com . - começa na pasta Ambiente.
• Caminho começa com .. - começa um nível acima na hierarquia da pasta Ambiente para cada .. no caminho (por exemplo, ../ para um nível acima, ../../ para dois níveis acima na hierarquia).

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 oriundos de atividades de fluxo de trabalho. Para incluí-lo, você deve adicionar manualmente $count=true ao ponto de extremidade desejado.

Solicitações GET

As solicitações GET geralmente são as mais simples de serem feitas. Eles ajudam você a recuperar dados e usar cláusulas OData genéricas:

• $topo
• $filter
• $expandir
• $selecionar
• $orderby
• $skip

$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 https://{yourDomain}/{organizationName}/{tenantName}/orchestrator_/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:
  • https://{yourDomain}/{organizationName}/{tenantName}/orchestrator_/odata/Environments?$filter=Id%20eq%2015 - solicita um ambiente específico com base em seu ID
• Propriedades do texto:
  • https://{yourDomain}/{organizationName}/{tenantName}/orchestrator_/odata/Environments?$filter=contains(Name,'N')&$top=10 - retorna os 10 primeiros ambientes cujo nome contenha a letra "N"
• propriedades booleanas:
  • https://{yourDomain}/{organizationName}/{tenantName}/orchestrator_/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:
  • https://{yourDomain}/{organizationName}/{tenantName}/orchestrator_/odata/QueueItems?$filter=Priority%20eq%20'High' - retorna todos os itens da fila com alta prioridade
• a propriedade de uma propriedade:
  • https://{yourDomain}/{organizationName}/{tenantName}/orchestrator_/odata/Jobs?$top=10$filter=Robot/MachineName%20eq%20'Documentation' - retorna os primeiros 10 trabalhos que foram executados por qualquer Robô existente na máquina "Documentação"

Os parâmetros do filtro podem ser combinados usando operadores lógicos "and", "or" e/ou "not" e podem ser agrupados com parênteses "( )", como a seguinte solicitação:

• https://{yourDomain}/{organizationName}/{tenantName}/orchestrator_/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 nullpor MachineName ne null, MachineNamepois 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: os caracteres especiais não podem ter escape no corpo das solicitações POST. Para usar caracteres especiais, você precisa primeiro declarar o parâmetro em que os usa como string, usando o seguinte formato "[e-mail]": "#String". Para entender melhor, veja 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

PATCH é usado para atualizar o conteúdo de uma entidade existente, com a entidade desejada especificada adicionando seu Id na URL. O corpo da solicitação contém apenas o conteúdo que você deseja alterar. Isso se distingue 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.