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.

Oracle Public Cloud ou Multicloud
Exadata Cloud@Customer

Uma conectividade de saída deve ter sido configurada usando um gateway NAT, pelo administrador da frota, conforme descrito abaixo:

Crie um gateway NAT na VCN (Virtual Cloud Network) em que seus recursos do Autonomous AI Database residem seguindo as instruções em Criar um Gateway NAT na Documentação do Oracle Cloud Infrastructure.
Após criar o gateway NAT, adicione uma regra da rota e uma regra da segurança da saída a cada sub-rede (na VCN) na qual os recursos do Autonomous AI Database residem para que esses recursos possam usar o gateway para obter a chave pública da sua instância doAzure AD
1. Vá para a página Detalhes de Sub-rede da sub-rede.
2. Na guia Informações da Sub-rede, clique no nome da Tabela da Rota da sub-redes para exibir sua página Detalhes da Tabela de Roteamento.
3. Na tabela de Regras de Rota existentes, verifique se já existe uma regra com as seguintes características:
  - Destino: 0.0.0.0/0
  - Target Type: Gateway NAT
  - Destino: O nome do gateway NAT que você acaba de criar na VCN
  Se essa regra não existir, clique em Adicionar Regras de Roteamento e adicione uma regra de roteamento com essas características.
4. Retorne à página Detalhes da Subrede da sub-rede.
5. Na tabela Listas de Segurança da sub‑rede, clique no nome da lista da sub‑rede para exibir sua página Detalhes da Lista de Segurança.
6. No menu lateral, em Recursos, clique em Regras de Saída.
7. Na tabela de Regras de Saída existentes, verifique se já existe uma regra com as seguintes características:
  - Tipo de Destino:CIDR
  - Destino:0.0.0.0/0
  - Protocolo IP:TCP
  - Faixa de Portas de Origem:443
  - Intervalo de Portas de Destino:Tudo
  Se essa regra não existir, clique em Adicionar Regras de Saída e adicione uma regra de saída com essas características.

As definições de Proxy HTTP em seu ambiente devem permitir que o banco de dados acesse o provedor de serviços em nuvem.

Essas definições são definidas pelo administrador da frota ao criar a infraestrutura do Exadata Cloud@Customer conforme descrito em Usando a Console para Provisionar o Exadata Database Service on Cloud@Customer.

Observação: A configuração de rede, incluindo o Proxy HTTP, só poderá ser editada até que o Exadata Infrastructure esteja no estado Exige Ativação. Uma vez ativado, você não pode editar essas configurações.

A configuração de um Proxy HTTP para uma Infraestrutura do Exadata já provisionada precisa de uma Solicitação de Serviço (SR) no My Oracle Support. Consulte Criar uma Solicitação de Serviço no My Oracle Support para obter detalhes.

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:

Oracle Cloud Infrastructure

Consulte Referência e Pontos Finais de API para obter informações sobre APIs REST do Oracle Cloud Infrastructure.
Nuvem do Azure

Consulte Referência da API REST do Azure para obter informações sobre APIs REST do Azure.

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:

Você executa diretamente o DBMS_CLOUD.SEND_REQUEST como uma instrução de nível superior e a chamada para DBMS_CLOUD.SEND_REQUEST e os resultados da API REST são salvos com o mesmo nome de usuário. Nesse caso, você tem acesso a todos os resultados com o valor padrão, 'PRIVATE', definido para cache_scope.
Você grava o procedimento de direitos de um invocador de encapsulador e, como usuário atual, sua chamada com DBMS_CLOUD.SEND_REQUEST chama o procedimento e os resultados da API REST são salvos com o mesmo nome de usuário. Nesse caso, e você tem acesso a todos os resultados com o valor padrão, 'PRIVATE', definido para cache_scope.
Você escreve o procedimento de direitos de um definidor de encapsulador e o procedimento pertence a outro usuário. Quando você chama DBMS_CLOUD.SEND_REQUEST dentro do procedimento, os resultados são salvos com o nome de usuário do proprietário do procedimento.

Nesse caso, um usuário de direitos de um definidor diferente está chamando DBMS_CLOUD.SEND_REQUEST, e os resultados da API REST são salvos com o proprietário desse procedimento de definidores. Para esse caso, por padrão, quando cache_scope é PRIVATE', a sessão do chamador não pode ver os resultados.

Se o proprietário do procedimento do definidor quiser disponibilizar os resultados para qualquer usuário de sessão de chamada, ele deverá definir cache_scope como 'PUBLIC' no DBMS_CLOUD.SEND_REQUEST.

DBMS_CLOUD REST API SESSION_CLOUD_API_RESULTS View

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

Se você estiver usando o Oracle Cloud Infrastructure, use um valor de credencial baseado em Chave de Assinatura para o credential_name. Consulte Procedimento CREATE_CREDENTIAL para obter mais informações.
Os parâmetros opcionais async_request_url, wait_for_states e timeout permitem que você trate solicitações de longa execução. Utilizando esta forma assíncrona de send_request, a função aguarda o status de conclusão especificado em wait_for_states antes de retornar. Com esses parâmetros na solicitação de envio, você especifica os estados de retorno esperados no parâmetro wait_for_states e usa o parâmetro async_request_url para especificar uma solicitação de serviço associada, a solicitação não retorna imediatamente. Em vez disso, a solicitação sonda o async_request_url até que o estado de retorno seja um dos estados esperados ou o timeout seja excedido (timeout é opcional). Se nenhuma timeout for especificada, a solicitação aguardará até que ocorra um estado encontrado em wait_for_states.

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

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

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);

APIs REST DBMS_CLOUD

Pré-requisitos

Resumo das APIs REST DBMS_CLOUD

Visão Geral da API REST DBMS_CLOUD

Constantes da API REST DBMS_CLOUD

Cache de Resultados da API REST DBMS_CLOUD

Parâmetro cache_scope dos Resultados da API REST DBMS_CLOUD

DBMS_CLOUD REST API SESSION_CLOUD_API_RESULTS View

Função GET_RESPONSE_HEADERS

Sintaxe

Parâmetros

Exceções

Função GET_RESPONSE_TEXT

Sintaxe

Parâmetros

Exceções

Função GET_API_RESULT_CACHE_SIZE

Sintaxe

Função e Procedimento SEND_REQUEST

Sintaxe

Parâmetros

Exceções

Observações sobre Uso

Procedimento SET_API_RESULT_CACHE_SIZE

Sintaxe

Parâmetros

Exceções

Exemplo

Conteúdo Relacionado