Uso de la API de Oracle AI Database para MongoDB

Oracle AI Database API for MongoDB permite conectarse a Oracle Autonomous AI Database mediante controladores y herramientas de lenguaje MongoDB.

Oracle AI Database API for MongoDB aprovecha las capacidades de base de datos convergente de una base de datos de IA autónoma para gestionar varios tipos de datos, incluidos los datos JSON, en una sola base de datos. Por ejemplo, estas capacidades de base de datos convergente le permiten utilizar SQL para consultar o actualizar datos JSON.

Nota

Nota: MongoDB requiere que configure el acceso de red para utilizar ACL o que defina un punto final privado para la instancia de base de datos de IA autónoma.

Consulte API de Oracle AI Database para MongoDB para obtener más información.

Consulte Acerca de Autonomous JSON Database para obtener más información.

Consulte Acerca de los tipos de carga de trabajo de base de datos de IA autónoma para obtener más información.

Configurar el acceso para MongoDB y activar MongoDB

La API de Oracle AI Database para MongoDB le permite utilizar Oracle Autonomous AI Database como almacén de datos.

Para utilizar la API MongoDB, puede crear y configurar una nueva base de datos de IA autónoma o modificar la configuración de una base de datos de IA autónoma existente.

Nota

Nota: MongoDB requiere que configure el acceso de red para utilizar ACL o que defina un punto final privado para la instancia de base de datos de IA autónoma. Además de configurar el acceso a la red, debe activar la API de MongoDB en la instancia de Autonomous AI Database.

Configurar acceso para MongoDB

Para utilizar la API MongoDB, puede crear y configurar una nueva base de datos de IA autónoma o modificar la configuración de una base de datos de IA autónoma existente mediante la configuración de ACL o la definición de un punto final privado.

Configuración de una nueva base de datos de IA autónoma para MongoDB

Siga los pasos de Aprovisionamiento o clonación de una base de datos de IA autónoma hasta el punto en el que seleccione el tipo de acceso de red.

Descripción de la ilustración adb_network_access_acl_provision.png

En este punto, para utilizar la API de Oracle AI Database para MongoDB, configure el acceso seguro seleccionando y configurando uno de estos tipos de acceso de red:

• Acceso seguro solo desde direcciones IP y VCN permitidas

• Solo acceso de punto final privado

  Consulte Configuración del acceso de red con puntos finales privados para obtener información sobre la configuración de una instancia de base de datos de IA autónoma con un punto final privado.

Configuración de una base de datos de IA autónoma existente para MongoDB

Abra la consola de Oracle Cloud Infrastructure para su instancia de base de datos de IA autónoma.

Descripción de la ilustración adb_ajd_console_details.png

Nota

Nota: para utilizar la API de Oracle AI Database para MongoDB, se debe configurar la red y el tipo de acceso debe ser: Acceso seguro solo desde IP permitidas y VCN o Acceso solo a punto final privado.

Definición de la lista de control de acceso (ACL)

Consulte Configuración de listas de control de acceso para una instancia de base de datos de IA autónoma existente para más información.

Para configurar la ACL para una dirección IP, deberá obtener la dirección IP pública. Existen varias formas de mostrar la dirección IP pública:

• En el área de acceso de red de selección, haga clic en Agregar mi dirección IP. Esto copia la dirección IP en el campo Valores.

• Después de desactivar cualquier VPN, utilice el sitio web WhatIsMyIP.

• Después de desactivar cualquier VPN, utilice el comando curl: curl -s https://ifconfig.me.

Nota

Nota: las direcciones IP públicas pueden cambiar. Cualquier cambio en la dirección IP pública requerirá un cambio en la ACL. Si no puede acceder a la base de datos, la ACL debe ser algo que compruebe.

Tipos y casos de uso de ACL

Activar API MongoDB en base de datos de IA autónoma

Después de configurar el acceso de red para la instancia de base de datos de IA autónoma, active la API MongDB.

Para activar la API MongoDB para una instancia existente:

1. En la página de detalles de Autonomous AI Database, seleccione el separador Configuración de herramienta.

2. Haga clic en Editar configuración de herramienta.

3. En la fila de API de MongoDB, seleccione en la columna Activar herramienta para mostrar Activado.

