Estamos muy contentos de presentarles las nuevas funciones de nuestra Capella API de gestión. La nueva versión de la API ha sido rediseñada desde cero para ser más RESTful, extensible, robusta y segura. Con una serie de funcionalidades centradas en mejorar el control, la seguridad y la facilidad de uso, estamos seguros de que encontrará muchas maneras de mejorar sus flujos de trabajo Capella DevOps aprovechando la API dentro de su Infraestructura como código (IAC) y scripts de despliegue. En este post, vamos a recorrer un ejemplo sencillo de uso de Cartero para interactuar con la API y ejecutarla. Pero antes, echemos un vistazo rápido a las características que hacen de nuestra nueva API de gestión una potente herramienta para las organizaciones.
Aspectos destacados de la API
-
- Los accesos a la API se autentican y autorizan mediante claves de API asociadas a roles de nivel de organización o de nivel de proyecto.
- La clave API inicial se genera a través de la interfaz de usuario de administración de Capella. A partir de entonces, puede utilizar la API para generar nuevas claves de API que se pueden asignar al nivel de organización o al nivel de proyecto.
- Los puntos finales relacionados con los proyectos le permiten listar, crear, actualizar y eliminar proyectos a través de la API.
- Además de desplegar y listar clusters, la API permite modificar el número de nodos e incluso cambiar el plan de soporte. También puedes escalar los clústeres horizontal y verticalmente.
- Ahora puede gestionar usuarios y modificar sus funciones mediante la API.
- Los CIDR permitidos por el clúster pueden gestionarse a través de un punto final de API dedicado.
- También se admite la adición dinámica de credenciales de bases de datos, lo que puede resultar útil para integrar sistemas externos de gestión de secretos como Vault.
- Además de desplegar clústeres, ahora también puede gestionar los buckets dentro de esos clústeres utilizando la API.
- La API permite obtener el certificado x.509 de un clúster determinado.
- Puede crear copias de seguridad bajo demanda de los buckets o listar las copias de seguridad existentes, e incluso restaurar esas copias de seguridad, todo a través de la API.
- Además de gestionar sus copias de seguridad bajo demanda, también puede programar copias de seguridad a través de la API.
- Y, por último, la API incluye ahora la funcionalidad para desplegar App Services.
La lista de puntos finales mencionada seguirá evolucionando. Consulte la referencia completa de la API para ver el conjunto completo de recursos y puntos finales.
Antes de entrar en materia, es importante tener en cuenta que las claves de la API v3 no serán compatibles con la v4, por lo que será necesario un nuevo conjunto de claves de API. Los detalles sobre la generación de una nueva clave de API se proporcionan en la sección de tutorial a continuación.
En el resto del artículo, te guiaremos a través de los pasos para empezar con nuestra nueva API utilizando Postman. Si eres un ingeniero DevOps, un desarrollador, QA, o cualquier persona interesada en integrarse con Capella, esta guía es para ti.
Recorrido
Paso 1: Instalar Postman
Si aún no ha instalado Postman, puede descargarlo desde Página web del cartero. Siga los pasos de instalación para ponerlo en marcha en su máquina.
Paso 2: Generar claves API
Inicie sesión en Capella y siga nuestra guía para configurar una clave de gestión que se adapte a su caso de uso. Debido a problemas de incompatibilidad con la v3, asegúrese de generar un nuevo conjunto de claves de API específicas para la API v4. Para los fines de este artículo, es aconsejable configurar una clave de API de gestión con una función de "Propietario de la organización" para permitir pruebas exhaustivas del punto final. Sin embargo, en un entorno de producción, siga el principio de mínimo privilegio y utilice la función "Direcciones IP permitidas" para mejorar la seguridad y restringir el acceso. Puede utilizar la función "Añadir su bloqueo de dirección IP actual" para permitir rápidamente el acceso desde su dirección IP.
Paso 3: Descargar la especificación OpenAPI
Descargue el archivo de especificación OpenAPI para la API v4 de nuestro sitio de documentación.
Paso 4: Importar la especificación OpenAPI a Postman
-
- Abra Postman y vaya al menú "Archivo".
- Seleccione "Importar" y vaya a la ubicación donde guardó el archivo de especificación OpenAPI.
- Elija el archivo y haga clic en "Abrir" para importarlo (openapi.json) en Postman.
Se creará automáticamente una nueva colección denominada API de gestión de Couchbase Capella en Postman que contiene todos los puntos finales de API disponibles.
Paso 5: Configurar la autorización
Seleccione toda la colección que acaba de importar. Vaya a la pestaña Autorización y seleccione el tipo "Token de portador". Coloque el Token de clave API que creó anteriormente en el campo de token. Haga clic en guardar para asegurarse de que el cambio se aplica a toda la colección.
Paso 6: Crear entorno Postman
En Postman, crea un nuevo entorno y añade una única variable llamada baseUrl con el valor https://cloudapi.cloud.couchbase.com/
-
- Haga clic en Entornos
- Haga clic en
crear un nuevo entorno - Nombre de su entorno Capella v4 haciendo clic en
- Añade una única variable llamada baseUrl con el valor https://cloudapi.cloud.couchbase.com
- Asegúrese de seleccionar este entorno como el activo.
> Nota: Asegúrese siempre de seleccionar el entorno correcto antes de ejecutar cualquier llamada a la API.
En este punto estamos listos para llamar a los diferentes puntos finales de la API.
Probar la API
Enumere sus organizaciones
El primer punto final de la API que probaremos es el punto final Lista de organizaciones. El objetivo es obtener una lista de organizaciones a las que la clave de API permite acceder.
Vuelva a Postman, y dentro de la colección que ha importado, navegue hasta el archivo organizaciones y haga clic en Organización de la lista.
La respuesta debe tener al menos una Organización Capella.
Para su comodidad, hemos creado un script que puede utilizar en Postman para obtener el identificador de la primera organización de la respuesta.
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 |
pm.prueba("El código de estado es 200", () => { pm.espere(pm.respuesta.código).a.eql(200); }); pm.prueba("La respuesta tiene todas las propiedades", () => { const responseJson = pm.respuesta.json(); pm.espere(responseJson.datos).a.sea.un(array).que.es.no.vacío; pm.prueba("La organización existe", () => { const org = responseJson.datos[0]; pm.espere(org.id).a.sea.a("cadena"); pm.prueba("Salvar la organización al medio ambiente", () => { pm.medio ambiente.configure("orgId", org.id); }); }); }); |
Todo lo que tienes que hacer es pegar esto en el archivo pruebas de la Organización de la lista llamar.
Consiga su organización
Suponiendo que la llamada a la organización List se haya realizado correctamente, ahora podemos pasar al siguiente paso para probar la función Conseguir organización punto final.
-
- Vaya y seleccione Obtener punto final de la organización en Postman dentro de la carpeta organizaciones carpeta.
- Antes de ejecutar la llamada a la API, cambie la variable Path llamada organizationId por la variable de entorno llamada orgId que que creamos en el paso anterior.
Una vez recuperada con éxito la información de su organización, acaba de dar el primer paso para aprovechar toda la potencia de nuestra API v4.
Crear un nuevo proyecto
Los proyectos se utilizan para organizar y gestionar grupos de bases de datos Couchbase dentro de las organizaciones. En este ejemplo vamos a crear un nuevo Proyecto
-
- Vaya a Postman y abra el proyectos carpeta
- Seleccione Crear proyecto operación
- No olvide cambiar el organizationId para utilizar su variable de entorno de la misma forma que en el ejemplo Obtener organización
-
- Haga clic en la pestaña Cuerpo para indicar el nombre y la descripción del proyecto que desea crear.
-
- Añada la siguiente secuencia de comandos al archivo Pruebas para capturar el identificador de proyecto devuelto por la API
|
1 2 3 4 5 6 7 8 9 10 |
pm.prueba("El código de estado es 201", () => { pm.espere(pm.respuesta.código).a.eql(201); }); pm.prueba("La respuesta tiene todas las propiedades", () => { const responseJson = pm.respuesta.json(); pm.espere(responseJson).a.sea.un(objeto).que.es.no.vacío; pm.espere(responseJson.id).a.sea.a("cadena"); pm.medio ambiente.configure("projectId", responseJson.id); }); |
-
- Haga clic en
para crear el proyecto. El script de prueba tomará el id de la respuesta y lo guardará como projectId en su entorno.
- Haga clic en
Conozca los detalles del proyecto
A continuación vamos a llamar al Obtener proyecto para validar que el proyecto se ha creado correctamente.
-
- En la carpeta de proyectos, seleccione la opción Obtener proyecto llame a
- Cambia la variable de ruta llamada organizationId utilizar el del entorno
- Cambia la variable de ruta llamada projectId utilizar el del entorno
Deberías ver la respuesta y los mismos detalles que proporcionaste en la llamada de creación.
Desplegar un nuevo clúster
Ahora estás listo para desplegar tu propio cluster. En este paso vas a desplegar un nuevo clúster en el proyecto que acabamos de crear.
Para desplegar un cluster necesitamos tener un organizationId y un projectId y los detalles de la agrupación.
En nuestro caso, utilizaremos las variables de entorno que hemos creado en los pasos anteriores.
-
- Abra el racimos carpeta en Postman
- Seleccione Crear clúster punto final api
- Cambia la variable de ruta llamada organizationId utilizar el del entorno
- Cambia la variable de ruta llamada projectId utilizar el del entorno
-
- Abra la pestaña Cuerpo y pegue el siguiente JSON:
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 |
{ "nombre":"Test-Postman-Cluster", "descripción":"Mi primer cluster AWS de prueba creado con postman"., "cloudProvider":{ "tipo":"aws", "región":"us-east-1", "cidr":"10.1.200.0/23" }, "couchbaseServer":{ "version":"7.1" }, "serviceGroups":[ { "nodo":{ "computar":{ "cpu":4, "carnero":16 }, "disco":{ "almacenamiento":50, "tipo":"gp3", "iops":3000 } }, "numOfNodes":3, "servicios":[ "datos", "consulta", "índice", "buscar" ] }, { "nodo":{ "computar":{ "cpu":4, "carnero":32 }, "disco":{ "almacenamiento":50, "tipo":"io2", "iops":3005 } }, "numOfNodes":2, "servicios":[ "analítica" ] } ], "disponibilidad":{ "tipo":"multi" }, "apoyo":{ "plan":"desarrollador profesional", "zona horaria":"PT" } } |
-
- Añada la siguiente secuencia de comandos al archivo Pruebas para capturar el identificador de clúster devuelto por la API
|
1 2 3 4 5 6 7 8 9 10 |
pm.prueba("El código de estado es 202", () => { pm.espere(pm.respuesta.código).a.eql(202); }); pm.prueba("La respuesta tiene todas las propiedades", () => { const responseJson = pm.respuesta.json(); pm.espere(responseJson).a.sea.un(objeto).que.es.no.vacío; pm.espere(responseJson.id).a.sea.a("cadena"); pm.medio ambiente.configure("clusterId", responseJson.id); }); |
-
- Haga clic en para crear el cluster. El script de prueba tomará el id de la respuesta y lo guardará como clusterId en su entorno.
- Haga clic en
En este punto, abriré Capella para comprobar si mi clúster está desplegado.
-
- Conectarse a Capella
- Vaya a la sección Bases de datos y busque su base de datos
- Haga clic en la base de datos
-
- Haga clic en su base de datos para abrir los detalles del clúster desplegado
- Haga clic en Configuración para comprobar el resumen del clúster
Aquí podemos ver nuestro clúster desplegado. Es importante tener en cuenta que la clave API que se utilizó para crear el clúster también se muestra en esta pantalla.
Configurar CIDR para el clúster
En la última sección, vamos a añadir una dirección IP a la lista permitida del clúster desplegado para asegurarnos de que puede acceder al clúster desde una ubicación determinada.
-
- Abra el allowedCIDRs(Cluster) carpeta en Postman
- Seleccione Crear CIDR permitido punto final api
- Cambia la variable de ruta llamada organizationId utilizar el del entorno
- Cambia la variable de ruta llamada projectId utilizar el del entorno
- Cambia la variable de ruta llamada clusterId utilizar el del entorno
-
- Haga clic en el botón Cuerpo para añadir su dirección IP
-
- Haga clic en para añadir su IP a la lista CIDR permitida de su cluster.
- Haga clic en
Conclusión
Esperamos que esta guía le haya proporcionado todos los pasos necesarios para ponerse en marcha con nuestra nueva API v4. Pero configurar y probar endpoints en Postman es sólo la punta del iceberg. La verdadera emoción comienza cuando empiezas a integrar esta robusta API en tus propias herramientas y flujos de trabajo para automatizar varias tareas que tu organización maneja a diario. Asegúrese de consultar nuestra Guía de referencia API para conocer los diferentes puntos finales y funcionalidades.
Si tiene alguna pregunta o comentario, déjelo a continuación. En Foros de Couchbase o Couchbase discord son otro buen lugar para plantear preguntas.
¡Feliz codificación!