Documentação do Oracle Cloud Infrastructure

Fornecendo Critérios de Conclusão com Sondagem

Para uma tarefa REST que chama uma operação de API REST de execução longa, marque a caixa de seleção Configurar uma condição de polling e encerramento para uma chamada REST sem espera na etapa Especificar critérios de conclusão para especificar a configuração de polling para identificar a conclusão da chamada REST.

Além da condição de sucesso, a configuração de sondagem inclui um URL REST de sondagem e uma condição, além de valores para um intervalo e um timeout de sondagem.

Você tem a opção de especificar uma configuração de encerramento para cancelar a operação de API de execução longa.

Para usar a resposta da API da etapa de execução na configuração de sondagem ou encerramento, crie expressões e inclua as expressões nomeadas nos URLs de sondagem e encerramento, bem como as condições de sondagem e sucesso.

Antes de configurar a sondagem ou o encerramento, crie as expressões para extrair os valores necessários de resposta da API.

Consulte também Sondagem em Operações de Execução Longa.

Adicionando Expressões para Uso em Sondagem

As expressões permitem designar um valor ou uma expressão a uma variável que você pode usar ao configurar a etapa de critérios de conclusão.

Crie expressões que usem a resposta da API na etapa de execução REST. Você fornece um nome para a expressão ao criá-la. Para incluir a expressão nomeada no URL de sondagem ou encerramento, ou a condição de sondagem ou sucesso, use a sintaxe #{expression_name}.

Por exemplo, se a tarefa REST chamar a operação de API para criar um projeto usando um nome de projeto específico, a solicitação de sondagem poderá verificar a chave do projeto para determinar se a sondagem continua ou é interrompida. Para usar a chave do projeto como variável no URL de pesquisa, crie uma expressão que extraia a chave da resposta do payload da API, convertendo-a em um valor do tipo de dados String ou JSON_TEXT.

Observe que uma expressão criada aqui não pode ser usada como saída de tarefa REST em outros operadores downstream da tarefa.

Para adicionar uma expressão:

  1. Na página Configurar detalhes da API REST, etapa Especificar critérios de conclusão, marque a caixa de seleção Configurar uma condição de sondagem e encerramento para uma chamada REST sem espera.
  2. Expanda a seção Expressões e selecione Adicionar expressão.
  3. No painel Adicionar expressão, seção Informações de expressão, faça o seguinte:
    1. Digite um nome para a expressão no campo Identificador.
    2. No menu Tipo de dados, selecione um tipo para essa expressão.
    3. Preencha os campos de propriedade para o tipo de dados selecionado. Por exemplo, digite um Tamanho para o tipo de dados STRING.
  4. Na seção Construtor de expressões, você pode construir visualmente uma expressão clicando duas vezes ou arrastando saídas, parâmetros ou funções de resposta de entrada para adicionar ao editor e criar a expressão. Ou você mesmo pode criar a expressão manualmente. Crie uma expressão que use a saída da resposta da solicitação REST.

    • Entrada: Você pode usar as saídas do sistema SYS.RESPONSE_PAYLOAD_JSON, SYS.RESPONSE_HEADERS_JSON e SYS.RESPONSE_STATUS.

    • Parâmetros: Você pode usar qualquer parâmetro definido no escopo dessa tarefa REST. Consulte Exibindo e Gerenciando Parâmetros em uma Tarefa REST.

    • Funções: Você pode usar as funções básicas String e Operador do Data Integration.

    Nem todas as funções são suportadas ao criar a expressão. Veja a lista suportada aqui.

    Para extrair valores de propriedade JSON do corpo de resposta da API, use a função String json_path com a saída de resposta recebida SYS.RESPONSE_PAYLOAD. Por exemplo:

    CAST(json_path(SYS.RESPONSE_PAYLOAD_JSON, '$.key') AS String)
    CAST(json_path(SYS.RESPONSE_PAYLOAD_JSON, '$.emp.ID') AS JSON_TEXT)
  5. Selecione Adicionar.
Editando ou Excluindo Expressões em Sondagem

Você pode editar e excluir expressões que você criou na sondagem.