4. Haga clic en Apply (Aplicar).

El estado del ciclo de vida cambia a actualización hasta que MongoDB esté activado.

También puede activar la API de MongoDB al aprovisionar o clonar una instancia seleccionando Mostrar opciones avanzadas y el separador Herramientas.

Consulte Gestión de herramientas incorporadas de base de datos de IA autónoma para obtener más información.

Gestión de usuarios para MongoDB

La API de Oracle AI Database para MongoDB le permite utilizar Oracle Autonomous AI Database como almacén de datos. Si desea utilizar una base de datos de IA autónoma existente para este fin, este es el flujo de trabajo.

La API de Oracle AI Database para MongoDB permite la asignación de objetos de base de datos de IA autónoma a objetos MongoDB de la siguiente manera:

Por ejemplo, puede crear una recopilación mediante la API de Oracle AI Database para MongoDB de la siguiente manera:

use scott;
db.createCollection('fruit');

En el esquema SCOTT se crea una tabla denominada FRUIT.

Cuando se conecta a la API de Oracle AI Database para MongoDB, se autentica mediante un nombre de usuario y una contraseña de base de datos de IA autónoma. Esta conexión autenticada accede a las recopilaciones dentro del esquema correspondiente. Este usuario debe cumplir los siguientes requisitos:

• El esquema del usuario debe estar activado para ORDS, que a veces se denomina activado para acceso web. Consulte Configuración básica para activar la API de base de datos de ORDS para obtener más información.

• El usuario debe tener los siguientes roles y privilegios: SODA_APP, CREATE TABLE y CREATE SESSION. Consulte Gestión de roles y privilegios de usuario en la base de datos de IA autónoma para obtener más información.

• El usuario tiene una cuota disponible en DATA de tablespace. Consulte Creación y gestión de usuarios en una base de datos de IA autónoma para obtener más información.

• Se debe otorgar al usuario el privilegio EXECUTE en el paquete CS_SESSION para beneficiarse de la creación automática de índices paralelos. De lo contrario, los índices se crean en serie.

  Consulte CS_SESSION Package para obtener más información.

Nota

Nota: El rol DWROLE en la base de datos de IA autónoma contiene estos roles, entre otros.

No se permite el acceso a los esquemas que no se hayan otorgado al usuario. Por ejemplo, el usuario SCOTT solo puede acceder a las recopilaciones del esquema SCOTT. Existe una excepción. Si el usuario autenticado tiene los privilegios de base de datos de IA autónoma CREATE USER, ALTER USER y DROP USER, ese usuario puede acceder a cualquier esquema activado para ORDS.

Además, un usuario con estos privilegios puede crear esquemas de forma implícita. Es decir, cuando el usuario crea una recopilación en una base de datos que no existe, el esquema se crea automáticamente. Consulte API de Oracle AI Database para MongoDB para obtener más información.

Creación de un usuario de base de datos de IA autónoma de prueba para MongoDB

Los pasos siguientes utilizan Database Actions para crear un usuario de prueba con los roles adecuados. También puede utilizar SQL de Database Actions u otras utilidades de línea de comandos SQL para ejecutar las sentencias SQL directamente. Consulte Creación de usuarios en Autonomous AI Database - Conexión con una herramienta de cliente para obtener más información.

1. Abra la consola de Oracle Cloud Infrastructure para su base de datos de IA autónoma.

2. Seleccione Database Actions.

3. En la pantalla de inicio de Database Actions, seleccione Administration > Database Users.

4. Seleccione + Crear usuario en la página Usuarios de base de datos.

5. Introduzca un User Name (Nombre de usuario) y una contraseña para el usuario de prueba. Seleccione Acceso Web y defina la Cuota en DATA de tablespace.

   

   Descripción de la ilustración database_actions_create_user_for_mongodb_use.png

6. Seleccione el separador Roles otorgados.

7. Además de los roles por defecto, seleccione y agregue el rol SODA_APP para el usuario.

   

   Descripción de la ilustración database_actions_grant_roles_for_mongodb_use.png

8. Seleccione el botón Create User (Crear usuario).

Puede utilizar este usuario, o un usuario autenticado de forma similar, para fines de prueba. Consulte Prueba de conexión mediante la línea de comandos para obtener más información.

