APIs REST DBMS_CLOUD

Esta seção abrange as APIs REST DBMS_CLOUD fornecidas com o Autonomous AI Database on Dedicated Exadata Infrastructure.

Pré-requisitos

Como desenvolvedor, você pode usar procedimentos DBMS_CLOUD com Autonomous AI Databases implantados na Oracle Public Cloud, Multicloud ou Exadata Cloud@Customer.

Dependendo da opção de implantação, os pré-requisitos a seguir devem ser atendidos para usar os procedimentos DBMS_CLOUD com os provedores de serviços Amazon S3, Azure Blob Storage e Google Cloud Storage.

Resumo das APIs REST DBMS_CLOUD

Esta seção aborda as APIs REST DBMS_CLOUD fornecidas com o Autonomous AI Database.

API REST Descrição
Função GET_RESPONSE_HEADERS Esta função retorna os cabeçalhos de resposta HTTP como dados JSON em um objeto JSON no Autonomous AI Database.
Função GET_RESPONSE_TEXT Essa função retorna a resposta HTTP no formato TEXT (VARCHAR2 ou CLOB) no Autonomous AI Database. Em geral, a maioria das APIs REST na nuvem retorna uma resposta JSON em formato de texto. Esta função é útil se você espera que a resposta HTTP esteja em formato de texto.
Função GET_API_RESULT_CACHE_SIZE Esta função retorna o tamanho do cache de resultados configurado.
Função e Procedimento SEND_REQUEST Essa função inicia uma solicitação HTTP, obtém a resposta e encerra a resposta no Autonomous AI Database. Esta função fornece um workflow para enviar uma solicitação de API REST na Nuvem com argumentos e um código de resposta de retorno e payload.
Procedimento SET_API_RESULT_CACHE_SIZE Este procedimento define o tamanho máximo do cache para a sessão atual.

Visão Geral da API REST DBMS_CLOUD

Quando você usa PL/SQL em seu aplicativo e precisa chamar APIs REST na Nuvem, pode usar DBMS_CLOUD.SEND_REQUEST para enviar as solicitações de API REST.

As funções da API REST DBMS_CLOUD permitem que você faça solicitações HTTP usando DBMS_CLOUD.SEND_REQUEST e obtenha e salve resultados. Essas funções fornecem uma API genérica que permite chamar qualquer API REST com os seguintes serviços de nuvem suportados:

Constantes da API REST DBMS_CLOUD

Descreve as constantes DBMS_CLOUD para fazer solicitações HTTP usando DBMS_CLOUD.SEND_REQUEST.

O DBMS_CLOUD suporta os métodos HTTP GET, PUT, POST, HEAD e DELETE. O método da API REST a ser usado para uma solicitação HTTP geralmente é documentado na documentação da API REST da Nuvem.

Nome Tipo Valor
METHOD_DELETE VARCHAR2(6) 'DELETE'
METHOD_GET VARCHAR2(3) 'GET'
METHOD_HEAD VARCHAR2(4) 'HEAD'
METHOD_POST VARCHAR2(4) 'POST'
METHOD_PUT VARCHAR2(3) 'PUT'

Cache de Resultados da API REST DBMS_CLOUD

Você pode salvar os resultados da API REST DBMS_CLOUD ao definir o parâmetro cache como verdadeiro com DBMS_CLOUD.SEND_REQUEST. A view SESSION_CLOUD_API_RESULTS descreve as colunas que você pode usar quando os resultados da API REST são salvos.

Por padrão, as chamadas da API REST DBMS_CLOUD não salvam os resultados da sua sessão. Nesse caso, você usa a função DBMS_CLOUD.SEND_REQUEST para retornar resultados.

Quando você usa DBMS_CLOUD.SEND_REQUEST e define o parâmetro cache como TRUE, os resultados são salvos e você pode exibir resultados anteriores na exibição SESSION_CLOUD_API_RESULTS. Salvar e consultar resultados históricos de solicitações da API REST DBMS_CLOUD pode ajudar quando você precisa trabalhar com os resultados anteriores em seus aplicativos.

Por exemplo, para consultar resultados recentes da API REST DBMS_CLOUD, use a view SESSION_CLOUD_API_RESULTS:

SELECT timestamp FROM SESSION_CLOUD_API_RESULTS;

Quando você salva os resultados da API REST DBMS_CLOUD com DBMS_CLOUD.SEND_REQUEST, os dados salvos só ficam disponíveis na mesma sessão (conexão). Após a sessão ser encerrada, os dados salvos não estarão mais disponíveis.

Use DBMS_CLOUD.GET_API_RESULT_CACHE_SIZE e DBMS_CLOUD.SET_API_RESULT_CACHE_SIZE para exibir e definir o tamanho do cache da API REST DBMS_CLOUD e para desativar o armazenamento em cache.

Parâmetro cache_scope dos Resultados da API REST DBMS_CLOUD

Quando você salva os resultados da API REST DBMS_CLOUD com DBMS_CLOUD.SEND_REQUEST, o acesso aos resultados no SESSION_CLOUD_API_RESULTS é fornecido com base no valor de cache_scope.