Para editar ou excluir uma expressão:

  1. Na página Configurar detalhes da API REST, etapa Especificar critérios de conclusão, expanda a seção Expressões.
  2. Na tabela Expressões, localize a expressão que você deseja editar ou excluir.
  3. No menu Ações (Ações menu) da expressão, selecione Editar ou Excluir.
    • No painel Editar expressão, faça as alterações e selecione Salvar.
    • Na caixa da caixa de diálogo Excluir expressão, confirme se a expressão nomeada é a que você deseja excluir e selecione Excluir.
Configurando o Método HTTP e o URL de Sondagem

Em uma operação de API de execução longa, defina o método HTTP e o URL para sondar o status da chamada REST.

Semelhante ao URL REST na etapa de execução, você pode incluir parâmetros no URL de sondagem usando a sintaxe ${parameter_name}.

Além disso, você pode incluir expressões nomeadas usando a sintaxe #{expression_name}. Crie as expressões de que você precisa antes de configurar o URL de sondagem.

Para configurar o método de sondagem e o URL:

  1. Na página Configurar detalhes da API REST, etapa Especificar critérios de conclusão, marque a caixa de seleção Configurar uma condição de sondagem e encerramento para uma chamada REST sem espera.
  2. Na guia Sondagem, selecione o Método HTTP a ser usado para o URL de polling.
  3. No campo URL, digite o URL completo e pressione Enter.

    Se a sintaxe do parâmetro ${} for usada para partes do URL, essas partes serão convertidas em parâmetros de URL para a tarefa REST.

    A tabela na guia Parâmetros de URL abaixo do campo de URL é atualizada com as partes parâmetros. O tipo de dados padrão para cada parâmetro de URL é String.

    Se você editar o URL a qualquer momento adicionando ou removendo a sintaxe de parâmetro, a tabela de parâmetros de URL será atualizada adequadamente.

  4. Para designar um valor padrão a um parâmetro, consulte Configurando Parâmetros de URL.
  5. Para mostrar ou ocultar o URL da sondagem usando os valores padrão de parâmetro que você configurou, selecione Mostrar URL da visualização ou Ocultar URL da visualização.
  6. Para adicionar um cabeçalho, consulte Adicionando e Gerenciando um Cabeçalho.
  7. Se um corpo de solicitação for necessário, consulte Fornecendo um Corpo de Solicitação.
Especificando a Condição de Sondagem

A configuração de sondagem inclui uma condição de sondagem e valores de intervalo e timeout de sondagem.

A condição de sondagem é uma expressão que determina a interrupção ou a continuação da sondagem. Quando a expressão retorna falso, a sondagem é interrompida.

O Data Integration emite uma chamada de pesquisa repetidamente no intervalo de pesquisa especificado até que o valor do timeout especificado seja atingido ou até que a condição de pesquisa retorne falso, o que ocorre primeiro.

Para configurar a condição de sondagem:

  1. Na página Configurar detalhes da API REST, etapa Especificar critérios de conclusão, marque a caixa de seleção Configurar uma condição de sondagem e encerramento para uma chamada REST sem espera.
  2. Na guia Sondagem, seção Condições, faça o seguinte:
    1. Ao lado de Condição de sondagem, selecione Criar.
    2. No painel Create polling condition, digite uma expressão que use a saída da resposta da solicitação REST.

      A expressão de condição pode incluir os seguintes elementos:

      • Entrada: Saídas de resposta de entrada (por exemplo, SYS.RESPONSE_PAYLOAD_JSON, SYS.RESPONSE_HEADERS_JSON, SYS.RESPONSE_STATUS).

      • Parâmetros: Parâmetros definidos no escopo desta tarefa REST. Consulte Exibindo e Gerenciando Parâmetros em uma Tarefa REST.

      • Functions: Funções Básicas de String e Integração de Dados do Operador. A função json_path, encontrada em String, permite extrair valores de propriedade da resposta usando elementos de sintaxe JSONPath no formato: json_path(json_string, json_filter_path)

      Por exemplo: CAST(json_path(SYS.RESPONSE_PAYLOAD, '$.name') AS String) != 'My_Project'

  3. Na seção Condições, abaixo de Condição de pesquisa, digite um valor e escolha uma unidade de medida para Intervalo de pesquisa e Timeout de pesquisa.
    • Timeout de pesquisa: O período máximo de tempo permitido para que a pesquisa repetida ocorra na taxa de intervalo especificada. O valor de timeout deve ser superior ou igual a 120 segundos, mas inferior ou igual a 30 dias.
    • Intervalo de pesquisa: O tempo de espera antes de enviar a próxima solicitação de pesquisa. O valor do intervalo deve ser superior ou igual a 60 segundos e inferior ao valor de timeout especificado.
  4. Para atribuir um parâmetro de tarefa à condição, selecione Atribuir parâmetro. Consulte Parametrizando a Condição de Sondagem.
