Colecciones Postman para la administración de Sync Gateway

Los clientes basados en web pueden administrar, supervisar e interactuar con Couchbase Sync Gateway utilizando un Interfaz RESTful. Con el Lanzamiento de Sync Gateway 3.0la administración de la base de datos se realiza exclusivamente a través del admin Punto final REST. Cartero es una herramienta de prueba, desarrollo y documentación de API que permite probar y utilizar estos puntos finales.

Esta entrada del blog le muestra cómo utilizar el Cliente API Postman para configurar, administrar e interactuar con Sync Gateway a través de la interfaz REST.

Colecciones Postman para Sync Gateway

Un cartero Colección es un grupo de solicitudes guardadas organizadas en carpetas y subcarpetas. Puede utilizar las colecciones como punto de partida y adaptarlas a su entorno y necesidades. 

Hemos elaborado un conjunto de referencia de Cartero y los correspondientes archivos de definición de variables de entorno para la interfaz REST de Sync Gateway 3.0. Estos archivos están disponibles en Github y diseñado para que puedas ponerte en marcha rápidamente con los siguientes pasos.

En primer lugar, clone el repositorio

El repositorio también contiene un viaje-muestra y una colección personalizada para la aplicación Travel Sample, como veremos más adelante.

Ahora exploremos los otros contenidos del repositorio clonado. Hay tres archivos JSON de Postman Collection con el sufijo postman_collection.json incluido y un archivo de configuración de Postman Environment como se describe en esta tabla:

Uso del cliente Postman

• Descargar el Cliente cartero gratis para su plataforma. 
• Siga las instrucciones detalladas en este puesto introductorio para importar las colecciones y los archivos de entorno a Postman. 
• Actualice la configuración del archivo de entorno según su implantación y comience a ejecutar solicitudes contra Sync Gateway.

Al final, su configuración debería parecerse a la siguiente captura de pantalla:

Administrar Sync Gateway a través de REST API: Ejemplo de recorrido

Una vez arrancado y conectado al cluster de Couchbase Server, Sync Gateway se gestiona a través del endpoint REST. Ahora vamos a recorrer el proceso con un ejemplo concreto.

El repositorio de GitHub contiene una versión personalizada de las colecciones de Postman para gestionar un Sync Gateway respaldado por un Cubo de muestras para viajes. Las siguientes colecciones se encuentran en viaje-muestra carpeta.

Visualización de los resultados de las pruebas

La mayoría de las solicitudes de las colecciones incluyen pruebas sencillas para verificar el éxito de la solicitud. Esta captura de pantalla muestra la pestaña Pruebas que incluye el código de prueba y la ventana de la consola Resultados de la prueba en la parte inferior.

Encadenamiento de solicitudes

El encadenamiento de peticiones toma el resultado de una petición y lo utiliza como entrada para una petición posterior. Esto se consigue actualizando dinámicamente las variables de entorno con los resultados de la ejecución de la solicitud y elimina la necesidad de editar manualmente las solicitudes.

Por ejemplo, al crear un documento se realiza una nueva revisión. La dirección revisionID del nuevo documento se devuelve a través de _rev campo. A continuación, la prueba asociada a la solicitud extrae el campo _rev y establece el valor rev variable de entorno.

La siguiente captura de pantalla muestra el código que establece la variable de entorno y el JSON de salida del Cuerpo rellenado.

Una posterior solicitud de actualización del documento puede recuperar el revisionId del documento que debe actualizarse desde el rev que fue rellenada por la petición anterior.

Esta captura de pantalla muestra una vista previa del ratón sobre el valor de la variable rev variable:

Instalación de Couchbase y Sync Gateway con Docker

Para poder ejecutar la colección, necesitas un entorno con Couchbase Server y Sync Gateway. Desplegarlos en contenedores Docker es la opción más sencilla. Tenemos imágenes pre-construidas que tienen todo pre-configurado para ti.

Docker debe estar instalado en su máquina. En Windows, es posible que necesite privilegios de administrador. Asegúrese de que tiene suficiente memoria y núcleos asignados a Docker. Se recomiendan al menos 3 GB de RAM.

Configuración de una red Docker

Crear una red docker llamada taller ejecutando estos comandos Docker

Tengo una imagen Docker personalizada de Couchbase Server que puede utilizar llamado:

La imagen viene preconfigurada con el viaje-muestra y tres usuarios RBAC:

• admin - que Sync Gateway utiliza para conectarse a Couchbase Server
• sgw-cluster - para operaciones a nivel de clúster a través de Sync Gateway admin/métricas Punto final REST
• sgw-admin - para operaciones administrativas a nivel de base de datos de Sync Gateway a través del punto final REST admin/metrics de Sync Gateway

Despliegue el servidor utilizando los siguientes comandos Docker:

Probar la instalación de Couchbase Server

El servidor tardará unos minutos en desplegarse e inicializarse por completo. Tenga paciencia, pero puede utilizar este comando para comprobar el estado:

Una vez finalizada la configuración, debería ver lo siguiente:

Abra la URL de Couchbase Web UI en un navegador web: http://localhost:8091 

En la pantalla de inicio de sesión, identifíquese como Administrador con contraseña: contraseña.

Ir a la Cubos y confirme que el viaje-muestra está cargado. Este bucket contiene los datos de muestra. Puede ver que el bucket existe y que hay muchos documentos cargados en esta captura de pantalla:

Ir a la Seguridad y confirme que se han creado nuestros tres usuarios, como se muestra a continuación:

Instalar y probar Sync Gateway 

