Postman Collections para administração do Sync Gateway

Os clientes baseados na Web podem administrar, monitorar e interagir com o Couchbase Sync Gateway usando um Interface RESTful. Com o Lançamento do Sync Gateway 3.0A administração do banco de dados é feita exclusivamente por meio do administrador Ponto de extremidade REST. Carteiro é uma ferramenta de teste, desenvolvimento e documentação de API que permite testar e usar esses pontos de extremidade.

Esta postagem do blog mostra como usar o Cliente da API do Postman para configurar, administrar e interagir com o Sync Gateway por meio da interface REST.

Coleções Postman para o Sync Gateway

Um carteiro Coleção é um grupo de solicitações salvas organizadas em pastas e subpastas. Você pode usar as coleções como ponto de partida e personalizá-las de acordo com seu ambiente e suas necessidades. 

Produzimos um conjunto de referência de Carteiro e os arquivos de definição de variáveis de ambiente correspondentes para a interface REST do Sync Gateway 3.0. Esses arquivos estão disponíveis em Github e projetado para que você comece a trabalhar rapidamente com as etapas a seguir.

Primeiro, clone o repositório

O repositório também contém um amostra de viagem e uma coleção personalizada para o aplicativo Travel Sample, conforme discutiremos um pouco mais adiante.

Agora vamos explorar os outros conteúdos do repositório clonado. Há três arquivos JSON da Postman Collection com o sufixo postman_collection.json incluído e um arquivo de configurações do Postman Environment, conforme descrito nesta tabela:

Usando o cliente Postman

• Faça o download do Cliente carteiro gratuitamente para sua plataforma. 
• Siga as instruções detalhadas nesta seção postagem introdutória para importar as coleções e os arquivos de ambiente para o Postman. 
• Atualize as configurações do arquivo de ambiente de acordo com sua implementação e comece a executar solicitações no Sync Gateway.

No final, sua configuração deve ser semelhante à seguinte captura de tela:

Administrar o Sync Gateway por meio da API REST: Exemplo de passo a passo

Uma vez inicializado e conectado ao cluster do Couchbase Server, o Sync Gateway é gerenciado por meio do ponto de extremidade REST. Agora, vamos examinar o processo com um exemplo concreto.

O repositório do GitHub contém uma versão personalizada das coleções Postman para gerenciar um Gateway de sincronização apoiado por um Balde de amostra de viagem. As seguintes coleções estão localizadas no amostra de viagem pasta.

Visualização dos resultados do teste

A maioria das solicitações nas coleções inclui testes simples para verificar o sucesso da solicitação. Esta captura de tela mostra a guia Testes que inclui o código de teste e a janela do console Resultados do teste na parte inferior.

Encadeamento de solicitações

O encadeamento de solicitações pega o resultado de uma solicitação e o usa como entrada para uma solicitação subsequente. Isso é feito por meio da atualização dinâmica das variáveis de ambiente com os resultados da execução da solicitação e elimina a necessidade de editar manualmente as solicitações.

Por exemplo, uma nova revisão de documento é feita quando você cria um documento. A revisão ID da revisão do novo documento é retornado por meio do _rev campo. O teste associado à solicitação extrai o campo _rev e define o valor rev variável de ambiente.

A captura de tela abaixo mostra o código que define a variável de ambiente e o JSON de saída do Body preenchido.

Uma solicitação de atualização subsequente para o documento pode recuperar o revisionId do documento a ser atualizado a partir do rev variável de ambiente que foi preenchida pela solicitação anterior.

Esta captura de tela mostra uma visualização de mouseover do valor do rev variável:

Instalação do Couchbase e do Sync Gateway com o Docker

Para poder executar a coleção, você precisa de um ambiente com o Couchbase Server e o Sync Gateway. Implementá-los em contêineres do Docker é a opção mais simples. Temos imagens pré-construídas que têm tudo pré-configurado para você.

Docker deve estar instalado em seu computador. No Windows, talvez você precise de privilégios de administrador. Certifique-se de que você tenha memória e núcleos suficientes alocados para o Docker. Recomenda-se pelo menos 3 GB de RAM.

Configuração de uma rede Docker

Crie uma rede docker chamada oficina executando estes comandos do Docker

Tenho uma imagem personalizada do Docker do Couchbase Server que você pode usar chamado:

A imagem vem pré-configurada com o amostra de viagem e três usuários RBAC:

• administrador - que o Sync Gateway usa para se conectar ao Couchbase Server
• cluster sgw - para operações em nível de cluster via Sync Gateway administrador/métricas Ponto de extremidade REST
• sgw-admin - para operações administrativas no nível do banco de dados do Sync Gateway por meio do ponto de extremidade REST admin/metrics do Sync Gateway

Implemente o servidor usando os seguintes comandos do Docker:

Teste a instalação do servidor Couchbase

O servidor levará alguns minutos para ser implantado e totalmente inicializado. Seja paciente, mas você pode usar este comando para verificar o status:

Você deverá ver o seguinte quando a configuração estiver concluída:

Abra o URL da interface do usuário da Web do Couchbase em um navegador da Web: http://localhost:8091 

Na tela de login, faça login como Administrador com senha: senha.

Ir para o Baldes e confirme que o amostra de viagem é carregado. Esse compartimento contém os dados de amostra. Você pode ver que o compartimento existe e que há muitos documentos carregados nesta captura de tela:

Ir para o Segurança e confirme que nossos três usuários foram criados, conforme mostrado abaixo:

Instalar e testar o Sync Gateway 

