Criação de solicitações de API

Estrutura e sintaxe das chamadas de API do Orchestrator, incluindo formato de URL e recomendações de HTTPS.

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.

Cabeçalhos de solicitação de pasta

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.

Formatos de cabeçalho de pasta compatíveis:

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

Obtendo FolderId

O FolderId pode ser obtido executando uma solicitação GET no 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. Se você alterar o plano de licenciamento para sua conta do Orchestrator (por exemplo, de Avaliação Enterprise para Enterprise), o valor FolderId também será alterado.

Obtendo FolderKey

O FolderKey pode ser obtido executando uma solicitação GET no ponto de extremidade /odata/Folders e copiando o valor de "Key". FolderKey é do tipo ID exclusivo/String. O valor FolderKey permanece o mesmo mesmo se você alterar seu plano de licenciamento.

Caminhos de pastas relativos

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

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

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

As solicitações GET são geralmente as mais simples de fazer. Elas ajudam você a recuperar dados e usam cláusulas genéricas do OData mostradas na tabela abaixo.

Referência das cláusulas do OData

Cláusula	Finalidade
$top	Limitar o número de resultados retornados
$filter	Filtrar resultados com base nas condições da propriedade
$expand	Carregar propriedades de navegação do recurso solicitado
$select	Especifique um subconjunto de propriedades do recurso a ser retornado
$orderby	Classificar resultados por propriedades especificadas
$skip	Ignorar um número especificado de itens nos resultados

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