Sync Gateway debe arrancar con un archivo de configuración de inicio. La dirección sync-gateway-config-travelsample-bootstrap.json está disponible en viaje-muestra del repositorio clonado.

Vaya a la carpeta que contiene el archivo de configuración descargado y ejecute los tres comandos siguientes para detener cualquier instancia en ejecución de Sync Gateway:

Ahora, para iniciar Sync Gateway utilizando Docker, ejecute los siguientes comandos en función de su sistema operativo. Tenga en cuenta que los comandos son una línea larga, que aquí se muestra en varias líneas para facilitar la lectura:

Windows

Máquina no Windows

Prueba de instalación de la puerta de enlace de sincronización

Puede confirmar que Sync Gateway está en funcionamiento verificando los mensajes de registro con Docker:

Verás un montón de mensajes de registro y ninguno de ellos debería ser un error.

Para confirmar que Sync Gateway se está ejecutando, vaya a http://localhost:4984 en un navegador web.
Deberías ver un mensaje similar a este:

Uso de Postman

Inicie el cliente API de Postman e importe los tres viaje-muestra y el archivo de entorno correspondiente, por ejemplo Sync-Gateway-3.0-TravelSample-Environment. Dedica algún tiempo a explorar el archivo de entorno.

Todas las solicitudes utilizan el usuario correspondiente para la autorización. Sin embargo, tendrá que proporcionar una contraseña cuando ejecute las solicitudes. Los usuarios se configuran con una contraseña de contraseña. Así que asegúrese de configurar el Cabecera de autorización de sus solicitudes con la contraseña correcta.

Prueba de cordura

En primer lugar, hagamos una prueba de cordura para asegurarnos de que las comunicaciones funcionan en general. Ejecute el programa Obtener información de la pasarela de sincronización solicitud del API de administración recogida. Debería ver los detalles de Sync Gateway en la respuesta. La siguiente captura de pantalla muestra la respuesta en el Cuerpo en la parte inferior de la pantalla.

Crear y configurar una base de datos de ejemplo de viajes en Sync Gateway

Dependiendo de si realizamos una solicitud a nivel de clúster o a nivel de base de datos, el usuario especificado en el campo Autorización puede ser {{clusteradmin}} o {{dbadmin}}} respectivamente. Utilice la contraseña de "contraseña"para todas las solicitudes.

La administración de bases de datos de Sync Gateway, incluida la creación de bases de datos, se gestiona a través del punto final REST admin y requiere una base de datos de Sync Gateway para funcionar. Para crear una, ejecute el comando Crear una base de datos de Sync Gateway solicitud del Sync Gateway 3.0 TravelSample Admin API colección como se muestra a continuación en la animación de captura de pantalla.

Una vez creada la base de datos de Sync Gateway, puede ejecutar otras operaciones en la base de datos, como crear una función de sincronización, establecer filtros de importación, etc.

Creación de un usuario de Sync Gateway

Antes de que pueda empezar a interactuar con la base de datos de Sync Gateway a través del punto final REST público, tendrá que crear un archivo usuario de la pasarela de sincronización. Para ello, ejecute el programa Crear un nuevo usuario solicitud del API de administración de TravelSample Sync Gateway 3.0 como se muestra a continuación. Esto creará un usuario llamado demo con la contraseña de contraseña. Una vez creado un usuario, puede utilizar el punto final REST público para interactuar con la base de datos.

Acceso a los datos

Se puede acceder a los documentos de la base de datos y modificarlos a través de la API REST del administrador o de la API REST pública. En este ejemplo, utilizamos la interfaz pública. Todas las solicitudes se ejecutan utilizando el método {{username}} que fue creado a través de Crear un nuevo usuario de la que hemos hablado antes. Utilice la contraseña de contraseña para solicitudes.

En viaje-muestra está precargado con datos de ejemplo. Por lo tanto, puede recuperar cualquier documento del bucket de muestra utilizando la función Obtener documento solicitud del Sync Gateway 3.0 TravelSample Public API recogida. Sustituya newdoc con doc en la solicitud para recuperar un documento existente del bucket.

Puede crear un nuevo documento y editarlo ejecutando peticiones desde la aplicación API pública de TravelSample Sync Gateway 3.0 como se muestra a continuación.

Supervisión

Por último, puede supervisar Sync Gateway ejecutando el comando Depuración/seguimiento de las estadísticas de ejecución en formato Prometheus solicitud del API de métricas de TravelSample de Sync Gateway 3.0 como se muestra a continuación.

Próximos pasos

Familiarícese con las demás API REST ejecutando las demás solicitudes y personalizándolas según sea necesario.

Las colecciones Postman en este repositorio se comparten como una conveniencia para los administradores y desarrolladores para empezar con Sync Gateway. No está soportado oficialmente por Couchbase y, como tal, no hay garantías de que las colecciones se mantengan actualizadas con la evolución de la API REST. Por ello, ¡las contribuciones para mantener las colecciones actualizadas son bienvenidas! 

Si tiene alguna pregunta o sugerencia, deje un comentario a continuación o póngase en contacto conmigo en Twitter @rajagp o envíeme un correo electrónico priya.rajagopal@couchbase.com. En Foros de Couchbase son otro buen lugar al que dirigirse con preguntas.

Agradecimientos

Me gustaría dar las gracias a Isaac Lambatingeniero del equipo Sync Gateway, por su aportación a esta entrada del blog.

Recursos

• Sitio web del cliente de la API Postman
• Archivos Postman en Github para Couchbase Sync Gateway
• Documentación de ejemplo de Couchbase Travel
• Sitio de descarga de Docker
• Empieza por Couchbase Capella - en la nube, con una prueba gratuita (sin tarjeta de crédito)