Conecte las aplicaciones MongoDB a una base de datos de IA autónoma

La conexión de la aplicación MongoDB a la base de datos de IA autónoma incluye varios pasos, según sus requisitos.

Recuperar la cadena de conexión MongoDB de la base de datos de IA autónoma

Puede recuperar la cadena de conexión de la API MongoDB desde la consola de Oracle Cloud Infrastructure.

Después de obtener la cadena de conexión de la API de MongoDB, puede utilizar el shell de MongoDB, que es una utilidad de línea de comandos, para conectar y consultar los datos.

En primer lugar, debe configurar el acceso de red y activar la API de MongoDB. Consulte Configuración del acceso para MongoDB para obtener más información.

Para recuperar la cadena de conexión de la API MongoDB:

1. En la página de detalles de Autonomous AI Database, seleccione el separador Configuración de herramienta.

2. En la fila API de MongoDB, en URL de acceso, haga clic en Copiar.

   

   Descripción de la ilustración adb_tools_mongo_connect_string.png

Recuperación de la cadena de conexión de base de datos de IA autónoma desde Database Actions

Utilice el shell MongoDB, que es una utilidad de línea de comandos que se utiliza para conectar y consultar los datos.

1. Puede recuperar la cadena de conexión para su instancia de base de datos de IA autónoma con Database Actions.

   Consulte Acceso a Database Actions como ADMIN para obtener más información.

2. En la pantalla de inicio Database Actions, en Related Services, haga clic en Oracle AI Database API for MongoDB.

3. En la página API de Oracle AI Database para MongoDB, haga clic en Copiar.

Prueba de conexión mediante la línea de comandos

1. Conéctese como usuario de prueba. Consulte Creación de un usuario de base de datos de IA autónoma de prueba para MongoDB para obtener más información.

   $ mongosh --tls --tlsAllowInvalidCertificates 'mongodb://TESTUSER:<PASSWORD>@<database URL>.
   <OCI region>.oraclecloudapps.com:27017/admin?authMechanism=PLAIN&authSource=$external&ssl=true&loadBalanced=false'
   Current Mongosh Log ID: 614c9e2a01e3575c8c0b2ec7
   Connecting to:         mongodb://TESTUSER:<PASSWORD>@<database URL>.<OCIregion>.oraclecloudapps.com:27017/admin?
   authMechanism=PLAIN&authSource=$external&tls=true&loadBalanced=false
   Using MongoDB:                   3.6.2
   Using Mongosh:                   1.0.7
   For mongosh info see: https://docs.mongodb.com/mongodb-shell/admin
   > show dbs
   
   **testuser    0 B**
   >

   Utilice la codificación porcentual de URI para sustituir los caracteres reservados en el URI de la cadena de conexión, en particular, los caracteres del nombre de usuario y la contraseña. Estos son los caracteres reservados y sus codificaciones porcentuales:

   Caracteres	Porcentaje de codificación
   !	%21
   #	%23
   $	%24
   %	%25
   &	%26
   '	%27
   (	%28
   )	%29
   *	%2A
   +	%2B
   ,	%2C
   /	%2F
   :	%3A
   ;	%3B
   =	%3D
   ?	%3F
   @	%40
   [	%5B
   ]	%5D

   Por ejemplo, si su nombre de usuario es RUTH y su contraseña es @least1/2#?, la cadena de conexión MongoDB al servidor <server> podría tener este aspecto:

   'mongodb://RUTH:**%40**least1**%2F**2**%23****%3F**@*<server>*:27017/ruth/ ...'

   Según las herramientas o los controladores que utilice, es posible que pueda proporcionar un nombre de usuario y una contraseña como parámetros independientes, en lugar de como parte de una cadena de conexión URI. En ese caso, es probable que no necesite codificar los caracteres reservados que contienen.

   Consulte Porcent Encoding - Reserved Characters y Uniform Resource Identifier (URI): Generic Syntax para obtener más información.