Parametrizando a Condição de Sondagem

Depois de adicionar uma condição de sondagem, você pode designar um parâmetro de tarefa à condição.

Para parametrizar a condição de sondagem em uma tarefa REST:

  1. Na página Configurar detalhes da API REST, vá para a etapa Especificar critérios de conclusão.
  2. No bloco Condições, ao lado de Condição de sondagem, selecione Designar parâmetro.
  3. No painel Adicionar parâmetro, digite um nome para o parâmetro no campo Identifier ou use o valor padrão.

    O nome do parâmetro deve ser exclusivo na tarefa REST. Para obter uma lista atual dos parâmetros na tarefa, consulte Exibindo Todos os Parâmetros em uma Tarefa REST.

  4. (Opcional) Digite uma Descrição para ajudar a identificar a finalidade do parâmetro para outros usuários.
  5. O Tipo do parâmetro é Expressão, que você não pode alterar.
  6. No Construtor de condições, defina a expressão de condição padrão para esse parâmetro. Essa condição padrão é usada no runtime, a menos que você altere o valor posteriormente (no design time ou no runtime).

    A expressão de condição pode incluir os seguintes elementos:

    • Entrada: Saídas de resposta de entrada (por exemplo, SYS.RESPONSE_PAYLOAD_JSON, SYS.RESPONSE_HEADERS_JSON, SYS.RESPONSE_STATUS).

    • Parâmetros: Parâmetros definidos no escopo desta tarefa REST. Consulte Exibindo e Gerenciando Parâmetros em uma Tarefa REST.

    • Functions: Funções Básicas de String e Integração de Dados do Operador. A função json_path, encontrada em String, permite extrair valores de propriedade da resposta usando elementos de sintaxe JSONPath no formato: json_path(json_string, json_filter_path)

    Por exemplo: CAST(json_path(SYS.RESPONSE_PAYLOAD, '$.name') AS String) != 'My_Project'

  7. Selecione Adicionar.
    O nome do parâmetro é adicionado ao lado da condição de sondagem.
Editando o Parâmetro de Condição de Sondagem

É possível alterar a descrição e o valor padrão do parâmetro de tarefa para a condição de polling.

Para editar a condição de sondagem parametrizada:

  1. Na página Configurar detalhes da API REST, vá para a etapa Especificar critérios de conclusão.
  2. No bloco Condições, selecione Editar parâmetro.
  3. No painel Editar parâmetro, você só pode editar a descrição e a expressão da condição de sondagem. Você não pode alterar o identificador (nome) e o tipo de dados.
  4. Selecione Salvar alterações.
Removendo o Parâmetro de Condição de Sondagem

A remoção do parâmetro de condição só remove a associação do parâmetro com a condição de sondagem especificada para a tarefa REST.

Para cancelar a designação do parâmetro da condição de sondagem:

  1. Na página Configurar detalhes da API REST, vá para a etapa Especificar critérios de conclusão.
  2. No bloco Condições, selecione Remover parâmetro.
  3. Na caixa de diálogo Remover parâmetro, selecione Remover.

    A designação do parâmetro é cancelada na condição de sondagem. A expressão de condição designada ao parâmetro se torna a condição de sondagem padrão para a tarefa REST.

    Observação

    O parâmetro não é excluído da tarefa REST. Para excluir o parâmetro, consulte Excluindo um Parâmetro de Tarefa REST.
Configurando o Método HTTP e o URL de Encerramento

Para uma tarefa REST que chama uma operação de API REST de longa execução, você pode especificar os detalhes da API REST para encerrar a operação de longa execução.

Na guia Encerramento, defina o método HTTP e o URL para encerrar a chamada REST.