Por padrão, cache_scope é 'PRIVATE' e somente o usuário atual da sessão pode acessar os resultados. Se você definir o cache_scope como 'PUBLIC', todos os usuários da sessão poderão acessar os resultados. O valor padrão para cache_scope especifica que cada usuário só pode ver os resultados da API REST DBMS_CLOUD.SEND_REQUEST gerados pelos procedimentos que eles chamam com os direitos do chamador. Quando você chama DBMS_CLOUD.SEND_REQUEST em uma sessão, há três possibilidades que determinam se o usuário atual pode ver resultados no cache, com base no valor cache_scope:

DBMS_CLOUD REST API SESSION_CLOUD_API_RESULTS View

Você pode salvar os resultados da API REST DBMS_CLOUD ao definir o parâmetro cache como verdadeiro com DBMS_CLOUD.SEND_REQUEST. A view SESSION_CLOUD_API_RESULTS descreve as colunas que você pode usar quando os resultados da API REST são salvos.

A view SESSION_CLOUD_API_RESULTS é a view criada se você armazenar em cache os resultados com DBMS_CLOUD.SEND_REQUEST. Você pode consultar resultados históricos que pertencem à sua sessão de usuário. Quando a sessão termina, os dados no SESSION_CLOUD_API_RESULTS são expurgados.

Coluna Descrição
URI O URL da solicitação da API REST DBMS_CLOUD
TIMESTAMP O timestamp da resposta da API REST DBMS_CLOUD
CLOUD_TYPE O tipo de nuvem da API REST DBMS_CLOUD, como Oracle Cloud Infrastructure e AZURE_BLOB
REQUEST_METHOD O método de solicitação da API REST DBMS_CLOUD, como GET, PUT, HEAD
REQUEST_HEADERS Os cabeçalhos da solicitação da API REST DBMS_CLOUD
REQUEST_BODY_TEXT O corpo da solicitação da API REST DBMS_CLOUD em CLOB
RESPONSE_STATUS_CODE O código de status de resposta da API REST DBMS_CLOUD, como 200(OK), 404(Not Found)
RESPONSE_HEADERS Os cabeçalhos de resposta da API REST DBMS_CLOUD
RESPONSE_BODY_TEXT O corpo da resposta da API REST DBMS_CLOUD em CLOB
SCOPE O cache_scope definido por DBMS_CLOUD.SEND_REQUEST. Os valores válidos são PUBLIC ou PRIVATE.

Função GET_RESPONSE_HEADERS

Esta função retorna os cabeçalhos de resposta HTTP como dados JSON em um objeto JSON.

Sintaxe

DBMS_CLOUD.GET_RESPONSE_HEADERS(
       resp          IN DBMS_CLOUD_TYPES.resp)
   RETURN JSON_OBJECT_T;

Parâmetros

Parâmetro Descrição
resp Tipo de Resposta HTTP retornado de DBMS_CLOUD.SEND_REQUEST.

Exceções

Exceção Erro Descrição
invalid_response ORA-20025 Objeto de tipo de resposta inválido informado para DBMS_CLOUD.GET_RESPONSE_HEADERS.

Função GET_RESPONSE_TEXT

Essa função retorna a resposta HTTP no formato TEXT (VARCHAR2 ou CLOB). Em geral, a maioria das APIs REST na nuvem retorna uma resposta JSON em formato de texto. Esta função é útil se você espera que a resposta HTTP esteja no formato de texto.

Sintaxe

DBMS_CLOUD.GET_RESPONSE_TEXT(
       resp          IN DBMS_CLOUD_TYPES.resp)
   RETURN CLOB;

Parâmetros

Parâmetro Descrição
resp Tipo de Resposta HTTP retornado de DBMS_CLOUD.SEND_REQUEST.

Exceções

Exceção Erro Descrição
invalid_response ORA-20025 Objeto de tipo de resposta inválido informado para DBMS_CLOUD.GET_RESPONSE_TEXT.

Função GET_API_RESULT_CACHE_SIZE

Esta função retorna o tamanho do cache de resultados configurado. O valor do tamanho do cache só se aplica à sessão atual.

Sintaxe

DBMS_CLOUD.GET_API_RESULT_CACHE_SIZE()
   RETURN NUMBER;

Função e Procedimento SEND_REQUEST

Esta função e procedimento inicia uma solicitação HTTP, obtém a resposta e encerra a resposta. Esta função fornece um workflow para enviar uma solicitação de API REST na nuvem com argumentos e a função retorna um código de resposta e um payload. Se você usar o procedimento, poderá exibir os resultados e os detalhes da resposta dos resultados salvos com a exibição SESSION_CLOUD_API_RESULTS.

Sintaxe