2. Cree una recopilación e inserte documentos en la recopilación.

   testuser> show collections
   
   testuser> db.createCollection( 'fruit' )
   { ok: 1 }
   testuser> show collections
   fruit
   testuser> db.fruit.insertOne( {name:"orange", count:42} )
   {
     acknowledged: true,
     insertedId: ObjectId("614ca31fdab254f63e4c6b47")
   }
   testuser> db.fruit.insertOne( {name:"apple", count:12, color: "red"} )
   {
     acknowledged: true,
     insertedId: ObjectId("614ca340dab254f63e4c6b48")
   }
   testuser> db.fruit.insertOne( {name:"pear", count:5} )
   {
     acknowledged: true,
     insertedId: ObjectId("614ca351dab254f63e4c6b49")
   }
   testuser>

3. Consultar la recopilación mediante un cliente SQL como Database Actions.

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

   

   Descripción de la ilustración database_actions_sql_for_mongodb_use.png

Prueba de conexión mediante una aplicación Node.js

1. Descargue Node.js. Si ya ha descargado o instalado Node.js para su entorno, puede omitir este paso.

   $ wget https://nodejs.org/dist/latest-v14.x/node-v14.17.5-linux-x64.tar.xz

2. Extraiga el contenido del archivo Node,js. Si ya ha descargado o instalado Node.js para su entorno, puede omitir este paso.

   $ tar -xf node-v14.17.5-linux-x64.tar.xz

3. Configure la variable PATH de entorno. Si ya ha descargado o instalado Node.js para su entorno, puede omitir este paso.

   $ export PATH="`pwd`"/node-v14.17.5-linux-x64/bin:$PATH

4. Pruebe su conexión con un ejemplo de Javascript.

   1. Crear Nuevo Directorio.

      $ mkdir autonomous_mongodb
      $ cd autonomous_mongodb
      $ npm init -y

   2. Instale la dependencia de mongodb.

      $ npm install mongodb

   3. Cree una aplicación JavaScript denominada connect.js.

      const { MongoClient } = require("mongodb");
      const uri =
        "mongodb://TESTUSER:<PASSWORD>@<Database URI>.<OCI region>.oraclecloudapps.com:27017/admin?authMechanism=PLAIN&authSource=$external&ssl=true&loadBalanced=false";
      
      const client = new MongoClient(uri);
      
      async function run() {
        try {
              await client.connect();
      
              const database = client.db('admin');
              const movies = database.collection('movies');
      
              // Insert a movie
              const doc = { title: 'Back to the Future',
                            year: 1985, genres: ['Adventure', 'Comedy', 'Sci-Fi'] }
              const result = await movies.insertOne(doc);
      
              // Query for a movie that has the title 'Back to the Future' :)
              const query = { title: 'Back to the Future' };
              const movie = await movies.findOne(query);
      
              console.log(movie);
        } finally {
          // Ensures that the client will close when you finish/error
          await client.close();
        }
      }
      run().catch(console.dir);

      Utilice la codificación porcentual de URI para sustituir los caracteres reservados en el URI de la cadena de conexión, en particular, los caracteres del nombre de usuario y la contraseña. Estos son los caracteres reservados y sus codificaciones porcentuales:

      Caracteres	Porcentaje de codificación
      !	%21
      #	%23
      $	%24
      %	%25
      &	%26
      '	%27
      (	%28
      )	%29
      *	%2A
      +	%2B
      ,	%2C
      /	%2F
      :	%3A
      ;	%3B
      =	%3D
      ?	%3F
      @	%40
      [	%5B
      ]	%5D

      Por ejemplo, si su nombre de usuario es RUTH y su contraseña es @least1/2#?, la cadena de conexión MongoDB al servidor <server> podría tener este aspecto:

      'mongodb://RUTH:**%40**least1**%2F**2**%23****%3F**@*<server>*:27017/ruth/ ...'

      Según las herramientas o los controladores que utilice, es posible que pueda proporcionar un nombre de usuario y una contraseña como parámetros independientes, en lugar de como parte de una cadena de conexión URI. En ese caso, es probable que no necesite codificar los caracteres reservados que contienen.

      Consulte Porcent Encoding - Reserved Characters y Uniform Resource Identifier (URI): Generic Syntax para obtener más información.

   4. Ejecute el ejemplo. La salida debe tener un aspecto similar al siguiente.

      $ node connect
      {
        _id: new ObjectId("611e3266005202371acf27c1"),
        title: 'Back to the Future',
        year: 1985,
        genres: [ 'Adventure', 'Comedy', 'Sci-Fi' ]
      }