Estamos incrivelmente animados para apresentar a você os novos recursos de nossa Capela API de gerenciamento. A nova versão da API foi redesenhada desde o início para ser mais RESTful, extensível, robusta e segura. Com uma série de funcionalidades focadas no aumento do controle, da segurança e da facilidade de uso, temos certeza de que você encontrará muitas maneiras de aprimorar seus fluxos de trabalho Capella DevOps aproveitando a API em seu Infraestrutura como código (IAC) e scripts de implantação. Nesta postagem, vamos apresentar um exemplo simples de uso de Carteiro para interagir com a API e executá-la. Mas, primeiro, vamos dar uma olhada rápida nos recursos que tornam nossa nova API de gerenciamento uma ferramenta poderosa para as organizações.
Destaques da API
-
- Os acessos à API são autenticados e autorizados usando chaves de API associadas às funções no nível da organização ou do projeto.
- A chave inicial da API de inicialização é gerada por meio da interface de usuário do Capella Admin. Posteriormente, você pode usar a API para gerar novas chaves de API que podem ter o escopo no nível da organização ou no nível do projeto.
- Os pontos de extremidade relacionados a projetos permitem que você liste, crie, atualize e exclua projetos por meio da API.
- Além de implantar e listar clusters, a API permite modificar o número de nós e até mesmo alterar o plano de suporte. Você também pode dimensionar os clusters horizontal e verticalmente.
- Agora você pode gerenciar usuários e modificar funções de usuário usando a API.
- Os CIDRs permitidos pelo cluster podem ser gerenciados por meio de um ponto de extremidade de API dedicado.
- Também há suporte para a adição dinâmica de credenciais de banco de dados, o que pode ser útil para a integração de sistemas externos de gerenciamento de segredos, como o Vault.
- Além de implantar clusters, agora você também pode gerenciar os buckets dentro desses clusters usando a API.
- A API oferece o recurso de buscar o certificado x.509 para um determinado cluster.
- Você pode criar backups sob demanda de buckets ou listar backups existentes, e até mesmo restaurar esses backups, tudo por meio da API.
- Além de gerenciar seus backups sob demanda, você também pode agendar backups por meio da API.
- E, por fim, a API agora inclui a funcionalidade para implementar serviços de aplicativos.
A lista de endpoints mencionada acima continuará a evoluir. Consulte a seção Referência abrangente de API para obter o conjunto completo de recursos e pontos de extremidade.
Antes de começarmos, é importante observar que as chaves da API v3 não serão compatíveis com a v4, portanto, será necessário um novo conjunto de chaves de API. Os detalhes sobre a geração de uma nova chave de API são fornecidos na seção de passo a passo abaixo.
No restante do artigo, vamos orientá-lo nas etapas para começar a usar nossa nova API usando o Postman. Se você é um engenheiro de DevOps, um desenvolvedor, QA ou qualquer pessoa interessada em se integrar com a Capella, este guia é para você.
Passo a passo
Etapa 1: Instalar o Postman
Se ainda não tiver instalado o Postman, você pode baixá-lo em Site do carteiro. Siga as etapas de instalação para colocá-lo em funcionamento em seu computador.
Etapa 2: Gerar chaves de API
Faça login no Capella e siga Nosso guia para configurar uma chave de gerenciamento adequada ao seu caso de uso. Devido a problemas de incompatibilidade com a v3, certifique-se de gerar um novo conjunto de chaves de API especificamente para a API v4. Para os fins deste artigo, é recomendável configurar uma chave de API de gerenciamento com uma função de "Proprietário da organização" para permitir testes abrangentes de endpoints. No entanto, em um ambiente de produção, adote o Princípio do Menor Privilégio e empregue o recurso "Endereços IP permitidos" para aumentar a segurança e restringir o acesso. Você pode usar o recurso "Add your current IP address block" para permitir rapidamente o acesso a partir do seu endereço IP.
Etapa 3: Faça o download da especificação OpenAPI
Faça o download do arquivo de especificação da OpenAPI para a API v4 em nosso site de documentação.
Etapa 4: Importar a especificação da OpenAPI para o Postman
-
- Abra o Postman e acesse o menu "File" (Arquivo).
- Selecione "Import" e navegue até o local em que você salvou o arquivo de especificação OpenAPI.
- Escolha o arquivo e clique em "Open" (Abrir) para importá-lo (openapi.json) para o Postman.
Isso criará automaticamente uma nova coleção chamada API de gerenciamento do Couchbase Capella no Postman contendo todos os endpoints de API disponíveis.
Etapa 5: Configurar a autorização
Selecione a coleção inteira que você acabou de importar. Navegue até a guia Authorization (Autorização) e selecione o tipo como "Bearer Token" (Token de portador). Coloque o Token de chave de API que você criou anteriormente no campo do token. Clique em salvar para garantir que a alteração seja aplicada a toda a coleção.
Etapa 6: Criar ambiente Postman
No Postman, crie um novo ambiente e adicione uma única variável chamada baseUrl com o valor https://cloudapi.cloud.couchbase.com/
-
- Clique em Environments (Ambientes)
- Clique em
para criar um novo ambiente - Dê um nome ao seu ambiente Capella v4 clicando em
- Adicione uma única variável chamada baseUrl com o valor https://cloudapi.cloud.couchbase.com
- Certifique-se de selecionar esse ambiente como o ativo.
> Observação: Certifique-se sempre de selecionar o ambiente correto antes de executar qualquer chamada de API.
Neste ponto, estamos prontos para chamar os diferentes pontos de extremidade da API.
Testando a API
Liste suas organizações
O primeiro ponto de extremidade da API que testaremos é o ponto de extremidade Listar organizações. O objetivo é buscar uma lista de organizações às quais a chave da API permite acesso.
Volte para o Postman e, dentro da coleção que você importou, navegue até o arquivo organizações e clique em Organização da lista.
A resposta deve conter pelo menos uma Organização Capella.
Para sua comodidade, criamos um script que você pode usar no Postman para obter o ID da primeira organização da resposta.
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 |
pm.teste("O código de status é 200", () => { pm.esperar(pm.resposta.código).para.eql(200); }); pm.teste("A resposta tem todas as propriedades", () => { const responseJson = pm.resposta.json(); pm.esperar(responseJson.dados).para.ser.e('array').que.é.não.vazio; pm.teste("A organização existe", () => { const org = responseJson.dados[0]; pm.esperar(org.id).para.ser.a("string"); pm.teste("Salvar a organização para o meio ambiente", () => { pm.ambiente.definir("orgId", org.id); }); }); }); |
Tudo o que você precisa fazer é colar isso no arquivo testes seção do Organização da lista ligar.
Obtenha sua organização
Supondo que a chamada da organização List tenha sido bem-sucedida, agora podemos passar para a próxima etapa para tentar a chamada Obter organização ponto final.
-
- Vá e selecione Obter ponto de extremidade da organização no Postman dentro de organizações pasta.
- Antes de executar a chamada à API, altere a variável Path chamada organizationId para a variável de ambiente chamada orgId que que criamos na etapa anterior.
Com a recuperação bem-sucedida das informações da sua organização, você acaba de dar o primeiro passo para aproveitar todo o potencial da nossa API v4.
Criar um novo projeto
Os projetos são usados para organizar e gerenciar grupos de bancos de dados do Couchbase dentro das organizações. Neste exemplo, vamos criar um novo projeto
-
- Vá para o Postman e abra o arquivo projetos pasta
- Selecione o Criar projeto operação
- Não se esqueça de alterar o organizationId path para usar sua variável de ambiente da mesma forma que usamos no exemplo Get Organization
-
- Clique na guia Body (Corpo) para fornecer o nome e a descrição do projeto que você gostaria de criar
-
- Adicione o seguinte script ao arquivo Testes para capturar o ID do projeto retornado pela API
|
1 2 3 4 5 6 7 8 9 10 |
pm.teste("O código de status é 201", () => { pm.esperar(pm.resposta.código).para.eql(201); }); pm.teste("A resposta tem todas as propriedades", () => { const responseJson = pm.resposta.json(); pm.esperar(responseJson).para.ser.e('objeto').que.é.não.vazio; pm.esperar(responseJson.id).para.ser.a("string"); pm.ambiente.definir("projectId", responseJson.id); }); |
-
- Clique em
para criar o projeto. O script de teste pegará o ID da resposta e o salvará como projectId em seu ambiente.
- Clique em
Obtenha os detalhes do projeto
Em seguida, chamaremos o Obter projeto para validar se o projeto foi criado corretamente.
-
- Na pasta de projetos, selecione a opção Obter projeto chamada
- Altere a variável de caminho chamada organizationId para usar o do ambiente
- Altere a variável de caminho chamada projectId para usar o do ambiente
Você deverá ver a resposta e os mesmos detalhes que forneceu na chamada de criação.
Implantar um novo cluster
Agora você está pronto para implementar seu próprio cluster. Nesta etapa, você implantará um novo cluster no projeto que acabamos de criar.
Para implantar um cluster, precisamos ter um organizationId e um projectId e os detalhes do cluster.
No nosso caso, usaremos as variáveis de ambiente que criamos nas etapas anteriores.
-
- Abra o agrupamentos pasta no Postman
- Selecione o Criar cluster ponto de extremidade da API
- Altere a variável de caminho chamada organizationId para usar o do ambiente
- Altere a variável de caminho chamada projectId para usar o do ambiente
-
- Abra a guia Body e cole o seguinte 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 |
{ "name" (nome):"Test-Postman-Cluster", "description" (descrição):"Meu primeiro cluster de teste do AWS criado com o postman.", "cloudProvider":{ "tipo":"aws", "region" (região):"us-east-1", "cidr":"10.1.200.0/23" }, "couchbaseServer":{ "versão":"7.1" }, "serviceGroups":[ { "nó":{ "compute" (computar):{ "cpu":4, "ram":16 }, "disco":{ "armazenamento":50, "tipo":"gp3", "iops":3000 } }, "numOfNodes":3, "serviços":[ "dados", "query" (consulta), "índice", "search" (pesquisa) ] }, { "nó":{ "compute" (computar):{ "cpu":4, "ram":32 }, "disco":{ "armazenamento":50, "tipo":"io2", "iops":3005 } }, "numOfNodes":2, "serviços":[ "analytics" ] } ], "disponibilidade":{ "tipo":"multi" }, "suporte":{ "plano":"desenvolvedor profissional", "timezone":"PT" } } |
-
- Adicione o seguinte script ao arquivo Testes para capturar o ID do cluster retornado pela API
|
1 2 3 4 5 6 7 8 9 10 |
pm.teste("O código de status é 202", () => { pm.esperar(pm.resposta.código).para.eql(202); }); pm.teste("A resposta tem todas as propriedades", () => { const responseJson = pm.resposta.json(); pm.esperar(responseJson).para.ser.e('objeto').que.é.não.vazio; pm.esperar(responseJson.id).para.ser.a("string"); pm.ambiente.definir("clusterId", responseJson.id); }); |
-
- Clique em para criar o cluster. O script de teste pegará o ID da resposta e o salvará como clusterId em seu ambiente.
- Clique em
Nesse momento, abrirei o Capella para verificar se o meu cluster está implantado.
-
- Faça login na Capella
- Vá para a seção Databases (Bancos de dados) e localize seu banco de dados
- Clique no banco de dados
-
- Clique no seu banco de dados para abrir os detalhes do cluster implantado
- Clique em Settings (Configurações) para verificar o resumo do cluster
Podemos ver nosso cluster implantado aqui. É importante observar que a chave de API que foi usada para criar o cluster também é mostrada nessa tela.
Configurar CIDRs para o cluster
Na última seção, adicionaremos um endereço IP à lista de permissões do cluster implantado para garantir que você possa acessar o cluster de um determinado local.
-
- Abra o allowedCIDRs(Cluster) pasta no Postman
- Selecione o Criar CIDR permitido ponto de extremidade da API
- Altere a variável de caminho chamada organizationId para usar o do ambiente
- Altere a variável de caminho chamada projectId para usar o do ambiente
- Altere a variável de caminho chamada clusterId para usar o do ambiente
-
- Clique no botão Corpo para adicionar seu endereço IP
-
- Clique em para adicionar seu IP à lista de CIDRs permitidos de seu cluster.
- Clique em
Concluindo
Esperamos que este guia tenha lhe fornecido todas as etapas necessárias para começar a trabalhar com nossa nova API v4. Mas configurar e testar endpoints no Postman é apenas a ponta do iceberg. A verdadeira empolgação começa quando você começa a integrar essa API robusta em suas próprias ferramentas e fluxos de trabalho para automatizar várias tarefas que sua organização realiza diariamente. Não deixe de conferir nosso Guia de referência da API para saber mais sobre os diferentes pontos de extremidade e funcionalidades.
Se você tiver dúvidas ou comentários, deixe um comentário abaixo. Os Fóruns do Couchbase ou Discórdia do Couchbase Os canais são outro bom lugar para entrar em contato com perguntas.
Boa codificação!