DBMS_CLOUD.SEND_REQUEST(
       credential_name    IN VARCHAR2,
       uri                IN VARCHAR2,
       method             IN VARCHAR2,
       headers            IN CLOB DEFAULT NULL,
       async_request_url  IN VARCHAR2 DEFAULT NULL,
       wait_for_states    IN DBMS_CLOUD_TYPES.wait_for_states_t DEFAULT NULL,
       timeout            IN NUMBER DEFAULT 0,
       cache              IN PL/SQL BOOLEAN DEFAULT FALSE,
       cache_scope        IN VARCHAR2 DEFAULT 'PRIVATE',
       body               IN BLOB DEFAULT NULL)
   RETURN DBMS_CLOUD_TYPES.resp;

DBMS_CLOUD.SEND_REQUEST(
       credential_name    IN VARCHAR2,
       uri                IN VARCHAR2,
       method             IN VARCHAR2,
       headers            IN CLOB DEFAULT NULL,
       async_request_url  IN VARCHAR2 DEFAULT NULL,
       wait_for_states    IN DBMS_CLOUD_TYPES.wait_for_states_t DEFAULT NULL,
       timeout            IN NUMBER DEFAULT 0,
       cache              IN PL/SQL BOOLEAN DEFAULT FALSE,
       cache_scope        IN VARCHAR2 DEFAULT 'PRIVATE',
       body               IN BLOB DEFAULT NULL);

Parâmetros

Parâmetro Descrição
credential_name O nome da credencial para autenticação com a API nativa da nuvem correspondente.
uri URI HTTP para fazer a solicitação.
method

Método de Solicitação HTTP: GET, PUT, POST, HEAD, DELETE. Use a constante de pacote DBMS_CLOUD para especificar o método.

Consulte Constantes da API REST DBMS_CLOUD para obter mais informações.

headers Cabeçalhos de Solicitação HTTP para a API nativa da nuvem correspondente no formato JSON. Os cabeçalhos de autenticação são definidos automaticamente, somente passam cabeçalhos personalizados.
async_request_url

Um URL de solicitação assíncrona.

Para obter o URL, selecione sua API de solicitação na lista de APIs (consulte https://docs.cloud.oracle.com/en-us/iaas/api/). Em seguida, navegue para localizar a API da sua solicitação no painel esquerdo. Por exemplo, API de Serviços de Banco de Dados -> Autonomous AI Database -> StopAutonomousDatabase. Esta página mostra o home da API (e o ponto final base). Em seguida, anexe o ponto final base com o caminho relativo obtido para o link Solicitação de Serviço da solicitação de serviço.

wait_for_states

O status Aguardar estados é do tipo: DBMS_CLOUD_TYPES.wait_for_states_t. Estes são valores válidos para os estados esperados: 'ACTIVE', 'CANCELED', 'COMPLETED', 'DELETED', 'FAILED', 'SUCCEEDED'.

Vários estados são permitidos para wait_for_states. O valor padrão para wait_for_states é aguardar qualquer um dos estados esperados: 'ACTIVE', 'CANCELED', 'COMPLETED', 'DELETED', 'FAILED', 'SUCCEEDED'.

timeout

Especifica o timeout, em segundos, para solicitações assíncronas com os parâmetros async_request_url e wait_for_states.

O valor padrão é 0. Isso indica para aguardar a conclusão da solicitação sem qualquer timeout.

cache

Se TRUE especificar que a solicitação deve ser armazenada em cache no cache da API de resultado REST.

O valor padrão é FALSE, o que significa que as solicitações da API REST não são armazenadas em cache.

cache_scope Especifica se todos podem ter acesso a este cache de resultados de solicitação. Valores válidos: "PRIVATE" e "PUBLIC". O valor-padrão é "PRIVATE".
body Corpo da Solicitação HTTP para solicitações PUT e POST.

Exceções

Exceção Erro Descrição
invalid_req_method ORA-20023 O método de solicitação informado para DBMS_CLOUD.SEND_REQUEST é inválido.
invalid_req_header ORA-20024 Os cabeçalhos de solicitação informados para DBMS_CLOUD.SEND_REQUEST não estão no formato JSON válido.

Observações sobre Uso

Procedimento SET_API_RESULT_CACHE_SIZE

Este procedimento define o tamanho máximo do cache para a sessão atual. O valor do tamanho do cache só se aplica à sessão atual.

Sintaxe

DBMS_CLOUD.SET_API_RESULT_CACHE_SIZE(
       cache_size          IN NUMBER);

Parâmetros

Parâmetro Descrição
cache_size

Defina o tamanho máximo do cache para o valor especificado cache_size. Se o novo tamanho máximo do cache for menor que o tamanho atual, os registros mais antigos serão eliminados até que o número de linhas seja igual ao tamanho máximo especificado do cache. O valor máximo é 10000.

Se o tamanho do cache for definido como 0, o armazenamento em cache será desativado na sessão.

O tamanho do cache padrão é 10.

Exceções

Exceção Erro Descrição
invalid API result cache size ORA-20032 O valor mínimo é 0 e o máximo é 10000. Esta exceção é mostrada quando o valor de entrada é menor que 0 ou maior que 10000.

Exemplo

EXEC DBMS_CLOUD.SET_API_RESULT_CACHE_SIZE(101);

Conteúdo Relacionado