APIs REST DBMS

Pré-requisitos

Como desenvolvedor, você pode usar procedimentos DBMS_CLOUD com Autonomous Databases implantados no 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 as APIs REST DBMS_CLOUD com 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 Rede Virtual na Nuvem (VCN) em que seus recursos do Autonomous 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 de roteamento e uma regra de segurança de saída a cada sub-rede (na VCN) na qual os recursos do Autonomous Database residem para que esses recursos possam usar o gateway para obter uma chave pública da sua instância do Azure AD:
1. Vá para a página Detalhes da Sub-rede da sub-rede.
2. Na guia Informações da Sub-rede, clique no nome da Tabela de Rota da sub-rede para exibir sua respectiva página Detalhes da Tabela de Rota.
3. Na tabela de Regras de Roteamento existentes, verifique se já existe uma regra com as seguintes características:
  - Destino: 0.0.0.0/0
  - Tipo de Destino: Gateway NAT
  - Alvo: O nome do gateway NAT recém-criado na VCN
  Se essa regra não existir, clique em Adicionar Regras de Rota e adicione uma regra de roteamento com essas características.
4. Retorne à página Detalhes da Sub-rede da sub-rede.
5. Na tabela Listas de Segurança da sub-rede, clique no nome da lista de segurança da sub-rede para exibir a 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
  - Faixa de Portas de Destino: Todas
  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. Depois de ativado, você não poderá 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.

APIs REST DBMS_CLOUD

Esta seção abrange as APIs REST DBMS_CLOUD que acompanham o Autonomous Database.

API REST	Descrição
Função GET_RESPONSE_HEADERS	Essa função retorna os cabeçalhos de resposta HTTP como dados JSON em um objeto JSON no Autonomous Database.
Função GET_RESPONSE_TEXT	Essa função retorna a resposta HTTP no formato TEXT (`VARCHAR2` ou `CLOB`) no Autonomous Database. Geralmente, a maioria das APIs REST na Nuvem retorna a resposta JSON em formato de texto. Esta função é útil se você espera que a resposta HTTP esteja no formato de texto.
Função GET_API_RESULT_CACHE_SIZE	Essa função retorna o tamanho do cache de resultados configurado.
Procedimento SEND_REQUEST Função e	Essa função inicia uma solicitação HTTP, obtém a resposta e encerra a resposta no Autonomous Database. Essa função oferece um workflow para enviar uma solicitação de API REST na Nuvem com argumentos e um código de resposta e payload de retorno.
Procedimento SET_API_RESULT_CACHE_SIZE	Esse 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 no seu aplicativo e precisa chamar APIs REST na Nuvem, pode usar DBMS_CLOUD.SEND_REQUEST para enviar as solicitações da API REST.

As funções da API REST DBMS_CLOUD permitem que você faça solicitações HTTP usando DBMS_CLOUD.SEND_REQUEST, obtenha os resultados e os salve. 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 de API e Pontos Finais para obter informações sobre APIs REST do Oracle Cloud Infrastructure.
^{Rolo 1} do Azure Cloud
Consulte Referência de API REST do Azure para obter informações sobre APIs REST do Azure.

Constantes de 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 é descrito na documentação da API REST na 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 de API REST DBMS_CLOUD não salvam os resultados da 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 os resultados passados na view SESSION_CLOUD_API_RESULTS. Salvar e consultar resultados históricos de solicitações da API REST DBMS_CLOUD podem ajudar você quando precisar trabalhar com 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). Depois que a sessão for 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 no cache.

Parâmetro cache_scope de Resultados da API REST DBMS_CLOUD

Quando você salva resultados da API REST DBMS_CLOUD com DBMS_CLOUD.SEND_REQUEST, o acesso aos resultados em 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 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 DBMS_CLOUD.SEND_REQUEST como 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 um procedimento de direitos do invocador do 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, você tem acesso a todos os resultados com o valor padrão, 'PRIVATE', definido para cache_scope.
Você grava o procedimento de direitos do definidor de um 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.

Para esse caso, um usuário dos direitos de outro definidor está chamando DBMS_CLOUD.SEND_REQUEST e os resultados da API REST são salvos com o proprietário do procedimento desse definidor. 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 da sessão de chamada, ele deverá definir cache_scope como 'PUBLIC' no DBMS_CLOUD.SEND_REQUEST.

View SESSION_CLOUD_API_RESULTS 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.

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

Coluna	Descrição
`URI`	O URL de solicitação da API REST `DBMS_CLOUD`
`TIMESTAMP`	O timestamp de 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 de 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

Essa 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`	O tipo de Resposta HTTP retornada 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). Geralmente, a maioria das APIs REST na Nuvem retorna a 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`	O tipo de Resposta HTTP retornada 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

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

Procedimento SEND_REQUEST Função e

Essa função e procedimento inicia uma solicitação HTTP, obtém a resposta e finaliza 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 resultados e detalhes da resposta dos resultados salvos com a view 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 correspondente API nativa da nuvem.
`uri`	URI HTTP para fazer a solicitação.
`method`	Método de Solicitação HTTP: `GET`, `PUT`, `POST`, `HEAD`, `DELETE`. Use a constante do pacote `DBMS_CLOUD` para especificar o método. Para obter mais informações, consulte Constantes da API REST DBMS_CLOUD.
`headers`	Cabeçalhos da Solicitação HTTP para a correspondente API nativa da nuvem no formato JSON. Os cabeçalhos de autenticação são definidos automaticamente; só informam 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 encontrar a API da sua solicitação no painel esquerdo. Por exemplo, API de Serviços de Banco de Dados → Autonomous Database → StopAutonomousDatabase. Esta página mostra o home da API (e mostra o ponto final base). Em seguida, anexe o ponto final base com o caminho relativo obtido para o link WorkRequest da solicitação de serviço.
`wait_for_states`	Aguardar estados é um status 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 de `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`, especifica que a solicitação deve ser armazenada no cache da API REST de resultados. O valor padrão é `FALSE`, o que significa que as solicitações da API REST não são armazenadas no cache.
`cache_scope`	Especifica se todos podem ter acesso a esse 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 especificados para `DBMS_CLOUD.SEND_REQUEST` não estão em formato JSON válido.

Observações sobre Uso

Se você estiver usando o Oracle Cloud Infrastructure, utilize 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 tratar solicitações de longa execução. Usando essa 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ê informa os estados esperados de retorno 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 é retornada imediatamente. Em vez disso, ela sonda async_request_url até que o estado de retorno seja um dos estados esperados ou até que timeout seja excedido (timeout é opcional). Se nenhum timeout for especificado, a solicitação aguardará até que ocorra um estado encontrado em wait_for_states.

Procedimento SET_API_RESULT_CACHE_SIZE

Esse 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 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 no cache será desativado na sessão. O tamanho padrão do cache é `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 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 no cache será desativado na sessão.

O tamanho padrão do cache é 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. Essa 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);