Assim como o URL de sondagem, você pode incluir parâmetros e expressões no URL de encerramento usando a sintaxe ${parameter_name} e #{expression_name}. Crie as expressões necessárias antes de configurar o URL de encerramento.

Para configurar o método e o URL de encerramento:

  1. Na página Configurar detalhes da API REST, etapa Especificar critérios de conclusão, marque a caixa de seleção Configurar uma condição de sondagem e encerramento para uma chamada REST sem espera.
  2. Na guia Desligamento, selecione o método HTTP a ser usado para o URL.
  3. No campo URL, digite o URL completo e pressione Enter.

    Se a sintaxe do parâmetro ${} for usada para partes do URL, essas partes serão convertidas em parâmetros de URL para a tarefa REST.

    A tabela na guia Parâmetros de URL abaixo do campo de URL é atualizada com as partes parâmetros. O tipo de dados padrão para cada parâmetro de URL é String.

    Se você editar o URL a qualquer momento adicionando ou removendo a sintaxe de parâmetro, a tabela de parâmetros de URL será atualizada adequadamente.

  4. Para designar um valor padrão a um parâmetro, consulte Configurando Parâmetros de URL.
  5. Para mostrar ou ocultar o URL usando os valores padrão de parâmetro que você configurou, selecione Mostrar URL da visualização ou Ocultar URL da visualização.
  6. Para adicionar um cabeçalho, consulte Adicionando e Gerenciando um Cabeçalho.
  7. Se um corpo de solicitação for necessário, consulte Fornecendo um Corpo de Solicitação.
Especificando os Critérios de Conclusão (Condição de Sucesso)

A condição de sucesso em uma tarefa REST é uma expressão que determina uma conclusão bem-sucedida da chamada da API REST. A sondagem é interrompida quando a condição de sucesso é atendida.

Por padrão, o Data Integration fornece uma condição de sucesso para uma tarefa REST. A condição de sucesso padrão é um código de status HTTP igual ou superior a 200, mas inferior a 300, gravado como a seguinte expressão:

SYS.RESPONSE_STATUS >= 200 AND SYS.RESPONSE_STATUS < 300

A expressão da condição de sucesso faz referência à saída na resposta JSON recebida da solicitação REST definida na etapa de execução.

Você pode usar a condição de sucesso padrão ou pode criar uma expressão de condição usando saídas do sistema ou valores de propriedade JSON extraídos da resposta.

Para editar a condição de sucesso:

  1. Na página Configurar detalhes da API REST, vá para a etapa Especificar critérios de conclusão.
  2. Se a API REST chamar uma operação de longa execução, marque a caixa de seleção Configurar uma condição de polling e encerramento para uma chamada REST sem espera.
  3. No bloco Condições, ao lado de Condição do sucesso, selecione Editar.
  4. No painel Editar condição de sucesso, digite uma expressão que use a saída da resposta da solicitação REST.

    A expressão de condição pode incluir os seguintes elementos:

    • Entrada: Você pode usar as saídas de resposta de entrada (por exemplo, SYS.RESPONSE_PAYLOAD_JSON, SYS.RESPONSE_HEADERS_JSON, SYS.RESPONSE_STATUS).

    • Parâmetros: Você pode usar qualquer parâmetro definido no escopo dessa tarefa REST. Consulte Exibindo e Gerenciando Parâmetros em uma Tarefa REST.

    • Funções: Você pode usar as funções básicas String e Operador do Data Integration. A função json_path, encontrada em String, permite extrair valores de propriedade da resposta usando elementos de sintaxe JSONPath no formato: json_path(json_string, json_filter_path)

      Por exemplo: json_path(SYS.RESPONSE_PAYLOAD, '$.@STATUS')

    Nem todas as funções são suportadas em uma expressão de condição de sucesso. Veja a lista suportada aqui.

    (Para operações de execução longa) Se você tiver marcado a caixa de seleção Configurar uma condição de polling e encerramento para uma chamada REST sem espera, a condição de sucesso será uma expressão gravada na resposta da solicitação de polling. Você pode criar expressões que usam a resposta da API da etapa de execução e, em seguida, incluir as expressões nomeadas para criar a condição de sucesso.

  5. Para atribuir um parâmetro de tarefa à condição de sucesso, selecione Atribuir parâmetro. Consulte Parametrizando a Condição de Sucesso.