Usar SODA for REST com Autonomous Database

O Autonomous Database suporta o Simple Oracle Document Access (SODA) para REST.

Visão Geral do Uso do SODA for REST

SODA for REST é um serviço REST pré-implantado que pode ser usado para armazenar documentos JSON em seu banco de dados.

O SODA permite o desenvolvimento de aplicativos flexíveis no estilo NoSQL sem precisar usar SQL. Com o SODA, os documentos JSON são armazenados em coleções nomeadas e gerenciados usando operações CRUD simples (criar, ler, atualizar e excluir). E, embora o SQL não seja obrigatório, o JSON armazenado nas coleções SODA ainda estará totalmente acessível no SQL quando necessário. Por exemplo, um aplicativo operacional pode ser totalmente criado usando SODA (sem SQL), mas os dados podem ser posteriormente analisados usando SQL fora do aplicativo. O SODA do Autonomous Database oferece aos desenvolvedores de aplicativos o melhor dos mundos NoSQL e SQL - desenvolvimento de aplicativos rápido, flexível e escalável sem perder a capacidade de aproveitar o SQL para análise e relatório.

O SODA for REST é implantado no ORDS sob o seguinte padrão de URL, em que o esquema corresponde a um esquema de banco de dados ativado para REST.

/ords/schema/soda/latest/*

Os exemplos a seguir usam a ferramenta de linha de comando cURL (http://curl.haxx.se/) para enviar solicitações REST ao banco de dados. No entanto, outros clientes REST e bibliotecas 3rd party também devem funcionar. Os exemplos usam o esquema de banco de dados ADMIN, que é ativado para REST. Você pode usar o SODA for REST com comandos cURL no Oracle Cloud Shell.

Esse comando cria uma nova coleção chamada "fruit" no esquema ADMIN:

> curl -X PUT -u 'ADMIN:<password>' \
"https://example-db.adb.us-phoenix-1.oraclecloudapps.com/ords/admin/soda/latest/fruit"

Estes comandos inserem três documentos JSON na coleção fruit:

> curl -X POST -u 'ADMIN:<password>' \
 -H "Content-Type: application/json" --data '{"name":"orange", "count":42}' \
 "https://example-db.adb.us-phoenix-1.oraclecloudapps.com/ords/admin/soda/latest/fruit"

{"items":[{"id":"6F7E5C60197E4C8A83AC7D7654F2E375"...
 
> curl -X POST -u 'ADMIN:<password>' \
 -H "Content-Type: application/json" --data '{"name":"pear", "count":5}' \
 "https://example-db.adb.us-phoenix-1.oraclecloudapps.com/ords/admin/soda/latest/fruit"

{"items":[{"id":"83714B1E2BBA41F7BA4FA93B109E1E85"...
 
> curl -X POST -u 'ADMIN:<password>' \
 -H "Content-Type: application/json" \
 --data '{"name":"apple", "count":12, "color":"red"}' \
 "https://example-db.adb.us-phoenix-1.oraclecloudapps.com/ords/admin/soda/latest/fruit"

{"items":[{"id":"BAD7EFA9A2AB49359B8F5251F0B28549"...

Este exemplo recupera da coleção um documento JSON armazenado:

> curl -X POST -u 'ADMIN:<password>' \
 -H "Content-Type: application/json" --data '{"name":"orange"}' \
 "https://example-db.adb.us-phoenix-1.oraclecloudapps.com/ords/admin/soda/latest/fruit?action=query"

{
  "items": [
    {
      "id":"6F7E5C60197E4C8A83AC7D7654F2E375",
      "etag":"57215643953D7C858A7CB28E14BB48549178BE307D1247860AFAB2A958400E16",
      "lastModified":"2019-07-12T19:00:28.199666Z",
      "created":"2019-07-12T19:00:28.199666Z",
      "value":{"name":"orange", "count":42}
    }
  ],
  "hasMore":false,
  "count":1
}

Esta consulta SQL acessa a coleção fruit:

SELECT 
     f.json_document.name,
     f.json_document.count,
     f.json_document.color
FROM fruit f;

A consulta retorna estas três linhas:

name      count     color
--------- --------- -------
orange    42        null
pear      5         null
apple     12        red
Observação

Se você estiver usando o Autonomous Database Always Free com o Oracle Database 23ai, a Oracle recomenda o seguinte:

Para projetos que foram iniciados usando uma release do banco de dados anterior ao Oracle Database 21c, especifique explicitamente os metadados da coleção padrão conforme especificado no exemplo da seção Drivers SODA. Para projetos iniciados usando a release Oracle Database 21c ou mais recente, basta usar os metadados padrão. Consulte SODA Drivers para obter mais informações.

Esses exemplos mostram um subconjunto dos recursos SODA e SQL/JSON. Para obter mais informações, consulte:

Carregar Amostra de Dados da Ordem de Compra Usando o SODA for REST

A Oracle fornece um conjunto substancial de documentos JSON de ordem de compra, em formato de arquivo de texto simples POList.json, como um array JSON de objetos, em que cada objeto representa um documento.

Os exemplos a seguir usam a ferramenta de linha de comando cURL (http://curl.haxx.se/) para enviar solicitações REST ao banco de dados. No entanto, outros clientes REST e bibliotecas 3rd party também devem funcionar. Os exemplos usam o esquema de banco de dados ADMIN, que é ativado para REST. Você pode usar o SODA for REST com comandos cURL no Oracle Cloud Shell.

Você pode carregar esse conjunto de dados de ordem de compra de amostra em uma coleção purchaseorder no seu Autonomous Database com o SODA for REST, usando estes comandos curl:

curl -X GET "https://raw.githubusercontent.com/oracle/db-sample-schemas/master/order_entry/POList.json" -o POList.json

curl -X PUT -u 'ADMIN:password' \
"https://example-db.adb.us-phoenix-1.oraclecloudapps.com/ords/admin/soda/latest/purchaseorder"

curl -X POST -H -u 'ADMIN:password' 'Content-type: application/json' -d @POList.json \
"https://example-db.adb.us-phoenix-1.oraclecloudapps.com/ords/admin/soda/latest/purchaseorder?action=insert"

Você pode usar esses dados de ordem de compra para testar exemplos no Oracle Database JSON Developer's Guide.

Por exemplo, a consulta a seguir seleciona o id de um documento JSON e os valores da coleção JSON de ordem de compra armazenada na coluna json_document da tabela purchaseorder. Os valores selecionados são dos campos PONumber, Reference e Requestor da coluna JSON json_document, que são projetados com base no documento como colunas virtuais (consulte Cláusula SQL NESTED em vez de JSON_TABLE para obter mais informações).

SELECT id, t.*
  FROM purchaseorder
    NESTED json_document COLUMNS(PONumber, Reference, Requestor) t;

Para obter mais informações, consulte:

Use SODA for REST with OAuth Client Credentials

Você pode acessar o SODA for REST no Autonomous Database usando a autenticação OAuth. Dependendo do seu aplicativo, o acesso ao SODA for REST com autenticação OAuth pode melhorar o desempenho e a segurança.

Execute as seguintes etapas para usar a autenticação OAuth para fornecer acesso limitado ao SODA for REST no Autonomous Database:

  1. Como usuário ADMIN, acesse o Database Actions e crie um usuário com os privilégios exigidos.
    1. Acesse o Database Actions como ADMIN.
      Consulte Access Database Actions como ADMIN para obter mais informações.
    2. No Database Actions, clique em ícone de navegação para mostrar as ações disponíveis.
    3. No Database Actions, em Administração, selecione Usuários de Banco de Dados.
    4. Clique em Criar Usuário.
    5. Na área Criar Usuário, na guia Usuário, digite Nome do Usuário e uma Senha e confirme a senha.
    6. Selecione Web Access.
    7. Na área Criar Usuário, selecione a guia Atribuições Concedidas e conceda DWROLE ao usuário.
    8. Clique em Criar Usuário.
  2. Use uma planilha SQL no Database Actions para conceder ao usuário os privilégios exigidos para carregar dados.
    1. Acesse o Database Actions como ADMIN.
      Consulte Access Database Actions como ADMIN para obter mais informações.
    2. No Database Actions, clique em ícone de navegação para mostrar as ações disponíveis.
    3. No Database Actions, em Desenvolvimento, clique em SQL para abrir uma planilha SQL.
    4. Conceda ao usuário os privilégios exigidos para carregar dados na Etapa 1.
      GRANT UNLIMITED TABLESPACE TO user_name;
  3. Saia como usuário ADMIN.
  4. Acesse o Database Actions como o usuário que está configurando o uso da autenticação OAuth.
  5. No Database Actions, use uma planilha SQL para registrar o cliente OAuth.
    1. Registre o cliente OAuth.
      Por exemplo, digite os comandos a seguir na planilha SQL, na qual você fornece os valores apropriados para seu usuário e seu aplicativo cliente.
      BEGIN
        OAUTH.create_client(
          p_name            => 'my_client',
          p_grant_type      => 'client_credentials',
          p_owner           => 'Example Company',
          p_description     => 'A client for my SODA REST resources',
          p_support_email   => 'user_name@example.com',
          p_privilege_names => 'my_priv'
        );
       
        OAUTH.grant_client_role(
          p_client_name => 'my_client',
          p_role_name   => 'SQL Developer'
        );
       
        OAUTH.grant_client_role(
          p_client_name => 'my_client',
          p_role_name   => 'SODA Developer'
        );
        COMMIT;
      END;
      /
    2. Na planilha SQL, clique em Executar Script para executar o comando.

    Consulte Referência do Pacote PL/SQL OAUTH para obter mais informações.

    Isso registrará um cliente chamado my_client para acessar o privilégio my_priv usando as credenciais do cliente OAuth.

  6. Obtenha o client_id e o client_secret exigidos para gerar o token de acesso.
    Por exemplo, na planilha SQL, execute o seguinte comando:
    SELECT id, name, client_id, client_secret FROM user_ords_clients;
  7. Obtenha o token de acesso. Para obter um token de acesso, envie uma solicitação REST GET para database_ORDS_urluser_name/oauth/token.

    O database_ORDS_url está disponível no Database Actions, em Serviços Relacionados, no cartão RESTful Services and Soda. Consulte Acessar Serviços RESTful e SODA for REST para obter mais informações.

    No comando a seguir, use client_id e client_secret obtidos na Etapa 6.

    O exemplo a seguir usa a ferramenta de linha de comando cURL (http://curl.haxx.se/) para submeter solicitações REST ao Autonomous Database. No entanto, outros clientes REST e bibliotecas 3rd party também devem funcionar.

    Você pode usar a ferramenta de linha de comando cURL para submeter a solicitação REST GET. Por exemplo:

    > curl -i -k --user SBA-iO9Xe12cdZHYfryBGQ..:vvUQ1AagTqAqdA2oN7afSg.. --data "grant_type=client_credentials"https://mqssyowmqvgac1y-doc.adb.region.oraclecloudapps.com/ords/user_name/oauth/token
    HTTP/1.1 200 OK
    Date: Mon, 22 Jun 2020 15:17:11 GMT
    Content-Type: application/jsonTransfer-Encoding: chunked
    Connection: keep-alive
    X-Frame-Options: SAMEORIGIN  
    
    {"access_token":"JbOKtAuDgEh2DXx0QhvPGg","token_type":"bearer","expires_in":3600}

    Para especificar client_id e client_secret com o argumento curl --user, digite dois pontos para separar client_id e client_secret. Se você especificar apenas o nome de usuário, client_id, o curl solicitará uma senha e você poderá digitar client_secret no prompt.

  8. Use o token de acesso para acessar o recurso protegido.

    O token obtido na etapa anterior é informado no cabeçalho de Autorização. Por exemplo:

    > curl -i -H "Authorization: Bearer JbOKtAuDgEh2DXx0QhvPGg" -X GET https://database_id.adb.region.oraclecloudapps.com/ords/user_name/soda/latest
    HTTP/1.1 200 OK
    Date: Mon, 22 Jun 2020 15:20:58 GMT
    Content-Type: application/json
    Content-Length: 28
    Connection: keep-alive
    X-Frame-Options: SAMEORIGIN
    Cache-Control: private,must-revalidate,max-age=0
    
    
    {"items":[],"hasMore":false}

Consulte Configurando o Acesso Seguro para os Serviços RESTful para obter informações completas sobre o acesso seguro aos Serviços RESTful.