O Sync Gateway precisa ser inicializado com um arquivo de configuração de inicialização. O arquivo sync-gateway-config-travelsample-bootstrap.json está disponível no arquivo amostra de viagem do repositório clonado.

Vá para a pasta que contém o arquivo de configuração baixado e execute os três comandos a seguir para interromper todas as instâncias em execução do Sync Gateway:

Agora, para iniciar o Sync Gateway usando o Docker, execute os seguintes comandos, dependendo do seu sistema operacional. Observe que os comandos são uma linha longa, mostrada aqui em várias linhas para facilitar a leitura:

Windows

Máquina não-Windows

Teste a instalação do Sync Gateway

Você pode confirmar que o Sync Gateway está em funcionamento verificando as mensagens de registro com o Docker:

Você verá várias mensagens de registro e nenhuma delas deve ser um erro.

Para confirmar que o Sync Gateway está em execução, vá para http://localhost:4984 em um navegador da Web.
Você deverá ver uma mensagem semelhante a esta:

Usando o Postman

Inicie o cliente da API do Postman e importe todos os três amostra de viagem e o arquivo de ambiente correspondente, por exemplo, Sync-Gateway-3.0-TravelSample-Environment. Passe algum tempo explorando o arquivo de ambiente.

Todas as solicitações usam o usuário relevante para autorização. No entanto, você precisará fornecer uma senha ao executar as solicitações. Os usuários são configurados com uma senha de senha. Portanto, certifique-se de configurar o Cabeçalho de autorização de suas solicitações com a senha correta.

Teste de sanidade

Primeiro, vamos fazer um teste de sanidade para garantir que as comunicações estejam funcionando de modo geral. Execute o Obter informações do gateway de sincronização solicitação do API do administrador cobrança. Você deverá ver os detalhes do Sync Gateway na resposta. A captura de tela abaixo mostra a resposta na seção Corpo na parte inferior da tela.

Criar e configurar o banco de dados de amostra de viagens no Sync Gateway

Dependendo se fizermos uma solicitação no nível do cluster ou no nível do banco de dados, o usuário especificado no Autorização O cabeçalho pode ser {{clusteradmin}} ou {{dbadmin}} respectivamente. Use a senha de "senha" para todas as solicitações.

A administração do banco de dados do Sync Gateway, incluindo a criação do banco de dados, é feita por meio do ponto de extremidade REST do admin e requer um banco de dados do Sync Gateway para funcionar. Para criar um, execute o comando Criar um banco de dados do Sync Gateway solicitação do Sync Gateway 3.0 TravelSample Admin APEu coleciono como mostrado abaixo na animação da captura de tela.

Depois que o banco de dados do Sync Gateway for criado, você poderá executar outras operações no banco de dados, como criar uma função de sincronização, definir filtros de importação etc.

Criação de um usuário do Sync Gateway

Antes de começar a interagir com o banco de dados do Sync Gateway por meio do ponto de extremidade REST público, você terá que criar um arquivo usuário do gateway de sincronização. Para isso, execute o Criar um novo usuário solicitação do API de administração do Sync Gateway 3.0 TravelSample conforme mostrado abaixo. Isso criará um usuário chamado demonstração com a senha de senha. Depois que um usuário é criado, você pode usar o ponto de extremidade REST público para interagir com o banco de dados.

Acesso aos dados

O acesso aos documentos no banco de dados e a modificação deles podem ser feitos por meio da API REST do administrador ou da API REST pública. Neste exemplo, usamos a interface pública. Todas as solicitações são executadas usando a interface {{username}} usuário que foi criado por meio do Criar um novo usuário discutida anteriormente. Use a senha de senha para solicitações.

O amostra de viagem é pré-carregado com dados de amostra. Portanto, você pode recuperar qualquer documento no bucket de amostra usando o comando Obter documento solicitação do Sync Gateway 3.0 TravelSample Public APEu coleciono. Substituir novo documento com doc na solicitação para recuperar um documento existente do bucket.

Você pode criar um novo documento e editá-lo executando solicitações do API pública do Sync Gateway 3.0 TravelSample conforme mostrado abaixo.

Monitoramento

Por fim, você pode monitorar o Sync Gateway executando o comando Depuração/monitoramento de estatísticas de tempo de execução no formato Prometheus solicitação do API de métricas do TravelSample do Sync Gateway 3.0 como mostrado abaixo.

Próximas etapas

Familiarize-se com as outras APIs REST executando as outras solicitações e personalizando-as conforme necessário.

As coleções Postman neste repositório são compartilhadas como uma conveniência para administradores e desenvolvedores começarem a usar o Sync Gateway. Ele não é oficialmente suportado pelo Couchbase e, como tal, não há garantias de que as coleções permanecerão atualizadas com a evolução da API REST. Para isso, contribuições para manter as coleções atualizadas são bem-vindas! 

Se tiver dúvidas ou comentários, deixe um comentário abaixo ou entre em contato comigo pelo Twitter @rajagp ou envie-me um e-mail priya.rajagopal@couchbase.com. O Fóruns do Couchbase são outro bom lugar para entrar em contato com perguntas.

Agradecimentos

Gostaria de agradecer a Isaac Lambatengenheiro da equipe do Sync Gateway, por sua contribuição para esta publicação do blog.

Recursos

• Site do cliente da API do Postman
• Arquivos Postman no Github para o Couchbase Sync Gateway
• Documentação de amostra do Couchbase Travel
• Site de download do Docker
• Comece a usar Couchbase Capella - na nuvem, com uma avaliação gratuita (não é necessário cartão de crédito)