Amazon® DocumentDB - Guia do desenvolvedordocs.aws.amazon.com/pt_br/documentdb/...Amazon DocumentDB Guia do desenvolvedor Janela de backup.....167

Amazon DocumentDBGuia do desenvolvedor

Amazon DocumentDB Guia do desenvolvedor

Amazon DocumentDB: Guia do desenvolvedorCopyright © 2020 Amazon Web Services, Inc. and/or its affiliates. All rights reserved.

Amazon's trademarks and trade dress may not be used in connection with any product or service that is not Amazon's,in any manner that is likely to cause confusion among customers, or in any manner that disparages or discreditsAmazon. All other trademarks not owned by Amazon are the property of their respective owners, who may or may notbe affiliated with, connected to, or sponsored by Amazon.


Table of ContentsO que é Amazon DocumentDB? ........................................................................................................... 1

Visão geral ................................................................................................................................ 1Clusters ..................................................................................................................................... 2Instances ................................................................................................................................... 3Regiões e AZs ........................................................................................................................... 4

Regions ............................................................................................................................. 4Zonas de disponibilidade ..................................................................................................... 4

Definição de preço ...................................................................................................................... 5Monitoring ................................................................................................................................. 6Interfaces .................................................................................................................................. 6

Console de gerenciamento da AWS ...................................................................................... 6AWS CLI ........................................................................................................................... 6O shell do Mongo ............................................................................................................... 6Drivers do MongoDB ........................................................................................................... 7

E o próximo? ............................................................................................................................. 7: Como ele funciona ................................................................................................................... 7

Amazon DocumentDBEndpoints do ....................................................................................... 8TLS Support ..................................................................................................................... 11Amazon DocumentDBArmazenamento do ............................................................................. 11Amazon DocumentDB Replicação ....................................................................................... 12Amazon DocumentDBConfiabilidade do ................................................................................ 12Opções de preferência de leitura ........................................................................................ 12Exclusões de TTL ............................................................................................................. 15Recursos facturáveis ......................................................................................................... 16

O que é um banco de dados de documentos? .............................................................................. 18Casos de uso ................................................................................................................... 18Noções básicas sobre documentos ...................................................................................... 19Como trabalhar com documentos ........................................................................................ 23

Guia de Introdução ........................................................................................................................... 32Prerequisites ............................................................................................................................ 32Passo 1: Criar um ambiente do AWS Cloud9 ................................................................................ 33Passo 2: Crie um grupo de segurança ......................................................................................... 36Passo 3: Criar um cluster do Amazon DocumentDB ....................................................................... 38Passo 4: Instale o shell do mongo .............................................................................................. 41Passo 5: Ligue-se ao seu Amazon DocumentDB cluster ................................................................. 42Passo 6: Inserir e dados de consulta ........................................................................................... 44Passo 7: Explorar ..................................................................................................................... 45

Início rápido usando o AWS CloudFormation ........................................................................................ 46Prerequisites ............................................................................................................................ 46

Obrigatório IAM Permissões ............................................................................................... 46Amazon EC2Par de chaves do ........................................................................................... 47

Iniciar um Amazon DocumentDB AWS CloudFormation Pilha .......................................................... 48Aceder ao Amazon DocumentDB Cluster ..................................................................................... 51Proteção contra encerramento e exclusão .................................................................................... 51

Práticas recomendadas ...................................................................................................................... 53Diretrizes operacionais básicas ................................................................................................... 53Dimensionamento de instância .................................................................................................... 54Trabalho com índices ................................................................................................................ 55

Criação de índices ............................................................................................................ 55Seletividade do índice ....................................................................................................... 55Impacto dos índices na gravação de dados .......................................................................... 56Identificar índices ausentes ................................................................................................ 56Identificar índices não utilizados .......................................................................................... 56

Melhores práticas de segurança .................................................................................................. 56

iii


Otimização de custo .................................................................................................................. 57Usar métricas para identificar problemas de desempenho ............................................................... 57

Visualização de métricas de desempenho ............................................................................ 57Configurar um alarme CloudWatch ...................................................................................... 58Avaliação de métricas de desempenho ................................................................................ 58Ajuste das consultas ......................................................................................................... 59

Cargas de trabalho TTL e temporais ........................................................................................... 59Migrations ................................................................................................................................ 60Trabalhar com grupos de parâmetros de cluster ............................................................................ 60Consultas de pipeline de agregação ............................................................................................ 60batchInsert e batchUpdate .................................................................................................. 60

Diferenças funcionais com o MongoDB ................................................................................................ 61Benefícios funcionais do Amazon DocumentDB ............................................................................. 61

Transações implícitas ........................................................................................................ 61Diferenças funcionais atualizadas ............................................................................................... 62

Indexação de matriz .......................................................................................................... 62Índices de várias chaves .................................................................................................... 63Caracteres nulos em strings ............................................................................................... 63Controle de acesso com base em função ............................................................................ 63$regexIndexação ............................................................................................................. 64

Diferenças funcionais com o MongoDB ........................................................................................ 64Bancos de dados e coleções de administradores ................................................................... 64explain() .......................................................................................................................... 64Restrições de nome de campo .......................................................................................... 65Compilações de índice ...................................................................................................... 65APIs, operações e tipos de dados do MongoDB .................................................................... 65O mongodump e mongorestore Serviços públicos ............................................................... 65Ordenação de resultados ................................................................................................... 66Gravações que podem ser recuperadas ............................................................................... 66Índice esparso .................................................................................................................. 66Compactação de armazenamento ....................................................................................... 66Usar $elemMatch em uma expressão $all ............................................................................ 67$distinct, $elemMatch, e $lookup Indexação ................................................................. 67$lookup ........................................................................................................................... 67

Consulta .......................................................................................................................................... 68Consultar documentos ............................................................................................................... 68

Recuperar todos os documentos ......................................................................................... 77Valores de campo correspondentes ..................................................................................... 77Documentos incorporados .................................................................................................. 77Valores de campo em documentos incorporados ................................................................... 78Combinar uma Matriz ........................................................................................................ 78Valores correspondentes numa matriz .................................................................................. 78Utilizar operadores ............................................................................................................ 78

Plano de consulta ..................................................................................................................... 79Plano de consulta ............................................................................................................. 79Cache do plano de consulta ............................................................................................... 80

Explicar resultados .................................................................................................................... 80Fase de leitura e filtro ....................................................................................................... 81Intersecção de índice ........................................................................................................ 82União de Índices ............................................................................................................... 82Intersecção/União de Múltiplos Índices ................................................................................. 83Índice composto ............................................................................................................... 83Ordenar fase .................................................................................................................... 83Fase do grupo .................................................................................................................. 84

APIs, operações e tipos de dados do MongoDB compatíveis ................................................................... 85Comandos do banco de dados ................................................................................................... 85

Comandos administrativos .................................................................................................. 86

iv


Aggregation ...................................................................................................................... 86Authentication ................................................................................................................... 87Comandos de diagnóstico .................................................................................................. 87Operações de gravação e de consulta ................................................................................. 87Comandos de gerenciamento de função ............................................................................... 88Comandos de sessões ...................................................................................................... 88Gerenciamento de usuários ................................................................................................ 89

Operadores de consulta e projeção ............................................................................................. 89Operadores de matriz ........................................................................................................ 89Operadores bitwise ........................................................................................................... 89Operador de comentários ................................................................................................... 90Operadores de comparação ............................................................................................... 90Operadores de elemento .................................................................................................... 90Operadores de consulta de avaliação .................................................................................. 90Operadores lógicos ........................................................................................................... 91Operadores de projeção .................................................................................................... 91

Operadores de atualização ......................................................................................................... 91Operadores de matriz ........................................................................................................ 91Operadores bitwise ........................................................................................................... 92Operadores de campo ....................................................................................................... 92Modificadores de atualização .............................................................................................. 92

Geospatial ............................................................................................................................... 93Especificadores de geometria ............................................................................................. 93Seletores de consulta ........................................................................................................ 93

Métodos de cursor .................................................................................................................... 93Operadores de pipeline de agregação .......................................................................................... 94

Expressões do acumulador ................................................................................................ 95Operadores aritméticos ...................................................................................................... 95Operadores de matriz ........................................................................................................ 96Operadores booleanos ....................................................................................................... 96Operadores de comparação ............................................................................................... 97Operadores de expressão condicional .................................................................................. 97Operador de tipo de dados ................................................................................................ 97Operadores de data .......................................................................................................... 97Operador literal ................................................................................................................. 98Operador de mesclagem .................................................................................................... 98Operador natural ............................................................................................................... 98Configurar operadores ....................................................................................................... 99Operadores de estágio ...................................................................................................... 99Operadores de sequência ................................................................................................ 100Variáveis de sistema ....................................................................................................... 100Operador de pesquisa de texto ......................................................................................... 101Operadores variáveis ....................................................................................................... 101

Tipos de dados ....................................................................................................................... 101Índices e propriedades de índice ............................................................................................... 102

Indexes .......................................................................................................................... 102Propriedades de índice .................................................................................................... 102

Migrar para o Amazon DocumentDB .................................................................................................. 103Ferramentas de migração ......................................................................................................... 103

AWS Database Migration Service ...................................................................................... 103Utilitários de linha de comando ......................................................................................... 104

Descoberta ............................................................................................................................. 104Planeamento: requisitos de cluster do Amazon DocumentDB ......................................................... 107Abordagens de migração ......................................................................................................... 109

Off-line ........................................................................................................................... 109Online ............................................................................................................................ 110Abordagem híbrida .......................................................................................................... 111

v


Origens de migração ............................................................................................................... 112Conectividade de migração ....................................................................................................... 113no dispositivo ......................................................................................................................... 115

Considerações sobre os testes do plano de migração ........................................................... 115Testes de desempenho ............................................................................................................ 117Testes de failover ................................................................................................................... 117Recursos adicionais ................................................................................................................. 117

Segurança ...................................................................................................................................... 118Proteção de dados .................................................................................................................. 118

Criptografar dados em repouso do ..................................................................................... 119Criptografia de dados em trânsito ...................................................................................... 122Gerenciamento de chaves ................................................................................................ 128

Identity and Access Management .............................................................................................. 129Autenticação ................................................................................................................... 129Visão geral do gerenciamento de acesso ............................................................................ 130Gerenciamento do acesso usando políticas ......................................................................... 134Uso de políticas baseadas em identidade (políticas do IAM) .................................................. 134Referência de permissões da API do Amazon DocumentDB .................................................. 137

Gerenciamento de usuários do Amazon DocumentDB .................................................................. 142Usuário mestre e serviceadmin ..................................................................................... 142Criação de usuários adicionais .......................................................................................... 142Alteração automática de senhas ........................................................................................ 144

Controle de acesso com base em função ................................................................................... 144Conceitos do RBAC ........................................................................................................ 145Conceitos básicos do RBAC ............................................................................................. 146Conectar-se ao Amazon DocumentDB como um usuário ...................................................... 149Comandos comuns .......................................................................................................... 150Diferenças funcionais ...................................................................................................... 152Limites ........................................................................................................................... 152Funções integradas ......................................................................................................... 152

Registro e monitoramento ........................................................................................................ 157Updating Certificates ................................................................................................................ 158

Updating Your Application and Amazon DocumentDB Cluster ................................................ 158Troubleshooting .............................................................................................................. 160Frequently Asked Questions ............................................................................................. 160

Validação de conformidade ....................................................................................................... 166Resiliência .............................................................................................................................. 167Segurança da infraestrutura ...................................................................................................... 167Melhores práticas de segurança ................................................................................................ 168Auditoria de eventos ................................................................................................................ 168

Eventos com suporte ....................................................................................................... 169Ativação da auditoria ....................................................................................................... 170Desativação da auditoria .................................................................................................. 172Como acessar seus eventos de auditoria ............................................................................ 174

Backup e restauração ...................................................................................................................... 175Cópia de segurança e restauro: Conceitos .................................................................................. 175Noções básicas do uso do armazenamento de backup ................................................................ 176Despejo, restauração, importação e exportação de dados ............................................................ 177

mongodump ................................................................................................................... 178mongorestore ............................................................................................................. 178mongoexport ............................................................................................................... 179mongoimport ............................................................................................................... 179Tutorial ......................................................................................................................... 179

Considerações sobre snapshot de cluster ................................................................................... 181Armazenamento de backup .............................................................................................. 181Janela de backup ............................................................................................................ 182Backup Retention Period .................................................................................................. 182

vi


Comparação dos snapshots automáticos e manuais .................................................................... 183Criação de um snapshot manual de cluster ................................................................................ 184

Criar um snapshot de cluster usando a Console de gerenciamento da AWS ............................ 184Criar um snapshot de cluster usando a AWS CLI ................................................................ 185

Cópia de um snapshot de cluster .............................................................................................. 186Copiar snapshots compartilhados ...................................................................................... 187Cópia de snapshots entre regiões da AWS ......................................................................... 187Limitações: .................................................................................................................... 187Lidar com a criptografia .................................................................................................. 187Considerações sobre o grupo de parâmetros ..................................................................... 188Cópia de um snapshot de cluster ...................................................................................... 188

Compartilhamento de um snapshot de cluster ............................................................................ 192Compartilhamento de um snapshot criptografado ................................................................ 193Compartilhar um snapshot ................................................................................................ 195

Restauração de um snapshot de cluster ..................................................................................... 196Restaurar de um snapshot de cluster usando a Console de gerenciamento da AWS .................. 197Restaurar de um snapshot de cluster usando a AWS CLI ..................................................... 198

Restauração point-in-time ......................................................................................................... 201Restaurar para um point-in-time usando o Console de gerenciamento da AWS ........................ 201Restaurar para um point-in-time usando a AWS CLI ............................................................. 203

Exclusão de um snapshot de cluster .......................................................................................... 205Excluir um snapshot de cluster usando o Console de gerenciamento da AWS .......................... 205Excluir um snapshot de cluster usando o AWS CLI ............................................................. 206

Gerenciamento do Amazon DocumentDB ........................................................................................... 207Visão geral de tarefas operacionais ........................................................................................... 207

Adicionar uma réplica a um cluster do Amazon DocumentDB ................................................. 207Descrever clusters e instâncias ......................................................................................... 208Criação de um snapshot de cluster .................................................................................... 209Restauração a partir de um snapshot ................................................................................. 210Remoção de uma instância de um cluster ........................................................................... 211Exclusão de um cluster .................................................................................................... 211

Gerenciar clusters do ............................................................................................................... 212Noções básicas dos clusters ............................................................................................. 212Configurações do cluster .................................................................................................. 214Determinar o status de um cluster ..................................................................................... 215Ciclo de vida de clusters .................................................................................................. 216Dimensionar clusters do Amazon DocumentDB ................................................................... 244Noções básicas de tolerância a falhas ............................................................................... 246

Managing Instances ................................................................................................................. 247Managing Instance Classes .............................................................................................. 247Determining an Instance's Status ....................................................................................... 251Instance Lifecycle ............................................................................................................ 251

Gerenciamento de grupos de sub-redes do ................................................................................. 266Criação de um grupo de sub-redes .................................................................................... 267Como descrever um grupo de sub-redes ............................................................................ 271Como modificar um grupo de sub-redes ............................................................................. 273Exclusão de um grupo de sub-redes .................................................................................. 275

Alta disponibilidade e replicação ................................................................................................ 276Escalabilidade de leitura ................................................................................................... 276Alta disponibilidade .......................................................................................................... 276Como adicionar réplicas ................................................................................................... 277Failover ......................................................................................................................... 278Atraso de replicação ........................................................................................................ 281

Gerenciamento de eventos ....................................................................................................... 281Exibição de categorias de eventos ..................................................................................... 282Exibição de eventos do Amazon DocumentDB .................................................................... 284

Escolher regiões e zonas de disponibilidade ............................................................................... 286

vii


Disponibilidade da região ................................................................................................. 287Managing Cluster Parameter Groups ......................................................................................... 287

Describing Cluster Parameter Groups ................................................................................ 288Creating Cluster Parameter Groups ................................................................................... 293Modifying Cluster Parameter Groups .................................................................................. 295Modifying Clusters to Use Customized Cluster Parameter Groups ........................................... 298Copying Cluster Parameter Groups .................................................................................... 299Resetting Cluster Parameter Groups .................................................................................. 301Deleting Cluster Parameter Groups .................................................................................... 303Cluster Parameters Reference .......................................................................................... 305

Noções básicas sobre endpoints ............................................................................................... 312Localizar os endpoints de um cluster ................................................................................. 312Localizar o endpoint de uma instância ................................................................................ 314Conexão a endpoints ....................................................................................................... 316

Noções básicas de ARNs do Amazon DocumentDB ..................................................................... 317Criação de um ARN ........................................................................................................ 317Localizar um ARN ........................................................................................................... 319

Marcação de recursos ............................................................................................................. 321Visão geral de tags de recurso ......................................................................................... 321Restrições de tag ............................................................................................................ 322Adicionar ou atualizar tags ............................................................................................... 322Listar tags ...................................................................................................................... 323Remover tags ................................................................................................................. 324

Manutenção do Amazon DocumentDB ....................................................................................... 325Determinação de ações de manutenção pendentes .............................................................. 326Aplicação de atualizações ................................................................................................ 327Atualizações iniciadas pelo usuário .................................................................................... 329Gerenciamento de janelas de manutenção .......................................................................... 330

Noções básicas das funções vinculadas ao serviço ...................................................................... 331Permissões de função vinculada ao serviço ........................................................................ 332Criar uma função vinculada ao serviço ............................................................................... 333Modificar uma função vinculada ao serviço ......................................................................... 333Excluir uma função vinculada ao serviço ............................................................................ 333Regiões com suporte para funções vinculadas ao serviço Amazon DocumentDB ....................... 334

Monitoramento do Amazon DocumentDB ............................................................................................ 335Monitorar o status de um cluster ............................................................................................... 336

Valores de status do cluster ............................................................................................. 336Monitorar o status de um cluster usando o Console de gerenciamento da AWS ......................... 337Monitorar o status de um cluster usando a AWS CLI ............................................................ 337

Monitorar o status de uma instância .......................................................................................... 338Valores de status de instâncias ......................................................................................... 338Monitorar o status de uma instância usando o Console de gerenciamento da AWS .................... 340Monitoramento do status de uma instância usando a AWS CLI .............................................. 340

Monitoramento do Amazon DocumentDB com o CloudWatch ......................................................... 341Amazon DocumentDBMétricas do no ................................................................................. 341Visualização CloudWatch Dados ....................................................................................... 346Amazon DocumentDBDimensões de do ............................................................................. 350Contador de monitorização ............................................................................................... 350Monitorar conexões de banco de dados ............................................................................. 350

Registro em log de chamadas da API do Amazon DocumentDB com o CloudTrail ............................. 351Informações do Amazon DocumentDB no CloudTrail ............................................................ 351

Profiling Operations ................................................................................................................. 352Supported Operations ...................................................................................................... 352Limitations ...................................................................................................................... 353Enabling the Profiler ........................................................................................................ 353Disabling the Profiler ....................................................................................................... 356Disabling Profiler Logs Export ........................................................................................... 356

viii


Accessing Your Profiler Logs ............................................................................................ 358Common Queries ............................................................................................................ 358

Desenvolvimento com o Amazon DocumentDB .................................................................................... 360Conexão de forma programática ................................................................................................ 360

Como determinar o valor tls ........................................................................................... 360Conectar-se com o TLS habilitado ..................................................................................... 362Conectar-se com o TLS desabilitado .................................................................................. 371

Usar fluxos de alterações ......................................................................................................... 377Operações compatíveis .................................................................................................... 378Faturamento ................................................................................................................... 378Limitações ...................................................................................................................... 378Ativar fluxos de alterações ................................................................................................ 378Exemplo ........................................................................................................................ 380Pesquisa completa de documentos .................................................................................... 381Retomar um fluxo de alterações ........................................................................................ 381Modificação da duração da retenção do log do fluxo de alterações ......................................... 382

Conectar-se como um conjunto de réplicas ................................................................................. 384Usar conexões de cluster ................................................................................................. 386Vários grupos de conexões .............................................................................................. 387Summary ....................................................................................................................... 387

Conexão de fora de uma Amazon VPC ...................................................................................... 388Ligar utilizando Robo 3T .......................................................................................................... 389

Pré-requisitos: ................................................................................................................. 389Ligar com Robo 3T ......................................................................................................... 389

Ligar utilizando o Studio 3T ...................................................................................................... 392Pré-requisitos: ................................................................................................................. 389Ligar ao Studio 3T .......................................................................................................... 392

Conexão usando Amazon EC2 ................................................................................................. 398Prerequisites .................................................................................................................. 398Etapa 1 Criar um Amazon EC2 Instância ............................................................................ 399Etapa 2. Crie um grupo de segurança ................................................................................ 400Etapa 3 Criar um Amazon DocumentDB Cluster .................................................................. 400Etapa 4. Ligue-se ao seu Amazon EC2 instância ................................................................. 401Etapa 5. Instale o shell do mongo ..................................................................................... 402Etapa 6. Gerir Amazon DocumentDB SLT .......................................................................... 403Etapa 7. Ligue-se ao seu Amazon DocumentDB cluster ........................................................ 403Etapa 8 Inserir e consultar dados ........................................................................................ 44Etapa 9 Explorar ............................................................................................................. 405

Cotas e limites ................................................................................................................................ 406Tipos de instâncias do compatíveis ............................................................................................ 406Regiões do com suporte .......................................................................................................... 407Cotas regionais ....................................................................................................................... 407Limites de agregação .............................................................................................................. 409Limites de cluster .................................................................................................................... 409Limites de instâncias ............................................................................................................... 410Restrições de nomenclatura ...................................................................................................... 411Restrições de TTL ................................................................................................................... 412

Solução de problemas ..................................................................................................................... 413Problemas de ligação .............................................................................................................. 413

Não é possível ligar a um Amazon DocumentDB Parâmetro de avaliação ................................ 413Testar uma ligação a um Amazon DocumentDB Instância ..................................................... 415Conexão a um endpoint inválido ....................................................................................... 416

Criação de índice .................................................................................................................... 416Falha de compilação de índice .......................................................................................... 416O índice de antecedentes gera problemas e falha ............................................................... 417

Performance and Resource Utilization ........................................................................................ 417Find and Terminate Long Running or Blocked Queries .......................................................... 418

ix


See a Query Plan and Optimize a Query ............................................................................ 419List All Running Operations on an Instance ......................................................................... 420Know When a Query Is Making Progress ............................................................................ 422Determine Why a System Suddenly Runs Slowly ................................................................. 424Determine the Cause of High CPU Utilization ...................................................................... 425How Do I Determine the Open Cursors on an Instance? ....................................................... 425How do I Determine the Current Amazon DocumentDB Engine Version? .................................. 426How Do I Identify Unused Indexes? ................................................................................... 426How Do I Identify Missing Indexes? ................................................................................... 426Summary of Useful Queries .............................................................................................. 427

Referência de API de gerenciamento de recurso ................................................................................. 429Actions .................................................................................................................................. 429

AddTagsToResource ....................................................................................................... 431ApplyPendingMaintenanceAction ....................................................................................... 433CopyDBClusterParameterGroup ........................................................................................ 435CopyDBClusterSnapshot .................................................................................................. 437CreateDBCluster ............................................................................................................. 441CreateDBClusterParameterGroup ...................................................................................... 447CreateDBClusterSnapshot ................................................................................................ 449CreateDBInstance ........................................................................................................... 451CreateDBSubnetGroup ..................................................................................................... 455DeleteDBCluster .............................................................................................................. 457DeleteDBClusterParameterGroup ....................................................................................... 459DeleteDBClusterSnapshot ................................................................................................. 460DeleteDBInstance ............................................................................................................ 462DeleteDBSubnetGroup ..................................................................................................... 464DescribeCertificates ......................................................................................................... 466DescribeDBClusterParameterGroups .................................................................................. 468DescribeDBClusterParameters .......................................................................................... 470DescribeDBClusters ......................................................................................................... 472DescribeDBClusterSnapshotAttributes ................................................................................ 474DescribeDBClusterSnapshots ............................................................................................ 476DescribeDBEngineVersions ............................................................................................... 479DescribeDBInstances ....................................................................................................... 482DescribeDBSubnetGroups ................................................................................................ 484DescribeEngineDefaultClusterParameters ........................................................................... 486DescribeEventCategories .................................................................................................. 488DescribeEvents ............................................................................................................... 489DescribeOrderableDBInstanceOptions ................................................................................ 492DescribePendingMaintenanceActions ................................................................................. 494FailoverDBCluster ............................................................................................................ 496ListTagsForResource ....................................................................................................... 498ModifyDBCluster ............................................................................................................. 500ModifyDBClusterParameterGroup ....................................................................................... 505ModifyDBClusterSnapshotAttribute ..................................................................................... 507ModifyDBInstance ............................................................................................................ 509ModifyDBSubnetGroup ..................................................................................................... 513RebootDBInstance ........................................................................................................... 515RemoveTagsFromResource .............................................................................................. 517ResetDBClusterParameterGroup ........................................................................................ 519RestoreDBClusterFromSnapshot ........................................................................................ 521RestoreDBClusterToPointInTime ........................................................................................ 526StartDBCluster ................................................................................................................ 531StopDBCluster ................................................................................................................ 533

Data Types ............................................................................................................................ 534AvailabilityZone ............................................................................................................... 535Certificate ....................................................................................................................... 536

x


CloudwatchLogsExportConfiguration ................................................................................... 538DBCluster ...................................................................................................................... 539DBClusterMember ........................................................................................................... 544DBClusterParameterGroup ................................................................................................ 545DBClusterRole ................................................................................................................ 546DBClusterSnapshot ......................................................................................................... 547DBClusterSnapshotAttribute .............................................................................................. 550DBClusterSnapshotAttributesResult .................................................................................... 551DBEngineVersion ............................................................................................................ 552DBInstance ..................................................................................................................... 554DBInstanceStatusInfo ....................................................................................................... 558DBSubnetGroup .............................................................................................................. 559Endpoint ........................................................................................................................ 561EngineDefaults ................................................................................................................ 562Event ............................................................................................................................. 563EventCategoriesMap ........................................................................................................ 565Filter .............................................................................................................................. 566OrderableDBInstanceOption .............................................................................................. 567Parameter ...................................................................................................................... 569PendingCloudwatchLogsExports ........................................................................................ 571PendingMaintenanceAction ............................................................................................... 572PendingModifiedValues .................................................................................................... 574ResourcePendingMaintenanceActions ................................................................................ 577Subnet ........................................................................................................................... 578Tag ............................................................................................................................... 579UpgradeTarget ................................................................................................................ 580VpcSecurityGroupMembership ........................................................................................... 581

Common Errors ...................................................................................................................... 581Common Parameters ............................................................................................................... 583

Document History ............................................................................................................................ 585.................................................................................................................................................... dxci

xi

Amazon DocumentDB Guia do desenvolvedorVisão geral

O que é Amazon DocumentDB(compatibilidade com o MongoDB)?

Amazon DocumentDB (compatível com MongoDB) é um serviço de base de dados rápido, fiável etotalmente gerido. Amazon DocumentDB permite configurar, operar e dimensionar bases de dadoscompatíveis com mongodb na cloud. Com o Amazon DocumentDB, você pode executar o mesmo códigode aplicativo e usar os mesmos drivers e ferramentas que você usa com o MongoDB.

Antes de usar o Amazon DocumentDB, é necessário revisar os conceitos e recursos descritos em : Comoele funciona (p. 7). Depois disso, conclua as etapas em Guia de Introdução (p. 32).

Tópicos• Visão geral do Amazon DocumentDB (p. 1)• Clusters (p. 2)• Instances (p. 3)• Regiões e zonas de disponibilidade (p. 4)• Amazon DocumentDBDefinição de preço do (p. 5)• Monitoring (p. 6)• Interfaces (p. 6)• E o próximo? (p. 7)• Amazon DocumentDB: Como ele funciona (p. 7)• O que é um banco de dados de documentos? (p. 18)

Visão geral do Amazon DocumentDBA seguir estão alguns recursos de alto nível do Amazon DocumentDB:

• Amazon DocumentDBO aumenta automaticamente o tamanho do volume de armazenamento àmedida que as necessidades de armazenamento do seu banco de dados aumentam. Seu volumede armazenamento aumenta em incrementos de 10 GB, até um máximo de 64 TB. Você não precisaprovisionar nenhum armazenamento em excesso para o seu cluster para lidar com o crescimento futuro.

• Com Amazon DocumentDB, pode aumentar o rendimento de leitura para suportar pedidos de aplicaçõesde volumes elevados, criando até 15 réplica de instâncias. Amazon DocumentDB As réplicas partilhamo mesmo armazenamento subjacente, reduzindo os custos e evitando a necessidade de realizarpedidos nos nós de réplica. Esse recurso libera mais capacidade de processamento para atender àssolicitações de leitura e reduz a defasagem das réplicas para menos de 10 milissegundos— na maioriadas vezes. Você pode adicionar réplicas em minutos, independentemente do tamanho do volume dearmazenamento. O Amazon DocumentDB também fornece um endpoint do leitor, para que o aplicativopossa se conectar sem precisar rastrear as réplicas à medida que elas são adicionadas e removidas.

• Amazon DocumentDBO permite aumentar ou diminuir a escala dos recursos de computação e memóriapara cada uma das suas instâncias. As operações de escalabilidade de computação geralmente sãoconcluídas em poucos minutos.

1

Amazon DocumentDB Guia do desenvolvedorClusters

• Amazon DocumentDB corridas em Amazon Virtual Private Cloud (Amazon VPC), para que possa isolar asua base de dados na sua própria rede virtual. Você também pode definir configurações de firewall paracontrolar o acesso de rede ao cluster.

• Amazon DocumentDBO monitora continuamente a integridade e o progresso do cluster. Numa falhade instância, Amazon DocumentDB reinicia automaticamente a instância e os processos associados.Amazon DocumentDB não necessita de uma reprodução de recuperação de colisão de registos dereenchimento da base de dados, o que reduz significativamente os tempos de reinicialização. AmazonDocumentDB também isola a cache da base de dados do processo da base de dados, permitindo que acache sobreviva uma instância reinicie.

• Falha na instância, Amazon DocumentDB automatiza o failover até um máximo de 15 AmazonDocumentDB réplicas criadas noutras zonas de disponibilidade. Se não houver réplicas de fornecimentoe ocorrer uma falha, Amazon DocumentDB tenta criar um novo Amazon DocumentDB instânciaautomática.

• O recurso de backup do Amazon DocumentDB permite a recuperação point-in-time do cluster. Esserecurso permite que você restaure seu cluster para qualquer segundo dos últimos cinco minutos doperíodo de retenção. Você pode configurar o período de retenção de backup automático para até35 dias. As cópias de segurança automatizadas são guardadas em Amazon Simple Storage Service(Amazon S3), que foi concebido para uma durabilidade de 99,999999999%. Amazon DocumentDB ascópias de segurança são automáticas, incrementais e contínuas e não têm impacto no desempenho doseu grupo.

• Com o Amazon DocumentDB, você pode criptografar seus bancos de dados usando chaves que vocêcria e controla por meio do AWS Key Management Service (AWS KMS). Em um cluster de banco dedados em execução com a criptografia do Amazon DocumentDB, os dados armazenados em repousono armazenamento subjacente são criptografados. Os backups automatizados, snapshots e réplicas nomesmo cluster também são criptografados.

Se você ainda não estiver familiarizado com os serviços da AWS, use os seguintes recursos para sabermais:

• A AWS oferece serviços para computação, bancos de dados, armazenamento, análises e outrasfuncionalidades. Para obter uma descrição geral de todos os serviços AWS, consulte Computação emnuvem com serviços Amazon Web.

• A AWS fornece vários serviços de banco de dados. Para obter orientações sobre qual o melhor serviçopara o seu ambiente, consulte Bases de dados em AWS.

ClustersUm cluster consiste em 0 a 16 instâncias e um volume de armazenamento de grupo que gere os dadospara esses casos. Todas as gravações são feitas por meio da instância principal. Todas as instâncias(principais e de réplicas) são compatíveis com leituras. Os dados do cluster são armazenados no volumedo cluster com cópias em três zonas de disponibilidade diferentes.

2

https://aws.amazon.com/what-is-aws/

https://aws.amazon.com/what-is-aws/

https://aws.amazon.com/products/databases/

Amazon DocumentDB Guia do desenvolvedorInstances

InstancesUma instância do Amazon DocumentDB é um ambiente de banco de dados na nuvem. Uma instância podeconter vários bancos de dados criados pelo usuário. Você pode criar e modificar uma instância usando oConsole de gerenciamento da AWS ou a AWS CLI.

A capacidade de cálculo e memória de uma instância é determinada pelo seu classe de instância. Vocêpode selecionar a instância que melhor atenda às suas necessidades. Se suas necessidades mudaremcom o tempo, você poderá escolher uma classe de instância diferente. Para conhecer as especificações declasses de instância, consulte Instance Class Specifications (p. 250).

Amazon DocumentDB as ocorrências só são executadas no Amazon VPC ambiental. Amazon VPCpermite controlar o seu ambiente de rede virtual: Pode escolher o seu próprio intervalo de endereços IP,criar subredes e configurar listas de controlo de encaminhamento e acesso (acls).

Antes de criar instâncias do Amazon DocumentDB, é necessário criar um cluster para conter as instâncias.

Nem todas as classes de instância são suportadas em todas as regiões. A tabela a seguir mostra quaisclasses de instância são compatíveis em cada região.

Classes de instância compatíveis por região

Região R5 R4 T3

Leste dos EUA (Ohio) Compatível Compatível Compatível

Leste dos EUA (Norte daVirgínia)

Compatível Compatível Compatível

Oeste dos EUA (Oregon) Compatível Compatível Compatível

Ásia Pacífico (Mumbai) Compatível Compatível

Ásia-Pacífico (Seul) Compatível Compatível

Ásia-Pacífico (Sydney) Compatível Compatível

3

Amazon DocumentDB Guia do desenvolvedorRegiões e AZs

Região R5 R4 T3

Ásia-Pacífico (Cingapura) Compatível Compatível

Ásia-Pacífico (Tóquio) Compatível Compatível

Canadá (Central) Compatível Compatível

Europa (Frankfurt) Compatível Compatível

Europa (Irlanda) Compatível Compatível Compatível

Europa (Londres) Compatível Compatível

Europa (Paris) Compatível Compatível

AWS GovCloud (US) Compatível Compatível

Regiões e zonas de disponibilidadeRegiões e zonas de disponibilidade definem os locais físicos do seu cluster e instâncias.

RegionsOs recursos de computação em nuvem da AWS estão hospedados em instalações de datacenteraltamente disponíveis em diferentes áreas do mundo (por exemplo, América do Norte, Europa ou Ásia).Cada localização do centro de dados é chamada de Região.

Toda região da AWS é projetada para que fique completamente isolada das outras regiões da AWS.Dentro de cada região, há várias zonas de disponibilidade. Ao iniciar seus nós em diferentes zonasde disponibilidade, você é capaz de alcançar o máximo possível de tolerância a falhas. O diagrama aseguir mostra uma visualização de alto nível sobre como funcionam as regiões da AWS e as zonas dedisponibilidade.

Zonas de disponibilidadeCada região AWS contém várias localizações diferentes chamadas Zonas de disponibilidade. Além de serprojetada para ser isolada das falhas de outras zonas de disponibilidade, cada zona de disponibilidadefornece conectividade de rede de baixa latência e baixo custo para outras zonas de disponibilidade damesma região. Ao executar instâncias para um cluster em várias zonas de disponibilidade, você podeproteger seus aplicativos contra o evento improvável de falha de uma zona de disponibilidade.

A arquitetura do Amazon DocumentDB separa armazenamento e computação. Para a camadade armazenamento, o Amazon DocumentDB replica seis cópias de seus dados em três zonas de

4

Amazon DocumentDB Guia do desenvolvedorDefinição de preço

disponibilidade da AWS. Por exemplo, se você estiver executando um cluster do Amazon DocumentDB emuma região que ofereça suporte apenas a duas zonas de disponibilidade, seu armazenamento de dadosserá replicado de seis maneiras em três zonas de disponibilidade, mas suas instâncias de computaçãoestarão disponíveis somente em duas zonas de disponibilidade.

A tabela a seguir lista o número de zonas de disponibilidade que você pode usar em uma determinadaregião da AWS para provisionar instâncias de computação para seu cluster.

Nome da região Região Zonas de disponibilidade (computação)

Leste dos EUA (Ohio) us-east-2 3.

Leste dos EUA (Norteda Virgínia)

us-east-1 6.

Oeste dos EUA(Oregon)

us-west-2 4.

Ásia Pacífico (Mumbai) ap-south-1 3.

Ásia-Pacífico (Seul) ap-northeast-2 4.

Ásia-Pacífico(Cingapura)

ap-southeast-1 3.

Ásia-Pacífico (Sydney) ap-southeast-2 3

Ásia-Pacífico (Tóquio) ap-northeast-1 3

Canadá (Central) ca-central-1 3

Europa (Frankfurt) eu-central-1 3

Europa (Irlanda) eu-west-1 3

Europa (Londres) eu-west-2 3

Europa (Paris) eu-west-3 3

AWS GovCloud (US) us-gov-west-1 3

Amazon DocumentDBDefinição de preço doAmazon DocumentDB são facturados com base nos seguintes componentes. Amazon DocumentDB nãotem actualmente um nível gratuito, por isso, criar um grupo irá incorrer em custos.

• Horas de instância (por hora)—Com base na classe de instância da instância (por exemplo,db.r5.xlarge). A definição de preço está listada em uma base por hora, mas as faturas sãocalculadas em segundos e mostram o tempo no formato decimal. O uso do Amazon DocumentDB écobrado em incrementos de um segundo, com um mínimo de 10 minutos. Para obter mais informações,consulte Managing Instance Classes (p. 247).

• Pedidos de E/S (por 1 milhão de pedidos por mês) — Número total de pedidos de E/S dearmazenamento que faz num ciclo de faturação.

• Armazenamento da cópia de segurança (por gib por mês) — O armazenamento da cópia de segurançaé o armazenamento que está associado a cópias de segurança automáticas da base de dados e aquaisquer capturas de dados ativas que tenha tomado. Aumentar seu período de retenção de backup ou

5

Amazon DocumentDB Guia do desenvolvedorMonitoring

fazer snapshots de bancos de dados adicionais aumenta o armazenamento de backup utilizado por seubanco de dados. O armazenamento de backup é medido em GB-meses e por segundo não se aplica.Para obter mais informações, consulte Backup e restauração no Amazon DocumentDB (p. 175).

• Transferência de dados (por GB) — Transferência de dados dentro e fora da sua instância de ou para aInternet ou outras regiões AWS.

Para informações detalhadas, consulte Amazon DocumentDB (compatível com MongoDB) preços.

MonitoringExistem várias maneiras de controlar o desempenho e a integridade de uma instância. Você pode usar oserviço gratuito do Amazon CloudWatch para monitorar o desempenho e a integridade de uma instância.Pode encontrar gráficos de desempenho no Amazon DocumentDB consola. Você pode assinar eventosdo Amazon DocumentDB para obter notificações quando ocorrerem alterações em uma instância, umsnapshot, um grupo de parâmetros ou um grupo de segurança.

Para obter mais informações, consulte o seguinte: .

• Monitoramento do Amazon DocumentDB com o CloudWatch (p. 341)• Registro em log de chamadas da API do Amazon DocumentDB com o AWS CloudTrail (p. 351)

InterfacesExistem várias formas de interagir com Amazon DocumentDB, incluindo o Console de gerenciamento daAWS e o AWS CLI.

Console de gerenciamento da AWSO Console de gerenciamento da AWS é uma interface de usuário simples e baseada na Web. Você podegerenciar os clusters e as instâncias no console sem necessidade de programação. Para aceder aoAmazon DocumentDB consola, iniciar sessão no Console de gerenciamento da AWS e abra o AmazonDocumentDB a consola em https://console.aws.amazon.com/docdb.

AWS CLIPode utilizar o AWS Command Line Interface (AWS CLI) para gerir o seu Amazon DocumentDB clusters einstâncias. Com o mínimo de configuração, você pode começar a usar todas as funcionalidades fornecidaspelo console do Amazon DocumentDB do seu programa de terminal favorito.

• Para instalar o AWS CLI, consulte Instalar a interface da linha de comando AWS.• Para começar a utilizar o AWS CLI para Amazon DocumentDB, consulte Referência da interface da linha

de comandos AWS para Amazon DocumentDB.

O shell do MongoPara se conectar ao seu cluster para criar, ler, atualizar, excluir documentos nos bancos de dados, vocêpode usar o shell do mongo com o Amazon DocumentDB. Para fazer download e instalar o shell mongo3.6, consulte Passo 4: Instale o shell do mongo (p. 41).

6

https://aws.amazon.com/documentdb/pricing/

https://console.aws.amazon.com/docdb

https://docs.aws.amazon.com/cli/latest/userguide/installing.html

https://docs.aws.amazon.com/cli/latest/reference/docdb/index.html

https://docs.aws.amazon.com/cli/latest/reference/docdb/index.html

Amazon DocumentDB Guia do desenvolvedorDrivers do MongoDB

Drivers do MongoDBPara desenvolver e escrever aplicativos em um cluster do Amazon DocumentDB, você também pode usaros drivers do MongoDB com o .Amazon DocumentDB.

E o próximo?Na seção anterior, você conheceu os componentes de infraestrutura básicos que o Amazon DocumentDBoferece. O que você deve fazer em seguida? Dependendo de suas circunstâncias, consulte um dostópicos a seguir para começar.

• Comece a usar o Amazon DocumentDB criando um cluster e uma instância usando AWSCloudFormation Amazon DocumentDBInício rápido do usando o AWS CloudFormation (p. 46).

• Comece com Amazon DocumentDB criando um grupo e por exemplo utilizando as instruções na nossaGuia de Introdução (p. 32).

• Migre sua implementação do MongoDB para o Amazon DocumentDB usando as orientações em Migrarpara o Amazon DocumentDB (p. 103)

Amazon DocumentDB: Como ele funcionaAmazon DocumentDB (compatível com MongoDB)O é um serviço de banco de dados totalmentegerenciado compatível com o MongoDB. Com Amazon DocumentDB, pode executar o mesmo códigode aplicação e utilizar os mesmos controladores e ferramentas que utiliza com mongodb. AmazonDocumentDB é compatível com mongodb 3.6.

Tópicos• Amazon DocumentDBEndpoints do (p. 8)• TLS Support (p. 11)• Amazon DocumentDBArmazenamento do (p. 11)• Amazon DocumentDB Replicação (p. 12)• Amazon DocumentDBConfiabilidade do (p. 12)• Opções de preferência de leitura (p. 12)• Exclusões de TTL (p. 15)• Recursos facturáveis (p. 16)

Quando utiliza Amazon DocumentDB, começa por criar uma cluster. Um cluster consiste em zero ou maisinstâncias de banco de dados e em um volume de cluster que gerencia os dados para essas instâncias.Um Amazon DocumentDB volume de cluster é um volume de armazenamento de base de dados virtualque abrange várias zonas de disponibilidade. Cada zona de disponibilidade tem uma cópia de dados docluster.

Um cluster do Amazon DocumentDB consiste em dois componentes:

• Volume do cluster—Utiliza um serviço de armazenamento nativo da nuvem para replicar os dados seisformas em três Zonas de disponibilidade, proporcionando um armazenamento altamente duradouroe disponível. Um Amazon DocumentDB o cluster tem exatamente um volume de cluster, que podearmazenar até 64 TB de dados.

7

Amazon DocumentDB Guia do desenvolvedorAmazon DocumentDBEndpoints do

• Instâncias—Forneça a potência de processamento da base de dados, escreva dados e leia os dados dovolume de armazenamento do grupo. Um Amazon DocumentDB o cluster pode ter 0–16 instâncias.

Instâncias atendem a uma das duas funções:

• Instância primária—Suporta operações de leitura e escrita e executa todas as modificações de dados aovolume de cluster. Cada cluster do Amazon DocumentDB apresenta uma instância principal.

• Instância de réplica—Suporta apenas operações de leitura. Um Amazon DocumentDB o cluster pode teraté 15 réplicas para além da instância primária. Ter várias réplicas permite distribuir cargas de trabalhode leitura. Além disso, ao colocar réplicas em zonas de disponibilidade separadas, você tambémaumenta a disponibilidade do cluster.

O diagrama seguinte ilustra a relação entre o volume do grupo, a instância primária e as réplicas numAmazon DocumentDB grupo:

As instâncias de cluster não precisam ser da mesma classe de instância e podem ser provisionadas eencerradas conforme desejado. Essa arquitetura permite escalar a capacidade computacional do cluster,independentemente do armazenamento.

Quando o aplicativo grava dados na instância principal, ela executa uma gravação durável no volumedo cluster. Depois, replica o estado dessa escrita (não os dados) para cada réplica ativa. AmazonDocumentDB as réplicas não participam nos pedidos de processamento, e assim Amazon DocumentDBas réplicas são vantajosas para a escala de leitura. Leituras de Amazon DocumentDB as réplicas são, emúltima instância, consistentes com o atraso mínimo da réplica—normalmente menos de 100 milissegundosapós a instância primária escrever os dados. É garantido que as leituras das réplicas sejam lidas na ordemem que foram gravadas na instância principal. O atraso de réplica varia dependendo da taxa de alteraçãode dados, e períodos de alta atividade de gravação podem aumentar o atraso da réplica. Para obtermais informações, consulte as métricas do ReplicationLag em Amazon DocumentDBMétricas do no (p. 341).

Amazon DocumentDBEndpoints doAmazon DocumentDBO fornece várias opções de conexão para atender a uma ampla variedade de casosde uso. Para se conectar a uma instância em um cluster do Amazon DocumentDB, você especifica oendpoint da instância. Um endpoint é um endereço de host e um número de porta, separados por umcólon.

Recomendamos que a conexão com o cluster use o endpoint do cluster e o modo de conjunto de réplicas(consulte Conectar-se ao Amazon DocumentDB como um conjunto de réplicas (p. 384)), a menosque você tenha um caso de uso específico para a conexão com o endpoint de leitor ou um endpoint da

8


instância. Para rotear solicitações para suas réplicas, escolha uma configuração de preferência de leiturado driver que maximize a escalabilidade de leitura, sem deixar de atender aos requisitos de consistênciade leitura do aplicativo. A preferência de leitura secondaryPreferred permite leituras de réplica e liberaa instância primária para trabalhar mais.

Os seguintes parâmetros de avaliação estão disponíveis a partir de um Amazon DocumentDB grupo.

Endpoint de clusterO parâmetro de avaliação de cluster liga à instância principal atual do seu grupo. O endpoint do clusterpode ser usado para operações de leitura e gravação. Um cluster do Amazon DocumentDB temexatamente um endpoint de cluster.

O endpoint de cluster dá suporte a failover para conexões de leitura e gravação para o cluster. Se ainstância principal atual do cluster falhar e o cluster tiver pelo menos uma réplica de leitura ativa, oendpoint do cluster redirecionará automaticamente as solicitações de conexão para uma nova instânciaprincipal. Ao estabelecer a conexão com o cluster do Amazon DocumentDB, recomendamos que você useo endpoint do cluster e o modo de conjunto de réplicas (consulte Conectar-se ao Amazon DocumentDBcomo um conjunto de réplicas (p. 384)).

O seguinte é um exemplo Amazon DocumentDB parâmetro de avaliação de cluster:

sample-cluster.cluster-123456789012.us-east-1.docdb.amazonaws.com:27017

O exemplo a seguir é um exemplo de string de conexão utilizando esse endpoint de cluster:

mongodb://username:password@sample-cluster.cluster-123456789012.us-east-1.docdb.amazonaws.com:27017

Para obter informações sobre como localizar os endpoints de um cluster, consulte Localizar os endpointsde um cluster (p. 312).

Endpoint de leitorO parâmetro de avaliação do leitor carregar saldos só de leitura em todas as réplicas disponíveis no seugrupo. A tentativa de executar uma operação de gravação em uma conexão com o endpoint do leitorresulta em um erro. Um cluster do Amazon DocumentDB tem exatamente um endpoint de leitor.

Se o cluster contiver apenas uma instância (principal), o endpoint do leitor se conectará à instânciaprincipal. Quando você adicionar uma instância de réplica ao cluster do Amazon DocumentDB, o endpointdo leitor abrirá as conexões somente leitura para a nova réplica depois que ela estiver ativa.

O seguinte é um exemplo de um parâmetro de avaliação do leitor para um Amazon DocumentDB grupo:

sample-cluster.cluster-ro-123456789012.us-east-1.docdb.amazonaws.com:27017

O exemplo a seguir é um exemplo de string de conexão utilizando um endpoint de leitor:

mongodb://username:password@sample-cluster.cluster-ro-123456789012.us-east-1.docdb.amazonaws.com:27017

O endpoint do leitor balanceia a carga de conexões somente leitura, e não solicitações de leitura. Sealgumas conexões do endpoint de leitor forem mais utilizadas do que outras, suas solicitações deleitura poderão não ser igualmente equilibradas entre as instâncias do cluster. É recomendável distribuirsolicitações conectando-se ao endpoint do cluster como um conjunto de réplicas e utilizando a opção depreferência de leitura secondaryPreferred.

9


Para obter informações sobre como localizar os endpoints de um cluster, consulte Localizar os endpointsde um cluster (p. 312).

Endpoint de instânciaUm parâmetro de instância liga-se a uma instância específica no seu grupo. O endpoint da instância paraa instância principal atual pode ser usado para operações de leitura e gravação. No entanto, a tentativa deexecutar operações de gravação em um endpoint da instância para uma réplica de leitura resulta em umerro. Um cluster do Amazon DocumentDB tem um endpoint de instância por instância ativa.

Um endpoint de instância oferece controle direto sobre conexões para uma instância específica, paracenários nos quais o endpoint de cluster ou o endpoint de leitor talvez não seja apropriado. Um exemplode caso de uso é o provisionamento de uma carga de trabalho de análise periódica somente leitura. Vocêpode provisionar uma instância de réplica maior que o normal, conectar-se diretamente à nova instânciamaior com o endpoint da instância, executar as consultas analíticas e encerrar a instância. Usar o endpointda instância impede que o tráfego analítico cause impacto em outras instâncias do cluster.

O seguinte é um exemplo de avaliação para uma instância única num Amazon DocumentDB grupo:

sample-instance.123456789012.us-east-1.docdb.amazonaws.com:27017

O exemplo a seguir é um exemplo de string de conexão utilizando esse endpoint da instância:

mongodb://username:password@sample-instance.123456789012.us-east-1.docdb.amazonaws.com:27017

Note

A função de uma instância como principal ou de réplica pode mudar devido a um evento defailover. Os aplicativos nunca devem presumir que um endpoint de instância específico seja ainstância principal. Não recomendamos a conexão com endpoints de instância para aplicativosde produção. Em vez disso, recomendamos a conexão com o cluster usando o endpoint docluster e o modo de conjunto de réplicas (consulte Conectar-se ao Amazon DocumentDBcomo um conjunto de réplicas (p. 384)). Para obter mais controle avançado da prioridadede failover da instância, consulte Noções básicas de tolerância a falhas do cluster do AmazonDocumentDB (p. 246).

Para obter informações sobre como localizar os endpoints de um cluster, consulte Localizar o endpoint deuma instância (p. 314).

Modo de conjuntos de réplicasPode ligar-se ao seu Amazon DocumentDB parâmetro de avaliação do cluster no modo de definiçãode réplica especificando o nome do conjunto de réplica rs0. A ligação ao modo de definição de réplicapermite especificar as opções Ler Preocupação, Escrever Preocupação e Preferência de Leitura. Paraobter mais informações, consulte Consistência de leituras (p. 13).

O exemplo a seguir é de uma string de conexão conectando-se no modo de conjunto de réplicas:

mongodb://username:password@sample-cluster.cluster-123456789012.us-east-1.docdb.amazonaws.com:27017/?replicaSet=rs0

Quando você se conecta no modo de conjunto de réplicas, o cluster do Amazon DocumentDB aparecepara os seus drivers e clientes como um conjunto de réplicas. As instâncias adicionadas e removidas docluster do Amazon DocumentDB são refletidas automaticamente na configuração do conjunto de réplicas.

10

Amazon DocumentDB Guia do desenvolvedorTLS Support

Cada Amazon DocumentDB o grupo consiste numa única réplica definida com o nome predefinido rs0.Não é possível modificar o nome do conjunto de réplica.

A conexão ao endpoint do cluster no modo de conjunto de réplicas é o método recomendado para usogeral.

Note

Todas as instâncias em um cluster do Amazon DocumentDB atendem a mesma porta TCP paraconexões.

TLS SupportPara obter mais detalhes sobre a conexão ao Amazon DocumentDB usando o Transport Layer Security(TLS), consulte Criptografia de dados em trânsito (p. 122).

Amazon DocumentDBArmazenamento doAmazon DocumentDB os dados são armazenados num volume de cluster, que é um volume único e virtualque utiliza unidades de estado sólido (ssds). Um volume de cluster consiste em seis cópias dos dados, quesão replicados automaticamente em diversas zonas de disponibilidade em uma única região da AWS. Essareplicação ajuda a garantir que seus dados sejam resilientes, com menor possibilidade de perda de dados.Isso também ajuda a garantir que o cluster esteja mais disponível durante um failover, pois as cópias dosdados já existem em outras zonas de disponibilidade. Estas cópias podem continuar a servir pedidos dedados para as instâncias na sua Amazon DocumentDB grupo.

Como o armazenamento de dados do é faturadoAmazon DocumentDBO aumenta automaticamente o tamanho de um volume de cluster à medidaque a quantidade de dados aumenta. Um Amazon DocumentDB o volume de cluster pode cresceraté um tamanho máximo de 64 joules; no entanto, só é cobrado pelo espaço que utiliza num AmazonDocumentDB volume de cluster. Quando os dados do Amazon DocumentDB são removidos, como pormeio do descarte de uma tabela ou partição, o espaço total alocado permanece o mesmo. O espaço livre éreutilizado automaticamente quando o volume de dados aumenta no futuro.

Note

Como os custos de armazenamento são baseados no nível mais alto da marca d'água doarmazenamento (o valor máximo que foi alocado para o cluster do Amazon DocumentDB emqualquer momento), você pode gerenciar os custos evitando as práticas de ETL que criamgrandes volumes de informação temporária ou que carregam grandes volumes de dados novosantes de remover os dados antigos desnecessários.

Se remover dados de um Amazon DocumentDB o cluster resulta numa quantidade substancial de espaçoatribuído mas não utilizado, reiniciando a marca de água elevada que requer uma descarga de dadoslógicos e retendo a sua restauração para um novo grupo, utilizando uma ferramenta como mongodump oumongorestore. Criar e restaurar um instantâneo faz não reduzir o armazenamento atribuído porque adisposição física do armazenamento subjacente permanece igual no instantâneo restaurado.

Note

Utilizar utilitários como mongodump e mongorestore encargos de I/O incorridos com base nostamanhos dos dados que estão a ser lidos e escritos no volume de armazenamento.

Para informações sobre Amazon DocumentDB armazenamento de dados e preços de E/S, consulteAmazon DocumentDB (compatível com MongoDB) preços e Perguntas mais frequentes sobre preços.

11

https://aws.amazon.com/documentdb/pricing

https://aws.amazon.com/documentdb/faqs/#Pricing

Amazon DocumentDB Guia do desenvolvedorAmazon DocumentDB Replicação

Amazon DocumentDB ReplicaçãoEm um cluster do Amazon DocumentDB, cada instância de réplica expõe um endpoint independente.Esses endpoints de réplica fornecem acesso somente leitura aos dados no volume do cluster. Elespermitem escalar a carga de trabalho de leitura para os dados em várias instâncias replicadas. Tambémajudam a melhorar o desempenho das leituras de dados e aumentam a disponibilidade dos dados noseu Amazon DocumentDB grupo. Amazon DocumentDB as réplicas também são alvos de ativação e sãorapidamente promovidos se a instância principal para o seu Amazon DocumentDB falha do cluster.

Amazon DocumentDBConfiabilidade doAmazon DocumentDBO foi projetado para ser confiável, durável e tolerante a falhas. (Para melhorar adisponibilidade, deve configurar o seu Amazon DocumentDB para que tenha várias instâncias de réplicaem diferentes zonas de disponibilidade.) Amazon DocumentDB inclui várias funcionalidades automáticasque fazem dela uma solução de base de dados fiável.

Reparo automático de armazenamentoAmazon DocumentDB mantém múltiplas cópias dos seus dados em três Zonas de disponibilidade,reduzindo significativamente a probabilidade de perder dados devido a uma falha de armazenamento.Amazon DocumentDB deteta automaticamente falhas no volume do cluster. Quando um segmento deum volume de cluster falha, o Amazon DocumentDB repara imediatamente o segmento. Ele usa osdados dos outros volumes que compõem o volume do cluster para ajudar a garantir que os dados nosegmento reparado sejam atuais. Como resultado, o Amazon DocumentDB evita a perda de dados e reduza necessidade de executar uma restauração pontual para recuperação de uma falha de instância.

Aquecimento de cache possível de recuperarAmazon DocumentDBO gerencia seu cache de páginas em um processo separado do banco de dados,de modo que o cache de páginas possa sobreviver independentemente do banco de dados. No eventoimprovável de uma falha no banco de dados, o cache da página permanece na memória. Isso garante queo grupo de buffers seja aquecido com o estado mais atual quando o banco de dados é reiniciado.

Recuperação de falhaAmazon DocumentDB foi concebido para recuperar de um acidente quase instantaneamente e continuara servir os dados da sua aplicação. Amazon DocumentDB executa a recuperação de falhas de formaassíncrona em fios paralelos, de modo a que a sua base de dados esteja aberta e disponível quaseimediatamente após um acidente.

Opções de preferência de leituraAmazon DocumentDB utiliza um serviço de armazenamento partilhado nativo da nuvem que replica osdados seis vezes em três zonas de disponibilidade para proporcionar níveis elevados de durabilidade.Amazon DocumentDB não depende de replicar dados para várias instâncias para alcançar a durabilidade.Os dados do cluster são duráveis, quer contenham uma única instância ou 15 instâncias.

Durabilidade de gravaçãoAmazon DocumentDBO usa um sistema de armzenamento exclusivo, distribuído, tolerante a falhas ede recuperação automática. Esse sistema replica seis cópias (V = 6) dos seus dados em três zonas dedisponibilidade da AWS para fornecer alta disponibilidade e durabilidade. Ao gravar dados, o AmazonDocumentDB garante que todas as gravações sejam gravadas de forma durável na maioria dos nós antesde confirmar a gravação para o cliente. Se você estiver executando um conjunto de réplicas do MongoDB

12

Amazon DocumentDB Guia do desenvolvedorOpções de preferência de leitura

de três nós, o uso de uma Write Concern de {w:3, j:true} produzirá a melhor configuração possívelem comparação com o Amazon DocumentDB.

Escreve para um Amazon DocumentDB o cluster tem de ser processado pela instância do escritorde grupo. Tentar escrever num leitor resulta num erro. Um comentário reconhecido de um AmazonDocumentDB a instância principal é duradoura e não pode ser enrolada. Amazon DocumentDB éaltamente durável por predefinição e não suporta uma opção de escrita não duradoura. Não é possívelmodificar o nível de durabilidade (ou seja, escreva a preocupação). Amazon DocumentDB ignora w=algo eé eficaz: 3 e j: verdadeiro. O seu corte é reduzido.

Devido à separação de armazenamento e computação na arquitetura do Amazon DocumentDB, um clustercom uma única instância é resiliente. A durabilidade é processada na camada de armazenamento. Comoresultado, um cluster do Amazon DocumentDB com uma única instância e um com três instâncias alcançao mesmo nível de durabilidade. Você pode configurar o cluster para seu caso de uso específico e, aomesmo tempo, proporcionar resiliência aos seus dados.

As gravações em um cluster do Amazon DocumentDB são atômicas em um único documento.

Amazon DocumentDB não suporta o wtimeout e não devolverá um erro se for especificado um valor.É garantido que as gravações na instância principal do Amazon DocumentDB não sejam bloqueadasindefinidamente.

Isolamento de leituraAs leituras de uma instância do Amazon DocumentDB retornam apenas dados que sejam duráveis antesdo início da consulta. As leituras nunca retornam dados modificados depois que a consulta começa aexecução, nem as leituras contaminadas são possíveis sob qualquer circunstância.

Consistência de leiturasOs dados lidos em um cluster do Amazon DocumentDB são duráveis e não serão revertidos. Podemodificar a consistência de leitura para Amazon DocumentDB lê especificando a preferência de leiturapara o pedido ou ligação. Amazon DocumentDB não suporta uma opção de leitura não duradoura.

As leituras a partir de uma instância principal do cluster do Amazon DocumentDB são altamenteconsistentes em condições operacionais normais e consistência de leitura após gravação. Se ocorrer umevento de failover entre a leitura e a gravação subsequentes, o sistema poderá retornar em breve umaleitura que não seja altamente consistente. Todas as leituras a partir de uma réplica de leitura são, por fim,consistentes e retornam os dados na mesma ordem e, geralmente, com atraso de replicação inferior a 100ms.

Amazon DocumentDBPreferências de leitura doAmazon DocumentDBO oferece suporte à configuração de uma opção de preferência de leitura apenasao ler dados do endpoint do cluster no modo de conjunto de réplicas. Definir uma opção de preferênciade leitura afecta a forma como o cliente mongodb ou o motorista encaminha pedidos para instâncias noseu Amazon DocumentDB grupo. Você pode definir opções de preferência de leitura para uma consultaespecífica ou como uma opção geral no driver do MongoDB. (Consulte a documentação do cliente ou dodriver para obter instruções sobre como definir uma opção de preferência de leitura.)

Se o cliente ou o driver não estiver se conectando a um endpoint de cluster do Amazon DocumentDB nomodo de conjunto de réplicas, o resultado da especificação de uma preferência de leitura será indefinido.

Amazon DocumentDB não suporta a definição conjuntos de etiquetas como uma preferência de leitura.

Opções de preferência de leitura compatíveis

• primary— a especificação de uma preferência de leitura primary ajuda a garantir que todas asleituras sejam encaminhadas para a instância principal do cluster. Se a instância principal estiver

13

Amazon DocumentDB Guia do desenvolvedorOpções de preferência de leitura

indisponível, a operação de leitura falhará. Uma preferência de leitura primary produz a consistênciade leitura após gravação e é apropriada para casos de uso que priorizam a consistência de leitura apósgravação em alta disponibilidade e escalabilidade de leitura.

O exemplo seguinte especifica um primary preferência de leitura:

db.example.find().readPref('primary')

• primaryPreferred— a especificação de rotas de preferência de leitura primaryPreferred lê

para a instância principal em operação normal. Se houver um failover principal, o cliente encaminharásolicitações para uma réplica. Uma preferência de leitura primaryPreferred produz consistênciade leitura após gravação durante a operação normal e leituras eventualmente consistentes durante umevento de failover. Uma preferência de leitura primaryPreferred é apropriada para casos de uso quepriorizam a consistência de leitura após gravação em escalabilidade de leitura, mas ainda exigem altadisponibilidade.

O exemplo seguinte especifica um primaryPreferred preferência de leitura:

db.example.find().readPref('primaryPreferred')

• secondary— a especificação de uma preferência de leitura secondary garante que as leituras sejam

encaminhadas apenas para uma réplica, nunca para a instância principal. Se não houver instânciasde réplica em um cluster, a solicitação de leitura falhará. Uma preferência de leitura secondaryproduz leituras eventualmente consistentes e é apropriada para casos de uso que priorizam a taxa detransferência de gravação da instância principal em alta disponibilidade e consistência de leitura apósgravação.

O exemplo seguinte especifica um secondary preferência de leitura:

db.example.find().readPref('secondary')

• secondaryPreferred— a especificação de uma preferência de leitura secondaryPreferred

garante que as leituras sejam encaminhadas para uma réplica de leitura quando uma ou mais réplicasestiverem ativas. Se não houver instâncias de réplica ativas em um cluster, a solicitação de leitura seráencaminhada para a instância principal. Uma preferência de leitura secondaryPreferred produzleituras eventualmente consistentes quando a leitura é atendida por uma réplica de leitura. Ela produzconsistência de leitura após gravação quando a leitura é atendida pela instância principal (excetoeventos de failover). Uma preferência de leitura secondaryPreferred é apropriada para casos deuso que priorizam a escalabilidade de leitura e a alta disponibilidade sobre a consistência de leitura apósgravação.

O exemplo seguinte especifica um secondaryPreferred preferência de leitura:

db.example.find().readPref('secondaryPreferred')

• nearest—Especificar uma nearest ler as rotas de preferência com base apenas na latência medida

entre o cliente e todas as instâncias no Amazon DocumentDB grupo. Uma preferência de leituranearest produz leituras eventualmente consistentes quando a leitura é atendida por uma réplica deleitura. Ela produz consistência de leitura após gravação quando a leitura é atendida pela instânciaprincipal (exceto eventos de failover). Uma preferência de leitura nearest é apropriada para casos de

14

Amazon DocumentDB Guia do desenvolvedorExclusões de TTL

uso que priorizam alcançar a menor latência de leitura e alta disponibilidade sobre a consistência deleitura após gravação e escalabilidade de leitura.

O exemplo seguinte especifica um nearest preferência de leitura:

db.example.find().readPref('nearest')

Alta disponibilidadeAmazon DocumentDBO oferece suporte a configurações de cluster altamente disponíveis usando réplicascomo destinos de failover para a instância principal. Se a instância principal falhar, uma réplica do AmazonDocumentDB será promovida como a nova principal, com uma breve interrupção durante a qual assolicitações de leitura e gravação feitas na instância principal falham com uma exceção.

Se o cluster do Amazon DocumentDB não incluir réplicas, a instância principal será recriada durante umafalha. No entanto, promover uma réplica do Amazon DocumentDB é muito mais rápido do que recriar ainstância primária. Portanto, recomendamos que você crie uma ou mais réplicas do Amazon DocumentDBcomo destinos de failover.

As réplicas que devem ser usadas como destinos de failover devem ser da mesma classe de instânciada instância principal. Elas devem ser provisionadas em zonas de disponibilidade diferentes da principal.Você pode controlar quais réplicas são preferenciais como destinos de failover. Para obter as melhorespráticas sobre como configurar o Amazon DocumentDB para alta disponibilidade, consulte Noções básicasde tolerância a falhas do cluster do Amazon DocumentDB (p. 246).

Leituras de escalabilidadeAmazon DocumentDBAs réplicas do são ideais para escalabilidade de leitura. Elas são totalmentededicadas a operações de leitura no volume de cluster, ou seja, as réplicas não processam gravações. Areplicação de dados acontece dentro do volume de cluster e não entre as instâncias. Portanto, os recursosde cada réplica são dedicados ao processamento de consultas, e não às replicações e gravações dedados.

Se o aplicativo precisar de mais capacidade de leitura, você poderá adicionar uma réplica ao clusterrapidamente (geralmente em menos de dez minutos). Se os requisitos de capacidade de leituradiminuírem, você poderá remover as réplicas desnecessárias. Com as réplicas do Amazon DocumentDB,você paga apenas pela capacidade de leitura de que precisa.

Amazon DocumentDBO oferece suporte a escalabilidade de leitura do lado do cliente por meiodo uso de opções de preferência de leitura. Para obter mais informações, consulte AmazonDocumentDBPreferências de leitura do (p. 13).

Exclusões de TTLAs exclusões de uma área de índice TTL alcançada por meio de um processo em segundo plano são omelhor esforço e não são garantidas dentro de um período de tempo específico. Fatores como tamanho deinstância, utilização de recursos da instância, tamanho do documento e taxa de transferência geral podemafetar a sincronização de uma exclusão de TTL.

Quando o monitor TTL exclui seus documentos, cada exclusão resulta em custos de E/S, o que aumentarásua fatura. Se as taxas de taxa de transferência e de exclusão de TTL aumentarem, espere um aumentoem sua fatura devido ao aumento no uso de E/S.

Quando cria um índice TTL numa recolha existente, tem de eliminar todos os documentos expirados antesde criar o índice. A implementação atual do TTL é optimizada para eliminar uma pequena fracção dedocumentos na coleção, que é típica se TTL estivesse ativado na coleção desde o início e pode resultar

15

Amazon DocumentDB Guia do desenvolvedorRecursos facturáveis

em IOPS mais elevadas do que o necessário se for necessário eliminar um grande número de documentosde uma só vez.

Se não pretender criar um índice TTL para eliminar documentos, pode, em vez disso, segmentardocumentos em recolhas com base no tempo e simplesmente deixar essas colecções quando osdocumentos já não forem necessários. Por exemplo: pode criar uma recolha por semana e largando-a semincorrer custos IO. Isto pode ser significativamente mais rentável do que utilizar um índice TTL.

Recursos facturáveisIdentificar faturável Amazon DocumentDB RecursosComo um serviço de banco de dados gerenciado, o Amazon DocumentDB cobra por instâncias,armazenamento, E/Ss, backups e transferência de dados. Para mais informações, consulte AmazonDocumentDB (compatível com MongoDB) preços.

Para descobrir recursos faturáveis em sua conta e possivelmente excluir os recursos, você pode usar oConsole de gerenciamento da AWS ou a AWS CLI.

Uso do Console de gerenciamento da AWS

Utilizar o Console de gerenciamento da AWS, pode descobrir Amazon DocumentDB clusters, instâncias einstantâneos que tenha provisionado para uma determinada região AWS.

Para descobrir clusters, instâncias e snapshots

1. Faça login no Console de gerenciamento da AWS e abra o console do Amazon DocumentDB emhttps://console.aws.amazon.com/docdb.

2. Para descobrir recursos faturáveis em uma região diferente de sua região padrão, no canto superiordireito da tela, escolha a região da AWS na qual você deseja pesquisar.

3. No painel de navegação, escolha o tipo de recurso facturável que está interessado em: Clusters,Instâncias, ou Instantâneos.

4. Todos os seus clusters provisionados, instâncias ou snapshots para a região são listados no paineldireito. Você será cobrado por clusters, instâncias e snapshots.

Uso do AWS CLI

Utilizar o AWS CLI, pode descobrir Amazon DocumentDB clusters, instâncias e instantâneos que tenhaprovisionado para uma determinada região AWS.

16




Amazon DocumentDB Guia do desenvolvedorRecursos facturáveis

Para descobrir clusters e instâncias

O código a seguir lista todos os clusters e instâncias para a região especificada. Se quiser pesquisarconjuntos e instâncias na sua Região predefinida, pode omitir o --region parâmetro.

Example

Para Linux, macOS ou Unix:

aws docdb describe-db-clusters \ --region us-east-1 \ --query 'DBClusters[?Engine==`docdb`]' | \ grep -e "DBClusterIdentifier" -e "DBInstanceIdentifier"

Para Windows:

aws docdb describe-db-clusters ^ --region us-east-1 ^ --query 'DBClusters[?Engine==`docdb`]' | ^ grep -e "DBClusterIdentifier" -e "DBInstanceIdentifier"

A saída dessa operação é semelhante à seguinte.

"DBClusterIdentifier": "docdb-2019-01-09-23-55-38", "DBInstanceIdentifier": "docdb-2019-01-09-23-55-38", "DBInstanceIdentifier": "docdb-2019-01-09-23-55-382","DBClusterIdentifier": "sample-cluster","DBClusterIdentifier": "sample-cluster2",

Para descobrir snapshots

O código a seguir lista todos os snapshots para a região especificada. Se quiser procurar instantâneos nasua Região predefinida, pode omitir o --region parâmetro.


aws docdb describe-db-cluster-snapshots \ --region us-east-1 \ --query 'DBClusterSnapshots[?Engine==`docdb`].[DBClusterSnapshotIdentifier,SnapshotType]'

Para Windows:

aws docdb describe-db-cluster-snapshots ^ --region us-east-1 ^ --query 'DBClusterSnapshots[?Engine==`docdb`].[DBClusterSnapshotIdentifier,SnapshotType]'


[ [ "rds:docdb-2019-01-09-23-55-38-2019-02-13-00-06", "automated" ], [ "test-snap", "manual" ]]

17

Amazon DocumentDB Guia do desenvolvedorO que é um banco de dados de documentos?

Só tem de eliminar manual instantâneos. Automated as capturas são eliminadas quando eliminar ogrupo.

Exclusão de recursos faturáveis indesejadosPara excluir um cluster, primeiro exclua todas as instâncias no cluster.

• Para excluir instâncias, consulte Deleting an Amazon DocumentDB Instance (p. 263).Important

Mesmo se você excluir as instâncias em um cluster, você ainda será cobrado pelo uso dearmazenamento e backup associado a esse cluster. Para interromper todas as cobranças, vocêtambém deverá excluir seu cluster e snapshots manuais.

• Para excluir clusters, consulte Excluir um cluster do Amazon DocumentDB (p. 240).• Para excluir snapshots manuais, consulte Exclusão de um snapshot de cluster (p. 205).

O que é um banco de dados de documentos?Alguns desenvolvedores não pensam em seu modelo de dados em termos de linhas e colunasnormalizadas. Normalmente, na camada do aplicativo, os dados são representados como um documentoJSON, pois é mais intuitivo para os desenvolvedores pensarem em seu modelo de dados como umdocumento.

A popularidade dos bancos de dados de documentos cresceu porque eles permitem que você mantenha apersistência dos dados em um banco de dados usando o mesmo formato de modelo de documento usadono código do aplicativo. Os bancos de dados de documentos fornecem APIs poderosas e intuitivas paradesenvolvimento flexível e ágil.

Tópicos• Casos de uso do banco de dados de documentos (p. 18)• Noções básicas sobre documentos (p. 19)• Como trabalhar com documentos (p. 23)

Casos de uso do banco de dados de documentosSeu caso de uso indica se você precisa de um banco de dados de documentos ou algum outro tipo debanco de dados para gerenciar os dados. Os bancos de dados de documentos são úteis para cargas detrabalho que exigem um esquema flexível para desenvolvimento rápido e iterativo. A seguir estão algunsexemplos de casos de uso para os quais os bancos de dados de documentos podem fornecer vantagenssignificativas:

Tópicos• Perfis de usuário (p. 18)• Big Data em tempo real (p. 19)• Gerenciamento de conteúdo (p. 19)

Perfis de usuárioComo os bancos de dados de documentos têm um esquema flexível, eles podem armazenar documentoscom atributos e valores de dados diferentes. Os bancos de dados de documentos são uma soluçãoprática para perfis online nos quais usuários diferentes fornecem tipos de informações diferentes. Usando

18

Amazon DocumentDB Guia do desenvolvedorNoções básicas sobre documentos

um banco de dados de documentos, você pode armazenar o perfil de cada usuário de forma eficiente,armazenando apenas os atributos específicos de cada usuário.

Suponha que um usuário opte por adicionar ou remover informações do perfil. Nesse caso, o documentopode ser facilmente substituído por uma versão atualizada que contenha quaisquer atributos e dadosadicionados recentemente ou que omita quaisquer atributos e dados omitidos recentemente. Os bancos dedados de documentos gerenciam facilmente esse nível de individualidade e fluidez.

Big Data em tempo realHistoricamente, a capacidade de extrair informações de dados operacionais era dificultada pelo fato de quebancos de dados operacionais e bancos de dados analíticos eram mantidos em diferentes ambientes—operacional e de negócios/relatórios, respectivamente. A capacidade de extrair informações operacionaisem tempo real é fundamental em um ambiente de negócios altamente competitivo. Ao usar bancosde dados de documentos, uma empresa pode armazenar e gerenciar dados operacionais de qualquerorigem e, simultaneamente, alimentar os dados para o mecanismo de BI escolhido para análise. Não hánecessidade de ter dois ambientes.

Gerenciamento de conteúdoPara gerenciar o conteúdo com eficiência, é necessário coletar e agregar o conteúdo de várias fontes e,em seguida, enviá-lo ao cliente. Devido ao esquema flexível, os bancos de dados de documentos sãoperfeitos para coletar e armazenar qualquer tipo de dados. Você pode usá-los para criar e incorporar novostipos de conteúdo, incluindo conteúdo gerado pelo usuário, como imagens, comentários e vídeos.

Noções básicas sobre documentosOs bancos de dados de documentos são usados para armazenar dados semiestruturados como umdocumento — em vez de normalizar dados em várias tabelas, cada uma com uma estrutura única efixa, como em um banco de dados relacional. Os documentos armazenados em um banco de dadosde documentos usam pares de chave/valor aninhados para fornecer a estrutura ou o esquema dodocumento. No entanto, diferentes tipos de documentos podem ser armazenados no mesmo bancode dados de documentos, atendendo assim ao requisito de processamento de dados semelhantes emformatos diferentes. Por exemplo, como cada documento é autodescritivo, os documentos codificadosem JSON de uma loja online descritos no tópico Exemplo de documentos em um banco de dados dedocumentos (p. 21) podem ser armazenados no mesmo banco de dados de documentos.

Tópicos• Os tamanhos de volumes SQL Terminologia não relacional (p. 19)• Documentos simples (p. 20)• Documentos incorporados (p. 20)• Exemplo de documentos em um banco de dados de documentos (p. 21)• Noções básicas sobre normalização em um banco de dados de documentos (p. 22)

Os tamanhos de volumes SQL Terminologia não relacionalA tabela a seguir compara a terminologia usada pelos bancos de dados de documentos (MongoDB) com aterminologia usada pelos bancos de dados SQL.

SQL MongoDB

Tabela Coleta

Linha Documento

19


SQL MongoDB

Coluna Campo

Chave primária ObjectId

Índice Índice

Visualizar Visualizar

Tabela ou objeto aninhado Documento incorporado

Array Array

Documentos simplesTodos os documentos em um banco de dados de documentos são autodescritivos. Esta documentaçãousa documentos formatados como JSON, embora você possa usar outros meios de codificação.

Um documento simples tem um ou mais campos que estão todos no mesmo nível no documento. Noexemplo a seguir, os campos SSN, LName, FName, DOB, Street, City, State-Province, PostalCodee Country são todos irmãos no documento.

{ "SSN": "123-45-6789", "LName": "Rivera", "FName": "Martha", "DOB": "1992-11-16", "Street": "125 Main St.", "City": "Anytown", "State-Province": "WA", "PostalCode": "98117", "Country": "USA"}

Quando as informações são organizadas em um documento simples, cada campo é gerenciadoindividualmente. Para recuperar o endereço de uma pessoa, é necessário recuperar Street, City,State-Province, PostalCode e Country como itens de dados individuais.

Documentos incorporadosUm documento complexo organiza os dados criando documentos incorporados no documento.Documentos incorporados ajudam a gerenciar dados em agrupamentos e como itens de dados individuais,o que for mais eficiente em um determinado caso. Usando o exemplo anterior, você poderia incorporar umdocumento Address no documento principal. Isso resulta na estrutura do documento a seguir:

{ "SSN": "123-45-6789", "LName": "Rivera", "FName": "Martha", "DOB": "1992-11-16", "Address": { "Street": "125 Main St.", "City": "Anytown", "State-Province": "WA", "PostalCode": "98117", "Country": "USA" }

20


}

Agora, você pode acessar os dados no documento como campos individuais ( "SSN": ), como umdocumento incorporado ( "Address": ) ou como membro de um documento incorporado ( "Address":{"Street":} ).

Exemplo de documentos em um banco de dados de documentosComo afirmado anteriormente, como cada documento em um banco de dados de documentos éautodescritivo, a estrutura dos documentos em um banco de dados de documentos pode ser diferente. Osdois documentos seguintes, um de um livro e o outro de um periódico, são estruturalmente diferentes. Noentanto, ambos podem estar no mesmo banco de dados de documentos.

Veja a seguir um exemplo de documento de livro:

{ "_id" : "9876543210123", "Type": "book", "ISBN": "987-6-543-21012-3", "Author": { "LName":"Roe", "MI": "T", "FName": "Richard" }, "Title": "Understanding Document Databases"}

Veja a seguir um exemplo de documento de periódico com dois artigos:

{ "_id" : "0123456789012", "Publication": "Programming Today", "Issue": { "Volume": "14", "Number": "09" }, "Articles" : [ { "Title": "Is a Document Database Your Best Solution?", "Author": { "LName": "Major", "FName": "Mary" } }, { "Title": "Databases for Online Solutions", "Author": { "LName": "Stiles", "FName": "John" } } ], "Type": "periodical"}

Compare a estrutura desses dois documentos. Com um banco de dados relacional, você precisa detabelas de "periódico" e de "livros" separadas ou de uma única tabela com campos não utilizados, como

21


"Publicação", "Problema", "Artigos" e "MI", como valores null. Como os bancos de dados de documentossão semiestruturados, com cada documento definindo a própria estrutura, esses dois documentos podemcoexistir no mesmo banco de dados de documentos sem campos null. Bancos de dados de documentossão ideais para lidar com dados esparsos.

O desenvolvimento em um banco de dados de documentos permite um desenvolvimento rápido einterativo. Isso ocorre porque você pode alterar a estrutura de dados de um documento dinamicamente,sem precisar alterar o esquema para toda a coleção. Os bancos de dados de documentos são adequadospara o desenvolvimento ágil e para ambientes que mudam dinamicamente.

Noções básicas sobre normalização em um banco de dados dedocumentosBancos de dados de documentos não são normalizados; os dados encontrados em um documentopodem ser repetidos em outro documento. Além disso, algumas discrepâncias de dados podem existirentre documentos. Por exemplo, considere o cenário em que você faz uma compra em uma loja online etodos os detalhes de suas compras são armazenados em um único documento. O documento pode sersemelhante ao documento JSON a seguir:

{ "DateTime": "2018-08-15T12:13:10Z", "LName" : "Santos", "FName" : "Paul", "Cart" : [ { "ItemId" : "9876543210123", "Description" : "Understanding Document Databases", "Price" : "29.95" }, { "ItemId" : "0123456789012", "Description" : "Programming Today", "Issue": { "Volume": "14", "Number": "09" }, "Price" : "8.95" }, { "ItemId": "234567890-K", "Description": "Gel Pen (black)", "Price": "2.49" } ], "PaymentMethod" : { "Issuer" : "MasterCard", "Number" : "1234-5678-9012-3456" }, "ShopperId" : "1234567890" }

Todas essas informações são armazenadas como um documento em uma coleção de transações. Maistarde, você percebe que esqueceu de comprar um item. Então, você faz logon novamente na mesma loja efaz outra compra, que também é armazenada como outro documento na coleção de transações.

{ "DateTime": "2018-08-15T14:49:00Z", "LName" : "Santos", "FName" : "Paul",

22

Amazon DocumentDB Guia do desenvolvedorComo trabalhar com documentos

"Cart" : [ { "ItemId" : "2109876543210", "Description" : "Document Databases for Fun and Profit", "Price" : "45.95" } ], "PaymentMethod" : { "Issuer" : "Visa", "Number" : "0987-6543-2109-8765" }, "ShopperId" : "1234567890" }

Observe a redundância entre esses dois documentos— seu nome e ID de comprador (e, se você usouo mesmo cartão de crédito, suas informações de cartão de crédito). Mas não tem problema, porque oarmazenamento é barato e cada documento registra completamente uma única transação que pode serrecuperada rapidamente com uma consulta simples de chave/valor que não requer junções.

Existe também uma aparente discrepância entre os dois documentos— as informações do seu cartãode crédito. Essa é apenas uma discrepância aparente porque é provável que você tenha usado umcartão de crédito diferente para cada compra. Cada documento é preciso em relação à transação que eledocumenta.

Como trabalhar com documentosComo um banco de dados de documentos, o Amazon DocumentDB facilita o armazenamento, a consulta ea indexação de dados JSON. No Amazon DocumentDB, uma coleção de banco de dados de documentosé semelhante a uma tabela em um banco de dados relacional, exceto pelo fato de não haver um únicoesquema aplicado a todos os documentos. As coleções permitem agrupar documentos semelhantes,mantendo-os todos no mesmo banco de dados, sem exigir que eles tenham a estrutura idêntica.

Usando os exemplos de documentos das seções anteriores, é provável que você tenha coleções dereading_material e office_supplies. É função do software impor a que coleção um documentopertence.

Os exemplos a seguir usam a API do MongoDB para mostrar como adicionar, consultar, atualizar e excluirdocumentos.

Tópicos• Como adicionar documentos (p. 23)• Consultar documentos (p. 25)• Como atualizar documentos (p. 27)• Como excluir documentos (p. 31)

Como adicionar documentosNo Amazon DocumentDB, um banco de dados é criado quando você adiciona um documento a umacoleção. Neste exemplo, você está criando uma coleção chamada example no banco de dados test, queé o banco de dados padrão quando ao conectar-se a um cluster. Como a conexão é criada implicitamentequando o primeiro documento é inserido, não há erro ao verificar o nome da coleção. Portanto, um erro dedigitação no nome da coleção, como eexample em vez de example, criará e adicionará o documento àcoleção eexample em vez de à coleção pretendida. A verificação de erros deve ser processada pelo seuaplicativo.

Os exemplos a seguir usam a API do MongoDB para adicionar documentos.

23


Tópicos• Como adicionar um único documento (p. 24)• Como adicionar diversos documentos (p. 24)

Como adicionar um único documento

Para adicionar um único documento a uma coleção, use a operação insertOne( {} ) com odocumento que você deseja adicionar à coleção.

db.example.insertOne( { "Item": "Ruler", "Colors": ["Red","Green","Blue","Clear","Yellow"], "Inventory": { "OnHand": 47, "MinOnHand": 40 }, "UnitPrice": 0.89 })

A saída dessa operação é semelhante ao seguinte (formato JSON).

{ "acknowledged" : true, "insertedId" : ObjectId("5bedafbcf65ff161707de24f")}

Como adicionar diversos documentos

Para adicionar diversos documentos a uma coleção, use a operação insertMany( [{},...,{}] )com uma lista dos documentos que você deseja adicionar à coleção. Embora os documentos nessa listaespecífica tenham esquemas diferentes, todos eles podem ser adicionados à mesma coleção.

db.example.insertMany( [ { "Item": "Pen", "Colors": ["Red","Green","Blue","Black"], "Inventory": { "OnHand": 244, "MinOnHand": 72 } }, { "Item": "Poster Paint", "Colors": ["Red","Green","Blue","Black","White"], "Inventory": { "OnHand": 47, "MinOnHand": 50 } }, { "Item": "Spray Paint", "Colors": ["Black","Red","Green","Blue"], "Inventory": { "OnHand": 47, "MinOnHand": 50, "OrderQnty": 36

24


} } ])


{ "acknowledged" : true, "insertedIds" : [ ObjectId("5bedb07941ca8d9198f5934c"), ObjectId("5bedb07941ca8d9198f5934d"), ObjectId("5bedb07941ca8d9198f5934e") ]}

Consultar documentosÀs vezes, pode ser necessário examinar o inventário da sua loja online para que os clientes possamvisualizar e comprar o que você está vendendo. Consultar uma coleção é relativamente fácil, quer vocêqueira todos os documentos na coleção ou apenas os documentos que satisfazem a um critério específico.

Para consultar documentos, use a operação find(). O comando find() tem um único parâmetro dodocumento que define os critérios a serem usados na escolha dos documentos a serem retornados. Asaída de find() é um documento formatado como uma única linha de texto sem quebras de linha. Paraformatar o documento de saída para facilitar a leitura, use find().pretty(). Todos os exemplos destetópico usam .pretty() para formatar a saída.

Use os quatro documentos inseridos na coleção example nos últimos dois exercícios — insertOne() einsertMany().

Tópicos• Como recuperar todos os documentos em uma coleção (p. 25)• Como recuperar documentos que correspondem a um valor de campo (p. 25)• Como recuperar documentos que correspondem a um documento incorporado (p. 26)• Como recuperar documentos que correspondem a um valor de campo em um documento

incorporado (p. 26)• Como recuperar documentos que correspondem a uma matriz (p. 26)• Como recuperar documentos que correspondem a um valor em uma matriz (p. 26)• Recuperação de documentos usando operadores (p. 27)

Como recuperar todos os documentos em uma coleção

Para recuperar todos os documentos em sua coleção, use a operação find() com um documento deconsulta vazio.

A consulta a seguir retorna todos os documentos da coleção example.

db.example.find( {} ).pretty()

Como recuperar documentos que correspondem a um valor de campo

Para recuperar todos os documentos que correspondem a um campo e valor, use a operação find() comum documento de consulta que identifica os campos e valores a serem correspondidos.

25


Usando documentos anteriores, essa consulta retorna todos os documentos em que o campo "Item" seráigual a "Pen".

db.example.find( { "Item": "Pen" } ).pretty()

Como recuperar documentos que correspondem a um documento incorporadoPara localizar todos os documentos que correspondem a um documento incorporado, use a operaçãofind() com um documento de consulta que especifica o nome do documento incorporado e todos oscampos e valores desse documento incorporado.

Ao vincular um documento incorporado, o documento incorporado do documento deve ter o mesmo nomeque na consulta. Além disso, os campos e os valores no documento incorporado devem corresponder àconsulta.

A consulta a seguir retorna apenas o documento "Poster Paint". Isso ocorre porque o "Pen" tem valoresdiferentes para "OnHand" e "MinOnHand", e o "Spray Paint" tem um campo a mais (OrderQnty) que odocumento de consulta.

db.example.find({"Inventory": { "OnHand": 47, "MinOnHand": 50 } } ).pretty()

Como recuperar documentos que correspondem a um valor de campo em umdocumento incorporadoPara localizar todos os documentos que correspondem a um documento incorporado, use a operaçãofind() com um documento de consulta que especifica o nome do documento incorporado e todos oscampos e valores desse documento incorporado.

Considerando os documentos anteriores, a consulta a seguir usa "notação de pontos" para especificaro documento incorporado e os campos de interesse. Qualquer documento que seja correspondenteserá retornado, independentemente de quais outros campos possam estar presentes no documentoincorporado. A consulta retorna "Poster Paint" e "Spray Paint", pois ambos correspondem aos campos evalores especificados.

db.example.find({"Inventory.OnHand": 47, "Inventory.MinOnHand": 50 }).pretty()

Como recuperar documentos que correspondem a uma matrizPara localizar todos os documentos que correspondem a uma matriz, use a operação find() com o nomeda matriz de interesse e todos os valores na matriz. A consulta retorna todos os documentos que têm umamatriz com esse nome, com valores idênticos aos da matriz, e na mesma ordem que na consulta.

A consulta a seguir retorna apenas o documento "Pen", pois o "Poster Paint" tem uma cor adicional(White), e "Spray Paint" tem as cores em ordem diferente.

db.example.find( { "Colors": ["Red","Green","Blue","Black"] } ).pretty()

Como recuperar documentos que correspondem a um valor em uma matrizPara localizar todos os documentos que possuem um valor de matriz específico, use a operação find()com o valor e o nome da matriz de interesse.

db.example.find( { "Colors": "Red" } ).pretty()

26


A operação anterior retorna todos os três documentos, pois cada um deles tem uma matriz chamadaColors e o valor Red em algum lugar da matriz. Se você especificar o valor "White", a consulta retornaráapenas "Poster Paint".

Recuperação de documentos usando operadores

A consulta a seguir retorna todos os documentos em que o valor "Inventory.OnHand" é inferior a 50.

db.example.find( { "Inventory.OnHand": { $lt: 50 } } )

Para obter uma lista de operadores de consulta compatíveis, consulte Operadores de consulta eprojeção (p. 89).

Como atualizar documentosNormalmente, seus documentos não são estáticos e são atualizados como parte de seus fluxos detrabalho de aplicativos. Os exemplos a seguir mostram algumas maneiras de como atualizar documentos.

Para atualizar um documento existente, use a operação update(). A operação update() tem doisparâmetros de documento. O primeiro documento identifica qual(is) documento(s) atualizar. O segundodocumento especifica as atualizações a fazer.

Ao atualizar um campo existente — seja esse campo um campo simples, uma matriz ou um documentoincorporado — você especifica o nome do campo e seus valores. No final da operação, é como se ocampo no documento antigo tivesse sido substituído pelo novo campo e por novos valores.

Tópicos• Como atualizar os valores de um campo existente (p. 27)• Como adicionar um novo campo (p. 29)• Substituição de um documento incorporado (p. 29)• Como inserir novos campos a um documento incorporado (p. 30)• Como remover um campo de um documento (p. 30)• Remover um campo de vários documentos (p. 31)

Como atualizar os valores de um campo existente

Use os quatro documentos a seguir, que você adicionou anteriormente, para as seguintes operações deatualização.

{ "Item": "Ruler", "Colors": ["Red","Green","Blue","Clear","Yellow"], "Inventory": { "OnHand": 47, "MinOnHand": 40 }, "UnitPrice": 0.89},{ "Item": "Pen", "Colors": ["Red","Green","Blue","Black"], "Inventory": { "OnHand": 244, "MinOnHand": 72 }

27


},{ "Item": "Poster Paint", "Colors": ["Red","Green","Blue","Black","White"], "Inventory": { "OnHand": 47, "MinOnHand": 50 }},{ "Item": "Spray Paint", "Colors": ["Black","Red","Green","Blue"], "Inventory": { "OnHand": 47, "MinOnHand": 50, "OrderQnty": 36 }}

Para atualizar um campo simples

Para atualizar um campo simples, use update() com $set para especificar o nome e o novo valor docampo. O exemplo a seguir altera o Item de "Pen" para "Gel Pen".

db.example.update( { "Item" : "Pen" }, { $set: { "Item": "Gel Pen" } })

Os resultados dessa operação são semelhantes ao seguinte.

{ "Item": "Gel Pen", "Colors": ["Red","Green","Blue","Black"], "Inventory": { "OnHand": 244, "MinOnHand": 72 }}

Para atualizar uma matriz

O exemplo a seguir substitui a matriz de cores existente por uma nova matriz que inclui Orange e descartaWhite da lista de cores. A nova lista de cores está na ordem especificada na operação update().

db.example.update( { "Item" : "Poster Paint" }, { $set: { "Colors": ["Red","Green","Blue","Orange","Black"] } })


{ "Item": "Poster Paint", "Colors": ["Red","Green","Blue","Orange","Black"], "Inventory": { "OnHand": 47, "MinOnHand": 50 }}

28


Como adicionar um novo campo

Para modificar um documento adicionando um ou mais novos campos, use a operação update() com umdocumento de consulta que identifica o documento a ser inserido e os novos campos e valores a sereminseridos usando o operador $set.

O exemplo a seguir adiciona o campo UnitPrice com o valor 3.99 para o documento Spray Paints.Observe que o valor 3.99 é numérico, e não uma string.

db.example.update( { "Item": "Spray Paint" }, { $set: { "UnitPrice": 3.99 } } )

Os resultados dessa operação são semelhantes ao seguinte (formato JSON).

{ "Item": "Spray Paint", "Colors": ["Black","Red","Green","Blue"], "Inventory": { "OnHand": 47, "MinOnHand": 50, "OrderQnty": 36 }, "UnitPrice": 3.99}

Substituição de um documento incorporado

Para modificar um documento substituindo um documento incorporado, use a operação update() comdocumentos que identificam o documento incorporado e seus novos campos e valores com o uso dooperador $set.

Considerando o seguinte documento.

db.example.insert({ "DocName": "Document 1", "Date": { "Year": 1987, "Month": 4, "Day": 18 }})

Substituir um documento incorporado

O exemplo a seguir substitui o documento de data atual por um novo que tem somente os campos Monthe Day. O campo Year foi eliminado.

db.example.update( { "DocName" : "Document 1" }, { $set: { "Date": { "Month": 4, "Day": 18 } } })


{ "DocName": "Document 1",

29


"Date": { "Month": 4, "Day": 18 }}

Como inserir novos campos a um documento incorporado

Como adicionar campos a um documento incorporado

Para modificar um documento adicionando um ou mais novos campos a um documento incorporado,use a operação update() com documentos que identificam o documento incorporado e "notação depontos" para especificar o documento incorporado e os novos campos e valores a serem inseridos usandoo operador $set.

Considerando o documento a seguir, o código usa a "notação de pontos" para inserir os campos Year eDoW no documento Date incorporado, e Words no documento pai.

{ "DocName": "Document 1", "Date": { "Month": 4, "Day": 18 }}

db.example.update( { "DocName" : "Document 1" }, { $set: { "Date.Year": 1987, "Date.DoW": "Saturday", "Words": 2482 } })


{ "DocName": "Document 1", "Date": { "Month": 4, "Day": 18, "Year": 1987, "DoW": "Saturday" }, "Words": 2482}

Como remover um campo de um documento

Para modificar um documento removendo um campo do documento, use a operação update() com umdocumento de consulta que identifica o campo a ser removido do documento e o operador $unset paraespecificar o campo a ser removido.

O exemplo a seguir remove o campo Words do documento anterior.

db.example.update( { "DocName" : "Document 1" }, { $unset: { Words:1 } })

30



{ "DocName": "Document 1", "Date": { "Month": 4, "Day": 18, "Year": 1987, "DoW": "Saturday" }}

Remover um campo de vários documentos

Para modificar um documento removendo um campo de vários documentos, use a operação update()com o operador $unset e a opção multi definida como true.

O exemplo a seguir remove o campo Inventory de todos os documentos na coleção de exemplo. Se umdocumento não tiver o campo Inventory, nenhuma ação será executada nesse documento. Se multi:true for omitido, a ação será executada apenas no primeiro documento que atenda ao critério.

db.example.update( {}, { $unset: { Inventory:1 } }, { multi: true })

Como excluir documentosPara remover um documento do banco de dados, use a operação remove(), especificando qualdocumento remover. O código a seguir remove "Gel Pen" da sua coleção example.

db.example.remove( { "Item": "Gel Pen" } )

Para remover todos os documentos do seu banco de dados, use a operação remove() com uma consultavazia, conforme exemplo a seguir.

db.example.remove( { } )

31

Amazon DocumentDB Guia do desenvolvedorPrerequisites

Conceitos básicos da AmazonDocumentDB

Há muitas formas de se conectar e começar com Amazon DocumentDB. Criámos este guia porqueencontrámos esta forma de ser a forma mais rápida, simples e fácil de os utilizadores começarem a utilizara nossa poderosa base de dados de documentos. Este guia utiliza AWS Cloud9, um terminal baseadona Web para ligar e consultar o seu Amazon DocumentDB utilizando a concha de mongo diretamente doConsole de gerenciamento da AWS. Os novos clientes da AWS qualificados para o nível gratuito da AWSpodem usar o AWS Cloud9 gratuitamente. Se o seu AWS Cloud9 faz uso de recursos além do escalãolivre, são-lhe cobradas as tarifas normais da AWS por esses recursos. Este guia irá ajudá-lo a começarcom Amazon DocumentDB em menos de 15 minutos e o custo esperado é inferior a $0,10/hora.

Note

Amazon DocumentDB não tem um escalão gratuito. Para mais informações sobre preços,consulte Preços Amazon DocumentDB (com compatibilidade MongoDB).

Tópicos• Prerequisites (p. 32)• Passo 1: Criar um ambiente do AWS Cloud9 (p. 33)• Passo 2: Crie um grupo de segurança (p. 36)• Passo 3: Criar um cluster do Amazon DocumentDB (p. 38)• Passo 4: Instale o shell do mongo (p. 41)• Passo 5: Ligue-se ao seu Amazon DocumentDB cluster (p. 42)• Passo 6: Inserir e dados de consulta (p. 44)• Passo 7: Explorar (p. 45)

Se preferir conectar-se ao seu Amazon DocumentDB da sua máquina local criando uma ligação SSH paraum Amazon EC2 por exemplo, consulte o Ligar com instruções EC2

PrerequisitesAntes de criar o primeiro cluster do Amazon DocumentDB, você deve fazer o seguinte:

Criação de uma conta da Amazon Web Services (AWS)

Antes de começar a usar o Amazon DocumentDB, você deve ter uma conta da Amazon Web Services(AWS). A conta da AWS é gratuita. Você paga apenas pelos serviços e recursos usados.

Se você ainda não tiver uma conta da AWS, use o procedimento a seguir para criar uma.

Para cadastrar-se na AWS

1. Abra https://aws.amazon.com/ e escolha Create an AWS Account.

32

https://docs.aws.amazon.com/cloud9/latest/user-guide/welcome.html


https://docs.aws.amazon.com/documentdb/latest/developerguide/connect-ec2.html

https://aws.amazon.com/

Amazon DocumentDB Guia do desenvolvedorPasso 1: Criar um ambiente do AWS Cloud9

2. Siga as instruções online.

Configure as permissões necessárias do AWS Identity and Access Management (IAM).

O acesso para gerenciar recursos do Amazon DocumentDB como clusters, instâncias egrupos de parâmetros de cluster exige credenciais que a AWS pode usar para autenticar suassolicitações. Para obter mais informações, consulte Identity and Access Management no AmazonDocumentDB (p. 129).

1. Na barra de pesquisa da consola de gestão AWS, digite IAM e selecione LI no menu pendenteque aparece.

2. Quando estiver no IAM consola, seleccionar Utilizadores no painel de navegação.3. Selecione o seu nome de utilizador.4. Clique no botão Adicionar permissões.5. Selecione Attach existing policies directly (Anexar políticas existentes diretamente).6. Tipo AmazonDocDBFullAccess na barra de pesquisa e selecione-a assim que aparecer nos

resultados da pesquisa.7. Clique no botão azul na parte inferior que diz Seguinte: Review (Revisar)8. Clique no botão azul na parte inferior que diz Adicionar permissões.

Criar uma Amazon Virtual Private Cloud (Amazon VPC)

Este passo só é necessário se ainda não tiver uma predefinição Amazon VPC. Caso contrário,complete o passo 1 do Introdução ao Amazon VPC na Guia do usuário da Amazon VPC. Isto irádemorar menos de cinco minutos.

Passo 1: Criar um ambiente do AWS Cloud9AWS Cloud9 fornece um terminal baseado na Web que pode utilizar para se ligar e consultar o seuAmazon DocumentDB utilizando a concha de mongo.

1. Desde o Console de gerenciamento da AWS navegue para o AWS Cloud9 consola e escolha Criarambiente.

2. No Nome e descrição do ambiente secção, no Nome campo, introduzir DocumentDBCloud9.

33

https://docs.aws.amazon.com/vpc/latest/userguide/vpc-getting-started.html


3. Escolher Passo seguinte.

4. No Configurar secção de definições, escolha Passo seguinte.

34


5. No Revisão secção, escolha Criar ambiente.

Note

O fornecimento do AWS Cloud9 pode demorar até três minutos.

35

Amazon DocumentDB Guia do desenvolvedorPasso 2: Crie um grupo de segurança

Passo 2: Crie um grupo de segurançaEste grupo de segurança irá permitir-lhe ligar-se ao seu Amazon DocumentDB do seu AWS Cloud9ambiente de trabalho.

1. No Amazon EC2 Consola de gestão, sob Rede e segurança, escolha Grupos de segurança.

2. Escolher Criar grupo de segurança.

3. No Detalhes básicos , introduza o seguinte para cada campo:

• For Nome do security group, enter demodocdb.• For Description (Descrição), enter a description.• For VPC, accept the usage of your default VPC.

36

https://console.aws.amazon.com/ec2

Amazon DocumentDB Guia do desenvolvedorPasso 2: Crie um grupo de segurança

4. No Regras de entrada secção, escolha Adicionar regra.

5. Para Tipo, escolha Regra TCP personalizada.

6. Para Intervalo de porta, enter 27017.

7. A fonte é o grupo de segurança para o AWS Cloud9 que acabou de criar. Para ver uma lista de gruposde segurança disponíveis, introduza cloud9 no campo de destino. Escolha o grupo de segurançacom o nome aws-cloud9-<environment name>.

37

Amazon DocumentDB Guia do desenvolvedorPasso 3: Criar um cluster do Amazon DocumentDB

8. Aceitar todas as outras predefinições e escolher Criar grupo de segurança.

Note

A porta 27017 é a porta predefinida para Amazon DocumentDB.

Passo 3: Criar um cluster do Amazon DocumentDBNeste passo, irá criar um Amazon DocumentDB utilizando o grupo de segurança que criou no passoanterior.

1. No Amazon DocumentDB consola de gestão, sob Clusters, escolha Criar.

38


2. Na página Create Amazon documentdb cluster, no Configuração secção, escolha 1 para Númerode ocorrências. Escolher uma instância ajuda a minimizar os custos. Se este fosse um sistema deprodução, recomenda-se a provisão de três instâncias para alta disponibilidade. Pode deixar as outrasdefinições no Configuração na sua predefinição.

3. No Autenticação , introduza um nome de utilizador e palavra-passe.

39


4. Ligar Mostrar definições avançadas.

5. No Definições de rede , para Grupos de segurança VPC, escolha demodocdb.

40

Amazon DocumentDB Guia do desenvolvedorPasso 4: Instale o shell do mongo

6. Escolher Criar grupo.

Amazon DocumentDB está agora a fornecer o seu cluster, o que pode demorar até alguns minutos aterminar. Podes ligar-te ao teu cluster quando o estado do cluster e da instância for mostrado comoAvailable.

Passo 4: Instale o shell do mongoIrá agora instalar a armação de mongo no seu AWS Cloud9 que criou no Passo 1. A concha de mongo éum utilitário de linha de comandos que utiliza para ligar e consultar o seu Amazon DocumentDB cluster.

1. Se o seu AWS Cloud9 ainda está aberto a partir do Passo 1, volte para esse ambiente e avance paraa instrução 3. Se navegou longe de si AWS Cloud9 ambiente, no AWS Cloud9 consola de gestão, sobOs seus ambientes, encontre o ambiente rotuladodocumentodecatálogos9. Escolher Abrir IDE.

41

Amazon DocumentDB Guia do desenvolvedorPasso 5: Ligue-se ao seu Amazon DocumentDB cluster

2. Na linha de comandos, crie o ficheiro de repositório com o seguinte comando:

echo -e "[mongodb-org-3.6] \nname=MongoDB Repository\nbaseurl=https://repo.mongodb.org/yum/amazon/2013.03/mongodb-org/3.6/x86_64/\ngpgcheck=1 \nenabled=1 \ngpgkey=https://www.mongodb.org/static/pgp/server-3.6.asc" | sudo tee /etc/yum.repos.d/mongodb-org-3.6.repo

3. Quando terminar, instale o invólucro mongo com o seguinte comando:

sudo yum install -y mongodb-org-shell

4. Para criptografar dados em trânsito, faça download da chave pública do Amazon DocumentDB emhttps://s3.amazonaws.com/rds-downloads/rds-combined-ca-bundle.pem. Essa operação faz downloadde um arquivo chamado rds-combined-ca-bundle.pem.

wget https://s3.amazonaws.com/rds-downloads/rds-combined-ca-bundle.pem

Note

A encriptação em trânsito está activada por predefinição no documento Amazon. Podedesativar opcionalmente o TLS. Para mais informações, consulte Gerir definições de TLS dogrupo de documentdb da Amazon.

Passo 5: Ligue-se ao seu Amazon DocumentDBcluster

Agora, você se conectará ao seu Amazon DocumentDB utilizando a concha de mongo que instalou noPasso 4.

1. No Amazon DocumentDB consola de gestão, sob Clusters, localize o seu grupo. Escolha o grupo quecriou clicando no identificador de cluster.

42

https://s3.amazonaws.com/rds-downloads/rds-combined-ca-bundle.pem

https://docs.aws.amazon.com/documentdb/latest/developerguide/security.encryption.ssl.html


Amazon DocumentDB Guia do desenvolvedorPasso 5: Ligue-se ao seu Amazon DocumentDB cluster

2. No Conectividade e segurança , sob Ligue-se a este grupo com o revestimento mongo, copie a cadeiade ligação fornecida. Omitir cópia <insertYourPassword> para que lhe seja pedida a palavra-passe pela concha do mongo quando ligar.

3. Voltar ao seu AWS Cloud9 e cole a cadeia de ligação.

Quando introduz a sua palavra-passe e o seu pedido fica rs0:PRIMARY> , está ligado com sucesso aoseu Amazon DocumentDB cluster.

Note

Para obter informações sobre a resolução de problemas, consulte Resolução de problemasAmazon DocumentDB.

43

https://docs.aws.amazon.com/documentdb/latest/developerguide/troubleshooting.html


Amazon DocumentDB Guia do desenvolvedorPasso 6: Inserir e dados de consulta

Passo 6: Inserir e dados de consultaAgora que está ligado ao seu cluster, pode executar algumas consultas para se familiarizar com autilização de uma base de dados de documentos.

1. Para inserir um único documento, introduza o seguinte:

db.collection.insert({"hello":"DocumentDB"})

2. Você obterá a seguinte saída:

WriteResult({ "nInserted" : 1 })

3. Pode ler o documento que escreveu com o findOne() (porque apenas devolve um únicodocumento). Introduza o seguinte:

db.collection.findOne()


{ "_id" : ObjectId("5e401fe56056fda7321fbd67"), "hello" : "DocumentDB" }

5. Para realizar mais algumas perguntas, considere um caso de utilização de perfis. Primeiro, insiraalgumas entradas numa coleção intitulada profiles. Introduza o seguinte:

db.profiles.insertMany([ { "_id" : 1, "name" : "Matt", "status": "active", "level": 12, "score":202}, { "_id" : 2, "name" : "Frank", "status": "inactive", "level": 2, "score":9}, { "_id" : 3, "name" : "Karen", "status": "active", "level": 7, "score":87}, { "_id" : 4, "name" : "Katie", "status": "active", "level": 3, "score":27} ])

6. Copie o seguinte comando e volte ao seu AWS Cloud9 e cole-o no AWS Cloud9 terminal.



{ "acknowledged" : true, "insertedIds" : [ 1, 2, 3, 4 ] }

8. Utilize o find() para devolver todos os documentos na coleção de perfis. Introduza o seguinte:

db.profiles.find()

9. Irá obter uma saída que corresponda aos dados que introduziu no Passo 5.10. Utilize uma consulta para um único documento utilizando um filtro. Introduza o seguinte:

db.profiles.find({name: "Katie"})

11. Deve recuperar esta saída:

44

Amazon DocumentDB Guia do desenvolvedorPasso 7: Explorar

{ "_id" : 4, "name" : "Katie", "status": "active", "level": 3, "score":27}

12. Agora tente encontrar um perfil e modificá-lo utilizando o findAndModify comando. Iremos dar aoutilizador a Matt mais dez pontos com o seguinte código:

db.profiles.findAndModify({ query: { name: "Matt", status: "active"}, update: { $inc: { score: 10 } } })

13. Obtém a seguinte saída (note que a sua pontuação ainda não aumentou):

{ "_id" : 1, "name" : "Matt", "status" : "active", "level" : 12, "score" : 202 }

14. Pode verificar se a sua pontuação foi alterada com a seguinte consulta:

db.profiles.find({name: "Matt"})


{ "_id" : 1, "name" : "Matt", "status" : "active", "level" : 12, "score" :212 }

Passo 7: ExplorarParabéns! Concluiu com sucesso o Guia de Introdução para Amazon DocumentDB.

Qual será o próximo passo? Saiba como tirar o máximo partido desta base de dados com algumas dassuas funcionalidades populares:

• Gerenciamento Amazon DocumentDB• Escalabilidade• Fazer cópias de segurança e restaurar

Note

O grupo que criou a partir deste exercício inicial continuará a acumular custos, a menos que oelimine. Para instruções, consulte Eliminar uma Amazon DocumentDB Agrupamento.

45

https://docs.aws.amazon.com/documentdb/latest/developerguide/managing-documentdb.html

https://docs.aws.amazon.com/documentdb/latest/developerguide/operational_tasks.html

https://docs.aws.amazon.com/documentdb/latest/developerguide/backup_restore.html

https://docs.aws.amazon.com/documentdb/latest/developerguide/db-cluster-delete.html

Amazon DocumentDB Guia do desenvolvedorPrerequisites

Amazon DocumentDBInício rápido dousando o AWS CloudFormation

Esta secção contém passos e outras informações para o ajudar a começar rapidamente com AmazonDocumentDB (compatível com MongoDB) utilizar AWS CloudFormation. Para obter informações geraissobre políticas do Amazon DocumentDB, consulte O que é Amazon DocumentDB (compatibilidade com oMongoDB)? (p. 1)

Estas instruções utilizam um AWS CloudFormation modelo para criar um grupo e instâncias na suapredefinição Amazon VPC. Para obter instruções sobre a criação desses recursos por conta própria,consulte Conceitos básicos da Amazon DocumentDB (p. 32).

Important

O AWS CloudFormation a pilha criada por este modelo cria vários recursos, incluindo recursosem Amazon DocumentDB (por exemplo, um grupo e instâncias) e Amazon Elastic Compute Cloud(por exemplo, um grupo de sub-rede).Alguns desses recursos não são recursos de nível gratuito. Para informações sobre preços,consulte Amazon DocumentDB Preços e Amazon EC2 Preços. Você pode excluir a pilha aoterminar de usá-la para interromper as cobranças.

Essa pilha do AWS CloudFormation tem como objetivo ser apenas um tutorial. Se utilizar este modelopara um ambiente de produção, recomendamos que utilize mais uma vez IAM políticas e segurança. Paraobter informações sobre a proteção de recursos, consulte Amazon VPC Segurança e Amazon EC2 Rede esegurança.

Tópicos• Prerequisites (p. 46)• Iniciar um Amazon DocumentDB AWS CloudFormation Pilha (p. 48)• Aceder ao Amazon DocumentDB Cluster (p. 51)• Proteção contra encerramento e exclusão (p. 51)

PrerequisitesAntes de criar um cluster do Amazon DocumentDB (compatível com MongoDB), é preciso ter o seguinte:

• Uma padrãoAmazon VPC• O necessário IAM permissões

Obrigatório IAM PermissõesAs seguintes permissões permitem-lhe criar recursos para o AWS CloudFormation pilha:

Políticas gerenciadas da AWS

• AWSCloudFormationReadOnlyAccess

• AmazonDocDBFullAccess

46

https://docs.aws.amazon.com/en_us/AWSCloudFormation/latest/UserGuide/Welcome.html


https://aws.amazon.com/ec2/pricing/

https://docs.aws.amazon.com/vpc/latest/userguide/VPC_Security.html

https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/EC2_Network_and_Security.html

https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/EC2_Network_and_Security.html

Amazon DocumentDB Guia do desenvolvedorAmazon EC2Par de chaves do

Permissões do IAM adicionais

A seguinte política descreve as permissões adicionais necessárias para criar e eliminar este AWSCloudFormation pilha.

{ "Version": "2012-10-17", "Statement": [{ "Effect": "Allow", "Action": [ "iam:GetSSHPublicKey", "iam:ListSSHPublicKeys", "iam:CreateRole", "iam:CreatePolicy", "iam:PutRolePolicy", "iam:CreateInstanceProfile", "iam:AddRoleToInstanceProfile", "iam:GetAccountSummary", "iam:ListAccountAliases", "iam:PassRole", "iam:GetRole", "iam:DeleteRole", "iam:RemoveRoleFromInstanceProfile", "iam:DeleteRolePolicy", "iam:DeleteInstanceProfile", "cloudformation:*Stack", "ec2:DescribeKeyPairs", "ec2:*Vpc", "ec2:DescribeInternetGateways", "ec2:*InternetGateway", "ec2:createTags", "ec2:*VpcAttribute", "ec2:DescribeRouteTables", "ec2:*RouteTable", "ec2:*Subnet", "ec2:*SecurityGroup", "ec2:AuthorizeSecurityGroupIngress", "ec2:DescribeVpcEndpoints", "ec2:*VpcEndpoint", "ec2:*SubnetAttribute", "ec2:*Route", "ec2:*Instances", "ec2:DeleteVpcEndpoints" ], "Resource": "*" } ]}

Note

As permissões com negrito na política anterior apenas são necessárias para eliminar uma pilha:iam:DeleteRole, iam:RemoveRoleFromInstanceProfile, iam:DeleteRolePolicy,iam:DeleteInstanceProfile, e ec2:DeleteVpcEndpoints. Note também que ec2:*Vpcsubsídios ec2:DeleteVpc permissões.

Amazon EC2Par de chaves doTem de ter um par de teclas (e o ficheiro PEM) disponível na região onde irá criar o AWS CloudFormationpilha. Se precisar de criar um par de teclas, consulte Criar um par de teclas utilizando Amazon EC2 noGuia do usuário do Amazon EC2 para instâncias do Linux.

47

https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/ec2-key-pairs.html#having-ec2-create-your-key-pair

Amazon DocumentDB Guia do desenvolvedorIniciar um Amazon DocumentDB AWS CloudFormation Pilha

Iniciar um Amazon DocumentDB AWSCloudFormation Pilha

Esta secção descreve como iniciar e configurar um Amazon DocumentDB AWS CloudFormation pilha.

1. Faça login no Console de gerenciamento da AWS em https://console.aws.amazon.com/.2. A tabela a seguir lista os modelos de pilha do Amazon DocumentDB para cada região da AWS.

Escolher Pilha de lançamento para a região AWS onde pretende iniciar a sua pilha em.

Região Visualizar modelo Visualizar no Designer Executar

Leste dos EUA (Ohio) Visualizar modelo Visualizar no Designer

Leste dos EUA (Norteda Virgínia) Visualizar modelo Visualizar no Designer

Oeste dos EUA(Oregon) Visualizar modelo Visualizar no Designer

Ásia Pacífico (Mumbai) Visualizar modelo Visualizar no Designer

Ásia-Pacífico (Seul) Visualizar modelo Visualizar no Designer


Visualizar modelo Visualizar no Designer

Ásia-Pacífico (Sydney) Visualizar modelo Visualizar no Designer

Ásia-Pacífico (Tóquio) Visualizar modelo Visualizar no Designer

Canadá (Central) Visualizar modelo Visualizar no Designer

Europa (Frankfurt) Visualizar modelo Visualizar no Designer

Europa (Irlanda) Visualizar modelo Visualizar no Designer

Europa (Londres) Visualizar modelo Visualizar no Designer

Europa (Paris) Visualizar modelo Visualizar no Designer

3. Criar pilha — Descreve a Amazon DocumentDB modelo que selecionou. Cada pilha baseia-se nummodelo — um ficheiro JSON ou YLMA — que contém configuração sobre os recursos AWS quepretende incluir na pilha. Como você optou por executar uma pilha a partir dos modelos fornecidosacima, seu modelo já foi configurado de modo a criar uma pilha do Amazon DocumentDB para aregião da AWS escolhida.

48

https://console.aws.amazon.com/

https://s3.amazonaws.com/amazon-documentdb-samples/v1/cloudformation-templates/documentdb_full_stack.yaml

https://console.aws.amazon.com/cloudformation/designer/home?region=us-east-2&templateURL=https://s3.amazonaws.com/amazon-documentdb-samples/v1/cloudformation-templates/documentdb_full_stack.yaml

https://console.aws.amazon.com/cloudformation/home?region=us-east-2#/stacks/new?stackName=DocumentDBQuickStart&templateURL=https://s3.amazonaws.com/amazon-documentdb-samples/v1/cloudformation-templates/documentdb_full_stack.yaml


https://console.aws.amazon.com/cloudformation/designer/home?region=us-east-1&templateURL=https://s3.amazonaws.com/amazon-documentdb-samples/v1/cloudformation-templates/documentdb_full_stack.yaml

https://console.aws.amazon.com/cloudformation/home?region=us-east-1#/stacks/new?stackName=DocumentDBQuickStart&templateURL=https://s3.amazonaws.com/amazon-documentdb-samples/v1/cloudformation-templates/documentdb_full_stack.yaml


https://console.aws.amazon.com/cloudformation/designer/home?region=us-west-2&templateURL=https://s3.amazonaws.com/amazon-documentdb-samples/v1/cloudformation-templates/documentdb_full_stack.yaml

https://console.aws.amazon.com/cloudformation/home?region=us-west-2#/stacks/new?stackName=DocumentDBQuickStart&templateURL=https://s3.amazonaws.com/amazon-documentdb-samples/v1/cloudformation-templates/documentdb_full_stack.yaml


https://console.aws.amazon.com/cloudformation/designer/home?region=ap-south-1&templateURL=https://s3.amazonaws.com/amazon-documentdb-samples/v1/cloudformation-templates/documentdb_full_stack.yaml

https://console.aws.amazon.com/cloudformation/home?region=ap-south-1#/stacks/new?stackName=DocumentDBQuickStart&templateURL=https://s3.amazonaws.com/amazon-documentdb-samples/v1/cloudformation-templates/documentdb_full_stack.yaml


https://console.aws.amazon.com/cloudformation/designer/home?region=ap-northeast-2&templateURL=https://s3.amazonaws.com/amazon-documentdb-samples/v1/cloudformation-templates/documentdb_full_stack.yaml

https://console.aws.amazon.com/cloudformation/home?region=ap-northeast-2#/stacks/new?stackName=DocumentDBQuickStart&templateURL=https://s3.amazonaws.com/amazon-documentdb-samples/v1/cloudformation-templates/documentdb_full_stack.yaml


https://console.aws.amazon.com/cloudformation/designer/home?region=ap-southeast-1&templateURL=https://s3.amazonaws.com/amazon-documentdb-samples/v1/cloudformation-templates/documentdb_full_stack.yaml

https://console.aws.amazon.com/cloudformation/home?region=ap-southeast-1#/stacks/new?stackName=DocumentDBQuickStart&templateURL=https://s3.amazonaws.com/amazon-documentdb-samples/v1/cloudformation-templates/documentdb_full_stack.yaml


https://console.aws.amazon.com/cloudformation/designer/home?region=ap-southeast-2&templateURL=https://s3.amazonaws.com/amazon-documentdb-samples/v1/cloudformation-templates/documentdb_full_stack.yaml

https://console.aws.amazon.com/cloudformation/home?region=ap-southeast-2#/stacks/new?stackName=DocumentDBQuickStart&templateURL=https://s3.amazonaws.com/amazon-documentdb-samples/v1/cloudformation-templates/documentdb_full_stack.yaml


https://console.aws.amazon.com/cloudformation/designer/home?region=ap-northeast-1&templateURL=https://s3.amazonaws.com/amazon-documentdb-samples/v1/cloudformation-templates/documentdb_full_stack.yaml

https://console.aws.amazon.com/cloudformation/home?region=ap-northeast-1#/stacks/new?stackName=DocumentDBQuickStart&templateURL=https://s3.amazonaws.com/amazon-documentdb-samples/v1/cloudformation-templates/documentdb_full_stack.yaml


https://console.aws.amazon.com/cloudformation/designer/home?region=ca-central-1&templateURL=https://s3.amazonaws.com/amazon-documentdb-samples/v1/cloudformation-templates/documentdb_full_stack.yaml

https://console.aws.amazon.com/cloudformation/home?region=ca-central-1#/stacks/new?stackName=DocumentDBQuickStart&templateURL=https://s3.amazonaws.com/amazon-documentdb-samples/v1/cloudformation-templates/documentdb_full_stack.yaml


https://console.aws.amazon.com/cloudformation/designer/home?region=eu-central-1&templateURL=https://s3.amazonaws.com/amazon-documentdb-samples/v1/cloudformation-templates/documentdb_full_stack.yaml

https://console.aws.amazon.com/cloudformation/home?region=eu-central-1#/stacks/new?stackName=DocumentDBQuickStart&templateURL=https://s3.amazonaws.com/amazon-documentdb-samples/v1/cloudformation-templates/documentdb_full_stack.yaml


https://console.aws.amazon.com/cloudformation/designer/home?region=eu-west-1&templateURL=https://s3.amazonaws.com/amazon-documentdb-samples/v1/cloudformation-templates/documentdb_full_stack.yaml

https://console.aws.amazon.com/cloudformation/home?region=eu-west-1#/stacks/new?stackName=DocumentDBQuickStart&templateURL=https://s3.amazonaws.com/amazon-documentdb-samples/v1/cloudformation-templates/documentdb_full_stack.yaml








Quando lança um AWS CloudFormation pilha, proteção de eliminação (p. 51) para o seu AmazonDocumentDB o painel está desativado por predefinição. Se desejar habilitar a proteção contraexclusão para o cluster, conclua as etapas a seguir. Caso contrário, escolha Seguinte para avançarpara o passo seguinte.

Para permitir a proteção de eliminação para o seu Amazon DocumentDB grupo:

1. Escolher Ver no Designer no canto inferior direito do Criar pilha página.2. Modifique o modelo usando o editor JSON e YAML integrado na página Designer do AWS

CloudFormation resultante do console. Deslocar para o Resources e modificá-la para incluirDeletionProtection, como se segue. Para mais informações sobre a utilização AWSCloudFormation Designer, ver O que é AWS CloudFormation Designer?.

: JSON

"Resources": { "DBCluster": { "Type": "AWS::DocDB::DBCluster", "DeletionPolicy": "Delete", "Properties": { "DBClusterIdentifier": { "Ref": "DBClusterName" }, "MasterUsername": { "Ref": "MasterUser" }, "MasterUserPassword": { "Ref": "MasterPassword" }, "DeletionProtection": "true" } },

YAML

Resources: DBCluster: Type: 'AWS::DocDB::DBCluster' DeletionPolicy: Delete Properties: DBClusterIdentifier: !Ref DBClusterName MasterUsername: !Ref MasterUser MasterUserPassword: !Ref MasterPassword DeletionProtection: 'true'

3. Escolher Criar pilha ( ) no canto superior esquerdo da página para guardar as alterações e criaruma pilha com estas alterações ativadas.

4. Depois de guardar as alterações, será redirecionado para o Criar pilha página.5. Escolher Seguinte para continuar.

4. Especificar detalhes da pilha — Introduza o nome e os parâmetros da pilha para o seu modelo. Osparâmetros são definidos em seu modelo e permitem que você insira valores personalizados ao criarou atualizar uma pilha.• Abaixo Nome da pilha, introduza um nome para a sua pilha ou aceite o nome fornecido. O nome

da pilha pode incluir letras (A—Z e um—z), números (0—9) e travessões (—).• Abaixo Parâmetros, introduza os seguintes detalhes:

49

https://docs.aws.amazon.com/en_us/AWSCloudFormation/latest/UserGuide/working-with-templates-cfn-designer.html


• nomenomedeclusão — Introduza um nome para o seu Amazon DocumentDB ou aceite o nomefornecido.

Restrições de nomeação de cluster:• O comprimento é de [1—63] letras, números ou hifens.• O primeiro caractere deve ser uma letra.• Não podem terminar com um hífen ou conter dois hífens consecutivos• Tem de ser único para todos os grupos em Amazon RDS, Neptune, e Amazon DocumentDB

por conta AWS, por Região.• dbinstanlass — Na lista pendente, selecione a classe de instância para o seu Amazon

DocumentDB grupo.• dbinstancename — Introduza um nome para o seu Amazon DocumentDB ou aceite o nome

fornecido.

Restrições de nomenclatura da instância:• O comprimento é de [1—63] letras, números ou hifens.• O primeiro caractere deve ser uma letra.• Não podem terminar com um hífen ou conter dois hífens consecutivos• Deve ser único para todas as instâncias em Amazon RDS, Neptune, e Amazon DocumentDB

por conta AWS, por Região.• palavra-passe principal — A palavra-passe da conta de administrador da base de dados.• utilizador principal — O nome de utilizador da conta de administrador da base de dados. O

MasterUser deve começar com uma letra e pode conter apenas caracteres alfanuméricos.

Escolher Seguinte para guardar as alterações e continuar.5. Configurar opções de pilha — Configure as etiquetas, permissões e opções adicionais da sua pilha.

• Etiquetas — Especifique os pares de etiquetas (valor-chave) para aplicar aos seus recursos nasua pilha. Você pode adicionar até 50 tags exclusivas para cada pilha.

• Permissões — Opcional. Escolha um IAM função para definir explicitamente como AWSCloudFormation pode criar, modificar ou eliminar recursos na pilha. Se você não escolheruma função, o AWS CloudFormation usará permissões com base nas credenciais de usuário.Antes de especificar uma função de serviço, certifique-se de ter permissão para aprová-la(iam:PassRole). A permissão iam:PassRole especifica quais funções você pode usar.

Note

Quando você especifica uma função de serviço, o AWS CloudFormation sempre usaessa função para todas as operações que serão executadas nessa pilha. Outrosusuários com permissão para executar operações nessa pilha poderão usar essa função,mesmo que não tenham permissão para aprová-la. Se a função inclui permissões que ousuário não precisa, você pode ampliar involuntariamente as permissões de um usuário.Garantir que as funções menos privilégio..

• Opções avançadas — Pode definir as seguintes opções avançadas:

• Política de empilhamento — Opcional. Define os recursos que você deseja proteger contraatualizações não intencionais durante uma atualização da pilha. Por padrão, todos os recursospodem ser atualizados durante uma atualização da pilha.

É possível inserir a política de pilha diretamente como JSON ou fazer upload de um arquivoJSON que contém a política de pilha. Para mais informações, consulte Evitar atualizações paraempilhar recursos.

50

https://docs.aws.amazon.com/IAM/latest/UserGuide/best-practices.html#grant-least-privilege

https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/protect-stack-resources.html

https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/protect-stack-resources.html

Amazon DocumentDB Guia do desenvolvedorAceder ao Amazon DocumentDB Cluster

• Configuração de reversão — Opcional. Especificar CloudWatch Logs alarmes para AWSCloudFormation para monitorizar ao criar e atualizar a pilha. Se a operação violar um limiar dealarme, o AWS CloudFormation fará a reversão.

• Opções de notificação — Opcional. Especifique tópicos para o Simple Notification System(SNS).

• Opções de criação de pilha — Opcional. Você pode especificar as seguintes opções:• Reversão na falha — A pilha deve ser ou não rodada se a criação da pilha falhar.• Tempo limite —O número de minutos antes de um período de criação de pilha ser excedido.• Proteção de terminação — Impede que a pilha seja acidentalmente eliminada.

Note

AWS CloudFormation proteção de terminação é diferente do Amazon DocumentDBconceito de proteção contra eliminação. Para obter mais informações, consulteProteção contra encerramento e exclusão (p. 51).

Escolher Seguinte para continuar.6. Rever <nome da pilha> — Reveja o seu modelo de pilha, detalhes e opções de configuração.

Também pode abrir um ligação de criação rápida na parte inferior da página para criar pilhas com asmesmas configurações básicas que este.

• Escolher Criar para criar a pilha.• Em alternativa, pode escolher Criar conjunto de alterações. Um conjunto de alterações é uma pré-

visualização de como esta pilha será configurada antes de sua criação. Isso permite que vocêexamine diversas configurações antes de executar o conjunto de alterações.

Aceder ao Amazon DocumentDB ClusterQuando o AWS CloudFormation a pilha foi concluída, pode utilizar um Amazon EC2 para ligar ao seuAmazon DocumentDB grupo. Para obter informações sobre a ligação a um Amazon EC2 com o SSH,consulte Ligue-se à sua instância Linux no Guia do usuário do Amazon EC2 para instâncias do Linux.

Quando estiver conectado, consulte as seguintes seções, que contêm informações sobre o uso do AmazonDocumentDB.

• Passo 4: Instale o shell do mongo (p. 41)• Excluir um cluster do Amazon DocumentDB (p. 240)

Proteção contra encerramento e exclusãoÉ uma melhor prática do Amazon DocumentDB habilitar a proteção contra exclusão e a proteção contraencerramento. a proteção de terminação de turvação é uma característica distintamente diferente doAmazon DocumentDB característica de proteção de eliminação.

• Proteção de terminação — Pode evitar que uma pilha seja acidentalmente eliminada, permitindo aproteção de terminação para a sua pilha de formação de cloudformation. Se um usuário tentar excluiruma pilha com proteção contra encerramento habilitada, a exclusão falhará e a pilha, incluindo seustatus, permanecerá inalterada. A proteção contra encerramento é desabilitada por padrão quando vocêcria uma pilha usando o CloudFormation. Você pode ativar a proteção de encerramento em uma pilha aocriá-la. Para mais informações, consulte Definição AWS CloudFormation Opções de pilha.

• Proteção contra eliminação — Amazon DocumentDB também proporciona a capacidade de permitira proteção contra a eliminação para um grupo. Se um usuário tentar excluir um cluster do Amazon

51

https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/AccessingInstances.html

https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/cfn-console-add-tags.html

Amazon DocumentDB Guia do desenvolvedorProteção contra encerramento e exclusão

DocumentDB com a proteção de exclusão habilitada, a exclusão falhará e o cluster permaneceráinalterado. Proteção de eliminação, quando ativada, salvaguardas contra eliminações acidentais doAmazon DocumentDB Console de gerenciamento da AWS, AWS CLI, e turvação. Para obter maisinformações sobre como habilitar e desabilitar a proteção contra exclusão para um cluster do AmazonDocumentDB, consulte Proteção contra exclusão (p. 240).

52

Amazon DocumentDB Guia do desenvolvedorDiretrizes operacionais básicas

Melhores práticas do AmazonDocumentDB

Conheça as melhores práticas para trabalhar com o Amazon DocumentDB (compatível com MongoDB).Essa seção é continuamente atualizada conforme novas melhores práticas são identificadas.

Tópicos• Diretrizes operacionais básicas (p. 53)• Dimensionamento de instância (p. 54)• Trabalho com índices (p. 55)• Melhores práticas de segurança (p. 56)• Otimização de custo (p. 57)• Usar métricas para identificar problemas de desempenho (p. 57)• Cargas de trabalho TTL e temporais (p. 59)• Migrations (p. 60)• Trabalhar com grupos de parâmetros de cluster (p. 60)• Consultas de pipeline de agregação (p. 60)• batchInsert e batchUpdate (p. 60)

Diretrizes operacionais básicasAs diretrizes operacionais básicas a seguir devem ser seguidas por todos ao trabalhar com o AmazonDocumentDB. O Acordo de Nível de Serviço do Amazon DocumentDB requer que você siga essasdiretrizes.

• Implante um cluster com duas ou mais instâncias do Amazon DocumentDB em duas ou mais zonas dedisponibilidade da AWS. Para cargas de trabalho de produção, recomendamos implantar um cluster detrês ou mais instâncias do Amazon DocumentDB em três zonas de disponibilidade.

• Use o serviço dentro dos limites de serviço indicados. Para obter mais informações, consulte Cotas elimites do Amazon DocumentDB (p. 406).

• Monitore sua memória, CPU, conexões e uso de armazenamento. Para auxiliar a manutenção dodesempenho e da disponibilidade do sistema, configure o Amazon CloudWatch para lhe notificar quandoos padrões de uso mudarem ou quando você se aproximar da capacidade de implantação.

• Escale suas instâncias quando estiver se aproximando dos limites de capacidade. Suas instânciasdevem ser provisionadas com recursos computacionais suficientes (ou seja, RAM, CPU) para acomodaraumentos imprevistos na demanda de seus aplicativos.

• Defina seu período de retenção de backup para alinhar com seu objetivo de ponto de recuperação.• Teste o failover de seu cluster para entender quanto tempo o processo leva para seu caso de uso. Para

obter mais informações, consulte Failover do Amazon DocumentDB (p. 278).• Conecte-se ao cluster do Amazon DocumentDB com o endpoint do cluster (consulte Amazon

DocumentDBEndpoints do (p. 8)) e no modo de conjunto de réplicas (consulte Conectar-se ao Amazon

53

Amazon DocumentDB Guia do desenvolvedorDimensionamento de instância

DocumentDB como um conjunto de réplicas (p. 384)) para minimizar o impacto de um failover em seuaplicativo.

• Escolha uma configuração de preferência de leitura do driver que maximize a escalabilidade de leitura,sem deixar de atender aos requisitos de consistência de leitura de seu aplicativo. A preferência de leiturasecondaryPreferred permite leituras de réplica e libera a instância primária para trabalhar mais. Paraobter mais informações, consulte Opções de preferência de leitura (p. 12).

• Projete seu aplicativo para ser resistente no caso de erros de rede e banco de dados. Use o mecanismode erro do driver para distinguir entre erros transitórios e persistentes. Repita os erros transitóriosusando um mecanismo de recuo exponencial quando for apropriado. Certifique-se de que o seuaplicativo considerará a consistência de dados ao implementar a lógica da nova tentativa.

• Habilite a proteção contra exclusão de todos os clusters de produção ou de qualquer cluster que tenhadados valiosos. Antes de excluir um cluster do Amazon DocumentDB, faça um snapshot final. Se estiverimplantando recursos com o AWS CloudFormation, habilite a proteção contra encerramento. Para obtermais informações, consulte Proteção contra encerramento e exclusão (p. 51).

• Ao criar um Amazon DocumentDB , a versão --motor é um parâmetro opcional que repõe a versão maisrecente do motor. A versão atual do principal motor é 3.6.0. Quando forem lançadas novas versõesprincipais do motor, a versão predefinida do motor para --a versão do motor será atualizada pararefletir a versão principal do motor anterior. Como resultado, para volumes de trabalho de produção, eespecialmente aqueles que dependem de scripting, automatização ou AWS CloudFormation modelos,recomendamos que especifique explicitamente a versão --do motor para a versão principal pretendida.

Dimensionamento de instânciaUm dos aspetos mais críticos de escolher um tamanho de instância em Amazon DocumentDB é aquantidade de RAM para a sua cache. Amazon DocumentDB reserva um terço da RAM pelos seuspróprios serviços, o que significa que apenas dois terços da RAM da instância estão disponíveis paraa cache. Assim, é um Amazon DocumentDB para escolher um tipo de instância com RAM suficientepara o seu conjunto de trabalho (ou seja, dados e índices) na memória. Ter instâncias adequadamentedimensionadas ajuda a otimizar o desempenho geral e, potencialmente, minimizar o custo de E/S.

Para determinar se o conjunto de trabalho do aplicativo cabe na memória, monitore aBufferCacheHitRatio usando o Amazon CloudWatch para cada instância em um cluster que estejasob carga.

A métrica BufferCacheHitRatio do CloudWatch mede a porcentagem de dados e de índices atendidospor um cache de memória de instância (versus o volume de armazenamento). De modo geral, o valor deBufferCacheHitRatio deve ser o mais alto possível, pois a leitura de dados da memória do conjunto detrabalho é mais rápida e econômica do que a leitura do volume de armazenamento. Embora seja desejávelmanter a BufferCacheHitRatio mais próxima de 100%, o melhor valor possível dependerá dospadrões de acesso e dos requisitos de desempenho do aplicativo. Para manter a BufferCacheHitRatiomais alta possível, é recomendável que as instâncias do cluster sejam provisionadas com RAM suficientepara poder ajustar seus índices e conjunto de dados de trabalho na memória.

Se os seus índices não se encaixarem na memória, verá uma menor BufferCacheHitRatio. Aleitura contínua a partir do disco incorre em custos de E/S adicionais e não é tão eficaz como a leitura apartir da memória. Se sua proporção BufferCacheHitRatio for menor do que o esperado, aumenteo tamanho da instância do cluster para fornecer mais RAM para colocar os dados do conjunto detrabalho na memória. Se a ampliação da classe de instância resultar em um aumento drástico naBufferCacheHitRatio, o conjunto de trabalho do aplicativo não coube na memória. Continue aexpansão até que BufferCacheHitRatio não aumente mais consideravelmente após uma operação deescalabilidade. Para obter informações sobre como monitorar as métricas de instância, consulte AmazonDocumentDBMétricas do no (p. 341).

Dependendo dos requisitos de carga de trabalho e latência, pode ser aceitável que o aplicativotenha valores de BufferCacheHitRatio mais altos durante o uso em estado estável, mas que

54

Amazon DocumentDB Guia do desenvolvedorTrabalho com índices

BufferCacheHitRatio tenha períodos de queda periodicamente, pois consultas de análise queprecisam verificar uma coleção inteira são executadas em uma instância. Esses períodos de queda naBufferCacheHitRatio podem se manifestar como latência maior para consultas subsequentes queprecisam preencher novamente os dados do conjunto de trabalho do volume de armazenamento de voltapara o cache de buffer. Recomendamos que teste primeiro as suas cargas de trabalho num ambiente depré-produção com uma carga de trabalho de produção representativa para compreender as característicasde desempenho e BufferCacheHitRatio antes de implementar a carga de trabalho na produção.

A BufferCacheHitRatio é uma métrica específica da instância, portanto instâncias diferentes dentrodo mesmo cluster podem ter valores de BufferCacheHitRatio diferentes dependendo de como asleituras são distribuídas entre as instâncias principal e de réplica. Se a carga de trabalho operacional nãopuder lidar com aumentos periódicos de latência de preencher o cache do conjunto de trabalho novamenteapós a execução de consultas de análise, tente isolar o cache de buffer da carga de trabalho regular emrelação ao das consultas de análise. O isolamento completo da BufferCacheHitRatio pode ser obtidodirecionando consultas operacionais para a instância principal e consultas de análise somente para asinstâncias de réplica. Também é possível obter isolamento parcial direcionando consultas de análise parauma instância de réplica específica, entendendo que um percentual de consultas regulares também seráexecutado nessa réplica, podendo ser afetada.

Os valores de BufferCacheHitRatio adequados dependem do seu caso de uso e dos requisitosdo aplicativo. Não há nenhum valor melhor ou mínimo para essa métrica; somente você pode decidirse a compensação de uma BufferCacheHitRatio temporariamente mais baixa é aceitável de umaperspectiva de custo e desempenho.

Trabalho com índicesCriação de índicesAo importar dados para o Amazon DocumentDB, você deve criar seus índices antes de importar grandesconjuntos de dados. Você pode usar a ferramenta de índice do Amazon DocumentDB para extrair índicesde uma instância do MongoDB ou de um diretório mongodump em execução e criar esses índices em umcluster do Amazon DocumentDB. Para obter mais orientações sobre migrações, consulte Migrar para oAmazon DocumentDB (p. 103).

Seletividade do índiceRecomendamos que você limite a criação de índices a campos em que o número de valores duplicados éinferior a 1% do número total de documentos na coleção. Por exemplo, se sua coleção contiver 100.000documentos, crie índices somente em campos em que o mesmo valor ocorrer 1000 vezes ou menos.

Escolher um índice com um alto número de valores exclusivos (ou seja, uma alta cardinalidade) garanteque as operações de filtro retornem um pequeno número de documentos, gerando assim um bomdesempenho durante as verificações de índice. Um exemplo de índice de alta cardinalidade é um índiceexclusivo, que garante que predicados de igualdade retornem, no máximo, um documento. Exemplosde baixa cardinalidade incluem um índice sobre um campo booliano e um índice sobre o dia da semana.Devido a um desempenho insatisfatório, é improvável que índices de baixa cardinalidade sejam escolhidospelo otimizador de consultas do banco de dados. Ao mesmo tempo, índices de baixa cardinalidadecontinuam a consumir recursos como espaço em disco e E/S. Como regra geral, você deve direcionaríndices a campos em que a frequência típica do valor é de 1%, ou menos, do tamanho total da coleção.

Além disso, é recomendável criar apenas índices em campos comumente usados como filtro e procurarregularmente índices não usados. Para obter mais informações, consulte How Do I Identify UnusedIndexes? (p. 426).

55

https://github.com/awslabs/amazon-documentdb-tools

Amazon DocumentDB Guia do desenvolvedorImpacto dos índices na gravação de dados

Impacto dos índices na gravação de dadosEmbora os índices possam melhorar o desempenho da consulta evitando a necessidade de digitalizartodos os documentos em uma coleção, essa melhoria tem com uma compensação. Para cada índiceem uma coleção, sempre que um documento é inserido, atualizado ou excluído, o banco de dados deveatualizar a coleção e gravar os campos em cada um dos índices da coleção. Por exemplo, se uma coleçãotiver nove índices, o banco de dados deverá executar dez gravações antes de confirmar a operaçãopara o cliente. Assim, cada índice adicional incorre em latência de gravação adicional, E/S e aumento noarmazenamento geral utilizado.

As instâncias de cluster precisam ser dimensionadas adequadamente para manter toda a memória doconjunto de trabalho. Isso evita a necessidade de ler continuamente páginas de índice do volume dearmazenamento, o que afeta negativamente o desempenho e gera custos de E/S mais altos. Para obtermais informações, consulte Dimensionamento de instância (p. 54).

Para obter um melhor desempenho, minimize o número de índices em suas coleções, adicionando apenasos índices necessários para melhorar o desempenho de consultas comuns. Embora as cargas de trabalhovariem, uma boa orientação é manter cada coleção com cinco índices ou menos.

Identificar índices ausentesIdentificar e remover índices ausentes é uma prática recomendada que deve ser realizada regularmente.Para obter mais informações, consulte How Do I Identify Missing Indexes? (p. 426).

Identificar índices não utilizadosIdentificar e remover índices não utilizados é uma prática recomendada que deve ser realizadaregularmente. Para obter mais informações, consulte How Do I Identify Unused Indexes? (p. 426).

Melhores práticas de segurançaPara práticas recomendadas de segurança, você deve usar contas do AWS Identity and AccessManagement (IAM) para controlar o acesso a operações de API do Amazon DocumentDB, especialmenteoperações que criam, modificam ou excluem recursos do Amazon DocumentDB. Esses recursos incluemclusters, grupos de segurança e grupos de parâmetros. Você também deve usar o IAM para controlarações que executam ações administrativas comuns, como fazer backup e restaurar clusters. Ao criarfunções do IAM, utilize o princípio do privilégio mínimo.

• Aplique o menor privilégio com o controle de acesso baseado em função (p. 144).• Atribua uma conta do IAM individual a cada pessoa que gerencia os recursos do Amazon DocumentDB.

Não use o usuário raiz da conta da AWS para gerenciar recursos do Amazon DocumentDB. Crie umusuário do IAM para todos os usuários, incluindo você mesmo.

• Conceda a cada usuário do IAM o conjunto mínimo de permissões necessárias para realizar suasfunções.

• Use grupos do IAM para gerenciar efetivamente permissões para vários usuários. Para obter maisinformações sobre o IAM, consulte o Guia do usuário do IAM. Para obter mais informações sobre asmelhores práticas do IAM, consulte Melhores práticas do IAM.

• Mude suas credenciais do IAM regularmente.• Configure o AWS Secrets Manager para girar automaticamente os segredos do Amazon DocumentDB.

Para obter mais informações, consulte Rotação do AWS Secrets Manager Secrets e Rotação desegredos do Amazon DocumentDB no Guia do usuário do AWS Secrets Manager.

56

https://docs.aws.amazon.com/IAM/latest/UserGuide/Welcome.html

https://docs.aws.amazon.com/IAM/latest/UserGuide/IAMBestPractices.html

https://docs.aws.amazon.com/secretsmanager/latest/userguide/rotating-secrets.html

https://docs.aws.amazon.com/secretsmanager/latest/userguide/rotating-secrets-documentdb.html


Amazon DocumentDB Guia do desenvolvedorOtimização de custo

• Conceda a cada usuário do Amazon DocumentDB o conjunto mínimo de permissões necessárias pararealizar suas funções. Para obter mais informações, consulte Restringir o acesso ao banco de dadosusando o controle de acesso baseado em função (funções internas) (p. 144).

• Use a Transport Layer Security (TLS) para criptografar os dados em trânsito e o AWS KMS paracriptografar os dados em repouso.

Otimização de custoAs melhores práticas a seguir podem ajudar você a gerenciar e minimizar os custos ao usar o AmazonDocumentDB. Para obter informações de definição de preço, consulte Definição de preço do AmazonDocumentDB (compatível com MongoDB) e Perguntas frequentes sobre o Amazon DocumentDB(compatível com MongoDB).

• Crie alertas de faturamento em limites de 50% e 75% de sua fatura esperada para o mês. Para obtermais informações sobre como criar alertas de faturamento, consulte Criar um alarme de faturamento.

• A arquitetura do Amazon DocumentDB separa armazenamento e computação, portanto, até mesmoum cluster de instância única é resiliente. O volume de armazenamento do cluster replica os dados deseis maneiras por três zonas de disponibilidade, proporcionando alta resiliência independentementeda quantidade de instâncias no cluster. Um cluster de produção típico tem três ou mais instânciaspara fornecer alta disponibilidade. No entanto, você pode otimizar os custos usando um cluster dedesenvolvimento de instância única quando a alta disponibilidade não é necessária.

• Para cenários de desenvolvimento e teste, interrompa um cluster quando ele não for mais necessárioe inicie o cluster quando o desenvolvimento for retomado. Para obter mais informações, consulteInterromper e iniciar um cluster do Amazon DocumentDB (p. 237).

• Tanto o TTL quanto os fluxos de alteração incorrem em E/S quando os dados são gravados, lidos eexcluídos. Se você tiver habilitado esses recursos, mas não os estiver utilizando em seu aplicativo,desabilitar os recursos pode ajudar a reduzir custos.

Usar métricas para identificar problemas dedesempenho

Para identificar problemas de desempenho causados por recursos insuficientes e outros gargalos comuns,você pode monitorar as métricas disponíveis para o cluster do Amazon DocumentDB.

Visualização de métricas de desempenhoÉ necessário monitorar as métricas de desempenho regularmente para ver os valores médio, máximoe mínimo de uma série de intervalos de tempo. Isso ajuda a identificar quando o desempenho estádegradado. Você também pode definir alarmes do Amazon CloudWatch para limites métricos específicospara que você seja alertado se eles forem atingidos.

Para solucionar problemas de desempenho, é importante entender o desempenho de linha de base dosistema. Depois de configurar um novo cluster e executá-lo com uma carga de trabalho típica, captureos valores médio, máximo e mínimo de todas as métricas de desempenho em diferentes intervalos (porexemplo, uma hora, 24 horas, 1 semana, 2 semanas). Isso dá a você uma ideia do que é normal. Issoajuda a obter comparações para as horas de operação de pico e fora de pico. Você pode usar essasinformações para identificar quando o desempenho está ficando abaixo dos níveis padrão.

Você pode visualizar métricas de desempenho usando o Console de gerenciamento da AWS ou a AWSCLI. Para obter mais informações, consulte as informações a seguir:

57



https://aws.amazon.com/documentdb/faqs/

https://aws.amazon.com/documentdb/faqs/

https://docs.aws.amazon.com//AmazonCloudWatch/latest/monitoring/monitor_estimated_charges_with_cloudwatch.html#creating_billing_alarm_with_wizard

Amazon DocumentDB Guia do desenvolvedorConfigurar um alarme CloudWatch

• Ver métricas de relógio de visão utilizando o Amazon DocumentDB Consola de gestão (p. 346)• Ver métricas de relógio de visão utilizando o AWS CLI (p. 348)

Configurar um alarme CloudWatchPara definir um alarme de CloudWatch, consulte Usar alarmes do Amazon CloudWatch no Guia do usuáriodo Amazon CloudWatch.

Avaliação de métricas de desempenhoUma instância tem várias categorias diferentes de métricas. Como você determina valores aceitáveisdepende dessa métrica.

CPU

• Utilização da CPU — A porcentagem da capacidade de processamento computacional utilizada.

Memory

• Memória disponível — quanta RAM está disponível na instância.• Uso de troca — Quanto espaço de troca é usado pela instância, em megabytes.

Operações de entrada/saída

• IOPS de leitura, IOPS de gravação— O número médio de operações de leitura ou gravação de disco porsegundo.

• Latência de leitura, Latência de gravação — O tempo médio de uma operação de leitura ou gravação emmilissegundos.

• Taxa de transferência de leitura, Taxa de transferência de gravação — O número médio de megabyteslido ou gravado no disco por segundo.

• Profundidade da fila de disco — o número de operações de E/S que aguarda pela gravação ou leitura nodisco.

Tráfego de rede

• Taxa de transferência de recepção de rede, Taxa de transferência de transmissão de rede — A taxa detráfego de rede para e a partir da instância em megabytes por segundo.

Conexões de banco de dados

• Conexões de banco de dados — O número de sessões do cliente que estão conectadas à instância dobanco de dados.

De um modo geral, os valores aceitáveis para as métricas de desempenho dependem do aspecto da linhade base e do que o aplicativo está fazendo. Investigue variações consistentes ou tendenciais de sua linhade base.

Veja a seguir recomendações e instruções sobre os tipos específicos de métricas:

• Alto consumo de CPU — valores altos para o consumo de CPU podem ser adequados, desde queestejam de acordo com seus objetivos em relação ao aplicativo (como taxa de transferência ou

58

https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/AlarmThatSendsEmail.html

Amazon DocumentDB Guia do desenvolvedorAjuste das consultas

concorrência). Se o seu consumo de CPU for consistentemente superior a 80%, considere dimensionarsuas instâncias.

• Alto consumo de RAM— se sua métrica FreeableMemory ficar abaixo de um terço da memória totalda instância, considere dimensionar suas instâncias.

• Uso de troca— essa métrica deve permanecer em ou perto de zero. Se o uso de troca for significativo,considere dimensionar suas instâncias.

• Tráfego de rede — em relação ao tráfego de rede, fale com o administrador do sistema para entenderqual taxa de transferência é esperada para sua rede de domínio e conexão com a Internet. Inspecione otráfego de rede caso a taxa de transferência seja consistentemente menor do que a esperada.

• Conexões do banco de dados — considere restringir as conexões do banco de dados caso perceba umalto número de conexões de usuários em conjunto com uma diminuição no desempenho da instânciae no tempo de resposta. O melhor número de conexões de usuários para sua instância varia conformea classe da instância e a complexidade das operações em execução. Para problemas com qualquermétrica de desempenho, uma das primeiras coisas que você pode fazer para melhorar o desempenho éajustar as consultas mais utilizadas e mais caras para ver se isso reduz a pressão sobre os recursos dosistema.

Se suas consultas forem ajustadas e o problema persistir, considere atualizar sua instância de classe doAmazon DocumentDB para uma que tenha mais do recurso (CPU, RAM, espaço em disco, largura debanda de rede, capacidade de E/S) que está relacionado ao problema enfrentado.

Ajuste das consultasUm dos melhores jeitos de melhorar o desempenho do cluster é ajustar as consultas mais utilizadas e querequerem mais recursos para baixar o custo de operação delas.

É possível usar o profiler (consulte Profiling Amazon DocumentDB Operations (p. 352)) para registraro tempo de execução e detalhes das operações executadas em seu cluster. O profiler é útil para omonitoramento das operações mais lentas em seu cluster, aprimorando o desempenho individual deconsultas e o desempenho geral do cluster.

Também é possível usar o comando explain para aprender a analisar um plano de consulta para umaconsulta específica. É possível usar essas informações para modificar uma consulta ou uma coleçãosubjacente a fim de melhorar o desempenho da consulta (por exemplo, adicionar um índice).

Cargas de trabalho TTL e temporaisA exclusão de documentos resultante da expiração do índice TTL é um processo de best effort. Não hágarantia de que os documentos serão excluídos dentro de um período específico. Fatores como tamanhode instância, utilização de recursos de instância, tamanho do documento, taxa de transferência geral,número de índices e se os índices e o conjunto de trabalho cabem na memória podem afetar o momentoem que os documentos expirados são excluídos pelo processo TTL.

Quando o monitor TTL exclui seus documentos, cada exclusão resulta em custos de E/S, o que aumentasua fatura. Se as taxas de transferência e exclusão de TTL aumentarem, você deverá esperar umafatura mais alta devido ao aumento do uso de E/S. No entanto, se não criar um índice TTL para eliminardocumentos, em vez disso, segmente os documentos em coleções com base no tempo e simplesmentelargue essas coleções quando já não forem necessárias, não incorrerá em quaisquer custos de E/S. Istopode ser significativamente mais económico do que utilizar um índice TTL.

Para cargas de trabalho temporais, você pode considerar a criação de coleções contínuas em vez deum índice TTL, pois as coleções contínuas podem ser uma maneira mais eficiente de excluir dados econsomem menos E/S. Se você tiver coleções grandes (especialmente coleções acima de 1 TB) ou oscustos de E/S de exclusão de TTL forem uma preocupação, recomendamos a partição de documentos

59

Amazon DocumentDB Guia do desenvolvedorMigrations

em coleções com base no tempo e o descarte de coleções quando os documentos não forem maisnecessários. É possível criar uma coleção por dia ou uma por semana, dependendo da taxa de ingestãode dados. Embora os requisitos variem dependendo do aplicativo, uma boa regra é ter mais coleçõesmenores em vez de algumas coleções grandes. A eliminação dessas coleções não resulta em custos de E/S e pode ser mais rápida e mais econômica do que o uso de um índice TTL.

MigrationsComo prática recomendada, ao migrar dados para o Amazon DocumentDB, recomendamos que vocêcrie seus índices no Amazon DocumentDB antes de migrá-los. Criar os índices primeiro pode reduzir otempo geral e aumentar a velocidade da migração. Para o fazer, pode utilizar o Amazon DocumentDBFerramenta de índice. Para obter mais informações sobre migrações, consulte o Guia de migração doAmazon DocumentDB.

Também recomendamos que, antes de migrar a sua base de dados de produção, seja uma boaprática testar a sua aplicação na Amazon DocumentDB, levando em consideração a funcionalidade, odesempenho, as operações e o custo.

Trabalhar com grupos de parâmetros de clusterRecomendamos que você experimente fazer mudanças de grupo de parâmetros do cluster em um clusterde teste antes de aplicar as alterações em seus clusters de produção. Para obter informações sobre obackup do cluster, consulte Backup e restauração no Amazon DocumentDB (p. 175).

Consultas de pipeline de agregaçãoAo criar uma consulta de pipeline de agregação com vários estágios e avaliar apenas um subconjunto dedados na consulta, use o estágio $match como o primeiro estágio ou no início do pipeline. Usar $matchprimeiro reduz o número de documentos que as etapas subsequentes dentro da consulta de pipeline deagregação precisarão processar, melhorando assim o desempenho da consulta.

batchInsert e batchUpdateAo executar uma alta taxa de batchUpdate e/ou de operações batchInsert simultâneas e aquantidade de FreeableMemory (métrica do CloudWatch) atingir zero na instância principal, você podereduzir a simultaneidade da inserção de lote ou atualizar a carga de trabalho ou, se a simultaneidade dacarga de trabalho não puder ser reduzida, aumentar o tamanho da instância para aumentar a quantidadede FreeableMemory.

60


https://docs.aws.amazon.com/documentdb/latest/developerguide/docdb-migration.html

https://docs.aws.amazon.com/documentdb/latest/developerguide/docdb-migration.html

Amazon DocumentDB Guia do desenvolvedorBenefícios funcionais do Amazon DocumentDB

Diferenças funcionais: AmazonDocumentDB e MongoDB

Veja a seguir as diferenças funcionais entre o Amazon DocumentDB (compatível com MongoDB) e oMongoDB.

Tópicos• Benefícios funcionais do Amazon DocumentDB (p. 61)• Diferenças funcionais atualizadas (p. 62)• Diferenças funcionais com o MongoDB (p. 64)

Benefícios funcionais do Amazon DocumentDBTransações implícitasEm Amazon DocumentDB, todas as declarações CRUD (findAndModify, update, insert, delete)garantir a atomidade e consistência, mesmo para operações que modifiquem vários documentos. Essecomportamento é diferente do MongoDB 3.6, que fornece apenas garantias atômicas para comandosque modificam um único documento. Veja a seguir exemplos de operações no Amazon DocumentDB quemodificam vários documentos que satisfazem ambos os comportamentos atômico e consistente.

db.miles.update( { "credit_card": { $eq: true } }, { $mul: { "flight_miles.$[]": NumberInt(2) } }, { multi: true })

db.miles.updateMany( { "credit_card": { $eq: true } }, { $mul: { "flight_miles.$[]": NumberInt(2) } })

db.runCommand({ update: "miles", updates: [ { q: { "credit_card": { $eq: true } }, u: { $mul: { "flight_miles.$[]": NumberInt(2) } }, multi: true } ]})

db.products.deleteMany({ "cost": { $gt: 30.00 }})

61

Amazon DocumentDB Guia do desenvolvedorDiferenças funcionais atualizadas

db.runCommand({ delete: "products", deletes: [{ q: { "cost": { $gt: 30.00 } }, limit: 0 }]})

As operações individuais que compõem operações a granel, tais como updateMany e deleteManysão atómicos mas todo o funcionamento a granel não é atómico. Por exemplo, a totalidade da operaçãoinsertMany será atômica se as operações de inserção individuais forem executadas com êxitosem erros. Se for encontrado um erro com um insertMany operação, cada declaração individual noinsertMany funciona como uma operação atómica.

Amazon DocumentDB atualmente suporta semânticos transacionais implícitos para operações dedeclaração única, como mostrado anteriormente. Amazon DocumentDB actualmente não suportatransações multiextrato.

Diferenças funcionais atualizadasAmazon DocumentDBO continua a melhorar a compatibilidade com o MongoDB, trabalhandoretroativamente com as capacidades que nossos clientes nos pedem para criar. Esta seção contém asdiferenças funcionais removidas do Amazon DocumentDB para facilitar as migrações e a criação deaplicativos para nossos clientes.

Tópicos• Indexação de matriz (p. 62)• Índices de várias chaves (p. 63)• Caracteres nulos em strings (p. 63)• Controle de acesso com base em função (p. 63)• $regexIndexação (p. 64)

Indexação de matrizA partir de 23 de abril de 2020, o Amazon DocumentDB passa a oferecer suporte à capacidade de indexarmatrizes maiores que 2.048 bytes. O limite para um item individual numa matriz continua a ser de 2048bytes, o que é consistente com a mongodb.

Se você estiver criando um novo índice, nenhuma ação será necessária para aproveitar a funcionalidadeaprimorada. Se tiver um índice existente, você pode aproveitar a funcionalidade aprimorada, eliminando oíndice e recriando-o. A versão atual do índice com os recursos aprimorados é "v" : 3.

Note

Para clusters de produção, a eliminação do índice pode ter impacto no desempenho do aplicativo.Recomendamos que você teste primeiro e prossiga com cuidado ao fazer alterações em umsistema de produção. Além disso, o tempo que levará para recriar o índice será uma função dotamanho geral dos dados da coleção.

É possível consultar a versão dos índices usando o seguinte comando.

db.collection.getIndexes()

A saída dessa operação é semelhante à seguinte. Nesta saída, a versão do índice é "v" : 3, que é aversão mais atual.

62

Amazon DocumentDB Guia do desenvolvedorÍndices de várias chaves

[ { "v" : 3, "key" : { "_id" : 1 }, "name" : "_id_", "ns" : "test.test" }]

Índices de várias chavesA partir de 23 de abril de 2020, o Amazon DocumentDB passa a oferecer suporte à capacidade de criar umíndice composto com várias chaves na mesma matriz.

Se você estiver criando um novo índice, nenhuma ação será necessária para aproveitar a funcionalidadeaprimorada. Se tiver um índice existente, você pode aproveitar a funcionalidade aprimorada, eliminando oíndice e recriando-o. A versão atual do índice com os recursos aprimorados é "v" : 3.

Note

Para clusters de produção, a eliminação do índice pode ter impacto no desempenho do aplicativo.Recomendamos que você teste primeiro e prossiga com cuidado ao fazer alterações em umsistema de produção. Além disso, o tempo que levará para recriar o índice será uma função dotamanho geral dos dados da coleção.

É possível consultar a versão dos índices usando o seguinte comando.


A saída dessa operação é semelhante à seguinte. Nesta saída, a versão do índice é "v" : 3, que é aversão mais atual.

[ { "v" : 3, "key" : { "_id" : 1 }, "name" : "_id_", "ns" : "test.test" }]

Caracteres nulos em stringsA partir de 22 de Junho de 2020, Amazon DocumentDB agora suporta caracteres nulos ( '\0' ) emcadeias.

Controle de acesso com base em funçãoDesde 26 de março de 2020, o Amazon DocumentDB oferece suporte ao controle de acesso baseadoem função (RBAC) para funções internas. Para saber mais, consulte Controle de acesso com base emfunção (p. 144). Amazon DocumentDB ainda não suporta funções personalizadas para RBAC.

63

Amazon DocumentDB Guia do desenvolvedor$regexIndexação

$regexIndexaçãoA partir de 22 de Junho de 2020, Amazon DocumentDB agora suporta a capacidade de $regexoperadores para utilizar um índice.

Para utilizar um índice com o $regex operador, tem de utilizar o hint() comando. Quando utilizarhint(), tem de especificar o nome do campo onde está a aplicar o $regex em. Por exemplo, setiver um índice no campo product com o nome do índice como p_1, db.foo.find({product: /^x.*/}).hint({product:1}) irá utilizar o p_1 índice, mas db.foo.find({product: /^x.*/}).hint(“p_1”) não utilizará o índice. É possível verificar se um índice é escolhido utilizandoo comando explain() ou usando o profiler para registrar em log consultas lentas. Por exemplo,db.foo.find({product: /^x.*/}).hint(“p_1”).explain().

Note

O método hint() só pode ser usado com um índice de cada vez.

A utilização de um índice para um $regex a consulta está optimizada para consultas regex que utilizamum prefixo e não especifica o I, m, ou o opções de regex.

Ao usar um índice com $regex, é recomendável criar um índice em campos altamente seletivos onde onúmero de valores duplicados é inferior a 1% do número total de documentos na coleção. Por exemplo,se sua coleção contiver 100.000 documentos, crie índices somente em campos em que o mesmo valorocorrer 1000 vezes ou menos.

Diferenças funcionais com o MongoDBTópicos

• Bancos de dados e coleções de administradores (p. 64)• explain() (p. 64)• Restrições de nome de campo (p. 65)• Compilações de índice (p. 65)• APIs, operações e tipos de dados do MongoDB (p. 65)• O mongodump e mongorestore Serviços públicos (p. 65)• Ordenação de resultados (p. 66)• Gravações que podem ser recuperadas (p. 66)• Índice esparso (p. 66)• Compactação de armazenamento (p. 66)• Usar $elemMatch em uma expressão $all (p. 67)• $distinct, $elemMatch, e $lookup Indexação (p. 67)• $lookup (p. 67)

Bancos de dados e coleções de administradoresAmazon DocumentDB não suporta a base de dados administrativa ou local nem a mongodb system.* oustartup_log recolhas, respetivamente.

explain()Amazon DocumentDBO emula a API do MongoDB 3.6 em um mecanismo de banco de dadoscriado especificamente que utiliza um sistema de armazenamento distribuído, tolerante a falhas e de

64

Amazon DocumentDB Guia do desenvolvedorRestrições de nome de campo

autorrecuperação. Como resultado, planos de consulta e a saída de explain() pode diferir entre AmazonDocumentDB e mongodb. Os clientes que desejam ter controle sobre seu plano de consulta podem usar ooperador $hint para impor a seleção de um índice preferencial.

Restrições de nome de campoAmazon DocumentDB não suporta pontos “.” num nome de campo de documento, por exemplo,db.foo.insert({‘x.1’:1}).

Amazon DocumentDB também não suporta o prefixo $ nos nomes dos campos.

Por exemplo, tente o seguinte comando em Amazon DocumentDB ou mongodb:

rs0:PRIMARY< db.foo.insert({"a":{"$a":1}})

a mongodb irá devolver o seguinte:


Amazon DocumentDB irá devolver um erro:

WriteResult({"nInserted" : 0,"writeError" : {"code" : 2,"errmsg" : "Document can't have $ prefix field names: $a"}})

Note

Existe uma excepção a esta diferença funcional. Os seguintes nomes de campo que começamcom o prefixo $ foram apresentados em branco e podem ser utilizados com sucesso nodocumento Amazon documentdb: $id, $ref e $db.

Compilações de índiceAmazon DocumentDBO permite que apenas uma compilação de índice ocorra em uma coleção a qualquermomento (de primeiro ou segundo plano). Em caso de operações, tais como createIndex() oudropIndex() ocorre na mesma coleção quando uma construção de índice está actualmente em curso, aoperação recém-tentativa irá falhar.

O índice Vida útil (TTL) começa a expirar documentos após a compilação do índice (em primeiro ousegundo plano) ser concluída.

APIs, operações e tipos de dados do MongoDBAmazon DocumentDBO é compatível com a API do MongoDB 3.6. Para obter uma lista atualizadadas funcionalidades compatíveis, consulte APIs, operações e tipos de dados do MongoDBcompatíveis (p. 85).

O mongodump e mongorestore Serviços públicosAmazon DocumentDB não suporta uma base de dados de administrador e, assim, não é possível eliminarou restaurar a base de dados de administrador ao utilizar o mongodump ou mongorestore utilitários.

65

Amazon DocumentDB Guia do desenvolvedorOrdenação de resultados

Quando cria uma nova base de dados em Amazon DocumentDB utilizar mongorestore, tem de recriar asfunções do utilizador para além da operação de restauro.

Ordenação de resultadosAmazon DocumentDBO não garante a ordenação de resultados implícita dos conjuntos de resultados.Para garantir a ordenação de um conjunto de resultados, especifique explicitamente uma ordem declassificação usando sort().

O exemplo a seguir classifica os itens na coleção de inventário em ordem decrescente com base no campode estoque.

db.inventory.find().sort({ stock: -1 })

Gravações que podem ser recuperadasA partir dos drivers compatíveis com o MongoDB 4.2, as gravações repetíveis são ativadas por padrão.No entanto, o Amazon DocumentDB atualmente não oferece suporte a gravações repetíveis. A diferençafuncional se manifestará em uma mensagem de erro semelhante à seguinte.

{"ok":0,"errmsg":"Unrecognized field: 'txnNumber'","code":9,"name":"MongoError"}

Gravações repetíveis que podem ser desabilitadas por meio da string de conexão (por exemplo,MongoClient("mongodb://my.mongodb.cluster/db?retryWrites=false")) ou doargumento de palavra-chave do construtor MongoClient (por exemplo, MongoClient("mongodb://my.mongodb.cluster/db", retryWrites=False)).

Veja a seguir um exemplo de Python que desabilita gravações repetíveis na string de conexão.

client = pymongo.MongoClient('mongodb://<username>:<password>@docdb-2019-03-17-16-49-12.cluster-ccuszbx3pn5e.us-east-1.docdb.amazonaws.com:27017/?replicaSet=rs0',w='majority',j=True,retryWrites=False)

Índice esparsoPara usar um índice esparso que você criou em uma consulta, é necessário usar a cláusula $exists noscampos que abrangem o índice. Se omitir $exists, Amazon DocumentDB não utiliza o índice espaçado.

Veja um exemplo do a seguir:

db.inventory.count({ "stock": { $exists: true }})

Para índices esparsos de várias chaves, o Amazon DocumentDB não oferecerá suporte a uma restriçãode chave exclusiva se a pesquisa de um documento resultar em um conjunto de valores e apenas umsubconjunto dos campos indexados estiver ausente. Por exemplo, createIndex({"a.b" : 1 },{ unique : true, sparse :true }) não é suportado, dada a entrada de "a" : [ { "b" : 2 },{ "c" : 1 } ], como "a.c" é guardado no índice.

Compactação de armazenamentoAmazon DocumentDBO não oferece suporte à compactação para dados ou índices armazenados. Otamanho dos dados para dados e índices armazenados poderá ser maior do que ao usar outras opções.

66

Amazon DocumentDB Guia do desenvolvedorUsar $elemMatch em uma expressão $all

Usar $elemMatch em uma expressão $allAmazon DocumentDB não suporta atualmente a utilização do $elemMatch operador dentro de um $allexpressão. Como uma alternativa, pode utilizar o $and operador com $elemMatch a seguir.

Operação original:

db.col.find({ qty: { $all: [ { "$elemMatch": { part: "xyz", qty: { $lt: 11 } } }, { "$elemMatch": { num: 40, size: "XL" } } ] }})

Operação atualizada:

db.col.find({ $and: [ { qty: { "$elemMatch": { part: "xyz", qty: { $lt: 11 } } } }, { qty: { "$elemMatch": { qty: 40, size: "XL" } } } ]})

$distinct, $elemMatch, e $lookup IndexaçãoAmazon DocumentDB não suporta atualmente a capacidade de utilizar índices com o $distinct,$elemMatch, e $lookup operadores. Como resultado, a utilização desses operadores resultará emverificação da coleção. Executar um filtro ou correspondência antes de utilizar um desses operadoresreduzirá a quantidade de dados que precisam ser verificados e, portanto, pode melhorar o desempenho.

$lookupAmazon DocumentDBO oferece suporte para correspondências de igualdade (por exemplo, junção externaesquerda), mas não oferece suporte para subconsultas não correlacionadas.

67

Amazon DocumentDB Guia do desenvolvedorConsultar documentos

QueryingEsta secção explica todos os aspectos de consultar Amazon DocumentDB.

Tópicos• Consultar documentos (p. 68)• Plano de consulta (p. 79)• Explicar resultados (p. 80)

Consultar documentosÀs vezes, pode ser necessário examinar o inventário da sua loja online para que os clientes possamvisualizar e comprar o que você está vendendo. Consultar uma coleção é relativamente fácil, quer vocêqueira todos os documentos na coleção ou apenas os documentos que satisfazem a um critério específico.

Para consultar os documentos, utilize o find() operação. O comando find() tem um único parâmetrodo documento que define os critérios a serem usados na escolha dos documentos a serem retornados. Asaída de find() é um documento formatado como uma única linha de texto sem quebras de linha. Paraformatar o documento de saída para uma leitura mais fácil, utilize find().pretty(). Todos os exemplosdesta utilização de tópico .pretty() para formatar a saída.

As amostras de código seguintes utilizam os quatro documentos que inseriu no example recolha nosdois exercícios anteriores — insertOne() e insertMany() que estão localizados na secção AdicionarDocumentos de

Como um banco de dados de documentos, o Amazon DocumentDB facilita o armazenamento,a consulta e a indexação de dados JSON. No Amazon DocumentDB, uma coleção de bancode dados de documentos é semelhante a uma tabela em um banco de dados relacional, excetopelo fato de não haver um único esquema aplicado a todos os documentos. As coleçõespermitem agrupar documentos semelhantes, mantendo-os todos no mesmo banco de dados,sem exigir que eles tenham a estrutura idêntica.

Usando os exemplos de documentos das seções anteriores, é provável que você tenhacoleções de reading_material e office_supplies. É função do software impor a quecoleção um documento pertence.

Os exemplos a seguir usam a API do MongoDB para mostrar como adicionar, consultar,atualizar e excluir documentos.

Tópicos

• Como adicionar documentos (p. 23)• Consultar documentos (p. 25)• Como atualizar documentos (p. 27)• Como excluir documentos (p. 31)

Como adicionar documentosNo Amazon DocumentDB, um banco de dados é criado quando você adiciona um documentoa uma coleção. Neste exemplo, você está criando uma coleção chamada example no bancode dados test, que é o banco de dados padrão quando ao conectar-se a um cluster. Como

68


a conexão é criada implicitamente quando o primeiro documento é inserido, não há erroao verificar o nome da coleção. Portanto, um erro de digitação no nome da coleção, comoeexample em vez de example, criará e adicionará o documento à coleção eexample em vezde à coleção pretendida. A verificação de erros deve ser processada pelo seu aplicativo.

Os exemplos a seguir usam a API do MongoDB para adicionar documentos.

Tópicos

• Como adicionar um único documento (p. 24)• Como adicionar diversos documentos (p. 24)

Como adicionar um único documento

Para adicionar um único documento a uma coleção, use a operação insertOne( {} ) como documento que você deseja adicionar à coleção.

db.example.insertOne(

{

"Item": "Ruler",

"Colors": ["Red","Green","Blue","Clear","Yellow"],

"Inventory": {

"OnHand": 47,

"MinOnHand": 40

},

"UnitPrice": 0.89

}

)


{

"acknowledged" : true,

"insertedId" : ObjectId("5bedafbcf65ff161707de24f")

}

Como adicionar diversos documentos

Para adicionar diversos documentos a uma coleção, use a operaçãoinsertMany( [{},...,{}] ) com uma lista dos documentos que você deseja adicionarà coleção. Embora os documentos nessa lista específica tenham esquemas diferentes, todoseles podem ser adicionados à mesma coleção.

db.example.insertMany(

[

{

"Item": "Pen",

"Colors": ["Red","Green","Blue","Black"],

"Inventory": {

"OnHand": 244,

"MinOnHand": 72

}

},

{

"Item": "Poster Paint",

"Colors": ["Red","Green","Blue","Black","White"],

"Inventory": {

"OnHand": 47,

"MinOnHand": 50

}

69


},

{

"Item": "Spray Paint",

"Colors": ["Black","Red","Green","Blue"],

"Inventory": {

"OnHand": 47,

"MinOnHand": 50,

"OrderQnty": 36

}

}

]

)


{

"acknowledged" : true,

"insertedIds" : [

ObjectId("5bedb07941ca8d9198f5934c"),

ObjectId("5bedb07941ca8d9198f5934d"),

ObjectId("5bedb07941ca8d9198f5934e")

]

}

Consultar documentosÀs vezes, pode ser necessário examinar o inventário da sua loja online para que osclientes possam visualizar e comprar o que você está vendendo. Consultar uma coleçãoé relativamente fácil, quer você queira todos os documentos na coleção ou apenas osdocumentos que satisfazem a um critério específico.

Para consultar documentos, use a operação find(). O comando find() tem um únicoparâmetro do documento que define os critérios a serem usados na escolha dos documentosa serem retornados. A saída de find() é um documento formatado como uma única linha detexto sem quebras de linha. Para formatar o documento de saída para facilitar a leitura, usefind().pretty(). Todos os exemplos deste tópico usam .pretty() para formatar a saída.

Use os quatro documentos inseridos na coleção example nos últimos dois exercícios —insertOne() e insertMany().

Tópicos

• Como recuperar todos os documentos em uma coleção (p. 25)• Como recuperar documentos que correspondem a um valor de campo (p. 25)• Como recuperar documentos que correspondem a um documento incorporado (p. 26)• Como recuperar documentos que correspondem a um valor de campo em um documento


Como recuperar todos os documentos em uma coleção

Para recuperar todos os documentos em sua coleção, use a operação find() com umdocumento de consulta vazio.

A consulta a seguir retorna todos os documentos da coleção example.

70



Como recuperar documentos que correspondem a um valor de campo

Para recuperar todos os documentos que correspondem a um campo e valor, use a operaçãofind() com um documento de consulta que identifica os campos e valores a seremcorrespondidos.

Usando documentos anteriores, essa consulta retorna todos os documentos em que o campo"Item" será igual a "Pen".


Como recuperar documentos que correspondem a um documentoincorporado

Para localizar todos os documentos que correspondem a um documento incorporado, usea operação find() com um documento de consulta que especifica o nome do documentoincorporado e todos os campos e valores desse documento incorporado.

Ao vincular um documento incorporado, o documento incorporado do documento deve ter omesmo nome que na consulta. Além disso, os campos e os valores no documento incorporadodevem corresponder à consulta.

A consulta a seguir retorna apenas o documento "Poster Paint". Isso ocorre porque o "Pen"tem valores diferentes para "OnHand" e "MinOnHand", e o "Spray Paint" tem um campo a mais(OrderQnty) que o documento de consulta.

db.example.find({"Inventory": {

"OnHand": 47,

"MinOnHand": 50 } } ).pretty()

Como recuperar documentos que correspondem a um valor de campoem um documento incorporado

Para localizar todos os documentos que correspondem a um documento incorporado, usea operação find() com um documento de consulta que especifica o nome do documentoincorporado e todos os campos e valores desse documento incorporado.

Considerando os documentos anteriores, a consulta a seguir usa "notação de pontos" paraespecificar o documento incorporado e os campos de interesse. Qualquer documento que sejacorrespondente será retornado, independentemente de quais outros campos possam estarpresentes no documento incorporado. A consulta retorna "Poster Paint" e "Spray Paint", poisambos correspondem aos campos e valores especificados.


Como recuperar documentos que correspondem a uma matriz

Para localizar todos os documentos que correspondem a uma matriz, use a operação find()com o nome da matriz de interesse e todos os valores na matriz. A consulta retorna todos osdocumentos que têm uma matriz com esse nome, com valores idênticos aos da matriz, e namesma ordem que na consulta.

A consulta a seguir retorna apenas o documento "Pen", pois o "Poster Paint" tem uma coradicional (White), e "Spray Paint" tem as cores em ordem diferente.71



Como recuperar documentos que correspondem a um valor em umamatriz

Para localizar todos os documentos que possuem um valor de matriz específico, use aoperação find() com o valor e o nome da matriz de interesse.


A operação anterior retorna todos os três documentos, pois cada um deles tem uma matrizchamada Colors e o valor Red em algum lugar da matriz. Se você especificar o valor"White", a consulta retornará apenas "Poster Paint".

Recuperação de documentos usando operadores

A consulta a seguir retorna todos os documentos em que o valor "Inventory.OnHand" éinferior a 50.

db.example.find(

{ "Inventory.OnHand": { $lt: 50 } } )

Para obter uma lista de operadores de consulta compatíveis, consulte Operadores de consultae projeção (p. 89).

Como atualizar documentosNormalmente, seus documentos não são estáticos e são atualizados como parte de seusfluxos de trabalho de aplicativos. Os exemplos a seguir mostram algumas maneiras de comoatualizar documentos.

Para atualizar um documento existente, use a operação update(). A operação update()tem dois parâmetros de documento. O primeiro documento identifica qual(is) documento(s)atualizar. O segundo documento especifica as atualizações a fazer.

Ao atualizar um campo existente — seja esse campo um campo simples, uma matriz ou umdocumento incorporado — você especifica o nome do campo e seus valores. No final daoperação, é como se o campo no documento antigo tivesse sido substituído pelo novo campo epor novos valores.

Tópicos

• Como atualizar os valores de um campo existente (p. 27)• Como adicionar um novo campo (p. 29)• Substituição de um documento incorporado (p. 29)• Como inserir novos campos a um documento incorporado (p. 30)• Como remover um campo de um documento (p. 30)• Remover um campo de vários documentos (p. 31)

Como atualizar os valores de um campo existente

Use os quatro documentos a seguir, que você adicionou anteriormente, para as seguintesoperações de atualização.

72


{

"Item": "Ruler",

"Colors": ["Red","Green","Blue","Clear","Yellow"],

"Inventory": {

"OnHand": 47,

"MinOnHand": 40

},

"UnitPrice": 0.89

},

{

"Item": "Pen",


"Inventory": {

"OnHand": 244,

"MinOnHand": 72

}

},

{


"Colors": ["Red","Green","Blue","Black","White"],

"Inventory": {

"OnHand": 47,

"MinOnHand": 50

}

},

{



"Inventory": {

"OnHand": 47,

"MinOnHand": 50,

"OrderQnty": 36

}

}

Para atualizar um campo simples

Para atualizar um campo simples, use update() com $set para especificar o nome e o novovalor do campo. O exemplo a seguir altera o Item de "Pen" para "Gel Pen".

db.example.update(

{ "Item" : "Pen" },

{ $set: { "Item": "Gel Pen" } }

)


{

"Item": "Gel Pen",


"Inventory": {

"OnHand": 244,

"MinOnHand": 72

}

}

Para atualizar uma matriz

O exemplo a seguir substitui a matriz de cores existente por uma nova matriz que incluiOrange e descarta White da lista de cores. A nova lista de cores está na ordem especificadana operação update().

73


db.example.update(

{ "Item" : "Poster Paint" },

{ $set: { "Colors": ["Red","Green","Blue","Orange","Black"] } }

)


{


"Colors": ["Red","Green","Blue","Orange","Black"],

"Inventory": {

"OnHand": 47,

"MinOnHand": 50

}

}

Como adicionar um novo campo

Para modificar um documento adicionando um ou mais novos campos, use a operaçãoupdate() com um documento de consulta que identifica o documento a ser inserido e osnovos campos e valores a serem inseridos usando o operador $set.

O exemplo a seguir adiciona o campo UnitPrice com o valor 3.99 para o documento SprayPaints. Observe que o valor 3.99 é numérico, e não uma string.

db.example.update(

{ "Item": "Spray Paint" },

{ $set: { "UnitPrice": 3.99 } }

)

Os resultados dessa operação são semelhantes ao seguinte (formato JSON).

{



"Inventory": {

"OnHand": 47,

"MinOnHand": 50,

"OrderQnty": 36

},

"UnitPrice": 3.99

}

Substituição de um documento incorporado

Para modificar um documento substituindo um documento incorporado, use a operaçãoupdate() com documentos que identificam o documento incorporado e seus novos campos evalores com o uso do operador $set.

Considerando o seguinte documento.

db.example.insert({

"DocName": "Document 1",

"Date": {

"Year": 1987,

"Month": 4,

"Day": 18

}

74


})

Substituir um documento incorporado

O exemplo a seguir substitui o documento de data atual por um novo que tem somente oscampos Month e Day. O campo Year foi eliminado.

db.example.update(

{ "DocName" : "Document 1" },

{ $set: { "Date": { "Month": 4, "Day": 18 } } }

)


{


"Date": {

"Month": 4,

"Day": 18

}

}

Como inserir novos campos a um documento incorporado

Como adicionar campos a um documento incorporado

Para modificar um documento adicionando um ou mais novos campos a um documentoincorporado, use a operação update() com documentos que identificam o documentoincorporado e "notação de pontos" para especificar o documento incorporado e os novoscampos e valores a serem inseridos usando o operador $set.

Considerando o documento a seguir, o código usa a "notação de pontos" para inserir oscampos Year e DoW no documento Date incorporado, e Words no documento pai.

{


"Date": {

"Month": 4,

"Day": 18

}

}

db.example.update(


{ $set: { "Date.Year": 1987,

"Date.DoW": "Saturday",

"Words": 2482 } }

)


{


"Date": {

"Month": 4,

"Day": 18,

"Year": 1987,

"DoW": "Saturday"

75


},

"Words": 2482

}

Como remover um campo de um documento

Para modificar um documento removendo um campo do documento, use a operaçãoupdate() com um documento de consulta que identifica o campo a ser removido dodocumento e o operador $unset para especificar o campo a ser removido.

O exemplo a seguir remove o campo Words do documento anterior.

db.example.update(


{ $unset: { Words:1 } }

)


{


"Date": {

"Month": 4,

"Day": 18,

"Year": 1987,

"DoW": "Saturday"

}

}

Remover um campo de vários documentos

Para modificar um documento removendo um campo de vários documentos, use a operaçãoupdate() com o operador $unset e a opção multi definida como true.

O exemplo a seguir remove o campo Inventory de todos os documentos na coleção deexemplo. Se um documento não tiver o campo Inventory, nenhuma ação será executadanesse documento. Se multi: true for omitido, a ação será executada apenas no primeirodocumento que atenda ao critério.

db.example.update(

{},

{ $unset: { Inventory:1 } },

{ multi: true }

)

Como excluir documentosPara remover um documento do banco de dados, use a operação remove(), especificandoqual documento remover. O código a seguir remove "Gel Pen" da sua coleção example.

db.example.remove( { "Item": "Gel Pen" } )

Para remover todos os documentos do seu banco de dados, use a operação remove() comuma consulta vazia, conforme exemplo a seguir.

76

Amazon DocumentDB Guia do desenvolvedorRecuperar todos os documentos

db.example.remove( { } )

(p. 23).

Tópicos• Como recuperar todos os documentos em uma coleção (p. 77)• Como recuperar documentos que correspondem a um valor de campo (p. 77)• Como recuperar documentos que correspondem a um documento incorporado (p. 77)• Como recuperar documentos que correspondem a um valor de campo em um documento


Como recuperar todos os documentos em umacoleçãoPara recuperar todos os documentos em sua coleção, use a operação find() com um documento deconsulta vazio.

A seguinte consulta devolve todos os documentos no example recolha.


Como recuperar documentos que correspondem a umvalor de campoPara recuperar todos os documentos que correspondem a um campo e valor, use a operação find() comum documento de consulta que identifica os campos e valores a serem correspondidos.

Usando documentos anteriores, essa consulta retorna todos os documentos em que o campo "Item" seráigual a "Pen".


Como recuperar documentos que correspondem a umdocumento incorporadoPara localizar todos os documentos que correspondem a um documento incorporado, use a operaçãofind() com um documento de consulta que especifica o nome do documento incorporado e todos oscampos e valores desse documento incorporado.

Ao vincular um documento incorporado, o documento incorporado do documento deve ter o mesmo nomeque na consulta. Além disso, os campos e os valores no documento incorporado devem corresponder àconsulta.

A consulta a seguir retorna apenas o documento "Poster Paint". Isto porque a "Caneta" tem valoresdiferentes para "OnHand" e "MinOnHand" e "Spray Paint" tem mais um campo (OrderQnty) do que odocumento de consulta.

77

Amazon DocumentDB Guia do desenvolvedorValores de campo em documentos incorporados

db.example.find({"Inventory": { "OnHand": 47, "MinOnHand": 50 } } ).pretty()

Como recuperar documentos que correspondem a umvalor de campo em um documento incorporadoPara localizar todos os documentos que correspondem a um documento incorporado, use a operaçãofind() com um documento de consulta que especifica o nome do documento incorporado e todos oscampos e valores desse documento incorporado.

Considerando os documentos anteriores, a consulta a seguir usa "notação de pontos" para especificaro documento incorporado e os campos de interesse. Qualquer documento que seja correspondenteserá retornado, independentemente de quais outros campos possam estar presentes no documentoincorporado. A consulta retorna "Poster Paint" e "Spray Paint", pois ambos correspondem aos campos evalores especificados.


Como recuperar documentos que correspondem auma matrizPara localizar todos os documentos que correspondem a uma matriz, use a operação find() com o nomeda matriz de interesse e todos os valores na matriz. A consulta retorna todos os documentos que têm umamatriz com esse nome, com valores idênticos aos da matriz, e na mesma ordem que na consulta.

A consulta a seguir retorna apenas o documento "Pen", pois o "Poster Paint" tem uma cor adicional(White), e "Spray Paint" tem as cores em ordem diferente.


Como recuperar documentos que correspondem a umvalor em uma matrizPara localizar todos os documentos que possuem um valor de matriz específico, use a operação find()com o valor e o nome da matriz de interesse.


A operação anterior devolve os três documentos porque cada um deles tem uma matriz nomeada Colorse o valor "Red" algures na matriz. Se você especificar o valor "White", a consulta retornará apenas "PosterPaint".

Recuperação de documentos usando operadoresA consulta a seguir retorna todos os documentos em que o valor "Inventory.OnHand" é inferior a 50.

db.example.find( { "Inventory.OnHand": { $lt: 50 } } )

78

Amazon DocumentDB Guia do desenvolvedorPlano de consulta

Para obter uma lista de operadores de consulta compatíveis, consulte Operadores de consulta eprojeção (p. 89).

Plano de consultaComo posso ver os executionStats de um planode consulta?Ao determinar por que uma consulta está sendo executada mais lentamente do que o esperado, podeser útil entender quais são os executionStats desse plano de consulta. O executionStats fornecero número de documentos devolvidos de uma fase em particular (nReturned), a quantidade de tempode execução gasto em cada fase (executionTimeMillisEstimate) e o tempo que demora a gerarum plano de consulta (planningTimeMillis). É possível determinar os estágios mais demorados desua consulta para ajudar a concentrar seus esforços de otimização na saída de executionStats, comomostrado nos exemplos de consulta abaixo. O executionStats parâmetro não suporta atualmenteupdate e delete comandos.

Note

Amazon DocumentDBO emula a API do MongoDB 3.6 em um mecanismo de banco de dadoscriado especificamente que utiliza um sistema de armazenamento distribuído, tolerante a falhas ede autorrecuperação. Como resultado, planos de consulta e a saída de explain() pode diferirentre Amazon DocumentDB e mongodb. Os clientes que desejam ter controle sobre seu plano deconsulta podem usar o operador $hint para impor a seleção de um índice preferencial.

Execute a consulta que você deseja melhorar com o comando explain() da seguinte forma.

db.runCommand({explain: {query document}}).explain("executionStats").executionStats;

Veja a seguir um exemplo de operação.

db.fish.find({}).limit(2).explain("executionStats");


{ "queryPlanner" : { "plannerVersion" : 1, "namespace" : "test.fish", "winningPlan" : { "stage" : "SUBSCAN", "inputStage" : { "stage" : "LIMIT_SKIP", "inputStage" : { "stage" : "COLLSCAN" } } } }, "executionStats" : { "executionSuccess" : true, "executionTimeMillis" : "0.063", "planningTimeMillis" : "0.040", "executionStages" : { "stage" : "SUBSCAN",

79

Amazon DocumentDB Guia do desenvolvedorCache do plano de consulta

"nReturned" : "2", "executionTimeMillisEstimate" : "0.012", "inputStage" : { "stage" : "LIMIT_SKIP", "nReturned" : "2", "executionTimeMillisEstimate" : "0.005", "inputStage" : { "stage" : "COLLSCAN", "nReturned" : "2", "executionTimeMillisEstimate" : "0.005" } } } }, "serverInfo" : { "host" : "enginedemo", "port" : 27017, "version" : "3.6.0" }, "ok" : 1}

Se estiver interessado em ver apenas o executionStats da consulta acima, você pode usar o seguintecomando. Para pequenas coleções, o processador de consultas do Amazon DocumentDB pode optar pornão usar um índice se os ganhos de desempenho forem negligenciáveis.

db.fish.find({}).limit(2).explain("executionStats").executionStats;

Cache do plano de consultaPara otimizar o desempenho e reduzir a duração do planeamento, Amazon DocumentDB caches deplanos de consulta internamente. Isto permite que as consultas com a mesma forma sejam executadasdiretamente utilizando um plano em cache.

No entanto, este caching pode, por vezes, causar um atraso aleatório para a mesma consulta; porexemplo, uma consulta que normalmente demora um segundo a correr pode ocasionalmente demorardez segundos. Isto é porque ao longo do tempo, a instância do leitor cache várias formas da consulta,minimizando assim a memória. Se sentir esta lentidão aleatória, não é necessária qualquer ação quenecessite de fazer para libertar a memória--o sistema irá gerir a utilização da memória para si e assim quea memória atingir determinados limiares, será automaticamente lançada.

Explicar resultadosSe pretender devolver informações sobre planos de consulta, Amazon DocumentDB suporta modo deverbosidade queryPlanner. O explain Os resultados devolvem o plano de consulta selecionadoescolhido pelo otimizador num formato semelhante ao seguinte:

{ "queryPlanner" : { "plannerVersion" : <int>, "namespace" : <string>, "winningPlan" : { "stage" : <STAGE1>, ... "inputStage" : { "stage" : <STAGE2>, ...

80

Amazon DocumentDB Guia do desenvolvedorFase de leitura e filtro

"inputStage" : { ... } } } }}

As secções seguintes irão definir o comum explain resultados.

Tópicos• Fase de leitura e filtro (p. 81)• Intersecção de índice (p. 82)• União de Índices (p. 82)• Intersecção/União de Múltiplos Índices (p. 83)• Índice composto (p. 83)• Ordenar fase (p. 83)• Fase do grupo (p. 84)

Fase de leitura e filtroO optimizador pode escolher um dos seguintes exames:

CINTIGRAFIA

Esta fase é um exame de recolha sequencial.

{ "stage" : "COLLSCAN"}

IXSCAN

Esta fase lê as teclas de índice. O optimizador pode recuperar o documento nesta fase e isto pode resultarnuma fase FETCH anexada mais tarde.

db.foo.find({"a": 1}){ "stage" : "IXSCAN", "direction" : "forward", "indexName" : <idx_name>}

FETCH

Se o otimizador recuperou documentos numa platina que não IXSCAN, o resultado incluirá uma faseFETCH. Por exemplo, a consulta IXSCAN acima pode resultar numa combinação de fases FETCH eIXSCAN:

db.foo.find({"a": 1}){ "stage" : "FETCH", "inputStage" : {

81

Amazon DocumentDB Guia do desenvolvedorIntersecção de índice

"stage" : "IXSCAN", "indexName" : <idx_name> }}

IXONLYSCAN digitaliza apenas a tecla de índice. Criar índices compostos não irá evitar FETCH.

Intersecção de índiceIXE

Amazon DocumentDB pode incluir uma fase IXAND com um conjunto de etapas de inputéns de IXSCANse puder utilizar a intersecção de indexação. Por exemplo, podemos ver resultados como:

{ "stage" : "FETCH", "inputStage" : { "stage" : "IXAND", "inputStages" : [ { "stage" : "IXSCAN", "indexName" : "a_1" }, { "stage" : "IXSCAN", "indexName" : "b_1" } ] }}

União de ÍndicesIXOR

Semelhante à intersecção do índice, Amazon DocumentDB pode incluir IXOR com um inputStages parao $or operador.

db.foo.find({"$or": [{"a": {"$gt": 2}}, {"b": {"$lt": 2}}]})

Para a consulta acima, o resultado explicativo pode parecer este:

{ "stage" : "FETCH", "inputStage" : { "stage" : "IXOR", "inputStages" : [ { "stage" : "IXSCAN", "indexName" : "a_1" }, { "stage" : "IXSCAN", "indexName" : "b_1" } ] }

82

Amazon DocumentDB Guia do desenvolvedorIntersecção/União de Múltiplos Índices

}

Intersecção/União de Múltiplos ÍndicesAmazon DocumentDB pode combinar várias fases de intersecção de índice ou de união em conjunto edepois obter o resultado. Por exemplo, .

{ "stage" : "FETCH", "inputStage" : { "stage" : "IXOR", "inputStages" : [ { "stage" : "IXSCAN", ... }, { "stage" : "IXAND", "inputStages" : [ { "stage" : "IXSCAN", ... }, { "stage" : "IXSCAN", ... } ] } ] }}

A utilização de interseção de índice ou fases patrulares não é afetada pelo tipo de índice (espaçado,composto, etc.).

Índice compostoAmazon DocumentDB a utilização de índice composto não é limitada nos subconjuntos de camposindexados; pode utilizar o índice com a parte do sufixo, mas pode não ser muito eficiente.

Por exemplo, o índice composto de { a: 1, b: -1 } pode suportar as três questões abaixo:

db.orders.find( { a: 1 } } )

db.orders.find( { b: 1 } } )

db.orders.find( { a: 1, b: 1 } } )

Ordenar faseSe existir um índice na(s) chave(s) de ordenação solicitada, a documentdb pode utilizar o índice paraobter a encomenda. Nesse caso, o resultado não incluirá um SORT mas sim IXSCAN fase. Se o otimizadorfavorecer uma ordenação simples, irá incluir uma fase como esta:

{

83

Amazon DocumentDB Guia do desenvolvedorFase do grupo

"stage" : "SORT", "sortPattern" : { "a" : 1, "b" : -1 }}

Fase do grupoO documentador da Amazon suporta duas estratégias de grupo diferentes:

• ORDENAR_AGREGADO: On disk sort aggregate.• HASH_AGREGADO: In memory hash aggregate.

84

Amazon DocumentDB Guia do desenvolvedorComandos do banco de dados

APIs, operações e tipos de dados doMongoDB compatíveis

O Amazon DocumentDB (compatível com MongoDB) é um serviço de banco de dados de documentosrápido, escalável, totalmente gerenciado e altamente disponível que oferece suporte a cargas de trabalhodo MongoDB. O Amazon DocumentDB é compatível com a API 3.6 do MongoDB 3.6. Esta seção lista asfuncionalidades com suporte. Para diferenças funcionais entre Amazon DocumentDB e MongoDB, consulteDiferenças funcionais: Amazon DocumentDB e MongoDB (p. 61).

Os comandos e operadores do MongoDB somente para uso interno ou não aplicáveis a um serviçototalmente gerenciado não têm suporte e não são incluídos na lista de funcionalidades com suporte.

Adicionamos mais de 50 recursos desde o lançamento e continuaremos trabalhando para oferecer osrecursos de que nossos clientes precisam. Para obter informações sobre os lançamentos mais recentes,consulte Anúncios do Amazon DocumentDB.

Se houver uma funcionalidade que não seja suportada que gostaria que construíssemos, informe-nosenviando um e-mail com o seu ID de conta, as funcionalidades solicitadas e use o caso para o AmazonDocumentDB equipa de serviço.

Tópicos• Comandos do banco de dados (p. 85)• Operadores de consulta e projeção (p. 89)• Operadores de atualização (p. 91)• Geospatial (p. 93)• Métodos de cursor (p. 93)• Operadores de pipeline de agregação (p. 94)• Tipos de dados (p. 101)• Índices e propriedades de índice (p. 102)

Comandos do banco de dadosTópicos

• Comandos administrativos (p. 86)• Aggregation (p. 86)• Authentication (p. 87)• Comandos de diagnóstico (p. 87)• Operações de gravação e de consulta (p. 87)• Comandos de gerenciamento de função (p. 88)• Comandos de sessões (p. 88)• Gerenciamento de usuários (p. 89)

85

https://aws.amazon.com/documentdb/resources/

mailto:[email protected]

mailto:[email protected]

Amazon DocumentDB Guia do desenvolvedorComandos administrativos

Comandos administrativos

Comando Compatível

Coleções limitadas Não

cloneCollectionAsCapped Não

collMod Parcial

collMod: expireAfterSeconds Sim (8/1/19)

convertToCapped Não

copydb Não

create Sim

createView Não

createIndexes Sim

currentOp Sim

drop Sim

dropDatabase Sim

dropIndexes Sim

filemd5 Não

killCursors Sim

killOp Sim

listCollections Sim

listDatabases Sim

listIndexes Sim

reIndex Não

renameCollection Não

Aggregation

Comando Compatível

aggregate Sim

count Sim

distinct Sim

mapReduce Não

86

Amazon DocumentDB Guia do desenvolvedorAuthentication

Authentication

Comando Compatível

authenticate Sim

logout Sim

Comandos de diagnóstico

Comando Compatível

buildInfo Sim

collStats Sim

connPoolStats Não

connectionStatus Sim

dataSize Sim

dbHash Não

dbStats Sim

explain Sim

explain: executionStats Sim (03/23/20)

features Não

hostInfo Sim

listCommands Sim

profiler Sim (8/19/19)

serverStatus Sim

top Sim (8/1/19)

Operações de gravação e de consulta

Comando Compatível

delete Sim

find Sim

findAndModify Sim

getLastError Não

getMore Sim

87

https://docs.aws.amazon.com//documentdb/latest/developerguide/profiling.html

Amazon DocumentDB Guia do desenvolvedorComandos de gerenciamento de função

Comando Compatível

getPrevError Não

insert Sim

parallelCollectionScan Não

resetError Não

update Sim

Change streams Sim (10/23/19)

GridFS Não

Comandos de gerenciamento de função

Comando Compatível

createRole Não

dropRole Não

dropAllRolesFromDatabase Não

grantRolesToRole Não

revokePrivilegesFromRole Não

revokeRolesFromRole Não

updateRole Não

rolesInfo Não

Comandos de sessões

Comando Compatível

endSessões Não

EliminarTodas as lesões Não

EliminarTodas asSessõesPorPadrão Não

de arrasarSessões Não

refrescarSessões Não

iniciarSessão Não

88

https://docs.aws.amazon.com//documentdb/latest/developerguide/change_streams.html

Amazon DocumentDB Guia do desenvolvedorGerenciamento de usuários

Gerenciamento de usuários

Comando Compatível

createUser Sim

dropAllUsersFromDatabase Sim

dropUser Sim

grantRolesToUser Sim (03/26/20)

revokeRolesFromUser Sim (03/26/20)

updateUser Sim

userInfo Sim

Operadores de consulta e projeçãoTópicos

• Operadores de matriz (p. 89)• Operadores bitwise (p. 89)• Operador de comentários (p. 90)• Operadores de comparação (p. 90)• Operadores de elemento (p. 90)• Operadores de consulta de avaliação (p. 90)• Operadores lógicos (p. 91)• Operadores de projeção (p. 91)

Operadores de matriz

Operador Compatível

$all Sim

$elemMatch Sim

$size Sim

Operadores bitwise


$bitsAllSet Sim

$bitsAnySet Sim

89

Amazon DocumentDB Guia do desenvolvedorOperador de comentários


$bitsAllClear Sim

$bitsAnyClear Sim

Operador de comentários


$comment Sim

Operadores de comparação


$eq Sim

$gt Sim

$gte Sim

$lt Sim

$lte Sim

$ne Sim

$in Sim

$nin Sim

Operadores de elemento


$exists Sim

$type Sim

Operadores de consulta de avaliação


$expr Não

$jsonSchema Não

$mod Sim

90

Amazon DocumentDB Guia do desenvolvedorOperadores lógicos


$regex Sim

$text Não

$where Não

Operadores lógicos


$or Sim

$and Sim

$not Sim

$nor Sim

Operadores de projeção


$ Sim

$elemMatch Sim

$meta Não

$slice Sim

Operadores de atualizaçãoTópicos

• Operadores de matriz (p. 91)• Operadores bitwise (p. 92)• Operadores de campo (p. 92)• Modificadores de atualização (p. 92)

Operadores de matriz


$ Sim

$[] Sim

91

Amazon DocumentDB Guia do desenvolvedorOperadores bitwise


$[<identifier>] Sim

$addToSet Sim

$pop Sim

$pullAll Sim

$pull Sim

$push Sim

Operadores bitwise


$bit Sim

Operadores de campo


$inc Sim

$mul Sim

$rename Sim

$setOnInsert Sim

$set Sim

$unset Sim

$min Sim

$max Sim

$currentDate Sim

Modificadores de atualização


$each Sim

$slice Sim

$sort Sim

$position Sim

92

Amazon DocumentDB Guia do desenvolvedorGeospatial

GeospatialEspecificadores de geometria

Seletores de consulta Compatível

$box Não

$center Não

$centerSphere Não

$nearSphere Não

$geometry Não

$maxDistance Não

$minDistance Não

$polygon Não

$uniqueDocs Não

Seletores de consulta

Seletores de consulta Compatível

$geoIntersects Não

$geoWithin Não

$near Não

$nearSphere Não

Métodos de cursorMétodo Compatível

cursor.batchSize() Sim

cursor.close() Sim

cursor.isClosed() Sim

cursor.collation() Não

cursor.comment() Sim

cursor.count() Sim

cursor.explain() Sim

93

Amazon DocumentDB Guia do desenvolvedorOperadores de pipeline de agregação

Método Compatível

cursor.forEach() Sim

cursor.hasNext() Sim

cursor.hint() Sim

cursor.isExhausted() Sim

cursor.itcount() Sim

cursor.limit() Sim

cursor.map() Sim

cursor.maxScan() Sim

cursor.maxTimeMS() Sim

cursor.max() Não

cursor.min() Não

cursor.next() Sim

cursor.noCursorTimeout() Não

cursor.objsLeftInBatch() Sim

cursor.pretty() Sim

cursor.readConcern() Sim

cursor.readPref() Sim

cursor.returnKey() Não

cursor.showRecordId() Não

cursor.size() Sim

cursor.skip() Sim

cursor.sort() Sim

cursor.tailable() Não

cursor.toArray() Sim

Operadores de pipeline de agregaçãoTópicos

• Expressões do acumulador (p. 95)• Operadores aritméticos (p. 95)• Operadores de matriz (p. 96)• Operadores booleanos (p. 96)• Operadores de comparação (p. 97)

94

Amazon DocumentDB Guia do desenvolvedorExpressões do acumulador

• Operadores de expressão condicional (p. 97)• Operador de tipo de dados (p. 97)• Operadores de data (p. 97)• Operador literal (p. 98)• Operador de mesclagem (p. 98)• Operador natural (p. 98)• Configurar operadores (p. 99)• Operadores de estágio (p. 99)• Operadores de sequência (p. 100)• Variáveis de sistema (p. 100)• Operador de pesquisa de texto (p. 101)• Operadores variáveis (p. 101)

Expressões do acumulador

Expressão Compatível

$sum Sim

$avg Sim

$first Sim

$last Sim

$max Sim

$min Sim

$push Sim

$addToSet Sim

$stdDevPop Não

$stdDevSamp Não

Operadores aritméticos

Comando Compatível

$abs Sim

$add Sim

$ceil Não

$divide Sim

$exp Não

$floor Não

95

Amazon DocumentDB Guia do desenvolvedorOperadores de matriz

Comando Compatível

$ln Não

$log Não

$log10 Não

$mod Sim

$multiply Sim

$pow Não

$sqrt Não

$subtract Sim

$trunc Não

Operadores de matrizOperador Compatível

$arrayElemAt Sim

$arrayToObject Sim

$concatArrays Sim

$filter Sim

$indexOfArray Não

$isArray Sim

$objectToArray Sim

$range Sim

$reverseArray Não

$reduce Não

$size Sim

$slice Sim

$zip Não

$in Sim

Operadores booleanosOperador Compatível

$and Sim

96

Amazon DocumentDB Guia do desenvolvedorOperadores de comparação


$or Sim

$not Sim

Operadores de comparação


$cmp Sim

$eq Sim

$gt Sim

$gte Sim

$lt Sim

$lte Sim

$ne Sim

Operadores de expressão condicional


$cond Sim

$ifNull Não

$switch Não

Operador de tipo de dados


$type Não

Operadores de data


$dayOfYear Sim

$dayOfMonth Sim

$dayOfWeek Sim

97

Amazon DocumentDB Guia do desenvolvedorOperador literal


$year Sim

$month Sim

$week Sim

$hour Sim

$minute Sim

$second Sim

$millisecond Sim

$dateToString Sim

$isoDayOfWeek Sim

$isoWeek Sim

$dateFromParts Não

$dateToParts Não

$dateFromString Sim

$isoWeekYear Sim

Operador literal


$literal Não

Operador de mesclagem


$mergeObjects Não

Operador natural


$natural Não

98

Amazon DocumentDB Guia do desenvolvedorConfigurar operadores

Configurar operadoresOperador Compatível

$setEquals Não

$setIntersection Não

$setUnion Não

$setDifference Não

$setIsSubset Não

$anyElementTrue Não

$allElementsTrue Não

Operadores de estágioOperador Compatível

$collStats Não

$project Sim

$match Sim

$redact Sim

$limit Sim

$skip Sim

$unwind Sim

$group Sim

$sample Sim

$sort Sim

$geoNear Não

$lookup Sim

$out Sim

$indexStats Sim

$facet Não

$bucket Não

$bucketAuto Não

$sortByCount Não

$addFields Sim

99

Amazon DocumentDB Guia do desenvolvedorOperadores de sequência


$replaceRoot Não

$count Sim

$currentOp Sim

$listLocalSessions Não

$listSessions Não

$graphLookup Não

Operadores de sequênciaOperador Compatível

$concat Sim

$indexOfBytes Sim

$indexOfCP Sim

$split Sim

$strcasecmp Sim

$strLenBytes Sim

$strLenCP Sim

$substr Sim

$substrBytes Sim

$substrCP Sim

$toLower Sim

$toUpper Sim

Variáveis de sistemaVariável Compatível

$$CURRENT Não

$$DESCEND Sim

$$KEEP Sim

$$PRUNE Sim

$$REMOVE Não

$$ROOT Não

100

Amazon DocumentDB Guia do desenvolvedorOperador de pesquisa de texto

Operador de pesquisa de texto


$meta Não

Operadores variáveis


$map Não

$let Não

Tipos de dados

Tipo de dados Compatível

Double Sim

String Sim

Objeto Sim

Array Sim

Dados binários Sim

ObjectId Sim

Boolean Sim

Date Sim

Nulo Sim

Inteiro de 32 bits (int) Sim

Marca de data e hora Sim

Inteiro de 64 bits (longo) Sim

MinKey Sim

MaxKey Sim

Decimal128 Não

Expressão regular Não

JavaScript Não

JavaScript (com escopo) Não

101

Amazon DocumentDB Guia do desenvolvedorÍndices e propriedades de índice

Tipo de dados Compatível

Indefinido Não

Símbolo Não

DBPointer Não

Índices e propriedades de índiceTópicos

• Indexes (p. 102)• Propriedades de índice (p. 102)

Indexes

Tipo de índice Compatível

Índice de campo único Sim

Índice composto Sim

Índice de várias chaves Sim

Índice de texto Não

2dsphere Não

Índice 2d Não

Índice com hash Não

Propriedades de índice

Propriedade de índice Compatível

TTL Sim

Unique Sim

Parcial Não

Diferenciação entre maiúsculas e minúsculas Não

Sparse Sim

Contexto Sim

102

Amazon DocumentDB Guia do desenvolvedorFerramentas de migração

Migrar para o Amazon DocumentDBO Amazon DocumentDB (compatível com MongoDB) é um serviço de banco de dados gerenciadocompatível com a API do MongoDB. Você pode migrar dados para o Amazon DocumentDB de bancos dedados do MongoDB em execução no local ou no Amazon Elastic Compute Cloud (Amazon EC2) usando oprocesso detalhado nesta seção.

Tópicos• Ferramentas de migração (p. 103)• Descoberta (p. 104)• Planeamento: requisitos de cluster do Amazon DocumentDB (p. 107)• Abordagens de migração (p. 109)• Origens de migração (p. 112)• Conectividade de migração (p. 113)• no dispositivo (p. 115)• Testes de desempenho (p. 117)• Testes de failover (p. 117)• Recursos adicionais (p. 117)

Ferramentas de migraçãoPara migrar para o Amazon DocumentDB, as duas principais ferramentas que a maioria dos clientes usasão o AWS Database Migration Service (AWS DMS) e utilitários de linha de comando, como o mongodumpe o mongorestore. Como prática recomendada, e para qualquer uma dessas opções, recomendamosque você primeiro crie índices no Amazon DocumentDB antes de iniciar a migração, pois ela pode reduziro tempo geral e aumentar a velocidade da migração. Para fazer isso, você pode usar a Ferramenta deíndice do Amazon DocumentDB.

AWS Database Migration ServiceO AWS Database Migration Service (AWS DMS) é um serviço de nuvem que facilita a migração de bancosde dados relacionais e de bancos de dados não relacionais para o Amazon DocumentDB. Você pode usaro AWS DMS para migrar seus dados para o Amazon DocumentDB de bancos de dados hospedados nolocal ou no EC2. Com o AWS DMS, você pode executar migrações avulsas e replicar as alterações emandamento para manter as origens e os destinos em sincronia.

Para ajudar com o custo das migrações, você pode usar o AWS DMS gratuitamente por seis meses porinstância ao migrar para o Amazon DocumentDB. Para obter mais informações, consulte DMS gratuito.

Para obter mais informações sobre como usar o AWS DMS para migrar para o Amazon DocumentDB,consulte:

• Usar o MongoDB como origem para o AWS DMS• Usar o Amazon DocumentDB como destino para o AWS Database Migration Service

103

https://aws.amazon.com/dms/



https://aws.amazon.com/dms/free-dms/

https://docs.aws.amazon.com/dms/latest/userguide/CHAP_Source.MongoDB.html

https://docs.aws.amazon.com/dms/latest/userguide/target.docdb.html

Amazon DocumentDB Guia do desenvolvedorUtilitários de linha de comando

• Demonstração: Migração do MongoDB para o Amazon DocumentDB

Utilitários de linha de comandoOs utilitários comuns para migrar dados para o Amazon DocumentDB e vice-versa incluem mongodump,mongorestore, mongoexport e mongoimport. Normalmente, mongodump e mongorestore sãoos utilitários mais eficientes pois despejam e restauram dados de seus bancos de dados em formatobinário. Esta é geralmente a opção mais eficiente e produz um tamanho de dados menor em comparaçãocom as exportações lógicas. O mongoexport e o mongoimport são úteis se você deseja exportar eimportar dados em um formato lógico, como JSON ou CSV, pois os dados são legíveis por humanos, masgeralmente é mais lento do que o mongodump/mongorestore e produz um tamanho de dados maior.

A seção Abordagens de migração (p. 109) abaixo discutirá quando é melhor usar o AWS DMS e osutilitários de linha de comando com base em seu caso de uso e requisitos.

DescobertaPara cada uma das implantações do MongoDB, você deve identificar e registrar dois conjuntos de dados:Detalhes da arquitetura e Características operacionais. Essas informações ajudarão você a escolher aabordagem de migração apropriada e o dimensionamento do cluster.

Detalhes de arquitetura

• Name

Escolha um nome exclusivo para rastrear essa implantação.

• Versão

Registre a versão do MongoDB que a implantação está executando. Para encontrar a versão, conecte-se a um membro do conjunto de réplicas com o shell do Mongo e execute a operação db.version().

• Type

Registre se a implantação é uma instância do Mongo independente, um conjunto de réplicas ou umcluster estilhaçado.

• Membros

Registre os nomes de host, endereços e portas de cada cluster, conjunto de réplicas ou membroindependente.

Para uma implantação em cluster, você pode encontrar membros do estilhaço conectando-se a um hostdo Mongo com o shell do Mongo e executando a operação sh.status().

Para um conjunto de réplicas, você pode obter os membros conectando-se a um membro do conjunto deréplicas com o shell do Mongo e executando a operação rs.status().

104

https://docs.aws.amazon.com/dms/latest/userguide/target.docdb.tutorial.html

Amazon DocumentDB Guia do desenvolvedorDescoberta

• Tamanhos do Oplog

Para conjuntos de réplicas ou clusters estilhaçados, registre o tamanho do oplog para cada membrodo conjunto de réplicas. Para encontrar o tamanho do oplog de um membro, conecte-se ao membro doconjunto de réplicas com o shell do Mongo e execute a operação ps.printReplicationInfo().

• Prioridades do membro do conjunto de réplicas

Para conjuntos de réplicas ou clusters estilhaçados, registre a prioridade de cada membro do conjuntode réplicas. Para encontrar as prioridades do membro do conjunto de réplicas, conecte-se a um membrodo conjunto de réplicas com o shell do Mongo e execute a operação rs.conf(). A prioridade émostrada como o valor da chave priority.

• Uso do TLS/SSL

Registre se o Transport Layer Security (TLS)/Secure Sockets Layer (SSL) é usado em cada nó paracriptografia em trânsito.

Características operacionais

• Estatísticas de banco de dados

Para cada coleção, registre as seguintes informações:• Nome• Tamanho dos dados• Contagem de coleções

Para encontrar as estatísticas de banco de dados, conecte-se ao seu banco de dados com o shell doMongo e execute o comando db.runCommand({dbstats: 1}).

• Estatísticas de coleção

Para cada coleção, registre as seguintes informações:• Namespace• Tamanho dos dados• Contagem de índices• Se a coleção for limitada

• Estatísticas de índice

Para cada coleção, registre as seguintes informações de índice:• Namespace• ID• Tamanho• Chaves• TTL• Sparse• Plano de fundo

105

Amazon DocumentDB Guia do desenvolvedorDescoberta

Para encontrar as informações de índice, conecte-se ao seu banco de dados com o shell do Mongo eexecute o comando db.collection.getIndexes().

• Opcounters

Essas informações ajudam a entender os padrões de carga de trabalho atuais do MongoDB (de leituraintensa, de gravação intensa ou balanceada). Também fornece orientações sobre a seleção de instânciainicial do Amazon DocumentDB.

Veja a seguir as principais informações para coletar ao longo do período de monitoramento (em contas/s):• Consultas• Inserções• Atualizações• Exclusões

Você pode obter essas informações criando um gráfico do resultado do comando db.serverStatus()ao longo do tempo. Você também pode usar a ferramenta mongostat para obter valores instantâneospara essas estatísticas. No entanto, com essa opção, você corre o risco de planejar a migração emperíodos de utilização diferentes da sua carga de pico.

• Estatísticas de rede

Essas informações ajudam a entender os padrões de carga de trabalho atuais do MongoDB (de leituraintensa, de gravação intensa ou balanceada). Também fornece orientações sobre a seleção de instânciainicial do Amazon DocumentDB.

Veja a seguir as principais informações para coletar ao longo do período de monitoramento (em contas/s):• Conexões• Entrada de bytes na rede• Saída de bytes da rede

Você pode obter essas informações criando um gráfico do resultado do comando db.serverStatus()ao longo do tempo. Você também pode usar a ferramenta mongostat para obter valores instantâneospara essas estatísticas. No entanto, com essa opção, você corre o risco de planejar a migração emperíodos de utilização diferentes da sua carga de pico.

106

Amazon DocumentDB Guia do desenvolvedorPlaneamento: requisitos de cluster do Amazon DocumentDB

Planeamento: requisitos de cluster do AmazonDocumentDB

A migração bem-sucedida requer que você considere cuidadosamente a configuração do cluster doAmazon DocumentDB e como os aplicativos acessarão seu cluster. Considere cada uma das seguintesdimensões ao determinar os requisitos de seu cluster:

• Disponibilidade

O Amazon DocumentDB fornece alta disponibilidade por meio da implantação de instâncias de réplica,que podem ser promovidas a uma instância principal em um processo conhecido como failover. Aoimplantar instâncias de réplica em zonas de disponibilidade diferentes, você pode alcançar níveis maisaltos de disponibilidade.

A tabela a seguir fornece diretrizes para configurações de implantação do Amazon DocumentDB paraatender às metas de disponibilidade específicas.

Meta de disponibilidade Total de instâncias Réplicas Zonas dedisponibilidade

99% 1 0 1

99,9% 2 1 2

99,99% 3 2 3

A confiabilidade geral do sistema deve considerar todos os componentes, não apenas o bancode dados. Para obter as melhores práticas e recomendações para atender às necessidades deconfiabilidade geral do sistema, consulte o whitepaper Pilar de confiabilidade bem-arquitetada da AWS.

• Desempenho

As instâncias do Amazon DocumentDB permitem que você leia e grave no volume de armazenamentodo seu cluster. As instâncias do cluster são fornecidas em vários tipos, com quantidades diversificadasde memória e vCPU, que afetam o desempenho de leitura e gravação do cluster. Usando asinformações coletadas na fase de descoberta, escolha um tipo de instância que possa oferecer suportea seus requisitos de desempenho de carga de trabalho. Para obter uma lista dos tipos de instânciascompatíveis, consulte Managing Instance Classes (p. 247).

Ao escolher um tipo de instância para seu cluster do Amazon DocumentDB, considere os seguintesaspectos dos requisitos de desempenho de sua carga de trabalho:• vCPUs— arquiteturas que exigem contagens de conexão mais altas podem se beneficiar de instâncias

com mais vCPUs.

107

https://d1.awsstatic.com/whitepapers/architecture/AWS-Reliability-Pillar.pdf

Amazon DocumentDB Guia do desenvolvedorPlaneamento: requisitos de cluster do Amazon DocumentDB

• Memória— quando possível, manter seu conjunto de dados de trabalho na memória proporcionadesempenho máximo. Uma diretriz inicial é reservar um terço da memória da instância para omecanismo do Amazon DocumentDB, deixando dois terços para seu conjunto de dados de trabalho.

• Conexões— a contagem mínima de conexão ideais é oito conexões por vCPU de instância do

Amazon DocumentDB. Embora o limite de conexões de instância do Amazon DocumentDB seja muitomaior, os benefícios de desempenho de conexões adicionais diminuem acima de oito conexões porvCPU.

• Rede— cargas de trabalho com um grande número de clientes ou conexões devem considerar o

desempenho de rede agregado necessário para dados inseridos e recuperados. As operações emmassa podem fazer uso mais eficiente de recursos de rede.

• Desempenho de inserções— em geral, as inserções de documento únicas são a forma mais lenta de

inserir dados no Amazon DocumentDB. As operações de inserção em massa podem ser muito maisrápidas do que as inserções únicas.

• Desempenho de leitura— as leituras da memória de trabalho são sempre mais rápidas do que as

leituras retornadas do volume de armazenamento. Portanto, otimizar o tamanho da memória deinstância para reter seu conjunto de trabalho na memória é ideal.

Além de atender a leituras da sua instância principal, os clusters do Amazon DocumentDB sãoautomaticamente configurados como conjuntos de réplicas. Depois, você pode rotear consultas somenteleitura para réplicas de leitura, definindo a preferência de leitura em seu driver do MongoDB. Você podedimensionar o tráfego de leitura adicionando réplicas, reduzindo o carregamento global na instânciaprincipal.

É possível implantar réplicas do Amazon DocumentDB de diferentes tipos de instância no mesmocluster. Um caso de uso de exemplo pode ser reunir uma réplica com um tipo de instância maior paraatender ao tráfego de análise temporário. Se você implantar um conjunto misto de tipos de instância,certifique-se de configurar a prioridade de failover para cada instância. Isso ajuda a garantir que umevento de failover sempre promova uma réplica de dimensão suficiente para lidar com a carga degravação.

• Recuperação

O Amazon DocumentDB faz backup de forma contínua de seus dados durante a gravação. Ele fornecerecursos de recuperação point-in-time (PITR) em um período configurável de 1–35 dias, conhecidocomo período de retenção de backup. O período de retenção de backup padrão é um dia. O AmazonDocumentDB também cria automaticamente snapshots diários de seu volume de armazenamento, quetambém ficam retidos pelo período de retenção de backup configurado.

Se você deseja reter snapshots além do período de retenção de backup, também pode iniciar snapshotsmanuais a qualquer momento usando o Console de gerenciamento da AWS e a AWS CommandLine Interface (AWS CLI). Para obter mais informações, consulte Backup e restauração no AmazonDocumentDB (p. 175).

108

Amazon DocumentDB Guia do desenvolvedorAbordagens de migração

Considere o seguinte ao planejar a migração:• Escolha um período de retenção de backup, de 1 a 35 dias que atenda ao objetivo de ponto de

recuperação (RPO).• Decida se você precisa de snapshots manuais e, se esse for o caso, em qual intervalo.

Abordagens de migraçãoHá três principais abordagens de migração de dados para o Amazon DocumentDB.

Note

Embora você possa criar índices a qualquer momento no Amazon DocumentDB, em geral, émais rápido criar seus índices antes de importar grandes conjuntos de dados. Como práticarecomendada, e para cada uma das abordagens abaixo, recomendamos que você crie seusíndices no Amazon DocumentDB antes de executar a migração. Para fazer isso, você pode usar aFerramenta de índice do Amazon DocumentDB.

Off-lineA abordagem offline usa o mongodump e as ferramentas da mongorestore para migrar os dadosda implantação do MongoDB de origem para o cluster do Amazon DocumentDB. O método offline é aabordagem de migração mais simples, mas ele também gera mais tempo de inatividade para o seu cluster.

O processo básico para a migração offline é o seguinte:

1. Desativar gravações para a origem do MongoDB.2. Descartar índices e dados de coleta da implantação do MongoDB de origem.3. Restaurar índices ao cluster do Amazon DocumentDB.4. Restaurar dados de coleta ao cluster do Amazon DocumentDB.5. Alterar o endpoint do aplicativo para gravar o cluster do Amazon DocumentDB.

109


Amazon DocumentDB Guia do desenvolvedorOnline

OnlineA abordagem online usa o AWS Database Migration Service (AWS DMS). Ela executa uma carga total dedados da implantação do MongoDB de origem no cluster do Amazon DocumentDB. Em seguida, ela mudapara o modo de captura de dados de alteração (CDC) a fim de replicar as alterações. A abordagem onlineminimiza o tempo de inatividade de seu cluster, mas é o mais lento dos três métodos.

O processo básico para a migração online é o seguinte:

1. Seu aplicativo usa o banco de dados de origem normalmente.2. Opcionalmente, pré-crie índices no cluster do Amazon DocumentDB.3. Criar uma tarefa do AWS DMS para executar uma carga total e, em seguida, habilitar a CDC da

implantação do MongoDB de origem para o cluster do Amazon DocumentDB.4. Após a tarefa do AWS DMS ter concluído o carregamento completo e replicar as alterações para o

Amazon DocumentDB, mude o endpoint do aplicativo para o cluster do Amazon DocumentDB.

110

Amazon DocumentDB Guia do desenvolvedorAbordagem híbrida

Para obter mais informações sobre como usar o AWS DMS para migrar, consulte Usar o AmazonDocumentDB como destino para o AWS Database Migration Service e o Tutorial relacionado no Guia dousuário do AWS Database Migration Service.

Abordagem híbridaA abordagem híbrida usa o mongodump e as ferramentas da mongorestore para migrar os dados daimplantação do MongoDB de origem para o cluster do Amazon DocumentDB. Depois, ele usa o AWSDMS no modo CDC para replicar alterações. A abordagem híbrida equilibra a velocidade e o tempo deinatividade da migração, mas é a mais complexa das três abordagens.

O processo básico para a migração híbrida é o seguinte:

1. Seu aplicativo usa a implantação do MongoDB de origem normalmente.2. Descartar índices e dados de coleta da implantação do MongoDB de origem.3. Restaurar índices ao cluster do Amazon DocumentDB.4. Restaurar dados de coleta ao cluster do Amazon DocumentDB.5. Criar uma tarefa do AWS DMS para habilitar a CDC da implantação do MongoDB de origem para o

cluster do Amazon DocumentDB.6. Se a tarefa do AWS DMS é replicar as alterações em uma janela aceitável, altere o endpoint do

aplicativo para gravar no cluster do Amazon DocumentDB.

111




Amazon DocumentDB Guia do desenvolvedorOrigens de migração

Important

Atualmente, uma tarefa do AWS DMS pode migrar apenas um único banco de dados. Se a origemdo MongoDB tiver um grande número de bancos de dados, poderá ser necessário automatizar acriação de tarefas de migração ou usar o método offline.

Independentemente da abordagem de migração escolhida, é mais eficiente pré-criar índices no clusterdo Amazon DocumentDB antes de migrar seus dados. Isso ocorre porque os índices do AmazonDocumentDB são dados inseridos em paralelo, mas a criação de um índice em dados existentes é umaoperação de um único thread.

Como o AWS DMS não migra índices (somente os dados), não há nenhuma etapa extra necessária paraevitar a criação de índices pela segunda vez.

Origens de migraçãoSe a origem do MongoDB for um processo independente do mongo e quiser usar as abordagens demigração online ou híbrida, primeiro converta seu mongo independente em um conjunto de réplicas paraque o oplog seja criado para ser usado como origem do CDC.

Se você estiver migrando a partir de um conjunto de réplicas do MongoDB ou um cluster estilhaçado,considere criar um secundário encadeado ou oculto para cada conjunto de réplicas ou estilhaço paraser usado como origem de migração. A execução de dumps de dados pode fazer com que os dados doconjunto de trabalho fiquem sem memória e afetar o desempenho em instâncias de produção. Você podereduzir esse risco efetuando a migração de um nó que não sirva dados de produção.

Versões de origem de migração

112

Amazon DocumentDB Guia do desenvolvedorConectividade de migração

Se a versão do seu banco de dados de origem do MongoDB for diferente da versão de compatibilidadedo seu cluster de destino do Amazon DocumentDB, pode ser necessário realizar outras etapas depreparação para garantir uma migração bem-sucedida. Os dois requisitos mais comuns encontrados são anecessidade de atualizar a instalação de origem do MongoDB em uma versão com suporte para migraçãodo MongoDB (versão 3.0 ou superior) e atualizar seus drivers do aplicativo para oferecer suporte à versãode destino do Amazon DocumentDB.

Se a sua migração tiver um desses requisitos, inclua essas etapas em seu plano de migração paraatualizar e testar todas as alterações do driver.

Important

No momento, o AWS DMS não é compatível com o MongoDB 4.0 ou posterior como origem demigração.

Conectividade de migraçãoVocê pode migrar para o Amazon DocumentDB a partir de uma implantação de origem do MongoDBem execução no seu datacenter ou de uma implantação do MongoDB em execução em uma instânciado Amazon EC2. A migração do MongoDB em execução no EC2 é simples e requer apenas que vocêconfigure corretamente seus grupos de segurança e sub-redes.

A migração de um banco de dados local requer conectividade entre a implantação do MongoDB e suanuvem privada virtual (VPC). Você pode fazer isso por meio de uma conexão de rede privada virtual (VPN)ou usando o serviço AWS Direct Connect. Embora você possa migrar pela Internet para sua VPC, essemétodo de conexão é o menos desejável do ponto de vista da segurança.

O diagrama a seguir ilustra uma migração para o Amazon DocumentDB a partir de uma origem local pormeio de uma conexão VPN.

113

Amazon DocumentDB Guia do desenvolvedorConectividade de migração

O seguinte representa uma migração para o Amazon DocumentDB a partir de uma origem local usando oAWS Direct Connect.

As abordagens de migração online e híbrida exigem o uso de uma instância do AWS DMS, que deve serexecutada no Amazon EC2 em uma Amazon VPC. Todas as abordagens exigem que um servidor demigração execute mongodump e mongorestore. Em geral, é mais fácil executar o servidor de migraçãoem uma instância do Amazon EC2 na VPC onde o cluster do Amazon DocumentDB é iniciado, poissimplifica muito a conectividade com o seu cluster do Amazon DocumentDB.

114

Amazon DocumentDB Guia do desenvolvedorno dispositivo

no dispositivoVeja a seguir os objetivos de testes de pré-migração:

• Verifique se a abordagem escolhida atinge o resultado de migração desejado.• Verifique se o tipo de instância e as opções de preferência de leitura atendem aos seus requisitos de

desempenho do aplicativo.• Verifique o comportamento de seu aplicativo durante o failover.

Considerações sobre os testes do plano de migraçãoConsidere o seguinte ao testar seu plano de migração do Amazon DocumentDB.

Tópicos• Restauração de índices (p. 115)• Despejo de dados (p. 115)• Como restaurar dados (p. 115)• Dimensionamento do Oplog (p. 116)• Configuração do AWS Database Migration Service (p. 116)• Migração de um cluster estilhaçado (p. 116)

Restauração de índicesPor padrão, mongorestore cria índices para coleções despejadas, mas as cria depois que os dados sãorestaurados. Em geral, é mais rápido criar índices no Amazon DocumentDB antes que os dados sejamrestaurados para o cluster. Isso ocorre porque as operações de indexação são paralelizadas durante ocarregamento de dados.

Se você optar por criar previamente seus índices, ignore a etapa de criação de índices ao restaurar dadoscom mongorestore fornecendo a opção -–noIndexRestore.

Despejo de dadosA ferramenta mongodump é o método preferencial do despejo de dados da sua implantação de origemdo MongoDB. Dependendo dos recursos disponíveis na instância de migração, você pode acelerar omongodump aumentando o número de conexões paralelas despejadas do padrão 4 usando a opção –-numParallelCollections.

Como restaurar dadosA ferramenta mongorestore é o método preferencial para restaurar dados despejados parasua instância do Amazon DocumentDB. Você pode melhorar o desempenho da restauraçãoaumentando o número de operadores para cada coleção durante a restauração com a opção -–numInsertionWorkersPerCollection. Um operador por vCPU na instância principal do cluster doAmazon DocumentDB é um bom ponto de partida.

O Amazon DocumentDB não oferece suporte à opção --oplogReplay da ferramenta mongorestore.

Por padrão, o mongorestore ignora erros de inserção e continua o processo de restauração. Isso poderáocorrer se você estiver restaurando dados sem suporte em sua instância do Amazon DocumentDB. Por

115

Amazon DocumentDB Guia do desenvolvedorConsiderações sobre os testes do plano de migração

exemplo, poderá acontecer se você tiver um documento que contenha chaves ou valores com stringsnulas. Se você preferir que a operação mongorestore falhe inteiramente se qualquer erro de restauraçãofor encontrado, use a opção --stopOnError.

Dimensionamento do OplogO registro de operações do MongoDB (oplog) é uma coleção limitada que contém todas as modificaçõesde dados para seu banco de dados. Você pode visualizar o tamanho do oplog e o intervalo de tempo queele contém ao executar a operação db.printReplicationInfo() em um conjunto de réplicas oumembro do estilhaço.

Se você estiver usando as abordagens híbrida ou online, certifique-se de que o oplog em cada conjuntode réplicas ou estilhaço seja grande o suficiente para conter todas as alterações feitas durante toda aduração do processo de migração de dados (seja por mongodump ou uma carga completa de tarefas doAWS DMS), além de um buffer razoável. Para obter mais informações, consulte Verificar o tamanho dooplog na documentação do MongoDB. Determine o tamanho mínimo necessário do oplog registrando otempo utilizado pelo primeiro teste do processo mongodump ou mongorestore ou pela tarefa de cargacompleta do AWS DMS.

Configuração do AWS Database Migration ServiceO Guia do usuário do AWS Database Migration Service abrange os componentes e as etapas necessáriaspara migrar seus dados de origem do MongoDB para o seu cluster do Amazon DocumentDB. Veja a seguiro processo básico para usar o AWS DMS para executar uma migração online ou híbrida:

Para executar uma migração usando o AWS DMS

1. Crie um endpoint de origem do MongoDB. Para obter mais informações, consulte Uso do MongoDBcomo uma origem para o AWS DMS.

2. Crie um endpoint de destino do Amazon DocumentDB. Para obter mais informações, consulte Comotrabalhar com endpoints do AWS DMS.

3. Crie pelo menos uma instância de replicação do AWS DMS. Para obter mais informações, consulteComo trabalhar com uma instância de replicação do AWS DMS.

4. Crie pelo menos uma tarefa de replicação do AWS DMS. Para obter mais informações, consulte Comotrabalhar com tarefas do AWS DMS.

Para uma migração online, a tarefa de migração usa o tipo de migração Migrate existing data andreplicate ongoing changes (Migrar dados existentes e replicar as alterações em andamento).

Para uma migração híbrida, a tarefa de migração usa o tipo de migração Replicate data changes only(Replicar apenas as alterações de dados). Você pode escolher o horário de início do CDC para sealinhar com o tempo de despejo da sua operação mongodump. O oplog do MongoDB é idempotente.Para evitar a perda de alterações, é recomendável deixar alguns minutos de sobreposição entre ahora de término mongodump e a hora de início do CDC.

Migração de um cluster estilhaçadoO processo para migrar dados de um cluster estilhaçado para sua instância do Amazon DocumentDBé essencialmente o de várias migrações de conjunto de réplicas em paralelo. Uma consideraçãoimportante ao testar uma migração de cluster estilhaçado é que alguns estilhaços podem ser usados maisamplamente do que outros. Essa situação leva a diferentes intervalos de tempo decorridos para migraçãode dados. Certifique-se de que você avalie os requisitos de oplog de cada estilhaço no planejamento e noteste.

Veja a seguir alguns problemas de configuração a serem considerados ao migrar um cluster estilhaçado:

116

https://docs.aws.amazon.com/dms/latest/userguide/Welcome.html



https://docs.aws.amazon.com/dms/latest/userguide/CHAP_Endpoints.html

https://docs.aws.amazon.com/dms/latest/userguide/CHAP_Endpoints.html

https://docs.aws.amazon.com/dms/latest/userguide/CHAP_ReplicationInstance.html

https://docs.aws.amazon.com/dms/latest/userguide/CHAP_Tasks.html

https://docs.aws.amazon.com/dms/latest/userguide/CHAP_Tasks.html

Amazon DocumentDB Guia do desenvolvedorTestes de desempenho

• Antes de executar mongodump ou iniciar uma tarefa de migração do AWS DMS, desativa o balanceadorde cluster estilhaçado e aguarde até que todas as migrações em andamento sejam concluídas. Paraobter mais informações, consulte Desativar o balanceador na documentação do MongoDB.

• Se você estiver usando o AWS DMS para replicar dados, execute o comando cleanupOrphaned emcada estilhaço antes de executar as tarefas de migração. Se você não executar esse comando, poderáocorrer uma falha nas tarefas devido à duplicação de IDs de documento. Observe que esse comandopode afetar o desempenho. Para obter mais informações, consulte cleanupOrphaned na documentaçãodo MongoDB.

• Se você estiver usando a ferramenta mongodump para despejar dados, execute um processomongodump por estilhaço. A abordagem mais rápida pode exigir vários servidores de migração paramaximizar o desempenho do despejo.

• Se você estiver usando o AWS Database Migration Service para replicar dados, crie um endpointde origem para cada estilhaço. Além disso, execute pelo menos uma tarefa de migração para cadaestilhaço que você estiver migrando. A abordagem mais rápida pode exigir várias instâncias dereplicação para maximizar o desempenho da migração.

Testes de desempenhoAssim que conseguir migrar seus dados para o cluster de teste do Amazon DocumentDB, execute suacarga de trabalho de teste no cluster. Verifique por meio das métricas do Amazon CloudWatch se seudesempenho atende ou excede a taxa de transferência atual da implantação de origem do MongoDB.

Verifique as seguintes métricas essenciais do Amazon DocumentDB:

• Taxa de transferência na rede• Taxa de transferência de gravação• Taxa de transferência de leitura• Atraso da réplica

Para obter mais informações, consulte Monitoramento do Amazon DocumentDB (p. 335).

Testes de failoverVerifique se o comportamento do aplicativo durante um evento de failover do Amazon DocumentDBatende aos seus requisitos de disponibilidade. Para iniciar um failover manual de um cluster do AmazonDocumentDB no console, na página Clusters, escolha a ação Failover no menu Actions (Ações).

Você também pode iniciar um failover executando a operação failover-db-cluster a partir da AWSCLI. Para obter mais informações, consulte failover-db-cluster na seção do Amazon DocumentDBda referência de AWS CLI.

Recursos adicionaisVeja os seguintes tópicos no Guia do usuário do AWS Database Migration Service:

• Uso do Amazon DocumentDB como destino para o AWS Database Migration Service• Demonstração: Migração do MongoDB para Amazon DocumentDB

117

https://docs.aws.amazon.com/cli/latest/reference/rds/failover-db-cluster.html



Amazon DocumentDB Guia do desenvolvedorProteção de dados

Segurança no Amazon DocumentDBA segurança da nuvem na AWS é a nossa maior prioridade. Como cliente da AWS, você aproveita umdatacenter e uma arquitetura de rede criados para atender aos requisitos das empresas com as maioresexigências de segurança.

A segurança é uma responsabilidade compartilhada entre a AWS e você. Esta documentação ajuda vocêa entender como aplicar o modelo de responsabilidade compartilhada ao usar o Amazon DocumentDB. Omodelo de responsabilidade compartilhada descreve a segurança da nuvem e a segurança na nuvem:

• Segurança da nuvem — a AWS é responsável por proteger a infraestrutura que executa serviços daAWS na Nuvem AWS. A AWS também fornece serviços que você pode usar com segurança. Auditoresde terceiros testam e verificam regularmente a eficácia da nossa segurança como parte dos programasde conformidade da AWS. Para saber mais sobre os programas de conformidade que se aplicam àAmazon DocumentDB (compatível com MongoDB), consulte Serviços da AWS no escopo por programade conformidade.

• Segurança na nuvem — a responsabilidade é determinada pelo serviço da AWS usado. Você tambémé responsável por outros fatores, incluindo a confidencialidade de seus dados, os requisitos da suaorganização e as leis e regulamentos aplicáveis.

Você também aprende como usar outros serviços da AWS que ajudam a monitorar e proteger os recursosdo Amazon DocumentDB. Os tópicos a seguir mostram como configurar o Amazon DocumentDB paraatender aos seus objetivos de segurança e conformidade.

Tópicos• Proteção de dados no Amazon DocumentDB (p. 118)• Identity and Access Management no Amazon DocumentDB (p. 129)• Gerenciamento de usuários do Amazon DocumentDB (p. 142)• Restringir o acesso ao banco de dados usando o controle de acesso baseado em função (funções

internas) (p. 144)• Registro em log e monitoramento no Amazon DocumentDB (p. 157)• Updating Your Amazon DocumentDB TLS Certificates (p. 158)• Validação de conformidade no Amazon DocumentDB (p. 166)• Resiliência no Amazon DocumentDB (p. 167)• Segurança da infraestrutura no Amazon DocumentDB (p. 167)• Melhores práticas de segurança para o Amazon DocumentDB (p. 168)• Auditoria de eventos do Amazon DocumentDB (p. 168)

Proteção de dados no Amazon DocumentDBAmazon DocumentDBO está em conformidade com o modelo de responsabilidade compartilhada daAWS, que inclui as normas e diretrizes para proteção de dados. A AWS é responsável pela proteção dainfraestrutura global que executa todos os serviços da AWS. A AWS mantém o controle sobre os dadoshospedados nessa infraestrutura, incluindo os controles de configuração de segurança para lidar comconteúdos e dados pessoais dos clientes. Os clientes da AWS e os parceiros da APN, atuando comocontroladores de dados ou processadores de dados, são responsáveis por todos os dados pessoais quecolocam na Nuvem AWS.

118

https://aws.amazon.com/compliance/shared-responsibility-model/

https://aws.amazon.com/compliance/programs/


https://aws.amazon.com/compliance/services-in-scope/


Amazon DocumentDB Guia do desenvolvedorCriptografar dados em repouso do

Para fins de proteção de dados, recomendamos que proteja as credenciais da conta AWS e configurecontas de utilizador individuais com AWS Identity and Access Management (IAM), para que cada utilizadorreceba apenas as permissões necessárias para cumprir os seus deveres profissionais. Recomendamostambém que você proteja seus dados das seguintes formas:

• Use uma autenticação multifator (MFA) com cada conta.• Use SSL/TLS para se comunicar com os recursos da AWS.• Configure o registro em log das atividades da API e do usuário com o AWS CloudTrail.• Use as soluções de criptografia da AWS, juntamente com todos os controles de segurança padrão nos

serviços da AWS.• Use serviços gerenciados de segurança avançada, como o Amazon Macie, que ajudam a localizar e

proteger dados pessoais que são armazenados no Amazon Simple Storage Service (Amazon S3).

Recomendamos vivamente que nunca coloque informações de identificação sensíveis, tais como osnúmeros de conta dos seus clientes, em campos de forma livre, tais como Nome campo. Isto inclui quandotrabalha com Amazon DocumentDB ou outros serviços AWS utilizando o Console de gerenciamento daAWS, API, AWS CLI, ou SDK de AWS. Todos os dados inseridos no Amazon DocumentDB ou em outrosserviços poderão ser selecionados para inclusão em logs de diagnóstico. Ao fornecer um URL para umservidor externo, não inclua informações de credenciais no URL para validar a solicitação a esse servidor.

Para mais informações sobre proteção de dados, consulte o Modelo de responsabilidade partilhada AWS eRGPD publicação do blogue no Blogue de segurança AWS.

Tópicos• Encriptação Amazon DocumentDB Dados em repouso (p. 119)• Criptografia de dados em trânsito (p. 122)• Gerenciamento de chaves (p. 128)

Encriptação Amazon DocumentDB Dados em repousoVocê criptografa os dados em repouso no cluster do Amazon DocumentDB especificando a opção decriptografia de armazenamento ao criar o cluster. A criptografia de armazenamento é ativada em todo ocluster e é aplicada a todas as instâncias, incluindo a instância principal e todas as réplicas. Ela tambémé aplicada a volumes de armazenamento, dados, índices, logs, backups automatizados e snapshots docluster.

Amazon DocumentDBO usa o Advanced Encryption Standard de 256 bits (AES-256) para criptografarseus dados usando chaves de criptografia armazenadas em AWS Key Management Service (AWSKMS). Quando utilizar um Amazon DocumentDB com encriptação em descanso ativado, não precisa demodificar a lógica da sua aplicação ou a ligação ao cliente. Amazon DocumentDB processa a encriptaçãoe desencriptação dos seus dados de forma transparente, com impacto mínimo no desempenho.

Amazon DocumentDB integra com AWS KMS e utiliza um método conhecido como encriptação deenvelope para proteger os seus dados. Quando um Amazon DocumentDB o cluster está encriptado comum AWS KMS chave mestre de cliente (CMK), Amazon DocumentDB perguntar AWS KMS para utilizaro seu CMK para gerar uma chave de dados de eletutexto para encriptar o volume de armazenamento.A chave de dados de texto cifrado é criptografada usando a CMK definida e armazenada com os dadoscriptografados e os metadados de armazenamento. Quando Amazon DocumentDB precisa de aceder aosseus dados encriptados, solicita AWS KMS para desencriptar a chave de dados de eletutexto utilizandoo seu CMK e caches a chave de dados de linha na memória para encriptar e desencriptar dados comeficiência no volume de armazenamento.

As instalações de encriptação de armazenamento em Amazon DocumentDB está disponível para todosos tamanhos de instância suportados e em todas as regiões AWS onde Amazon DocumentDB estádisponível.

119

https://aws.amazon.com/blogs/security/the-aws-shared-responsibility-model-and-gdpr/

https://aws.amazon.com/blogs/security/the-aws-shared-responsibility-model-and-gdpr/

https://docs.aws.amazon.com/kms/latest/APIReference/API_GenerateDataKeyWithoutPlaintext.html


Ativar encriptação em repouso para um Amazon DocumentDBClusterPode ativar ou desativar a encriptação em repouso Amazon DocumentDB quando o cluster é provisionadoutilizando o Console de gerenciamento da AWS ou o AWS Command Line Interface (AWS CLI). Osclusters criados usando o console têm a criptografia em repouso habilitada por padrão. Os clusters criadosusando a AWS CLI têm a criptografia em repouso desabilitada por padrão. Por conseguinte, tem de ativarexplicitamente a encriptação em repouso utilizando o --storage-encrypted parâmetro. Em ambos oscasos, após o cluster ser criado, não é possível alterar a opção de criptografia em repouso.

Amazon DocumentDB utilizações AWS KMS para recuperar e gerir as chaves de encriptação, e paradefinir as políticas que controlam como estas teclas podem ser utilizadas. Se não especificar um AWSKMS identificador chave, Amazon DocumentDB utiliza a chave mestre de cliente de serviço gerido pelaAWS (CMK). Amazon DocumentDB cria um CMK separado para cada região AWS na sua conta AWS.Para mais informações, consulte Conceitos de serviço de gestão chave AWS.

Para começar a criar o seu próprio CMK, consulte Começar no AWS Key Management Service DeveloperGuide.

Important

Você deve usar uma CMK simétrica para criptografar o cluster, pois o Amazon DocumentDBsó oferece suporte a CMKs simétricas. Não utilize um CMK assimétrico para tentar encriptar osdados no seu Amazon DocumentDB grupos. Para mais informações, consulte Utilizar teclassimétricas e assimétricas no AWS Key Management Service Developer Guide.

Se Amazon DocumentDB já não pode obter acesso à chave de encriptação para um grupo — por exemplo,quando o acesso a uma chave é revogado — o cluster encriptado entra num estado de terminal. Nessecaso, só é possível restaurar o cluster a partir de um backup. Para o Amazon DocumentDB, os backupsestão sempre habilitados para 1 dia.

Além disso, se você desabilitar a chave para um cluster do Amazon DocumentDB criptografado, nãoserá possível ler ou gravar nesse cluster. Quando o Amazon DocumentDB encontra um cluster que écriptografado por uma chave à qual ele não tem acesso, ele coloca o cluster em um estado terminal. Nesseestado, o cluster deixa de estar disponível e o estado atual do banco de dados não pode ser recuperado.Para restaurar o cluster, você deve reativar o acesso à chave de criptografia para o Amazon DocumentDBe, depois, restaurar o cluster a partir de um backup.

Important

Não é possível alterar o CMK para um cluster criptografado depois de já tê-lo criado. Certifique-sede determinar seus requisitos de chave de criptografia antes de criar seu cluster criptografado.


Especifique a opção de criptografia em repouso ao criar um cluster. A criptografia em repouso é habilitadapor padrão quando você cria um cluster usando o Console de gerenciamento da AWS. Não é possívelalterá-la após criar o cluster.

Para especificar a opção de criptografia em repouso ao criar o cluster

1. Criar um Amazon DocumentDB como descrito no Começar secção. No entanto, no passo 6, nãoescolha Criar grupo.

2. Sob o Autenticação secção, escolha Mostrar definições avançadas.3. Deslocar para baixo até ao Encriptação em repouso secção.4. Escolha a opção que deseja para a criptografia em repouso. Seja qual for a opção que escolher, não

será possível alterá-la após criar o cluster.• Para encriptar dados em repouso neste grupo, escolha Ativar encriptação.

120

https://docs.aws.amazon.com/kms/latest/developerguide/concepts.html

https://docs.aws.amazon.com/kms/latest/developerguide/getting-started.html

https://docs.aws.amazon.com/kms/latest/developerguide/symmetric-asymmetric.html

https://docs.aws.amazon.com/kms/latest/developerguide/symmetric-asymmetric.html

https://docs.aws.amazon.com/documentdb/latest/developerguide/connect-ec2.launch-cluster.html


• Se não quiser encriptar dados em repouso neste grupo, escolha Desativar encriptação.5. Escolha a chave principal que pretende. Amazon DocumentDB utiliza o AWS Key Management

Service (AWS KMS) para recuperar e gerir as chaves de encriptação, e para definir as políticasque controlam a forma como estas teclas podem ser utilizadas. Se não especificar um AWS KMSidentificador chave, Amazon DocumentDB utiliza o serviço de gestão por defeito da AWS, CMK. Paramais informações, consulte Conceitos de serviço de gestão chave AWS.

Note

Depois de criar um cluster criptografado, não é possível alterar o CMK para esse cluster.Certifique-se de determinar seus requisitos de chave de criptografia antes de criar seu clustercriptografado.

6. Complete as outras seções conforme o necessário e crie o cluster.

Uso do AWS CLI

Para encriptar um Amazon DocumentDB cluster utilizando o AWS CLI, tem de especificar o --storage-encrypted quando criar o grupo. Amazon DocumentDB clusters criados utilizando o AWS CLI não activea encriptação de armazenamento por predefinição.

Veja a seguir um exemplo de como criar um cluster do Amazon DocumentDB com a criptografia dearmazenamento ativada.

Example


aws docdb create-db-cluster \ --db-cluster-identifier sample-cluster \ --port 27017 \ --engine docdb \ --master-username yourMasterUsername \ --master-user-password yourMasterPassword \ --storage-encrypted

Para Windows:

aws docdb create-db-cluster ^ --db-cluster-identifier sample-cluster ^ --port 27017 ^ --engine docdb ^ --master-username yourMasterUsername ^ --master-user-password yourMasterPassword ^ --storage-encrypted

Quando criar um código de barras encriptado Amazon DocumentDB cluster, pode especificar um AWSKMS identificador de chave, como no exemplo seguinte.

Example


aws docdb create-db-cluster \ --db-cluster-identifier sample-cluster \ --port 27017 \ --engine docdb \ --master-username yourMasterUsername \ --master-user-password yourMasterPassword \ --storage-encrypted \

121

https://docs.aws.amazon.com/kms/latest/developerguide/concepts.html

Amazon DocumentDB Guia do desenvolvedorCriptografia de dados em trânsito

--kms-key-id key-arn-or-alias

Para Windows:

aws docdb create-db-cluster ^ --db-cluster-identifier sample-cluster ^ --port 27017 ^ --engine docdb ^ --master-username yourMasterUsername ^ --master-user-password yourMasterPassword ^ --storage-encrypted ^ --kms-key-id key-arn-or-alias

Note

Depois de criar um cluster criptografado, não é possível alterar o CMK para esse cluster.Certifique-se de determinar seus requisitos de chave de criptografia antes de criar seu clustercriptografado.

Limitações para Amazon DocumentDB Clusters encriptadosExistem as seguintes limitações para Amazon DocumentDB clusters encriptados.

• Você pode habilitar ou desabilitar a criptografia em repouso para um cluster do Amazon DocumentDBsomente no momento em que ele é criado, e não após a criação ser concluída. No entanto, pode criaruma cópia encriptada de um cluster não encriptado, criando uma imagem do grupo não encriptado e,em seguida, restaurando o instantâneo não encriptado como um novo grupo, ao mesmo tempo queespecifica a encriptação na opção de descanso.

Para obter mais informações, consulte os seguintes tópicos:• Criação de um snapshot manual de cluster (p. 184)• Restauração de um snapshot de cluster (p. 196)• Copiar Amazon DocumentDB Instantâneos de aglomerados (p. 186)

• Amazon DocumentDBOs clusters do com criptografia de armazenamento habilitada não podem sermodificados para desabilitar a criptografia.

• Todas as instâncias, os backups automatizados, os snapshots e os índices em um cluster do AmazonDocumentDB são criptografados com a mesma CMK.

Criptografia de dados em trânsitoVocê pode usar o Transport Layer Security (TLS) para criptografar a conexão entre o aplicativo e umcluster do Amazon DocumentDB. Por padrão, a criptografia em trânsito é habilitada para clusters doAmazon DocumentDB recém-criados. Você pode desabilitá-la ao criar o cluster ou depois da criação serconcluída. Ao habilitar a criptografia em trânsito, as conexões seguras usando o TLS são obrigatórias parase conectar ao cluster. Para obter mais informações sobre como se conectar ao Amazon DocumentDBusando TLS, consulte Conexão com o Amazon DocumentDB de forma programática (p. 360).

Gerenciamento de configurações de TLS do cluster do AmazonDocumentDBA criptografia em trânsito para um cluster do Amazon DocumentDB é gerenciada por meio do parâmetrodo TLS em um grupo de parâmetros de cluster. Você pode gerenciar as configurações de TLS docluster do Amazon DocumentDB usando o Console de gerenciamento da AWS ou a AWS CommandLine Interface (AWS CLI). Consulte as seções a seguir para saber como verificar e modificar suasconfigurações de TLS atuais.

122

https://docs.aws.amazon.com/documentdb/latest/developerguide/cluster_parameter_groups.html


Usar o Console de gerenciamento da AWS

Siga essas etapas executar tarefas de gerenciamento para a criptografia de TLS usando o console, comoidentificar grupos de parâmetros, verificar o valor de TLS e fazer as modificações necessárias.

Note

A menos que você especifique de outra forma ao criar o cluster, ele será criado com o grupo deparâmetros de cluster padrão. Os parâmetros no grupo de parâmetros de cluster default nãopodem ser modificados (por exemplo, tls habilitado/desabilitado). Portanto, se o cluster estiverusando um grupo de parâmetros de cluster default, será necessário modificar o cluster parausar um grupo de parâmetros de cluster que não seja padrão. Primeiro, será necessário criar umgrupo de parâmetros de cluster personalizado. Para obter mais informações, consulte CreatingAmazon DocumentDB Cluster Parameter Groups (p. 293).

1. Determine o grupo de parâmetros de cluster usado pelo cluster.

a. Abra o console do Amazon DocumentDB em https://console.aws.amazon.com/docdb.b. No painel de navegação, escolha Clusters.

Tip

Se você não visualizar o painel de navegação à esquerda da tela, selecione o ícone domenu ( ) nocanto superior esquerdo da página.

c. Na lista de clusters, selecione o nome do cluster desejado.d. Role para baixo até a parte inferior de Cluster details (Detalhes do cluster) e localize o Cluster

parameter group (Grupo de parâmetros do cluster). Anote o nome do grupo de parâmetros decluster.

Se o nome do grupo de parâmetros do cluster for default (por exemplo default.docdb3.6),será necessário criar um grupo de parâmetros de cluster personalizado e defini-lo como o grupode parâmetros do cluster antes de continuar. Para obter mais informações, consulte:

1. Creating Amazon DocumentDB Cluster Parameter Groups (p. 293) — se você não tiver umgrupo de parâmetros de cluster personalizado para usar, crie um.

2. Modificar um cluster do Amazon DocumentDB (p. 231) — modifique seu cluster para usar ogrupo de parâmetros de cluster personalizado.

2. Determine o valor atual do parâmetro de cluster tls.

a. Abra o console do Amazon DocumentDB em https://console.aws.amazon.com/docdb.b. No painel de navegação, selecione Parameter groups.c. Na lista de grupos de parâmetros, selecione o nome do grupo de parâmetros de cluster desejado.d. Localize a seção Cluster parameters (Parâmetros do cluster). Na lista de parâmetros de cluster,

localize a linha do parâmetro de cluster tls. Nesse momento, as quatro colunas a seguir sãoimportantes:

• Nome do parâmetro de cluster — o nome do parâmetro de cluster. Para gerenciar TLS, vocêestá interessado no parâmetro de cluster tls.

• Valores — o valor atual de cada parâmetro de cluster.• Valores permitidos — uma lista de valores que podem ser aplicados a um parâmetro de cluster.• Aplicar tipo — pode ser static (estático) ou dynamic (dinâmico). As alterações em parâmetros

de cluster estáticos poderão ser aplicadas somente quando as instâncias forem reiniciadas. Asalterações feitas em parâmetros de cluster dinâmicos podem ser aplicadas imediatamente ouquando as instâncias são reiniciadas.

3. Modifique o valor do parâmetro do cluster tls.

123




Se o valor de tls não for o que é necessário, modifique o valor para esse grupo de parâmetros decluster. Para alterar o valor do parâmetro de cluster tls, continue na seção anterior seguindo estasetapas.

a. Escolha o botão à esquerda do nome do parâmetro de cluster (tls).b. Selecione Edit.c. Para alterar o valor de tls, na caixa de diálogo Modify tls (Modificar tls), selecione o valor

desejado para o parâmetro de cluster na lista suspensa.d. Escolha Modify cluster parameter (Modificar parâmetro do cluster). A alteração será aplicada a

cada instância do cluster quando ela for reinicializada.4. Reinicialize a instância Amazon DocumentDB.

Reinicialize cada instância do cluster para que a alteração seja aplicada a todas as instâncias nocluster.

a. Abra o console do Amazon DocumentDB em https://console.aws.amazon.com/docdb.b. No painel de navegação, escolha Instances (Instâncias).c. Para especificar a reinicialização de uma instância, localize a instância na lista de instâncias e

escolha o botão à esquerda de seu nome.d. Escolha Actions (Ações) e Reboot (Reinicializar). Confirme se deseja reinicializar selecionado

Reboot (Reinicializar).

Usar a AWS CLI

Siga essas etapas executar tarefas de gerenciamento para a criptografia de TLS usando a AWS CLI, comoidentificar grupos de parâmetros, verificar o valor de TLS e fazer as modificações necessárias.

Note

A menos que você especifique de outra forma ao criar o cluster, ele será criado com o grupode parâmetros de cluster padrão. Os parâmetros no grupo de parâmetros de cluster defaultnão podem ser modificados (por exemplo, tls habilitado/desabilitado). Portanto, se o clusterestiver usando um grupo de parâmetros de cluster default, será necessário modificar o clusterpara usar um grupo de parâmetros de cluster que não seja padrão. Pode ser necessário primeirocriar um grupo de parâmetros de cluster personalizado. Para obter mais informações, consulteCreating Amazon DocumentDB Cluster Parameter Groups (p. 293).

1. Determine o grupo de parâmetros de cluster usado pelo cluster.

Use o comando describe-db-clusters com os seguintes parâmetros:

• --db-cluster-identifier — obrigatório. O nome do cluster de interesse.• --query — opcional. Uma consulta que limita a saída apenas aos campos de interesse, neste

caso, o nome do cluster e o nome do grupo de parâmetros de cluster.

aws docdb describe-db-clusters \ --db-cluster-identifier docdb-2019-05-07-13-57-08 \ --query 'DBClusters[*].[DBClusterIdentifier,DBClusterParameterGroup]'


[ [

124



"docdb-2019-05-07-13-57-08", "custom3-6-param-grp" ]]

Se o nome do grupo de parâmetros do cluster for default (por exemplo, default.docdb3.6),será necessário ter um grupo de parâmetros de cluster personalizado e defini-lo como o grupo deparâmetros do cluster antes de continuar. Para obter mais informações, consulte os tópicos a seguir:

1. Creating Amazon DocumentDB Cluster Parameter Groups (p. 293) — se você não tiver um grupode parâmetros de cluster personalizado para usar, crie um.

2. Modificar um cluster do Amazon DocumentDB (p. 231) — modifique seu cluster para usar o grupode parâmetros de cluster personalizado.

2. Determine o valor atual do parâmetro de cluster tls.

Para obter mais informações sobre esse grupo de parâmetros de cluster, use a operação describe-db-cluster-parameters com os seguintes parâmetros:

• --db-cluster-parameter-group-name — Obrigatório. Use o nome do grupo de parâmetros decluster de saída do comando anterior.

• --query — opcional. Uma consulta que limita a saída apenas aos campos de interesse, nessecaso, ParameterName, ParameterValue, AllowedValues e ApplyType.

aws docdb describe-db-cluster-parameters \ --db-cluster-parameter-group-name custom3-6-param-grp \ --query 'Parameters[*].[ParameterName,ParameterValue,AllowedValues,ApplyType]'


[ [ "audit_logs", "disabled", "enabled,disabled", "dynamic" ], [ "tls", "disabled", "disabled,enabled", "static" ], [ "ttl_monitor", "enabled", "disabled,enabled", "dynamic" ]]

3. Modifique o valor do parâmetro do cluster tls.

Se o valor de tls for o que ele precisa ser, modifique seu valor para este grupo de parâmetros decluster. Para alterar o valor do parâmetro de cluster tls, use a operação modify-db-cluster-parameter-group com os seguintes parâmetros.

125


• --db-cluster-parameter-group-name — Obrigatório. O nome do grupo de parâmetros decluster a ser modificado. Não pode ser um grupo de parâmetros de cluster default.*.

• --parameters — Obrigatório. Uma lista de parâmetros do grupo de parâmetros de cluster paramodificar.• ParameterName — obrigatório. O nome do parâmetro do cluster a ser modificado.• ParameterValue — obrigatório. O novo valor desse parâmetro de cluster. Deve ser um dosAllowedValues do parâmetro de cluster.• enabled — o cluster só aceita conexões seguras usando o TLS.• disabled — o cluster não aceita conexões seguras usando o TLS.

• ApplyMethod — quando essa modificação deve ser aplicada. Para parâmetros de clusterestáticos, como tle, esse valor deve ser pending-reboot.• pending-reboot — a alteração é aplicada a uma instância somente depois de ser

reinicializada. Você deve reinicializar cada instância de cluster individualmente para que essamudança ocorra em todas as instâncias do cluster.

O código a seguir desativa o tls, aplicando a alteração a cada instância de banco de dados quandoela é reinicializada.

aws docdb modify-db-cluster-parameter-group \ --db-cluster-parameter-group-name custom3-6-param-grp \ --parameters "ParameterName=tls,ParameterValue=disabled,ApplyMethod=pending-reboot"

O código a seguir ativa o tls, aplicando a alteração a cada instância de banco de dados quando ela éreinicializada.

aws docdb modify-db-cluster-parameter-group \ --db-cluster-parameter-group-name custom3-6-param-grp \ --parameters "ParameterName=tls,ParameterValue=enabled,ApplyMethod=pending-reboot"


{ "DBClusterParameterGroupName": "custom3-6-param-grp"}

4. Reinicialize sua instância Amazon DocumentDB.

Reinicialize cada instância do cluster para que a alteração seja aplicada a todas as instâncias nocluster. Para reinicializar uma instância do Amazon DocumentDB, use a operação reboot-db-instance com o seguinte parâmetro:

• --db-instance-identifier — obrigatório. O identificador da instância a ser reinicializada.

O código a seguir reinicializa a instância sample-db-instance.

Example


aws docdb reboot-db-instance \ --db-instance-identifier sample-db-instance

126


Para Windows:

aws docdb reboot-db-instance ^ --db-instance-identifier sample-db-instance


{ "DBInstance": { "AutoMinorVersionUpgrade": true, "PubliclyAccessible": false, "PreferredMaintenanceWindow": "fri:09:32-fri:10:02", "PendingModifiedValues": {}, "DBInstanceStatus": "rebooting", "DBSubnetGroup": { "Subnets": [ { "SubnetStatus": "Active", "SubnetAvailabilityZone": { "Name": "us-east-1a" }, "SubnetIdentifier": "subnet-4e26d263" }, { "SubnetStatus": "Active", "SubnetAvailabilityZone": { "Name": "us-east-1c" }, "SubnetIdentifier": "subnet-afc329f4" }, { "SubnetStatus": "Active", "SubnetAvailabilityZone": { "Name": "us-east-1e" }, "SubnetIdentifier": "subnet-b3806e8f" }, { "SubnetStatus": "Active", "SubnetAvailabilityZone": { "Name": "us-east-1d" }, "SubnetIdentifier": "subnet-53ab3636" }, { "SubnetStatus": "Active", "SubnetAvailabilityZone": { "Name": "us-east-1b" }, "SubnetIdentifier": "subnet-991cb8d0" }, { "SubnetStatus": "Active", "SubnetAvailabilityZone": { "Name": "us-east-1f" }, "SubnetIdentifier": "subnet-29ab1025" } ], "SubnetGroupStatus": "Complete", "DBSubnetGroupDescription": "default", "VpcId": "vpc-91280df6", "DBSubnetGroupName": "default"

127

Amazon DocumentDB Guia do desenvolvedorGerenciamento de chaves

}, "PromotionTier": 2, "DBInstanceClass": "db.r5.4xlarge", "InstanceCreateTime": "2018-11-05T23:10:49.905Z", "PreferredBackupWindow": "00:00-00:30", "KmsKeyId": "arn:aws:kms:us-east-1:012345678901:key/0961325d-a50b-44d4-b6a0-a177d5ff730b", "StorageEncrypted": true, "VpcSecurityGroups": [ { "Status": "active", "VpcSecurityGroupId": "sg-77186e0d" } ], "EngineVersion": "3.6.0", "DbiResourceId": "db-SAMPLERESOURCEID", "DBInstanceIdentifier": "sample-cluster-instance-00", "Engine": "docdb", "AvailabilityZone": "us-east-1a", "DBInstanceArn": "arn:aws:rds:us-east-1:012345678901:db:sample-cluster-instance-00", "BackupRetentionPeriod": 1, "Endpoint": { "Address": "sample-cluster-instance-00.corcjozrlsfc.us-east-1.docdb.amazonaws.com", "Port": 27017, "HostedZoneId": "Z2R2ITUGPM61AM" }, "DBClusterIdentifier": "sample-cluster" }}

Demora alguns minutos para sua instância reinicializar. Você pode usar a instância somentequando seu status for disponível. Você pode monitorar o status da instância usando o console ou aAWS CLI. Para obter mais informações, consulte Monitorar o status de uma instância do AmazonDocumentDB (p. 338).

Gerenciamento de chavesAmazon DocumentDB utilizações AWS Key Management Service (AWS KMS) para recuperar e gerir aschaves de encriptação. AWS KMS combina hardware e software seguros e altamente disponíveis parafornecer um sistema de gestão de chaves dimensionado para a nuvem. Utilizar AWS KMS, pode criarchaves de encriptação e definir as políticas que controlam como estas teclas podem ser utilizadas. AWSKMS suporta AWS CloudTrail, para que possa auditar a utilização da chave para verificar se as chavesestão a ser utilizadas adequadamente.

O seu AWS KMS podem ser utilizadas em conjunto com Amazon DocumentDB e serviços AWSsuportados, tais como Amazon Simple Storage Service (Amazon S3), Amazon Relational DatabaseService (Amazon RDS), Amazon Elastic Block Store (Amazon EBS), e Amazon Redshift. Para uma listade serviços que suportam AWS KMS, consulte Como os serviços AWS utilizam os AWS KMS no AWSKey Management Service Guia da Ferramenta de Desenvolvimento. Para informações sobre AWS KMS,consulte O que é o serviço de gestão de chaves AWS?

128

https://docs.aws.amazon.com/kms/latest/developerguide/service-integration.html

https://docs.aws.amazon.com/kms/latest/developerguide/overview.html

Amazon DocumentDB Guia do desenvolvedorIdentity and Access Management

Identity and Access Management no AmazonDocumentDB

O acesso para gerenciar recursos do Amazon DocumentDB (compatível com MongoDB) como clusters,instâncias e grupos de parâmetros de cluster exige credenciais que a AWS pode usar para autenticar suassolicitações. Essas credenciais devem ter permissões para acessar recursos da AWS, como uma instânciado Amazon DocumentDB. As seções a seguir fornecem detalhes sobre como é possível usar o AWSIdentity and Access Management (IAM) e o Amazon DocumentDB para ajudar a proteger seus recursoscontrolando quem pode acessá-los.

Tópicos• Autenticação (p. 129)• Visão geral do gerenciamento de permissões para seus recursos do Amazon DocumentDB (p. 130)• Gerenciamento do acesso usando políticas (p. 134)• Uso de políticas baseadas em identidade (IAM políticas) para o Amazon DocumentDB (p. 134)• Permissões da API do Amazon DocumentDB: referência de ações, recursos e condições (p. 137)

AutenticaçãoVocê pode acessar a AWS como alguns dos seguintes tipos de identidade:

• Usuário raiz da conta da AWS – Ao criar uma conta da AWS, você começa com uma única identidadede login que tenha acesso total a todos os recursos e serviços da AWS na conta. Essa identidade échamada de AWS da conta da usuário raiz e é acessada pelo login com o endereço de e-mail e a senhaque você usou para criar a conta. Recomendamos que não use o usuário raiz para suas tarefas diárias,nem mesmo as administrativas. Em vez disso, siga as melhores práticas de uso do usuário raiz somentepara criar seu primeiro usuário do IAM. Depois, armazene as credenciais usuário raiz com segurança euse-as para executar apenas algumas tarefas de gerenciamento de contas e de serviços.

• Usuário do IAM – um usuário do IAM é uma identidade na sua conta da AWS que tem permissõespersonalizadas específicas (por exemplo, para criar an instance no Amazon DocumentDB). Você podeusar uma senha e um nome do usuário do IAM para fazer login em páginas da web seguras da AWScomo o Console de gerenciamento da AWS, os Fóruns de discussão da AWS ou o AWS Support Center.

Além de um nome e uma senha de usuário, você também pode gerar chaves de acesso para cadausuário. Você pode usar essas chaves ao acessar serviços da AWS de forma programática, seja comum dos vários SDKs ou usando a AWS Command Line Interface (CLI). As ferramentas de SDK e de CLIusam as chaves de acesso para o cadastramento criptográfico da sua solicitação. Se você não utilizarferramentas da AWS, cadastre a solicitação você mesmo. Amazon DocumentDB supports Signatureversão 4, um protocolo para autenticar solicitações de API de entrada. Para mais informações sobrea autenticação de solicitações, consulte Processo de cadastramento do Signature versão 4 na AWSGeneral Reference.

• As funções IAM – Uma função do IAM é uma identidade do IAM que você pode criar em sua conta que

tenha permissões específicas. Uma função do IAM é semelhante a um usuário do IAM, pois é umaidentidade da AWS com políticas de permissão que determinam o que a identidade pode e não podefazer na AWS. No entanto, em vez de ser exclusivamente associada a uma pessoa, uma função destina-se a ser assumida por qualquer pessoa que precisar. Além disso, uma função não tem credenciais delongo prazo padrão, como uma senha ou chaves de acesso, associadas a ela. Em vez disso, quando

129

https://docs.aws.amazon.com/IAM/latest/UserGuide/introduction.html


https://docs.aws.amazon.com/IAM/latest/UserGuide/best-practices.html#create-iam-users

https://docs.aws.amazon.com/IAM/latest/UserGuide/best-practices.html#create-iam-users

https://docs.aws.amazon.com/IAM/latest/UserGuide/id_users.html

https://console.aws.amazon.com/

https://forums.aws.amazon.com/

https://console.aws.amazon.com/support/home#/

https://docs.aws.amazon.com/IAM/latest/UserGuide/id_credentials_access-keys.html

https://aws.amazon.com/tools/#sdk

https://aws.amazon.com/cli/

https://docs.aws.amazon.com/general/latest/gr/signature-version-4.html

https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles.html

Amazon DocumentDB Guia do desenvolvedorVisão geral do gerenciamento de acesso

você assumir uma função, ela fornecerá credenciais de segurança temporárias para sua sessão defunção. IAM com credenciais temporárias são úteis nas seguintes situações:

• Acesso de usuário federado – Em vez de criar um usuário do IAM, você pode usar identidades

existentes do AWS Directory Service, do diretório de usuário da sua empresa ou de um provedor deidentidades da Web. Estes são conhecidos como usuários federados. A AWS atribui uma função aum usuário federado quando o acesso é solicitado por meio de um provedor de identidades. Paraobter mais informações sobre usuários federados, consulte Usuários federados e funções no Guia dousuário do IAM.

• Acesso ao serviço da AWS – Uma função de serviço é uma função do IAM que um serviço assume

para realizar ações em seu nome na sua conta. Ao configurar alguns ambientes de serviço da AWS,você deve definir uma função a ser assumida pelo serviço. Essa função de serviço deve incluir todasas permissões necessárias para o serviço acessar os recursos da AWS de que precisa. As funçõesde serviço variam de acordo com o serviço, mas muitas permitem que você escolha as permissões,desde que atenda aos requisitos documentados para esse serviço. As funções de serviço fornecemacesso apenas dentro de sua conta e não podem ser usadas para conceder acesso a serviços emoutras contas. Você pode criar, modificar e excluir uma função de serviço no IAM. Por exemplo, vocêpode criar uma função que permita que Amazon Redshift acesse um bucket do Amazon S3 em seunome e carregue dados desse bucket em um cluster Amazon Redshift. Para obter mais informações,consulte Criar uma função para delegar permissões a um serviço da AWS no Guia do usuário do IAM.

• Execução de aplicativos no Amazon EC2 – Você pode usar uma função do IAM para gerenciar

credenciais temporárias para aplicativos que estão sendo executados em uma instância do EC2 e quefazem solicitações de API da AWS CLI ou AWS. É preferível fazer isso do que armazenar chaves deacesso na instância do EC2. Para atribuir uma função da AWS a uma instância do EC2 e disponibilizá-la para todos os seus aplicativos, crie um perfil de instância que esteja anexado à instância. Um perfilde instância contém a função e permite que programas que estão em execução na instância do EC2obtenham credenciais temporárias. Para mais informações, consulte Uso de uma função do IAM paraconceder permissões aos aplicativos em execução nas instâncias do Amazon EC2 no Guia do usuáriodo IAM.

Visão geral do gerenciamento de permissões paraseus recursos do Amazon DocumentDBTodo recurso da AWS é de propriedade de uma conta da AWS, e as permissões para criar ou acessar osrecursos são regidas por políticas de permissões. Um administrador de conta pode anexar políticas depermissões a identidades do IAM (ou seja, usuários, grupos e funções), e alguns serviços (como o AWSLambda) também oferecem suporte à anexação de políticas de permissões a recursos.

Note

Um administrador da conta (ou usuário administrador) é um usuário com permissões deadministrador. Para obter mais informações, consulte Melhores práticas do IAM no Guia dousuário do IAM.

Ao conceder permissões, você decide quem recebe as permissões, os recursos relacionados àspermissões concedidas e as ações específicas que deseja permitir nesses recursos.

Tópicos• Recursos e operações do Amazon DocumentDB (p. 131)• Entender a propriedade de recursos (p. 131)

130

https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_providers.html

https://docs.aws.amazon.com/IAM/latest/UserGuide/introduction_access-management.html#intro-access-roles

https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_create_for-service.html

https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_use_switch-role-ec2.html

https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_use_switch-role-ec2.html

https://docs.aws.amazon.com/IAM/latest/UserGuide/best-practices.html


• Gerenciamento do acesso aos recursos (p. 131)• Especificação de elementos da política: ações, efeitos, recursos e principais (p. 133)• Especificação de condições em uma política (p. 133)

Recursos e operações do Amazon DocumentDBNo Amazon DocumentDB, o principal recurso é um cluster. O Amazon DocumentDB é compatível comoutros recursos que podem ser usados com o recurso principal, como instâncias, parameter groups eassinaturas de eventos. Esses recursos são chamados de sub-recursos.

Esses recursos e sub-recursos têm Nomes de recurso da Amazon (ARNs) exclusivos associados a eles,conforme mostrado na tabela a seguir.

Tipo de recurso Formato de Nome de região da Amazon (ARN)

Cluster arn:aws:rds:region:account-id:cluster:db-cluster-name

Grupo de parâmetros docluster

arn:aws:rds:region:account-id:cluster-pg:cluster-parameter-group-name

Snapshot de cluster arn:aws:rds:region:account-id:cluster-snapshot:cluster-snapshot-name

Instância arn:aws:rds:region:account-id:db:db-instance-name

Grupo de segurança arn:aws:rds:region:account-id:secgrp:security-group-name

Grupo de sub-rede arn:aws:rds:region:account-id:subgrp:subnet-group-name

O Amazon DocumentDB fornece um conjunto de operações para funcionar com recursos do AmazonDocumentDB. Para obter uma lista das operações disponíveis, consulte Ações.

Entender a propriedade de recursosUm proprietário do recurso é a conta da AWS que criou um recurso. Isto é, o proprietário do recurso é aconta da AWS da entidade principal (a conta-raiz, um usuário do IAM ou uma função do IAM) que autenticaa solicitação que cria o recurso. Os exemplos a seguir ilustram como isso funciona:

• Se você usar as credenciais da conta raiz de sua conta da AWS para criar um recurso do AmazonDocumentDB, como uma instância, sua conta da AWS será a proprietária do recurso do AmazonDocumentDB.

• Se você criar um usuário do IAM na sua conta da AWS e conceder permissões para criar recursosdo Amazon DocumentDB para esse usuário, ele poderá criar recursos do Amazon DocumentDB. Noentanto, a sua conta da AWS, à qual o usuário pertence, é a proprietária dos recursos do AmazonDocumentDB.

• Se você criar uma função do IAM em sua conta da AWS com permissões para criar recursos doAmazon DocumentDB, qualquer pessoa que possa assumir a função poderá criar recursos do AmazonDocumentDB. Sua conta da AWS, à qual a função pertence, é a proprietária dos recursos do AmazonDocumentDB.

Gerenciamento do acesso aos recursosA política de permissões descreve quem tem acesso a quê. A seção a seguir explica as opçõesdisponíveis para a criação das políticas de permissões.

131

https://docs.aws.amazon.com/documentdb/latest/developerguide/API_Operations.html


Note

Esta seção discute como usar o IAM no contexto do Amazon DocumentDB. Não são fornecidasinformações detalhadas sobre o serviço do IAM. Para obter a documentação completa do IAM,consulte O que é o IAM? no Guia do usuário do IAM. Para obter mais informações sobre a sintaxede e as descrições de política do IAM, consulte Referência de política do IAM da AWS no Guia dousuário do IAM.

As políticas anexadas a uma identidade do IAM são chamadas de políticas baseadas em identidade(políticas do IAM). As políticas anexadas a um recurso são conhecidas como políticas baseadas emrecurso. O Amazon DocumentDB oferece suporte somente a políticas baseadas em identidade (políticasdo IAM).

Tópicos• Políticas baseadas em identidade (políticas do IAM) (p. 132)• Políticas com base em recurso (p. 133)

Políticas baseadas em identidade (políticas do IAM)Você pode anexar políticas a identidades do IAM. Por exemplo, você pode fazer o seguinte:

• Anexar uma política de permissões a um usuário ou a um grupo em sua conta – um administrador daconta pode usar uma política de permissões associada a um determinado usuário a fim de concederpermissões para que o usuário crie um recurso do Amazon DocumentDB, como uma instância.

• Anexar uma política de permissões a uma função (conceder permissões entre contas) – você podeanexar uma política de permissões com base em identidade a uma função do IAM para concederpermissões entre contas. Por exemplo, o administrador na Conta A pode criar uma função paraconceder permissões entre contas a outra conta da AWS (por exemplo, Conta B) ou um serviço da AWSda seguinte forma:1. Um administrador da Conta A cria uma função do IAM e anexa uma política de permissões à função

que concede permissões em recursos da Conta A.2. Um administrador da Conta A anexa uma política de confiança à função identificando a Conta B como

a principal, que pode assumir a função.3. A seguir, o administrador da Conta B pode delegar permissões para assumir a função para todos os

usuários na Conta B. Isso permite que os usuários na Conta B criem ou acessem recursos na ContaA. O principal na política de confiança também poderá ser um principal do serviço da AWS, se vocêquiser conceder permissões a um serviço da AWS para assumir a função.

Para obter mais informações sobre o uso do IAM para delegar permissões, consulte Gerenciamento deacesso no Guia do usuário do IAM.

Veja a seguir um exemplo de política que permite ao usuário com o ID 123456789012 criar instânciaspara a sua conta da AWS. A nova instância deve usar um grupo de opções e um parameter group quecomeça com default e deve usar o grupo de sub-redes default.

{ "Version": "2012-10-17", "Statement": [ { "Sid": "AllowCreateDBInstanceOnly", "Effect": "Allow", "Action": [ "rds:CreateDBInstance" ], "Resource": [ "arn:aws:rds:*:123456789012:db:test*",

132


https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_policies.html

https://docs.aws.amazon.com/IAM/latest/UserGuide/access.html

https://docs.aws.amazon.com/IAM/latest/UserGuide/access.html


"arn:aws:rds:*:123456789012:pg:cluster-pg:default*", "arn:aws:rds:*:123456789012:subgrp:default" ] } ]}

Para obter mais informações sobre como usar políticas baseadas em identidade com o AmazonDocumentDB, consulte Uso de políticas baseadas em identidade (IAM políticas) para o AmazonDocumentDB (p. 134). Para obter mais informações sobre usuários, grupos, funções e permissões,consulte Identidades (usuários, grupos e funções) no Guia do usuário do IAM.

Políticas com base em recursoOutros serviços, como o Amazon Simple Storage Service (Amazon S3), também são compatíveis compolíticas de permissões baseadas em recursos. Por exemplo, você pode anexar uma política a um bucketdo S3 para gerenciar permissões de acesso a esse bucket. O Amazon DocumentDB não é compatível compolíticas baseadas em recursos.

Especificação de elementos da política: ações, efeitos, recursose principaisPara cada recurso do Amazon DocumentDB, (consulte Recursos e operações do AmazonDocumentDB (p. 131)), o serviço define um conjunto de operações da API. Para obter mais informações,consulte Ações. Para conceder permissões a essas operações da API, o Amazon DocumentDB define umconjunto de ações que podem ser especificadas em uma política. A execução de uma operação de APIpode exigir permissões para mais de uma ação.

Estes são os elementos de política básicos:

• Recurso – em uma política, você usa um nome de recurso da Amazon (ARN) para identificar o recursoao qual a política se aplica.

• Ação – Use palavras-chave de ação para identificar operações de recursos que você deseja permitirou negar. Por exemplo, a permissão rds:DescribeDBInstances permite que o usuário execute aoperação DescribeDBInstances.

• Efeito – você especifica o efeito quando o usuário solicita a ação específica — que pode ser permitirou negar. Se você não conceder (permitir) explicitamente acesso a um recurso, o acesso estaráimplicitamente negado. Você também pode negar explicitamente o acesso a um recurso, o que podefazer para ter a certeza de que um usuário não consiga acessá-lo, mesmo que uma política diferenteconceda acesso.

• Principal – em políticas baseadas em identidade (políticas do IAM), o usuário ao qual a política estáanexada é implicitamente o principal. Para as políticas baseadas em recursos, você especifica quaisusuários, contas, serviços ou outras entidades deseja que recebam permissões (aplica-se somente apolíticas baseadas em recursos). O Amazon DocumentDB não oferece suporte para politicas baseadasem recurso.

Para saber mais sobre a sintaxe e as descrições de políticas do IAM, consulte Referência de política doIAM da AWS no Guia do usuário do IAM.

Para obter uma tabela que mostra todas as ações da API do Amazon DocumentDB e os recursos a queelas se aplicam, consulte Permissões da API do Amazon DocumentDB: referência de ações, recursos econdições (p. 137).

Especificação de condições em uma políticaAo conceder permissões, é possível usar a linguagem de política do IAM para especificar as condições dequando uma política deverá entrar em vigor. Por exemplo, convém que uma política só seja aplicada após

133

https://docs.aws.amazon.com/IAM/latest/UserGuide/id.html

https://docs.aws.amazon.com/redshift/latest/APIReference/API_Operations.html



Amazon DocumentDB Guia do desenvolvedorGerenciamento do acesso usando políticas

uma data específica. Para obter mais informações sobre como especificar condições em uma linguagemde política, consulte Condição no Guia do usuário do IAM.

Para expressar condições, você usa chaves de condição predefinidas. O Amazon DocumentDB nãotem chaves de contexto específicas do serviço que possam ser usadas em uma política do IAM. Paraobter uma lista das chaves de contexto de condição global que estão disponíveis para todos os serviços,consulte Chaves disponíveis para condições no Guia do usuário do IAM.

Gerenciamento do acesso usando políticasVocê pode ter credenciais válidas para autenticar suas solicitações, mas, se não tiver permissões, nãopoderá criar nem acessar os recursos do Amazon DocumentDB. Por exemplo, você deve ter permissõespara criar um cluster do Amazon DocumentDB, criar um snapshot de cluster, modificar parameter groupsde cluster e assim por diante.

As seções a seguir descrevem como gerenciar permissões para o Amazon DocumentDB. Recomendamosque você leia a visão geral primeiro.

• Visão geral do gerenciamento de permissões para seus recursos do Amazon DocumentDB (p. 130)• Uso de políticas baseadas em identidade (IAM políticas) para o Amazon DocumentDB (p. 134)

Uso de políticas baseadas em identidade (IAMpolíticas) para o Amazon DocumentDBEste tópico fornece exemplos de políticas baseadas em identidade em que um administrador de contapode anexar políticas de permissões a identidades do IAM (ou seja, usuários, grupos e funções).

Important

Para alguns recursos de gerenciamento, o Amazon DocumentDB usa a tecnologia operacionalque é compartilhada com o Amazon Relational Database Service (Amazon RDS). As chamadasdo console do Amazon DocumentDB, da AWS CLI e da API são registradas como chamadasfeitas para a API do Amazon RDS.Recomendamos primeiro analisar os tópicos introdutórios que explicam os conceitos básicos e asopções disponíveis para gerenciar o acesso aos recursos do Amazon DocumentDB. Para obtermais informações, consulte Visão geral do gerenciamento de permissões para seus recursos doAmazon DocumentDB (p. 130).

As seções neste tópico abrangem o seguinte:

• Permissões necessárias para usar o console do Amazon DocumentDB (p. 135)• Políticas (predefinidas) gerenciadas pela AWS para o Amazon DocumentDB (p. 135)• Exemplos de política gerenciada pelo cliente (p. 136)

A seguir há um exemplo de uma política do IAM.

{ "Version": "2012-10-17", "Statement": [ { "Sid": "AllowCreateDBInstanceOnly", "Effect": "Allow", "Action": [ "rds:CreateDBInstance" ],

134

https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_policies_elements.html#Condition

https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_policies_elements.html#AvailableKeys

Amazon DocumentDB Guia do desenvolvedorUso de políticas baseadas em identidade (políticas do IAM)

"Resource": [ "arn:aws:rds:*:123456789012:db:test*", "arn:aws:rds:*:123456789012:pg:cluster-pg:default*", "arn:aws:rds:*:123456789012:subgrp:default" ] } ]}

A política inclui uma única instrução que especifica as seguintes permissões para o usuário do IAM:

• A política permite que o usuário do IAM crie uma instância usando a ação CreateDBInstance (issotambém se aplica à operação create-db-instance da AWS CLI e ao Console de gerenciamento da AWS).

• O elemento Resource especifica que o usuário pode realizar ações em ou com recursos. Vocêespecifica recursos usando um nome de recurso da Amazon (ARN). O ARN inclui o nome do serviço aque o recurso pertence (rds), a região da AWS (* indica qualquer região neste exemplo), o número deconta do usuário (123456789012 é o ID do usuário neste exemplo) e o tipo de recurso.

O elemento Resource neste exemplo especifica as restrições da política a seguir em recursos para ousuário:• O identificador de instância para a nova instância deve começar com test (por exemplo,testCustomerData1, test-region2-data).

• O grupo de parâmetros de cluster para a nova instância deve começar com default.• O grupo de sub-redes para a nova instância deve ser o grupo de sub-redes default.

A política não especifica o elemento Principal porque, em uma política baseada em identidade, não seespecifica o principal que obtém as permissões. Quando você anexar uma política um usuário, o usuárioserá o principal implícito. Quando você anexa uma política de permissões a uma função do IAM, o principalidentificado na política de confiança da função obtém as permissões.

Para obter uma tabela mostrando todas as operações da API do Amazon DocumentDB e os recursosaos quais elas se aplicam, consulte Permissões da API do Amazon DocumentDB: referência de ações,recursos e condições (p. 137).

Permissões necessárias para usar o console do AmazonDocumentDBPara um usuário trabalhar com o console do Amazon DocumentDB, esse usuário deve ter um conjuntode permissões mínimo. Essas permissões possibilitam que o usuário descreva os recursos do AmazonDocumentDB para a conta da AWS e forneça outras informações relacionadas, inclusive informações desegurança e rede do Amazon EC2.

Se você criar uma política do IAM que seja mais restritiva que as permissões mínimas necessárias,o console não funcionará como pretendido para os usuários com essa política do IAM. Para garantirque esses usuários ainda consigam usar o console do Amazon DocumentDB, associe também apolítica gerenciada do AmazonDocDBConsoleFullAccess ao usuário, conforme descrito em Políticas(predefinidas) gerenciadas pela AWS para o Amazon DocumentDB (p. 135).

Não é necessário conceder permissões mínimas do console para os usuários que estão fazendo ligaçõessomente com a AWS CLI ou a API do Amazon DocumentDB.

Políticas (predefinidas) gerenciadas pela AWS para o AmazonDocumentDBA AWS aborda muitos casos de uso comuns fornecendo políticas autônomas do IAM que são criadas eadministradas pela AWS. As políticas gerenciadas concedem permissões necessárias para casos de uso

135

https://docs.aws.amazon.com/documentdb/latest/developerguide/API_CreateDBInstance.html

https://docs.aws.amazon.com/cli/latest/reference/rds/create-db-instance.html

Amazon DocumentDB Guia do desenvolvedorUso de políticas baseadas em identidade (políticas do IAM)

comuns, de maneira que você possa evitar a necessidade de investigar quais permissões são necessárias.Para obter mais informações, consulte Políticas gerenciadas pela AWS no Guia do usuário do IAM.

As seguintes políticas gerenciadas pela AWS, que você pode associar a usuários na conta, sãoespecíficas para o Amazon DocumentDB:

• AmazonDocDBReadOnlyAccess – concede acesso somente leitura a todos os recursos do AmazonDocumentDB para a conta da AWS raiz.

• AmazonDocDBFullAccess – concede acesso completo a todos os recursos do Amazon DocumentDBpara a conta da AWS raiz.

• AmazonDocDBConsoleFullAccess – concede pleno acesso para gerenciar os recursos do AmazonDocumentDB usando o Console de gerenciamento da AWS.

Você também pode criar políticas personalizadas do IAM que permitem que os usuários acessem osrecursos e as ações necessários da API do Amazon DocumentDB. Você pode anexar essas políticaspersonalizadas a usuários ou grupos do IAM que exijam essas permissões.

Exemplos de política gerenciada pelo clienteNesta seção, você encontrará exemplos de políticas de usuário que concedem permissões para diversasações do Amazon DocumentDB. Essas políticas funcionam quando você está usando ações da APIdo Amazon DocumentDB, SDKs da AWS ou a AWS CLI. Ao usar o console, você precisa concederpermissões adicionais específicas ao console, o que é debatido em Permissões necessárias para usar oconsole do Amazon DocumentDB (p. 135).

Para determinados recursos de gerenciamento, o Amazon DocumentDB usa a tecnologia operacional queé compartilhada com o Amazon Relational Database Service (Amazon RDS) e o Amazon Neptune.

Note

Todos os exemplos usam a região Leste dos EUA (Norte da Virgínia) (us-east-1) e contêm IDsde conta fictícios.

Exemplos• Exemplo 1: permitir que um usuário execute qualquer ação de descrição em qualquer recurso do

Amazon DocumentDB (p. 136)• Exemplo 2: impedir que um usuário exclua uma instância (p. 137)

Exemplo 1: permitir que um usuário execute qualquer ação de descrição emqualquer recurso do Amazon DocumentDB

A seguinte política de permissões concede permissões a um usuário para executar todas as ações quecomeçam com Describe. Essas ações mostram informações sobre um recurso do Amazon DocumentDB,como uma instância. O caractere curinga (*) no elemento Resource indica que as ações são permitidaspara todos os recursos do Amazon DocumentDB que pertencem à conta.

{ "Version":"2012-10-17", "Statement":[ { "Sid":"AllowRDSDescribe", "Effect":"Allow", "Action":"rds:Describe*", "Resource":"*" }

136

https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies_managed-vs-inline.html#aws-managed-policies

Amazon DocumentDB Guia do desenvolvedorReferência de permissões da API do Amazon DocumentDB

]}

Exemplo 2: impedir que um usuário exclua uma instância

A seguinte política de permissões concede permissões para impedir que um usuário exclua uma instânciaespecífica. Por exemplo, você pode querer negar a capacidade de excluir suas instâncias de produção aqualquer usuário que não seja um administrador.

{ "Version":"2012-10-17", "Statement":[ { "Sid":"DenyDelete1", "Effect":"Deny", "Action":"rds:DeleteDBInstance", "Resource":"arn:aws:rds:us-east-1:123456789012:db:my-db-instance" } ]}

Permissões da API do Amazon DocumentDB:referência de ações, recursos e condiçõesUse as seções a seguir como referência ao configurar Gerenciamento do acesso usandopolíticas (p. 134) e escrever políticas de permissões que você pode anexar a uma identidade do IAM(políticas com base em identidade).

O conteúdo a seguir lista cada operação da API do Amazon DocumentDB. Estão incluídas na lista asações correspondentes para as quais você pode conceder permissões para executar a ação, o recursoda AWS para o qual você pode conceder permissões e chaves de condição que você pode incluir paracontrole de acesso granular. Você especifica as ações no campo Action da política, o valor de recursono campo Resource da política e as condições no campo Condition da política. Para obter maisinformações sobre as condições, consulte Especificação de condições em uma política (p. 133).

Você pode usar as chaves de condição em toda a AWS nas suas políticas do Amazon DocumentDBpara expressar condições. Para obter uma lista completa das chaves de toda a AWS, consulte Chavesdisponíveis no Guia do usuário do IAM.

Você pode testar políticas do IAM com o simulador de políticas do IAM. Ele fornece automaticamenteuma lista de recursos e de parâmetros necessários para cada ação da AWS, inclusive ações do AmazonDocumentDB. O simulador de políticas do IAM determina as permissões que são necessárias para cadauma das ações especificadas por você. Para obter informações sobre o simulador de políticas do IAM,consulte Teste de políticas do IAM com o simulador de políticas do IAM no Guia do usuário do IAM.

Note

Para especificar uma ação, use o prefixo rds: seguido do nome da operação da API (porexemplo, rds:CreateDBInstance).

O conteúdo a seguir lista operações de API do Amazon RDS e as ações, os recursos e as chaves decondição relacionados.

Tópicos• Ações do Amazon DocumentDB que dão suporte a permissões no nível do recurso (p. 138)• Ações do Amazon DocumentDB que não dão suporte a permissões no nível do recurso (p. 141)

137



https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies_testing-policies.html


Ações do Amazon DocumentDB que dão suporte a permissõesno nível do recursoAs permissões em nível de recurso fornecem a capacidade de especificar em quais os recursos sobreos quais os usuários têm permissões para executar ações. O Amazon DocumentDB oferece suporteparcial para permissões em nível de recurso. Isso significa que, para determinadas ações do AmazonDocumentDB, você pode controlar quando os usuários têm permissão para usar essas ações, com baseem condições que precisam ser atendidas, ou os recursos específicos que os usuários têm permissãopara usar. Por exemplo, você pode conceder a usuários permissão para modificar somente instânciasespecíficas.

O conteúdo a seguir lista operações de API do Amazon DocumentDB e as ações, os recursos e as chavesde condição relacionados.

Para determinados recursos de gerenciamento, o Amazon DocumentDB usa tecnologia operacionalcompartilhada com o Amazon RDS.

Operações e açõesda API do AmazonDocumentDB

Recursos Chaves de condição

Instância

arn:aws:rds:region:account-id:db:db-instance-name

rds:db-tagAddTagsToResource

rds:AddTagsToResource

Grupo de sub-rede

arn:aws:rds:region:account-id:subgrp:subnet-group-name

rds:subgrp-tag

ApplyPendingMaintenanceAction

rds:ApplyPendingMaintenanceAction

Instância


rds:db-tag

CopyDBClusterSnapshot

rds:CopyDBClusterSnapshot

Snapshot de cluster

arn:aws:rds:region:account-id:cluster-snapshot:cluster-snapshot-name

rds:cluster-snapshot-tag

Cluster

arn:aws:rds:region:account-id:cluster:db-cluster-name

rds:cluster-tag

Grupo de parâmetros do cluster


rds:cluster-pg-tag

CreateDBCluster

rds:CreateDBCluster

Grupo de sub-rede


rds:subgrp-tag

CreateDBClusterParameterGroupGrupo de parâmetros do cluster rds:cluster-pg-tag

138

https://docs.aws.amazon.com/documentdb/latest/developerguide/API_AddTagsToResource.html

https://docs.aws.amazon.com/documentdb/latest/developerguide/API_ApplyPendingMaintenanceAction.html

https://docs.aws.amazon.com/documentdb/latest/developerguide/API_CopyDBClusterSnapshot.html

https://docs.aws.amazon.com/documentdb/latest/developerguide/API_CreateDBCluster.html

https://docs.aws.amazon.com/documentdb/latest/developerguide/API_CreateDBClusterParameterGroup.html




rds:CreateDBClusterParameterGrouparn:aws:rds:region:account-id:cluster-pg:cluster-parameter-group-name

Cluster


rds:cluster-tagCreateDBClusterSnapshot

rds:CreateDBClusterSnapshot

Snapshot de cluster



Instância


rds:DatabaseClass

rds:db-tag

CreateDBInstance

rds:CreateDBInstance

Cluster


rds:cluster-tag

CreateDBSubnetGroup

rds:CreateDBSubnetGroup

Grupo de sub-rede


rds:subgrp-tag

DeleteDBInstance

rds:DeleteDBInstance

Instância


rds:db-tag

DeleteDBSubnetGroup

rds:DeleteDBSubnetGroup

Grupo de sub-rede


rds:subgrp-tag

DescribeDBClusterParameterGroups

rds:DescribeDBClusterParameterGroups



rds:cluster-pg-tag

DescribeDBClusterParameters

rds:DescribeDBClusterParameters



rds:cluster-pg-tag

DescribeDBClusters

rds:DescribeDBClusters

Cluster

arn:aws:rds:region:account-id:cluster:db-cluster-instance-name

rds:cluster-tag

139

https://docs.aws.amazon.com/documentdb/latest/developerguide/API_CreateDBClusterSnapshot.html

https://docs.aws.amazon.com/documentdb/latest/developerguide/API_CreateDBInstance.html

https://docs.aws.amazon.com/documentdb/latest/developerguide/API_CreateDBSubnetGroup.html

https://docs.aws.amazon.com/documentdb/latest/developerguide/API_DeleteDBInstance.html

https://docs.aws.amazon.com/documentdb/latest/developerguide/API_DeleteDBSubnetGroup.html

https://docs.aws.amazon.com/documentdb/latest/developerguide/API_DescribeDBClusterParameterGroups.html

https://docs.aws.amazon.com/documentdb/latest/developerguide/API_DescribeDBClusterParameters.html

https://docs.aws.amazon.com/documentdb/latest/developerguide/API_DescribeDBClusters.html




DescribeDBClusterSnapshotAttributes

rds:DescribeDBClusterSnapshotAttributes

Snapshot de cluster



DescribeDBSubnetGroups

rds:DescribeDBSubnetGroups

Grupo de sub-rede


rds:subgrp-tag

DescribePendingMaintenanceActions

rds:DescribePendingMaintenanceActions

Instância


rds:DatabaseClass

rds:db-tag

FailoverDBCluster

rds:FailoverDBCluster

Cluster


rds:cluster-tag

Instância


rds:db-tagListTagsForResource

rds:ListTagsForResource

Grupo de sub-rede


rds:subgrp-tag

Cluster


rds:cluster-tagModifyDBCluster

rds:ModifyDBCluster



rds:cluster-pg-tag

ModifyDBClusterParameterGroup

rds:ModifyDBClusterParameterGroup



rds:cluster-pg-tag

ModifyDBClusterSnapshotAttribute

rds:ModifyDBClusterSnapshotAttribute

Snapshot de cluster



140

https://docs.aws.amazon.com/documentdb/latest/developerguide/API_DescribeDBClusterSnapshotAttributes.html

https://docs.aws.amazon.com/documentdb/latest/developerguide/API_DescribeDBSubnetGroups.html

https://docs.aws.amazon.com/documentdb/latest/developerguide/API_DescribePendingMaintenanceActions.html

https://docs.aws.amazon.com/documentdb/latest/developerguide/API_FailoverDBCluster.html

https://docs.aws.amazon.com/documentdb/latest/developerguide/API_ListTagsForResource.html

https://docs.aws.amazon.com/documentdb/latest/developerguide/API_ModifyDBCluster.html

https://docs.aws.amazon.com/documentdb/latest/developerguide/API_ModifyDBClusterParameterGroup.html

https://docs.aws.amazon.com/documentdb/latest/developerguide/API_ModifyDBClusterSnapshotAttribute.html




ModifyDBInstance

rds:ModifyDBInstance

Instância


rds:DatabaseClass

rds:db-tag

RebootDBInstance

rds:RebootDBInstance

Instância


rds:db-tag

Instância


rds:db-tagRemoveTagsFromResource

rds:RemoveTagsFromResource

Grupo de sub-rede


rds:subgrp-tag

ResetDBClusterParameterGroup

rds:ResetDBClusterParameterGroup



rds:cluster-pg-tag

Cluster


rds:cluster-tagRestoreDBClusterFromSnapshot

rds:RestoreDBClusterFromSnapshot

Snapshot de cluster



Cluster


rds:cluster-tagRestoreDBClusterToPointInTime

rds:RestoreDBClusterToPointInTime

Grupo de sub-rede


rds:subgrp-tag

Ações do Amazon DocumentDB que não dão suporte apermissões no nível do recursoVocê pode usar todas as ações do Amazon DocumentDB em uma política do IAM para conceder ou negara usuários permissão para usar essa ação. Contudo, nem todas as ações do Amazon DocumentDB dão

141

https://docs.aws.amazon.com/documentdb/latest/developerguide/API_ModifyDBInstance.html

https://docs.aws.amazon.com/documentdb/latest/developerguide/API_RebootDBInstance.html

https://docs.aws.amazon.com/documentdb/latest/developerguide/API_RemoveTagsFromResource.html

https://docs.aws.amazon.com/documentdb/latest/developerguide/API_ResetDBClusterParameterGroup.html

https://docs.aws.amazon.com/documentdb/latest/developerguide/API_RestoreDBClusterFromSnapshot.html

https://docs.aws.amazon.com/documentdb/latest/developerguide/API_RestoreDBClusterToPointInTime.html

Amazon DocumentDB Guia do desenvolvedorGerenciamento de usuários do Amazon DocumentDB

suporte a permissões no nível do recurso, que permitem especificar os recursos nos quais uma ação podeser realizada. As ações de API do Amazon DocumentDB a seguir não oferecem suporte a permissõesem nível de recurso no momento. Por isso, para usar essas ações em uma política do IAM, você deveconceder a usuários permissão para usar todos os recursos para a ação usando um caractere curinga *para o elemento Resource na instrução.

• rds:DescribeDBClusterSnapshots

• rds:DescribeDBInstances

Gerenciamento de usuários do AmazonDocumentDB

No Amazon DocumentDB, os usuários se autenticam em um cluster em conjunto com uma senha. Cadacluster tem um usuário mestre e uma senha que são estabelecidos durante a criação do cluster.

Note

Todos os usuários criados antes de 26 de março de 2020 receberam as funçõesdbAdminAnyDatabase, readWriteAnyDatabase e clusterAdmin. Recomenda-se que vocêreavalie todos os usuários e modifique as funções conforme necessário para impor o privilégiomínimo para todos os usuários em seus clusters.Para obter mais informações, consulte Restringir o acesso ao banco de dados usando o controlede acesso baseado em função (funções internas) (p. 144).

Usuário mestre e serviceadminUm cluster do Amazon DocumentDB recém-criado tem dois usuários: o usuário mestre e o usuárioserviceadmin.

O usuário mestre é um usuário único e privilegiado que pode executar tarefas administrativas e criarusuários adicionais com funções. Ao conectar-se ao cluster do Amazon DocumentDB pela primeira vez,é necessário autenticar-se usando o nome do usuário mestre e a senha. O usuário mestre recebe essaspermissões administrativas para um cluster do Amazon DocumentDB quando esse cluster é criado erecebe a função de root.

O usuário serviceadmin é criado implicitamente quando o cluster é criado. Cada cluster do AmazonDocumentDB tem um usuário serviceadmin que fornece à AWS a capacidade de gerenciar seucluster. Não é possível fazer login, descartar, renomear, alterar a senha nem alterar permissões doserviceadmin. Qualquer tentativa de fazer isso resulta em um erro.

Note

Os usuários mestre e serviceadmin de um cluster do Amazon DocumentDB não podem serexcluídos, e a função root do usuário mestre não pode ser revogada.Se você esquecer sua senha de usuário mestre, poderá redefini-la usando o Console degerenciamento da AWS ou a AWS CLI.

Criação de usuários adicionaisDepois de conectar-se como usuário mestre (ou qualquer usuário que tenha a função createUser), vocêpode criar um usuário, como mostrado abaixo.

db.createUser( { user: "sample-user-1", pwd: "password123", roles:

142

Amazon DocumentDB Guia do desenvolvedorCriação de usuários adicionais

[{"db":"admin", "role":"dbAdminAnyDatabase" }] })

Para visualizar detalhes do usuário, você pode usar o comando show users da seguinte maneira. Vocêtambém pode remover usuários com o comando dropUser. Para obter mais informações, consulteComandos comuns (p. 150).

show users{ "_id" : "serviceadmin", "user" : "serviceadmin", "db" : "admin", "roles" : [ { "role" : "root", "db" : "admin" } ]},

{ "_id" : "myMasterUser", "user" : "myMasterUser", "db" : "admin", "roles" : [ { "role" : "root", "db" : "admin" } ]},

{ "_id" : "sample-user-1", "user" : "sample-user-1", "db" : "admin", "roles" : [ { "role" : "dbAdminAnyDatabase", "db" : "admin" } ]}

Neste exemplo, o novo usuário sample-user-1 é atribuído ao banco de dados admin. Esseé sempre o caso para um novo usuário. O Amazon DocumentDB não tem o conceito de umauthenticationDatabase e, portanto, toda a autenticação é executada no contexto do banco de dadosadmin.

Ao criar usuários, se você omitir o campo db ao especificar a função, o Amazon DocumentDB atribuiráimplicitamente a função ao banco de dados no qual a conexão está sendo emitida. Por exemplo, se suaconexão for emitida no banco de dados sample-database e você executar o comando a seguir, ousuário sample-user-2 será criado no banco de dados admin e terá permissões readWrite no bancode dados sample-database.

db.createUser( { user: "sample-user-2", pwd: "password123",

143

Amazon DocumentDB Guia do desenvolvedorAlteração automática de senhas

roles: [{role: "readWrite"}] })

A criação de usuários com funções com escopo em todos os bancos de dados (por exemplo,readInAnyDatabase) exige que você esteja no contexto do banco de dados admin ao criar o usuário ouindicar o banco de dados explicitamente para a função ao criar o usuário.

Para alternar o contexto do banco de dados, você pode usar o seguinte comando.

use admin

Para saber mais sobre o Controle de acesso baseado em função e impor o mínimo privilégio entre osusuários em seu cluster, consulte Restringir o acesso ao banco de dados usando o controle de acessobaseado em função (funções internas) (p. 144).

Alteração automática de senhas para o AmazonDocumentDBCom o AWS Secrets Manager, você pode substituir credenciais codificadas, incluindo senhas, por umachamada da API ao Secrets Manager para recuperar o segredo por programação. Isso ajuda a garantirque o segredo não será comprometido por alguém que esteja examinando seu código, pois o segredosimplesmente não está ali. Além disso, configure o Secrets Manager para rotacionar automaticamenteo segredo para você de acordo com a programação que você especificar. Isso permite substituirsegredos de longo prazo por outros de curto prazo, ajudando a reduzir de maneira significativa o risco decomprometimento.

Usando o Secrets Manager, você pode mudar automaticamente as senhas do Amazon DocumentDB (ouseja, os segredos) usando uma função do AWS Lambda fornecida pelo Secrets Manager.

Para obter mais informações sobre o AWS Secrets Manager e a integração nativa com o AmazonDocumentDB, consulte:

• Blog: How to rotate Amazon DocumentDB and Amazon Redshift credentials in AWS Secrets Manager• O que é o AWS Secrets Manager?• Mudança de segredos do Amazon DocumentDB

Restringir o acesso ao banco de dados usando ocontrole de acesso baseado em função (funçõesinternas)

É possível restringir o acesso às ações que os usuários podem executar em bancos de dados usando ocontrole de acesso baseado em função (RBAC) no Amazon DocumentDB (compatível com MongoDB). ORBAC funciona concedendo uma ou mais funções a um usuário. Essas funções determinam as operaçõesque um usuário pode executar em bancos de dados especificados. Atualmente, o Amazon DocumentDBoferece suporte a funções internas que têm escopo no nível do banco de dados, como read, readWrite,readAnyDatabase e clusterAdmin.

Casos de uso comuns para RBAC incluem a imposição de privilégios mínimos criando usuários comacesso somente leitura aos bancos de dados em um cluster e designs de aplicativos de vários locatáriosque permitem que um único usuário acesse um determinado banco de dados em um cluster.

144

https://aws.amazon.com/blogs/security/how-to-rotate-amazon-documentdb-and-amazon-redshift-credentials-in-aws-secrets-manager/

https://docs.aws.amazon.com/secretsmanager/latest/userguide/intro.html


Amazon DocumentDB Guia do desenvolvedorConceitos do RBAC

Note

Todos os usuários criados antes de 26 de março de 2020 receberam as funçõesdbAdminAnyDatabase, readWriteAnyDatabase e clusterAdmin. Recomenda-se que vocêreavalie todos os usuários existentes e modifique as funções conforme necessário para imporprivilégios mínimos para seus clusters.

Tópicos• Conceitos do RBAC (p. 145)• Conceitos básicos do RBAC (p. 146)• Conectar-se ao Amazon DocumentDB como um usuário (p. 149)• Comandos comuns (p. 150)• Diferenças funcionais (p. 152)• Limites (p. 152)• Funções integradas (p. 152)

Conceitos do RBACVeja a seguir os termos e conceitos importantes relacionados ao controle de acesso baseado em função.Para obter mais informações sobre os usuários do Amazon DocumentDB, consulte Gerenciamento deusuários do Amazon DocumentDB (p. 142).

• Usuário – uma entidade individual que pode autenticar-se no banco de dados e executar operações.• Senha – um segredo usado para autenticar o usuário.• Função – autoriza um usuário a executar ações em um ou mais bancos de dados.• Banco de dados de administrador – o banco de dados no qual os usuários são armazenados e

autorizados.• Banco de dados (db) – o namespace dentro dos clusters que contém coleções para armazenar

documentos.

O comando a seguir cria um cofre chamado sample-user.

db.createUser({user: "sample-user", pwd: "abc123", roles: [{role: "read", db: "sample-database"}]})

Neste exemplo.

• user: "sample-user" – indica o nome do usuário.• pwd: "abc123" – indica a senha do usuário.• role: "read", "db: "sample-database" – indica que o usuário sample-user terá permissões

de leitura no sample-database.

O exemplo a seguir mostra a saída depois que você obtiver o usuário sample-user comdb.getUser(sample-user). Neste exemplo, o usuário sample-user reside no banco de dadosadmin, mas tem a função de leitura no banco de dados sample-database.

145

Amazon DocumentDB Guia do desenvolvedorConceitos básicos do RBAC

Ao criar usuários, se você omitir o campo db ao especificar a função, o Amazon DocumentDB atribuiráimplicitamente a função ao banco de dados no qual a conexão está sendo emitida. Por exemplo, se suaconexão for emitida no banco de dados sample-database e você executar o comando a seguir, ousuário sample-user será criado no banco de dados admin e terá permissões readWrite no banco dedados sample-database.

db.createUser({user: "sample-user", pwd: "abc123", roles: ["readWrite"]})


{ "user" : "sample-user", "roles" : [ { "db" : "sample-database", "role" : "readWrite" } ]}

A criação de usuários com funções com escopo em todos os bancos de dados (por exemplo,readAnyDatabase) exige que você esteja no contexto do banco de dados admin ao criar o usuário ouque indique explicitamente o banco de dados para a função ao criar o usuário. Para emitir comandos nobanco de dados admin, use o comando use admin. Para obter mais informações, consulte Comandoscomuns (p. 150).

Conceitos básicos do RBACPara ajudar você a começar a usar o controle de acesso baseado em função, esta seção demonstra umcenário de exemplo de aplicação de privilégios mínimos criando funções para três usuários com funçõesde trabalho diferentes.

• O user1 é um novo gerente que precisa poder visualizar e acessar todos os bancos de dados em umcluster.

• O user2 é um novo funcionário que precisa acessar apenas um banco de dados, sample-database-1, nesse mesmo cluster.

• O user3 é um funcionário existente que precisa visualizar e acessar um banco de dados diferente,sample-database-2, ao qual ele não tinha acesso anteriormente, no mesmo cluster.

Em um ponto mais tarde, tanto o user1 como o user2 saem da empresa e, portanto, seu acesso deveser revogado.

146


Para criar usuários e conceder funções, o usuário com o qual você se autentica no cluster deve ter umafunção associada que possa executar ações para createUser e grantRole. Por exemplo, as funçõesadmin e userAdminAnyDatabase podem conceder essas capacidades, por exemplo. Para obter açõespor função, consulte Funções integradas (p. 152).

Note

No Amazon DocumentDB, todas as operações de usuário e função (por exemplo create,get, drop, grant, revoke etc.) são implicitamente executadas no banco de dados adminindependentemente de você estar emitindo comandos no banco de dados admin.

Primeiro, para entender quais são os usuários e funções atuais no cluster, você pode executar o comandoshow users, como no exemplo a seguir. Você verá dois usuários, o serviceadmin e o usuário mestredo cluster. Esses dois usuários sempre existem e não podem ser excluídos. Para obter mais informações,consulte Gerenciamento de usuários do Amazon DocumentDB (p. 142).

show users

Para o user1, crie uma função com acesso de leitura e gravação a todos os bancos de dados em todo ocluster com o seguinte comando.

db.createUser({user: "user1", pwd: "abc123", roles: [{role: "readWriteAnyDatabase", db: "admin"}]})


{ "user" : "user1", "roles" : [ { "role" : "readWriteAnyDatabase", "db" : "admin" } ]}

Para o user2, crie uma função com acesso somente leitura ao banco de dados sample-database-1com o seguinte comando.

db.createUser({user: "user2", pwd: "abc123", roles: [{role: "read", db: "sample-database-1"}]})


{ "user" : "user2", "roles" : [ { "role" : "read", "db" : "sample-database-1" } ]}

Para simular o cenário em que o user3 é um usuário existente, primeiro crie o usuário user3 e atribuauma nova função ao user3.

147


db.createUser({user: "user3", pwd: "abc123", roles: [{role: "readWrite", db: "sample-database-1"}]})


{ "user" : "user3", "roles" : [ { "role" : "readWrite", "db" : "sample-database-1" } ]}

Agora que o usuário user3 foi criado, atribua ao user3 a função read no sample-database-2.

db.grantRolesToUser("user3", [{role: "read", db: "sample-database-2"}])

Por fim, ambos user1 e user2 saem da empresa e precisam que seu acesso ao cluster seja revogado.Você pode fazer isso descartando os usuários, da seguinte forma.

db.dropUser("user1")db.dropUser("user2")

Para garantir que todos os usuários tenham as funções apropriadas, você pode listar todos os usuárioscom o comando a seguir.

show users


{ "_id" : "serviceadmin", "user" : "serviceadmin", "db" : "admin", "roles" : [ { "db" : "admin", "role" : "root" } ]}{ "_id" : "master-user", "user" : "master-user", "db" : "admin", "roles" : [ { "db" : "admin", "role" : "root" } ]}{ "_id" : "user3", "user" : "user3", "db" : "admin", "roles" : [

148

Amazon DocumentDB Guia do desenvolvedorConectar-se ao Amazon DocumentDB como um usuário

{ "db" : "sample-database-2", "role" : "read" }, { "db" : "sample-database-1", "role" : "readWrite" } ]}

Conectar-se ao Amazon DocumentDB como umusuárioAo conectar-se a um cluster do Amazon DocumentDB, você se conecta no contexto de um banco dedados específico. Por padrão, se não especificar um banco de dados em sua string de conexão, você seráautomaticamente conectado ao cluster no contexto do banco de dados test. Todos os comandos de nívelde coleção, como insert e find, são emitidos em coleções no banco de dados test.

Para ver o banco de dados em cujo contexto você está ou — em outras palavras — para o qual você estáemitindo comandos, use o comando db no shell do mongo, da seguinte forma.

Consulta:

db

Resultado:

test

Embora a conexão padrão possa estar no contexto do banco de dados test, isso não significanecessariamente que o usuário associado à conexão está autorizado a executar ações no banco de dadostest. No cenário de exemplo anterior, se você se autenticar como o usuário user3, que tem a funçãoreadWrite no banco de dados sample-database-1, o contexto padrão da conexão será o bancode dados test. No entanto, se você tentar inserir um documento em uma coleção no banco de dadostest, receberá uma mensagem de erro de falha de autorização. Isso ocorre porque esse usuário não estáautorizado a executar esse comando nesse banco de dados, como mostrado abaixo.

Consulta:

db

Resultado:

test

Consulta:

db.col.insert({x:1})

Resultado:

WriteCommandError({ "ok" : 0, "code" : 13, "errmsg" : "Authorization failure" })

Se você alterar o contexto da sua conexão com o banco de dados sample-database-1, poderá gravarna coleção na qual o usuário tem autorização para fazê-lo.

149

Amazon DocumentDB Guia do desenvolvedorComandos comuns

Consulta:

use sample-database-1

Resultado:

switched to db sample-database-1

Consulta:

db.col.insert({x:1})

Resultado:

WriteResult({ "nInserted" : 1})

Ao autenticar-se em um cluster com um usuário específico, você também pode especificar o banco dedados na string de conexão. Isso remove a necessidade de executar o comando use depois que o usuáriofoi autenticado no banco de dados admin.

A seguinte string de conexão autentica o usuário no banco de dados admin, mas o contexto da conexãoserá com o banco de dados sample-database-1.

mongo "mongodb://user3:[email protected]:27017/sample-database-2"

Comandos comunsEsta seção fornece exemplos de comandos comuns usando o controle de acesso baseado em funçãono Amazon DocumentDB. Você deve estar no contexto do banco de dados admin para criar e modificarusuários e funções. Você pode usar o comando use admin para alternar para o banco de dados admin.

Note

As modificações em usuários e funções ocorrerão implicitamente no banco de dados admin. Acriação de usuários com funções que têm escopo em todos os bancos de dados (por exemplo,readAnyDatabase) requer que você esteja no contexto do banco de dados admin (ou seja, useadmin) ao criar o usuário, ou que indique explicitamente o banco de dados para a função ao criaro usuário (como mostrado no Exemplo 2 nesta seção).

Exemplo 1: Criar um usuário com a função read para o banco de dados foo.

db.createUser({user: "readInFooBar", pwd: "abc123", roles: [{role: "read", db: "foo"}]})


{ "user" : "readInFooBar", "roles" : [ { "role" : "read", "db" : "foo" } ]}

150

Amazon DocumentDB Guia do desenvolvedorComandos comuns

Exemplo 2: Criar um usuário com acesso de leitura em todos os bancos de dados.

db.createUser({user: "readAllDBs", pwd: "abc123", roles: [{role: "readAnyDatabase", db: "admin"}]})


{ "user" : "readAllDBs", "roles" : [ { "role" : "readAnyDatabase", "db" : "admin" } ]}

Exemplo 3: Conceder a função read a um usuário existente em um novo banco de dados.

db.grantRolesToUser("readInFooBar", [{role: "read", db: "bar"}])

Exemplo 4: Atualizar a função de um usuário.

db.updateUser("readInFooBar", {roles: [{role: "read", db: "foo"}, {role: "read", db: "baz"}]})

Exemplo 5: Revogar o acesso a um banco de dados de um usuário.

db.revokeRolesFromUser("readInFooBar", [{role: "read", db: "baz"}])

Exemplo 6: Descrever uma função interna.

db.getRole("read", {showPrivileges:true})


{ "role" : "read", "db" : "sample-database-1", "isBuiltin" : true, "roles" : [ ], "inheritedRoles" : [ ], "privileges" : [ { "resource" : { "db" : "sample-database-1", "collection" : "" }, "actions" : [ "changeStream", "collStats", "dbStats", "find", "killCursors", "listCollections", "listIndexes" ]

151

Amazon DocumentDB Guia do desenvolvedorDiferenças funcionais

} ], "inheritedPrivileges" : [ { "resource" : { "db" : "sample-database-1", "collection" : "" }, "actions" : [ "changeStream", "collStats", "dbStats", "find", "killCursors", "listCollections", "listIndexes" ] } ]}

Exemplo 7: Descartar um usuário do cluster.

db.dropUser("readInFooBar")


true

Diferenças funcionaisNo Amazon DocumentDB, as definições de usuário e função são armazenadas no banco de dados admin,e os usuários são autenticados no banco de dados admin. Essa funcionalidade difere do MongoDBCommunity Edition, mas é consistente com o MongoDB Atlas.

O Amazon DocumentDB também oferece suporte a fluxos de alterações, que fornecem uma sequênciaordenada de eventos que ocorrem nas coleções do cluster. A ação listChangeStreams é aplicada nonível do cluster (ou seja, em todos os bancos de dados) e a ação modifyChangeStreams é aplicada nonível do banco de dados.

LimitesA tabela a seguir contém os limites de funções internas no Amazon DocumentDB. Observe que atualmenteo Amazon DocumentDB não oferece suporte a funções personalizadas do RBAC.

Descrição Limite

Número de usuários por cluster 1000

Número de funções associadas a um usuário 1000

Funções integradasCom o controle de acesso baseado em função, você pode criar um usuário e conceder a ele uma ou maisfunções para determinar quais operações esse usuário pode executar em um banco de dados ou cluster.

152

Amazon DocumentDB Guia do desenvolvedorFunções integradas

Veja a seguir uma lista de funções incorporadas que são compatíveis atualmente com o AmazonDocumentDB.

Tipo de função Função Descrição Ações

read Concede acessode leitura aum usuário aobanco de dadosespecificado.

changeStreams

collStats

dbStats

find

killCursors

listIndexes

listCollections

Usuário do bancode dados

readWrite Concede aousuário acesso deleitura e gravaçãoao banco de dadosespecificado.

Todas as ações depermissões read.

createCollection

dropCollection

createIndex

dropIndex

insert

killCursors

listIndexes

listCollections

remove

update

readAnyDatabase Concede acessode leitura a todosos bancos dedados do cluster aum usuário.

Todas as ações depermissões read.

listChangeStreams

listDatabases

readWriteAnyDatabase Concede a umusuário acesso deleitura e gravaçãoa todos os bancosde dados nocluster.

Todas as açõesde permissõesreadWrite.

listChangeStreams

listDatabases

Usuário do cluster

userAdminAnyDatabase Concede aum usuário acapacidade deatribuir e modificar

changeCustomData

changePassword

153

https://docs.aws.amazon.com//documentdb/latest/developerguide/change_streams.html


Tipo de função Função Descrição Açõesas funçõesou privilégiosque qualquerusuário tem aobanco de dadosespecificado.

createUser

dropRole

dropUser

grantRole

listDatabases

revokeRole

viewRole

viewUser

dbAdminAnyDatabase Concede aum usuário acapacidade deexecutar funçõesde administraçãode banco de dadosem qualquerbanco de dadosespecificado.

Todas as açõesde permissõesdbAdmin.

dropCollection

listDatabases

listChangeStreams

modifyChangeStreams

Superusuário root Concede a umusuário acessoaos recursose operaçõesde todas asseguintes funçõescombinadas:readWriteAnyDatabase,dbAdminAnyDatabase,userAdminAnyDatabase,clusterAdmin,restore ebackup.

Todas as ações dereadWriteAnyDatabase,dbAdminAnyDatabase,userAdminAnyDatabase,clusterAdmin,restore ebackup.

154



dbAdmin Concede aum usuário acapacidade deexecutar tarefasadministrativas nobanco de dadosespecificado.

collMod

collStats

createCollection

createIndex

dropCollection

dropDatabase

dropIndex

dbStats

find

killCursors

listIndexes

listCollections

modifyChangeStreams

Administração debanco de dados

dbOwner Concede aum usuário acapacidadede executarquaisquer tarefasadministrativas nobanco de dadosespecificadocombinando asfunções dbAdmine readWrite.

Todas as açõesde dbAdmin ereadWrite.

clusterAdmin Concede aum usuário omaior acesso degerenciamentode clustercombinandoas funçõesclusterManager,clusterMonitore hostManager.

Todas as ações declusterManager,clusterMonitore hostManager.

listChangeStreams

dropDatabase

modifyChangeStreams

Administração decluster

clusterManager Concede aum usuário acapacidade deexecutar açõesde gerenciamentoe monitoramentono clusterespecificado.

listChangeStreams

listSessions

modifyChangeStreams

replSetGetConfig

155



clusterMonitor Concede aum usuário acapacidadede ter acessosomente leituraa ferramentas demonitoramento.

collStats

dbStats

find

getParameter

hostInfo

indexStats

killCursors

listChangeStreams

listCollections

listDatabases

listIndexes

listSessions

replSetGetConfig

serverStatus

top

hostManager Concede aum usuário acapacidadede monitorare gerenciarservidores.

killCursors

killAnyCursor

killAnySession

killop

Administração debackup

backup Concede a umusuário o acessonecessário parafazer backup dedados.

getParameter

insert

find

listChangeStreams

listCollections

listDatabases

listIndexes

update

156

Amazon DocumentDB Guia do desenvolvedorRegistro e monitoramento


restore Concede a umusuário o acessonecessário pararestaurar dados.

changeCustomData

changePassword

collMod

createCollection

createIndex

createUser

dropCollection

dropRole

dropUser

getParameter

grantRole

find

insert

listCollections

modifyChangeStreams

revokeRole

remove

viewRole

viewUser

update

Registro em log e monitoramento no AmazonDocumentDB

O Amazon DocumentDB (compatível com MongoDB) fornece uma variedade de métricas do AmazonCloudWatch que você pode monitorar para determinar a integridade e o desempenho dos clusters einstâncias do Amazon DocumentDB. Você pode visualizar as métricas do Amazon DocumentDB usandovárias ferramentas, incluindo o console do Amazon DocumentDB, a AWS CLI, o console do AmazonCloudWatch e a API do CloudWatch. Para obter mais informações sobre monitoramento, consulteMonitoramento do Amazon DocumentDB (p. 335).

Além das métricas do Amazon CloudWatch, você pode usar o profiler para registrar o tempo de execuçãoe os detalhes das operações que foram executadas no cluster. O profiler é útil para o monitoramentodas operações mais lentas em seu cluster, aprimorando o desempenho individual de consultas e odesempenho geral do cluster. Quando habilitado, as operações são registradas no Amazon CloudWatchLogs e você pode usar o CloudWatch Insight para analisar, monitorar e arquivar os dados de criação de

157

Amazon DocumentDB Guia do desenvolvedorUpdating Certificates

perfil do Amazon DocumentDB. Para obter mais informações, consulte Profiling Amazon DocumentDBOperations (p. 352).

O Amazon DocumentDB também é integrado ao AWS CloudTrail, um serviço que fornece um registrode ações realizadas pelos usuários do IAM, funções do IAM ou um serviço da AWS no AmazonDocumentDB (compatível com MongoDB). O CloudTrail captura todas as chamadas da API da AWS CLIdo Amazon DocumentDB como eventos, incluindo as chamadas do Console de gerenciamento da AWSdo Amazon DocumentDB e as chamadas de código para o SDK do Amazon DocumentDB. Para obtermais informações, consulte Registro em log de chamadas da API do Amazon DocumentDB com o AWSCloudTrail (p. 351).

Com o Amazon DocumentDB, você pode auditar eventos que foram executados em seu cluster. Exemplosde eventos registrados incluem tentativas de autenticação bem-sucedidas e com falha, eliminação deuma coleção em um banco de dados ou a criação de um índice. Por padrão, a auditoria fica desativadano Amazon DocumentDB e requer que você opte por esse recurso. Para obter mais informações, consulteAuditoria de eventos do Amazon DocumentDB (p. 168).

Updating Your Amazon DocumentDB TLSCertificates

O certificado da autoridade do certificado (CA) para Amazon DocumentDB (compatível com MongoDB)clusters foram atualizados em March 5, 2020. Se estiver a utilizar Amazon DocumentDB com a opção deSegurança da Camada de Transporte (TLS) ativada (a predefinição) e não rodou os certificados do seucliente e servidor, são necessários os seguintes passos para mitigar problemas de conectividade entre asua candidatura e o seu Amazon DocumentDB grupos.

• Step 1: Download the New CA Certificate and Update Your Application (p. 158)• Step 2: Update the Server Certificate (p. 159)

Os certificados CA e de servidor foram atualizados como parte das melhores práticas de manutenção esegurança padrão do Amazon DocumentDB. O certificado CA anterior expirou em 5 de março de 2020.Os aplicativos cliente precisam adicionar os novos certificados de CA aos respectivos armazenamentosde confiança, e as instâncias do Amazon DocumentDB existentes precisam ser atualizadas para usar osnovos certificados de CA antes dessa data de expiração.

Updating Your Application and Amazon DocumentDBClusterSiga as etapas nesta seção para atualizar o pacote de certificados CA do aplicativo (Etapa 1) e oscertificados de servidor do cluster (Etapa 2). Antes de aplicar as alterações nos seus ambientes deprodução, recomendamos testar estas etapas em um ambiente de desenvolvimento ou teste.

Note

Você deverá concluir as etapas 1 e 2 em cada região da AWS na qual tiver clusters do AmazonDocumentDB.

Step 1: Download the New CA Certificate and Update YourApplicationFaça download do novo certificado da CA e atualize o aplicativo para usá-lo na criação de conexõesTLS com o Amazon DocumentDB. Faça download do novo pacote de certificados CA em https://

158

https://docs.aws.amazon.com/documentdb/latest/developerguide/ca_cert_rotation.html#ca_cert_rotation-updating_application_step1



Amazon DocumentDB Guia do desenvolvedorUpdating Your Application andAmazon DocumentDB Cluster

s3.amazonaws.com/rds-downloads/rds-combined-ca-bundle.pem. Essa operação faz download de umarquivo chamado rds-combined-ca-bundle.pem.

Note

Se você estiver acessando o armazenamento de chaves que contém o certificado CA antigo(rds-ca-2015-root.pem) e o novo certificado CA (rds-ca-2019-root.pem), verifique se oarmazenamento de chaves seleciona CA-2019.


Depois, atualize seus aplicativos para usar o novo pacote de certificados. O novo pacote da CA contém ocertificado antigo (rds-ca-2015-root.pem) e o novo (rds-ca-2019-root.pem) da CA. Com os doiscertificados da autoridade de certificação (CA) no novo pacote, é possível atualizar seu aplicativo e clusterem duas etapas.

Quaisquer downloads do pacote de certificados da autoridade de certificação após 1º de setembro de 2019deverão usar o novo pacote da CA. Para verificar se o aplicativo está usando o pacote de certificadosCA mais recente, consulte How can I be sure that I'm using the newest CA bundle? (p. 163). Se você jáestiver usando o pacote de certificados CA mais recente em seu aplicativo, poderá avançar para a Etapa 2.

Para obter exemplos de como usar um pacote CA com o seu aplicativo, consulte Criptografia de dados emtrânsito (p. 122) e Conectar-se com o TLS habilitado (p. 362).

Note

Atualmente, o mongodb Go Driver 1.2.1 aceita apenas um certificado de servidor CA emsslcertificateauthorityfile. Consulte Conectar-se com o TLS habilitado (p. 362) paraligar a documentos Amazon utilizando Go quando o TLS estiver ativado.

Step 2: Update the Server CertificateDepois que o aplicativo foi atualizado para usar o novo pacote de CA, o próximo passo é atualizar ocertificado de servidor modificando cada instância em um cluster do Amazon DocumentDB. Para modificaras instâncias para usarem o novo certificado de servidor, consulte as instruções a seguir.

Note

A atualização de suas instâncias requer uma reinicialização, o que pode causar interrupção noserviço. Antes de atualizar o certificado de servidor, verifique se você concluiu a Etapa 1.

Using the Console de gerenciamento da AWS

Conclua as etapas a seguir para identificar e alternar o certificado de servidor antigo para suas instânciasexistentes do Amazon DocumentDB usando a Console de gerenciamento da AWS.


2. Na lista de regiões no canto superior direito da tela, escolha a região da AWS em que os clustersresidem.

3. No painel de navegação, no lado esquerdo do console, escolha Instances (Instâncias).4. A coluna Certificate authority (Autoridade de certificação) (oculta por padrão) mostra quais instâncias

ainda estão no certificado antigo do servidor (rds-ca-2015). Para exibir a coluna Certificate authority(Autoridade de certificação), siga estas etapas:

a. Escolha o ícone Settings (Configurações).b. Na lista de colunas visíveis, selecione a coluna Certificate authority (Autoridade de certificação).c. Depois, escolha Confirm (Confirmar) para salvar as alterações.

159




Amazon DocumentDB Guia do desenvolvedorTroubleshooting

5. Selecione uma instância para modificá-la.6. Escolha Actions (Ações) e, em seguida, Modify (Modificar).7. Em Certificate authority (Autoridade de certificação), selecione o novo certificado do servidor (rds-

ca-2019) para essa instância.8. Você verá um resumo das alterações na próxima página. Há um alerta adicional para lembrar você de

garantir que o aplicativo esteja usando o pacote de certificados da CA mais recente antes de modificara instância, para evitar interrupções na conectividade.

9. Você pode optar por aplicar a modificação durante a próxima janela de manutenção ouimediatamente. Se sua intenção é modificar o certificado do servidor imediatamente, use a opçãoApply immediately (Aplicar imediatamente).

10. Escolha Modify instance (Modificar instância) para concluir a atualização.

Using the AWS CLI

Conclua as etapas a seguir para identificar e alternar o certificado de servidor antigo para suas instânciasexistentes do Amazon DocumentDB usando a AWS CLI.

1. Para modificar as instâncias imediatamente, execute o seguinte comando para cada instância docluster.

aws docdb modify-db-instance --db-instance-identifier <yourInstanceIdentifier> --ca-certificate-identifier rds-ca-2019 --apply-immediately

2. Para modificar as instâncias nos clusters para usarem o novo certificado CA na próxima janela demanutenção do cluster, execute o seguinte comando para cada instância no cluster.

aws docdb modify-db-instance --db-instance-identifier <yourInstanceIdentifier> --ca-certificate-identifier rds-ca-2019 --no-apply-immediately

TroubleshootingSe você estiver tendo problemas para conectar-se ao cluster como parte da alternância de certificado,sugerimos o seguinte:

• Reboot your instances. Rotating the new certificate requires that you reboot each of your instances.If you applied the new certificate to one or more instances but did not reboot them, reboot yourinstances to apply the new certificate. For more information, see Rebooting an Amazon DocumentDBInstance (p. 261).

• Verify that your clients are using the latest certificate bundle. See How can I be sure that I'm using thenewest CA bundle? (p. 163).

• Verify that your instances are using the latest certificate. See How do I know which of my AmazonDocumentDB instances are using the old/new server certificate? (p. 161).

• Verify that the latest certificate CA is being utilized by your application. Some drivers, like Java and Go,require extra code to import multiple certificates from a certificate bundle to the trust store. For moreinformation on connecting to Amazon DocumentDB with TLS, see Conexão com o Amazon DocumentDBde forma programática (p. 360).

• Contact support. If you have questions or issues, contact AWS Support.

Frequently Asked QuestionsVeja a seguir as respostas a algumas perguntas comuns sobre certificados TLS.

160

https://aws.amazon.com/premiumsupport/

Amazon DocumentDB Guia do desenvolvedorFrequently Asked Questions

What if I have questions or issues?Se você tiver dúvidas ou problemas, entre em contato com o AWS Support.

How do I know whether I'm using TLS to connect to my AmazonDocumentDB cluster?Para ver se o cluster está usando TLS, examine o parâmetro tls do seu grupo de parâmetros do cluster.Se o parâmetro tls estiver definido como enabled, você está usando o certificado TLS para se conectarao cluster. Para obter mais informações, consulte Managing Amazon DocumentDB Cluster ParameterGroups (p. 287).

Why are you updating the CA and server certificates?Os certificados CA e de servidor do Amazon DocumentDB foram atualizados como parte das melhorespráticas de manutenção e segurança padrão do Amazon DocumentDB. Os certificados CA e de servidoratuais estão definidos para expirar em 5 de março de 2020, quinta-feira.

What happens if I don't take any action by March 5, 2020?Se você estiver usando TLS para se conectar ao cluster do Amazon DocumentDB e não fizer a alteraçãoaté 5 de março de 2020, seus aplicativos que se conectam via TLS não poderão mais se comunicar com ocluster do Amazon DocumentDB.

O Amazon DocumentDB não alternará seus certificados de banco de dados automaticamente antes de5 de março de 2020. Você deve atualizar seus aplicativos e clusters para usar os novos certificados CAantes ou depois de 5 de março de 2020.

How do I know which of my Amazon DocumentDB instances areusing the old/new server certificate?Para identificar as instâncias do Amazon DocumentDB que ainda usam o certificado de servidor antigo, épossível usar o Console de gerenciamento da AWS do Amazon DocumentDB ou a AWS CLI.


Como identificar as instâncias em seus clusters que estão usando o certificado mais antigo


2. Na lista de regiões no canto superior direito da tela, escolha a região da AWS em que as instânciasresidem.


ainda estão com o certificado antigo do servidor (rds-ca-2015) e com o novo certificado de servidor(rds-ca-2019). Para exibir a coluna Certificate authority (Autoridade de certificação), siga estasetapas:


161




Using the AWS CLI

Para identificar as instâncias em seus clusters que estão usando o certificado de servidor mais antigo, useo comando describe-db-clusters com o seguinte.

aws docdb describe-db-instances \ --filters Name=engine,Values=docdb \ --query 'DBInstances[*].{CertificateVersion:CACertificateIdentifier,InstanceID:DBInstanceIdentifier}'

How do I modify individual instances in my Amazon DocumentDBcluster to update the server certificate?Recomendamos atualizar os certificados de servidor para todas as instâncias de um determinado clusterao mesmo tempo. Para modificar as instâncias em seu cluster, é possível usar o console ou a AWS CLI.

Note

A atualização de suas instâncias requer uma reinicialização, o que pode causar interrupção noserviço. Antes de atualizar o certificado de servidor, verifique se você concluiu a Etapa 1.





ainda estão no certificado antigo do servidor (rds-ca-2015). Para exibir a coluna Certificate authority(Autoridade de certificação), siga estas etapas:


5. Selecione uma instância para modificá-la.6. Escolha Actions (Ações) e, em seguida, Modify (Modificar).7. Em Certificate authority (Autoridade de certificação), selecione o novo certificado do servidor (rds-

ca-2019) para essa instância.8. Você verá um resumo das alterações na próxima página. Há um alerta adicional para lembrar você de

garantir que o aplicativo esteja usando o pacote de certificados da CA mais recente antes de modificara instância, para evitar interrupções na conectividade.

9. Você pode optar por aplicar a modificação durante a próxima janela de manutenção ouimediatamente.

10. Escolha Modify instance (Modificar instância) para concluir a atualização.

Using the AWS CLI

Conclua as etapas a seguir para identificar e alternar o certificado de servidor antigo para suas instânciasexistentes do Amazon DocumentDB usando a AWS CLI.

1. Para modificar as instâncias imediatamente, execute o seguinte comando para cada instância docluster.

162




aws docdb modify-db-instance --db-instance-identifier <yourInstanceIdentifier> --ca-certificate-identifier rds-ca-2019 --apply-immediately

2. Para modificar as instâncias nos clusters para usarem o novo certificado CA na próxima janela demanutenção do cluster, execute o seguinte comando para cada instância no cluster.

aws docdb modify-db-instance --db-instance-identifier <yourInstanceIdentifier> --ca-certificate-identifier rds-ca-2019 --no-apply-immediately

What happens if I add a new instance to an existing cluster?Todas as novas instâncias criadas usam o certificado de servidor antigo e exigem conexões TLS com ocertificado CA antigo. Todas as novas instâncias do Amazon DocumentDB criadas após 14 de janeiro de2020 usarão os novos certificados como padrão.

What happens if there is an instance replacement or failover onmy cluster?Se houver uma substituição de instância no cluster, a nova instância criada continuará usando o mesmocertificado do servidor que a outra instância estava usando anteriormente. Recomendamos atualizar oscertificados do servidor para todas as instâncias ao mesmo tempo. Se um failover acontecer no cluster, ocertificado do servidor no novo primário será usado.

If I'm not using TLS to connect to my cluster, do I still need toupdate each of my instances?Se você não usa TLS para se conectar aos seus clusters do Amazon DocumentDB, não precisa fazernada.

If I'm not using TLS to connect to my cluster but I plan to in thefuture, what should I do?Se você criou um cluster antes de 1º de novembro de 2019, siga a Etapa 1 e a Etapa 2 na seção anteriorpara garantir que seu aplicativo esteja usando o pacote de CA atualizado e que cada instância do AmazonDocumentDB esteja usando o certificado de servidor mais recente. Se você criou um cluster após 14 dejaneiro de 2020, ele já terá o certificado de servidor mais recente. Para verificar se o aplicativo está usandoo pacote de certificados CA mais recente, consulte If I'm not using TLS to connect to my cluster, do I stillneed to update each of my instances? (p. 163).

Can the deadline be extended beyond March 5, 2020?Se seus aplicativos estiverem se conectando via TLS, o prazo não pode ser prorrogado para além de 5 demarço de 2020.

How can I be sure that I'm using the newest CA bundle?Por motivos de compatibilidade, os ficheiros de grupo antigo e novo CA são nomeados rds-combined-ca-bundle.pem. Pode utilizar o tamanho e a tecla cardinal do pacote CA para determinar se o grupoCA é o mais recente. Além disso, também é possível usar ferramentas como openssl ou keytool parainspecionar o pacote de CA. O arquivo de pacote de CA antigo tem 26016 bytes de tamanho, e o hashSHA1 é 4cd5ba9e145006b17c400d5c778e1965b50172aa.

É possível verificar se tem o pacote mais recente usando os seguintes comandos.

163




macOS

Comando

ls -l rds-combined-ca-bundle.pem

Resultado

-rw-r--r-- 1 user users 65484 Sep 25 14:49 rds-combined-ca-bundle.pem

Comando

shasum rds-combined-ca-bundle.pem

Resultado

e12be0c71b499540ac6fe0c36a5050231616c9c4 rds-combined-ca-bundle.pem

Amazon Linux

Comando

ls -l rds-combined-ca-bundle.pem

Resultado

-rw-rw-r-- 1 ec2-user ec2-user 65484 Sep 25 20:52 rds-combined-ca-bundle.pem

Comando

sha1sum rds-combined-ca-bundle.pem

Resultado

e12be0c71b499540ac6fe0c36a5050231616c9c4 rds-combined-ca-bundle.pem

Windows

Comando

dir rds-combined-ca-bundle.pem

Resultado

09/25/2019 02:53 PM 65,484 rds-combined-ca-bundle.pem

Comando

certutil -hashfile rds-combined-ca-bundle.pem

Resultado

SHA1 hash of rds-combined-ca-bundle.pem:

164


e12be0c71b499540ac6fe0c36a5050231616c9c4

Why do I see "RDS" in the name of the CA bundle?Em determinados recursos de gerenciamento, como o gerenciamento de certificados, o AmazonDocumentDB usa uma tecnologia operacional compartilhada com o Amazon Relational Database Service(Amazon RDS).

When will the new certificate expire?O novo certificado de servidor expirará em 22 de agosto de 2024 GMT.

If I applied the new server certificate, can I revert it back to the oldserver certificate?Se for necessário reverter uma instância para o certificado de servidor antigo, recomendamos fazer issopara todas as instâncias do cluster. É possível reverter o certificado de servidor para cada instância em umcluster usando o Console de gerenciamento da AWS ou a AWS CLI.




3. No painel de navegação, no lado esquerdo do console, escolha Instances (Instâncias).4. Selecione uma instância para modificá-la. Escolha Actions (Ações) e, em seguida, Modify (Modificar).5. Em Certificate authority (Autoridade de certificação), é possível selecionar o certificado de servidor

antigo (rds-ca-2015).6. Escolha Continue (Continuar) para exibir um resumo das modificações.7. Nesta página resultante, você pode optar por programar suas modificações para serem aplicadas

na próxima janela de manutenção ou aplicá-las imediatamente. Faça sua seleção e escolha Modifyinstance (Modificar instância).

Note

Se você optar por aplicar as alterações imediatamente, todas as alterações na fila demodificações pendentes também serão aplicadas. Se qualquer uma das alteraçõespendentes exigir tempo de inatividade, escolher essa opção poderá causar um tempo deinatividade inesperado.

Using the AWS CLI

aws docdb modify-db-instance --db-instance-identifier <db_instance_name> ca-certificate-identifier rds-ca-2015 <--apply-immediately | --no-apply-immediately>

Se você escolher --no-apply-immediately, a alteração será aplicada na próxima janela demanutenção do cluster.

If I restore from a snapshot or a point in time restore, will it havethe new server certificate ?Se você restaurar um snapshot ou executar uma restauração point-in-time após 14 de janeiro de 2020, onovo cluster criado usará o novo certificado CA.

165


Amazon DocumentDB Guia do desenvolvedorValidação de conformidade

What if I’m having issues connecting directly to my AmazonDocumentDB cluster from Mac OS X Catalina?O Mac OS X Catalina atualizou os requisitos para certificados confiáveis. Os certificados confiáveis agoradevem ser válidos por 825 dias ou menos (consulte https://support.apple.com/en-us/HT210176). Oscertificados de instância do Amazon DocumentDB são válidos por mais de quatro anos, mais do queo máximo do Mac OS X. Para conectar-se diretamente a um cluster co Amazon DocumentDB em umcomputador que executa o Mac OS X Catalina, permita certificados inválidos ao criar a conexão TLS.Nesse caso, os certificados inválidos significam que o período de validade é superior a 825 dias. Entendaos riscos antes de permitir certificados inválidos ao conectar-se ao cluster do Amazon DocumentDB.

Para conectar-se a um cluster do Amazon DocumentDB do OS X Catalina usando a AWS CLI, use oparâmetro tlsAllowInvalidCertificates.

mongo --tls --host <hostname> --username <username> --password <password> --port 27017 --tlsAllowInvalidCertificates

Validação de conformidade no AmazonDocumentDB

Auditores terceiros avaliam a segurança e a conformidade do Amazon DocumentDB (compatível comMongoDB) como parte de vários programas de conformidade da AWS, incluindo o seguinte:

• System and Organization Controls (SOC – Controles do Sistema e da Organização) 1, 2 e 3. Para obtermais informações, consulte SOC.

• Payment Card Industry Data Security Standard (PCI DSS – Padrão de segurança de dados do setor decartão de pagamento) Para obter mais informações, consulte PCI DSS.

• ISO 9001, 27001, 27017 e 27018. Para obter mais informações, consulte Certificado ISO.• Acordo de associado comercial da Lei de Portabilidade e Responsabilidade de Provedores de Saúde

(HIPAA BAA) Para obter mais informações, consulte Conformidade com a HIPAA.

A AWS fornece uma lista atualizada com frequência de serviços da AWS no escopo de programas deconformidade específicos em Serviços da AWS no escopo do programa de conformidade.

Os relatórios de auditoria de terceiros estão disponíveis para download por meio do AWS Artifact. Paraobter mais informações, consulte Download de relatórios no AWS Artifact.

Para obter mais informações sobre programas de conformidade da AWS, consulte Programas deconformidade da AWS.

Sua responsabilidade de conformidade ao usar o Amazon DocumentDB é determinada pelaconfidencialidade de seus dados, pelas metas de conformidade da sua empresa e pelas regulamentaçõese leis aplicáveis. Se seu uso do Amazon DocumentDB estiver sujeito à conformidade com padrões comoHIPAA ou PCI, a AWS fornecerá recursos para ajudar:

• Recursos de conformidade da AWS – uma coleção de manuais e guias que pode ser aplicada ao seusetor e local.

• Guias de Início Rápido de segurança e conformidade – guias de implantação que discutem asconsiderações de arquitetura e fornecem etapas para implantação de ambientes de linha de basefocados em conformidade e segurança na AWS.

• AWS Config – um serviço que avalia até que ponto suas configurações de recursos estão emconformidade com práticas internas, diretrizes do setor e regulamentações.

166

https://support.apple.com/en-us/HT210176

https://aws.amazon.com/compliance/soc-faqs/

https://aws.amazon.com/compliance/pci-dss-level-1-faqs/

https://aws.amazon.com/compliance/iso-certified/

https://aws.amazon.com/compliance/hipaa-compliance


https://docs.aws.amazon.com/artifact/latest/ug/downloading-documents.html



https://aws.amazon.com/compliance/resources/

https://aws.amazon.com/quickstart/?awsf.quickstart-homepage-filter=categories%23security-identity-compliance

https://docs.aws.amazon.com/config/latest/developerguide/evaluate-config.html

Amazon DocumentDB Guia do desenvolvedorResiliência

• AWS Security Hub – uma visão abrangente do estado da segurança na AWS que ajuda você a verificara conformidade com os padrões do setor de segurança e as práticas recomendadas.

• Arquitetura para segurança e conformidade com HIPAA – um whitepaper que descreve como asempresas podem usar a AWS para criar aplicativos em conformidade com a HIPAA.

Resiliência no Amazon DocumentDBA infraestrutura global da AWS é criada com base em regiões e zonas de disponibilidade da AWS. Asregiões da AWS fornecem várias zonas de disponibilidade separadas e isoladas fisicamente, que sãoconectadas com baixa latência, altas taxas de transferência e redes altamente redundantes. Com as zonasde disponibilidade, você pode projetar e operar aplicativos e bancos de dados que executam o failoverautomaticamente entre as zonas de disponibilidade sem interrupção. As zonas de disponibilidade são maisaltamente disponíveis, tolerantes a falhas e escaláveis que uma ou várias infraestruturas de data centertradicionais.

Um cluster do Amazon DocumentDB só pode ser criado em uma Amazon VPC com pelo menos duassub-redes em pelo menos duas zonas de disponibilidade. Ao distribuir suas instâncias de cluster em pelomenos duas zonas de disponibilidade, o Amazon DocumentDB ajuda a garantir que haverá instânciasdisponíveis no cluster no caso improvável de ocorrer uma falha na zona de disponibilidade. O volumedo cluster do Amazon DocumentDB sempre abrange três zonas de disponibilidade para fornecer umarmazenamento durável com menor possibilidade de perda de dados.

Para obter mais informações sobre regiões da AWS e zonas de disponibilidade, consulte Infraestruturaglobal da AWS.

Além da infraestrutura global da AWS, o Amazon DocumentDB oferece vários recursos para ajudar aoferecer suporte às suas necessidades de resiliência de dados e backup.

Armazenamento tolerante a falhas e com recuperação automática

Cada porção de 10 GB do volume de armazenamento é replicada de seis formas nas zonas dedisponibilidade. O Amazon DocumentDB usa o armazenamento tolerante a falhas que lida com aperda de até duas cópias de dados de forma transparente sem afetar a disponibilidade de gravaçãodo banco de dados e até três cópias sem afetar a disponibilidade de leitura. O armazenamento doAmazon DocumentDB também se recupera automaticamente; os blocos e os discos de dados sãocontinuamente verificados quanto a erros e substituídos automaticamente.

Backups e restauração manuais

O Amazon DocumentDB fornece a capacidade de criar backups completos do cluster para retenção erecuperação a longo prazo. Para obter mais informações, consulte Backup e restauração no AmazonDocumentDB (p. 175).

Recuperação point-in-time

A recuperação point-in-time ajuda a proteger os clusters do Amazon DocumentDB contra operaçõesacidentais de gravação ou exclusão. Com a recuperação point-in-time, você não precisa se preocuparcom a criação, a manutenção ou a programação de backups sob demanda. Para obter maisinformações, consulte Restauração point-in-time (p. 201).

Segurança da infraestrutura no AmazonDocumentDB

Como serviço gerenciado, o Amazon DocumentDB é protegido pelos procedimentos de segurança da redeglobal da AWS descritos no whitepaper Amazon Web Services: visão geral dos processos de segurança.

167

https://docs.aws.amazon.com/securityhub/latest/userguide/what-is-securityhub.html

https://d0.awsstatic.com/whitepapers/compliance/AWS_HIPAA_Compliance_Whitepaper.pdf

https://aws.amazon.com/about-aws/global-infrastructure/

https://aws.amazon.com/about-aws/global-infrastructure/

https://d0.awsstatic.com/whitepapers/Security/AWS_Security_Whitepaper.pdf

Amazon DocumentDB Guia do desenvolvedorMelhores práticas de segurança

Você usa as chamadas de API da AWS para acessar o Amazon DocumentDB por meio da rede. Osclientes devem ter suporte ao TLS (Transport Layer Security) 1.0. Recomendamos o TLS 1.2 ou posterior.Os clientes também devem ter suporte a pacotes de criptografia com sigilo de encaminhamento perfeito(PFS) como Ephemeral Diffie-Hellman (DHE) ou Ephemeral Elliptic Curve Diffie-Hellman (ECDHE). Amaioria dos sistemas modernos como Java 7 e versões posteriores oferece suporte a esses modos. Alémdisso, as solicitações devem ser assinadas usando um ID da chave de acesso e uma chave de acessosecreta associada a uma entidade principal do IAM. Ou você pode usar o AWS Security Token Service(AWS STS) para gerar credenciais de segurança temporárias para assinar solicitações.

É possível chamar essas operações de API de qualquer local da rede, mas o Amazon DocumentDB nãooferece suporte a políticas de acesso baseadas em recurso, que podem incluir restrições com base noendereço IP de origem. Também é possível usar políticas do Amazon DocumentDB para controlar oacesso de endpoints da Amazon Virtual Private Cloud (Amazon VPC) ou VPCs específicas. Efetivamente,isso isola o acesso à rede para um determinado recurso do Amazon DocumentDB somente da VPCespecífica dentro da rede da AWS.

Melhores práticas de segurança para o AmazonDocumentDB

Para práticas recomendadas de segurança, você deve usar contas do AWS Identity and AccessManagement (IAM) para controlar o acesso a operações de API do Amazon DocumentDB, especialmenteoperações que criam, modificam ou excluem recursos do Amazon DocumentDB. Esses recursos incluemclusters, grupos de segurança e grupos de parâmetros. Você também deve usar o IAM para controlarações que executam ações administrativas comuns, como fazer backup e restaurar clusters. Ao criarfunções do IAM, utilize o princípio do privilégio mínimo.

• Aplique o menor privilégio com o controle de acesso baseado em função (p. 144).• Atribua uma conta do IAM individual a cada pessoa que gerencia os recursos do Amazon DocumentDB.

Não use o usuário raiz da conta da AWS para gerenciar recursos do Amazon DocumentDB. Crie umusuário do IAM para todos os usuários, incluindo você mesmo.

• Conceda a cada usuário o conjunto mínimo de permissões necessárias para realizar suas funções.• Use grupos do IAM para gerenciar efetivamente permissões para vários usuários. Para obter mais

informações sobre o IAM, consulte o Guia do usuário do IAM. Para obter mais informações sobre asmelhores práticas do IAM, consulte Melhores práticas do IAM.

• Mude suas credenciais do IAM regularmente.• Configure o AWS Secrets Manager para girar automaticamente os segredos do Amazon DocumentDB.

Para obter mais informações, consulte Rotação do AWS Secrets Manager Secrets e Rotação desegredos do Amazon DocumentDB no Guia do usuário do AWS Secrets Manager.

• Use Transport Layer Security (TLS) e criptografia em repouso para criptografar seus dados.

Auditoria de eventos do Amazon DocumentDBCom o Amazon DocumentDB (compatível com MongoDB), você pode auditar eventos que foramexecutados em seu cluster. Exemplos de eventos registrados incluem tentativas de autenticação bem-sucedidas e com falha, eliminação de uma coleção em um banco de dados ou a criação de um índice. Porpadrão, a auditoria fica desabilitada no Amazon DocumentDB e requer que você opte por esse recurso.

Quando a auditoria está ativada, o Amazon DocumentDB registra eventos de Data Definition Language(DDL), autenticação, autorização e gerenciamento de usuários no Amazon CloudWatch Logs. Quando aauditoria está ativada, o Amazon DocumentDB exporta registros de auditoria do seu cluster (documentos

168

https://docs.aws.amazon.com/STS/latest/APIReference/Welcome.html

https://docs.aws.amazon.com/IAM/latest/UserGuide/Welcome.html

https://docs.aws.amazon.com/IAM/latest/UserGuide/IAMBestPractices.html

https://docs.aws.amazon.com/secretsmanager/latest/userguide/rotating-secrets.html



Amazon DocumentDB Guia do desenvolvedorEventos com suporte

JSON) para o Amazon CloudWatch Logs. Você pode usar o Amazon CloudWatch Logs para analisar,monitorar e arquivar seus eventos de auditoria do Amazon DocumentDB.

Embora o Amazon DocumentDB não cobre um custo adicional para ativar a auditoria, você será cobradode acordo com as taxas padrão pelo uso do CloudWatch Logs. Para obter informações sobre a definiçãode preço do CloudWatch Logs, consulte Definição de preço do Amazon CloudWatch.

O recurso de auditoria do Amazon DocumentDB é totalmente diferente do uso de recursos do serviço queé monitorado com o AWS CloudTrail. O CloudTrail registra operações que são realizadas com a interfacede linha de comando da AWS (AWS CLI) ou o Console de gerenciamento da AWS em recursos comoclusters, instâncias, grupos de parâmetros e snapshots. A auditoria de recursos da AWS com o CloudTrailestá ativada por padrão e não pode ser desativada. O recurso de auditoria do Amazon DocumentDB é umrecurso opcional. Ele registra operações que ocorrem dentro do seu cluster em objetos, como bancos dedados, coleções, índices e usuários.

Tópicos• Eventos com suporte (p. 169)• Ativação da auditoria (p. 170)• Desativação da auditoria (p. 172)• Como acessar seus eventos de auditoria (p. 174)

Eventos com suporteA auditoria do Amazon DocumentDB oferece suporte às seguintes categorias de evento: conexão, datadefinition language (DDL), gerenciamento de usuários e autorização. Os tipos de evento são os seguintes.

Event Type Categoria Descrição

authenticate Conexão Tentativas deautenticação bem-sucedidas ou com falhaem uma nova conexão.

createDatabase DDL Criação de um novobanco de dados.

createCollection DDL Criação de uma novacoleção em um bancode dados.

createIndex DDL Criação de um novoíndice em uma coleção.

dropCollection DDL Eliminação de umacoleção em um bancode dados.

dropDatabase DDL Eliminação de um bancode dados.

dropIndex DDL Eliminação de um índiceem uma coleção.

createUser Gerenciamento deusuários

Criação de um novousuário.

169

https://aws.amazon.com/cloudwatch/pricing/

Amazon DocumentDB Guia do desenvolvedorAtivação da auditoria

Event Type Categoria Descrição

dropUser Gerenciamento deusuários

Eliminação de umusuário existente.

updateUser UserManagement Atualização de umusuário existente.

dropAllUsersFromDatabase Gerenciamento deusuários

Eliminação de todos osusuários em um bancode dados.

authCheck Autorização Tentativas nãoautorizadas de executaruma operação.

Ativação da auditoriaA ativação da auditoria em um cluster é um processo de duas etapas. Certifique-se de que ambas asetapas sejam concluídas ou os logs da auditoria não serão enviados para o CloudWatch Logs.

Etapa 1. Habilitar o parâmetro de cluster audit_logsPara definir o parâmetro audit_logs como enabled, crie um novo grupo de parâmetros do clusterou use um grupo de parâmetros personalizados existente e modifique-o definindo audit_logs comoenabled. Não é possível modificar um grupo de parâmetros padrão.

Para obter mais informações, consulte:

• Creating Amazon DocumentDB Cluster Parameter Groups (p. 293)

Depois que criar um grupo de parâmetros, modifique-o alterando o valor do parâmetro audit_logspara enabled.

• Modifying Amazon DocumentDB Cluster Parameter Groups (p. 295)

Etapa 2. Ativar a exportação do Amazon CloudWatch LogsAssim que o valor do parâmetro do cluster audit_logs for enabled, você também deverá ativar oAmazon DocumentDB para exportar logs para o Amazon CloudWatch. Se você omitir qualquer umadessas etapas, logs de auditoria não serão enviados para o CloudWatch.

Ao criar um cluster, executar uma restauração point-in-time ou restaurar um snapshot, você pode ativar oCloudWatch Logs com as etapas a seguir.

Usar o Console de gerenciamento da AWSPara habilitar a exportação de logs do Amazon DocumentDB para o CloudWatch usando o console,consulte os seguintes tópicos:

• Ao criar um cluster — em Criar um cluster e instância primária usando o Console de gerenciamento daAWS (p. 218), consulte Create a Cluster: Additional Configurations (Criar um cluster: configuraçõesadicionais), (etapa 5, Log exports (Exportações de log))

• Ao modificar um cluster existente – Uso do Console de gerenciamento da AWS (p. 231).• Ao executar uma restauração de snapshot de cluster – Restaurar de um snapshot de cluster usando a

Console de gerenciamento da AWS (p. 197), etapa 9.

170

Amazon DocumentDB Guia do desenvolvedorAtivação da auditoria

• Ao executar uma restauração point-in-time – Restaurar para um point-in-time usando o Console degerenciamento da AWS (p. 201) (etapa 9).

Usar a AWS CLI

Como habilitar logs de auditoria ao criar um novo cluster

O código a seguir cria o cluster sample-cluster e ativa os logs de auditoria do CloudWatch.

Example


aws docdb create-db-cluster \ --db-cluster-identifier sample-cluster \ --port 27017 \ --engine docdb \ --master-username master-username \ --master-user-password password \ --db-subnet-group-name default \ --enable-cloudwatch-logs-exports audit

Para Windows:

aws docdb create-db-cluster ^ --db-cluster-identifier sample-cluster ^ --port 27017 ^ --engine docdb ^ --master-username master-username ^ --master-user-password password ^ --db-subnet-group-name default ^ --enable-cloudwatch-logs-exports audit

Como habilitar logs de auditoria ao modificar um cluster existente

O código a seguir modifica o cluster sample-cluster e ativa os logs de auditoria do CloudWatch.

Example


aws docdb modify-db-cluster \ --db-cluster-identifier sample-cluster \ --cloudwatch-logs-export-configuration '{"EnableLogTypes":["audit"]}'

Para Windows:

aws docdb modify-db-cluster ^ --db-cluster-identifier sample-cluster ^ --cloudwatch-logs-export-configuration '{"EnableLogTypes":["audit"]}'

A saída dessas operações é semelhante ao seguinte (formato JSON).

{ "DBCluster": { "HostedZoneId": "ZNKXH85TT8WVW", "StorageEncrypted": false,

171

Amazon DocumentDB Guia do desenvolvedorDesativação da auditoria

"DBClusterParameterGroup": "default.docdb3.6", "MasterUsername": "<user-name>", "BackupRetentionPeriod": 1, "Port": 27017, "VpcSecurityGroups": [ { "Status": "active", "VpcSecurityGroupId": "sg-77186e0d" } ], "DBClusterArn": "arn:aws:rds:us-east-1:900083794985:cluster:sample-cluster", "Status": "creating", "Engine": "docdb", "EngineVersion": "3.6.0", "MultiAZ": false, "AvailabilityZones": [ "us-east-1a", "us-east-1c", "us-east-1f" ], "DBSubnetGroup": "default", "DBClusterMembers": [], "ReaderEndpoint": "sample-cluster.cluster-ro-corcjozrlsfc.us-east-1.docdb.amazonaws.com", "EnabledCloudwatchLogsExports": [ "audit" ], "PreferredMaintenanceWindow": "wed:03:08-wed:03:38", "AssociatedRoles": [], "ClusterCreateTime": "2019-02-13T16:35:04.756Z", "DbClusterResourceId": "cluster-YOS52CUXGDTNKDQ7DH72I4LED4", "Endpoint": "sample-cluster.cluster-corcjozrlsfc.us-east-1.docdb.amazonaws.com", "PreferredBackupWindow": "07:16-07:46", "DBClusterIdentifier": "sample-cluster" }}

Desativação da auditoriaÉ possível desabilitar a auditoria desabilitando a exportação do CloudWatch Logs e desabilitando oparâmetro audit_logs.

Desativação da exportação do CloudWatch LogsVocê pode desativar a exportação de logs de auditoria usando o Console de gerenciamento da AWS ou aAWS CLI.


O procedimento a seguir usa o Console de gerenciamento da AWS para desativar a exportação de logs doAmazon DocumentDB para o CloudWatch.

Como desabilitar logs de auditoria


2. No painel de navegação, escolha Clusters. Depois disso, escolha o botão à esquerda do nome docluster para o qual você deseja desabilitar a exportação de logs.

3. Escolha Actions (Ações) e, em seguida, Modify (Modificar).4. Role para baixo até a seção Log exports (Exportações de log) e escolha Disabled (Desativado).

172


Amazon DocumentDB Guia do desenvolvedorDesativação da auditoria

5. Escolha Continue.6. Analise as alterações e escolha quando você deseja que essa mudança seja aplicada ao seu cluster.

• Apply during the next scheduled maintenance window (Aplicar durante a próxima janela demanutenção programada)

• Apply immediately (Aplicar imediatamente)7. Selecione Modify Cluster (Modificar cluster).

Usar a AWS CLI

O código a seguir modifica o cluster sample-cluster e desativa os logs de auditoria do CloudWatch.

Example


aws docdb modify-db-cluster \ --db-cluster-identifier sample-cluster \ --cloudwatch-logs-export-configuration '{"DisableLogTypes":["audit"]}'

Para Windows:

aws docdb modify-db-cluster ^ --db-cluster-identifier sample-cluster ^ --cloudwatch-logs-export-configuration '{"DisableLogTypes":["audit"]}'


{ "DBCluster": { "DBClusterParameterGroup": "default.docdb3.6", "HostedZoneId": "ZNKXH85TT8WVW", "MasterUsername": "<user-name>", "Status": "available", "Engine": "docdb", "Port": 27017, "AvailabilityZones": [ "us-east-1a", "us-east-1c", "us-east-1f" ], "EarliestRestorableTime": "2019-02-13T16:35:50.387Z", "DBSubnetGroup": "default", "LatestRestorableTime": "2019-02-13T16:35:50.387Z", "DBClusterArn": "arn:aws:rds:us-east-1:900083794985:cluster:sample-cluster2", "Endpoint": "sample-cluster2.cluster-corcjozrlsfc.us-east-1.docdb.amazonaws.com", "ReaderEndpoint": "sample-cluster2.cluster-ro-corcjozrlsfc.us-east-1.docdb.amazonaws.com", "BackupRetentionPeriod": 1, "EngineVersion": "3.6.0", "MultiAZ": false, "ClusterCreateTime": "2019-02-13T16:35:04.756Z", "DBClusterIdentifier": "sample-cluster2", "AssociatedRoles": [], "PreferredBackupWindow": "07:16-07:46", "DbClusterResourceId": "cluster-YOS52CUXGDTNKDQ7DH72I4LED4", "StorageEncrypted": false, "PreferredMaintenanceWindow": "wed:03:08-wed:03:38", "DBClusterMembers": [],

173

Amazon DocumentDB Guia do desenvolvedorComo acessar seus eventos de auditoria

"VpcSecurityGroups": [ { "Status": "active", "VpcSecurityGroupId": "sg-77186e0d" } ] }}

Desativação do parâmetro audit_logsPara desabilitar o parâmetro audit_logs para o cluster, é possível modificar o cluster para que ele useum grupo de parâmetros em que o valor do parâmetro audit_logs é disabled. Ou é possível modificaro valor do parâmetro audit_logs no grupo de parâmetros de cluster para que ele seja disabled.

Para obter mais informações, consulte os tópicos a seguir:

• Modificar um cluster do Amazon DocumentDB (p. 231)• Modifying Amazon DocumentDB Cluster Parameter Groups (p. 295)

Como acessar seus eventos de auditoriaUse estas etapas para acessar seus eventos de auditoria no Amazon CloudWatch.

1. Abra o console do CloudWatch em https://console.aws.amazon.com/cloudwatch/.2. Certifique-se de estar na mesma região que seu cluster do Amazon DocumentDB.3. No painel de navegação, selecione Logs.4. Para localizar os logs de auditoria para o seu cluster, na lista, localize e escolha /aws/

docdb/yourClusterName/audit.

Os eventos de auditoria para cada uma das suas instâncias estão disponíveis em cada um dosrespectivos nomes de instância.

174

https://console.aws.amazon.com/cloudwatch/

Amazon DocumentDB Guia do desenvolvedorCópia de segurança e restauro: Conceitos

Backup e restauração no AmazonDocumentDB

Amazon DocumentDB (compatível com MongoDB) faz cópias de segurança dos seus dados para AmazonSimple Storage Service (Amazon S3) para 1–35 dias para que possa restaurar rapidamente a qualquerponto dentro do período de retenção de cópia de segurança. Amazon DocumentDB também tira capturasautomáticas dos seus dados como parte deste processo de cópia de segurança contínuo.

Você também pode reter os dados de backup além do período de retenção de backup, criando umsnapshot manual dos dados do cluster. O processo de backup não afeta o desempenho do cluster.

Esta secção discute os casos de utilização para as capacidades de cópia de segurança em AmazonDocumentDB e mostra como gerir cópias de segurança para o seu Amazon DocumentDB grupos.

Tópicos• Cópia de segurança e restauro: Conceitos (p. 175)• Noções básicas do uso do armazenamento de backup (p. 176)• Despejo, restauração, importação e exportação de dados (p. 177)• Considerações sobre snapshot de cluster (p. 181)• Comparação dos snapshots automáticos e manuais (p. 183)• Criação de um snapshot manual de cluster (p. 184)• Copiar Amazon DocumentDB Instantâneos de aglomerados (p. 186)• Partilhar Amazon DocumentDB Instantâneos de aglomerados (p. 192)• Restauração de um snapshot de cluster (p. 196)• Restauração point-in-time (p. 201)• Exclusão de um snapshot de cluster (p. 205)

Cópia de segurança e restauro: ConceitosSubstantivo Description

(Descrição)APIs (verbos)

Backup retention period(Período de retenção debackup)

Um períodoentre 1 e 35dias no qualvocê podeexecutarumarestauraçãopoint-in-time.

create-db-cluster

modify-db-cluster

restore-db-cluster-to-point-in-time

AmazonDocumentDBVolume dearmazenamento do

O volume dearmazenamentoresilientede altadisponibilidadeque replicadadosde seis

create-db-cluster

delete-db-cluster

175

Amazon DocumentDB Guia do desenvolvedorNoções básicas do uso do armazenamento de backup

Substantivo Description(Descrição)

APIs (verbos)

maneirasem trêszonas dedisponibilidade.Um clusterdo AmazonDocumentDBé resiliente,independentementedo númerode instânciasno cluster.

Janela de backup Períodono dia emque ossnapshotsautomáticossão obtidos.

create-db-cluster

describe-db-cluster

modify-db-cluster

Snapshot automático Snapshotsdiários quesão backupscompletosdo cluster esão criadosautomaticamentepeloprocessode backupcontínuono AmazonDocumentDB.

restore-db-cluster-from-snapshot

describe-db-cluster-snapshot-attributes

describe-db-cluster-snapshots

Snapshot manual Ossnapshotsquevocê criamanualmentepara reterbackupscompletosde umcluster alémdo períodode backup.

create-db-cluster-snapshot

copy-db-cluster-snapshot

delete-db-cluster-snapshot

describe-db-cluster-snapshot-attributes

describe-db-cluster-snapshots

modify-db-cluster-snapshot-attribute

Noções básicas do uso do armazenamento debackup

Amazon DocumentDBO armazenamento de backup do consiste em backups contínuos dentro do períodode retenção de backup e snapshots manuais fora do período de retenção. Para controlar o uso de

176

Amazon DocumentDB Guia do desenvolvedorDespejo, restauração, importação e exportação de dados

armazenamento de backup, você pode reduzir o intervalo de retenção de backup, remover snapshotsmanuais antigos quando eles não forem mais necessários, ou ambos. Para obter informações gerais sobrebackups do Amazon DocumentDB, consulte Backup e restauração no Amazon DocumentDB (p. 175).Para informações sobre o preço sobre Amazon DocumentDB armazenamento de cópias de segurança,consulte Amazon DocumentDB Preços.

Para controlar os custos, monitore a quantidade de armazenamento consumido por backups contínuos esnapshots manuais que persistem além do período de retenção. Em seguida, você pode reduzir o intervalode retenção de backup e remover snapshots manuais quando eles não forem mais necessários.

Pode utilizar o Amazon CloudWatch métricas TotalBackupStorageBilled, SnapshotStorageUsed,e BackupRetentionPeriodStorageUsed para rever e monitorizar a quantidade de armazenamentoutilizada pelo seu Amazon DocumentDB cópias de segurança, como se segue:

• BackupRetentionPeriodStorageUsed representa a quantidade de armazenamento de backupusado para armazenar backups contínuos na hora atual. Esse valor da métrica depende do tamanho dovolume do cluster e do número de alterações feitas durante o período de retenção. No entanto, para finsde faturamento a métrica não excede o tamanho cumulativo do volume do cluster durante o período deretenção. Por exemplo, se o tamanho do cluster for 100 GiB e o período de retenção for de dois dias, ovalor máximo de BackRetentionPeriodStorageUsed será 200 GiB (100 GiB + 100 GiB).

• SnapshotStorageUsed representa a quantidade de armazenamento de backup usado para

armazenar snapshots manuais além do período de retenção de backup. Os snapshots manuaistirados dentro do período de retenção não são contados no armazenamento de backup. Da mesmaforma, snapshots automáticos não são contados no armazenamento de backup. O tamanho decada snapshot é o tamanho do volume do cluster no momento em que você tira o snapshot. O valorSnapshotStorageUsed depende do número de snapshots que você mantém e do tamanho decada snapshot. Por exemplo, suponha que você tenha um snapshot fora do período de retenção e otamanho do volume de cluster tenha sido 100 GiB quando esse snapshot foi feito. A quantidade deSnapshotStorageUsed será 100 GiB.

• TotalBackupStorageBilled representa a soma de BackupRetentionPeriodStorageUsed

e SnapshotStorageUsed, menos uma quantidade de armazenamento de cópia de segurançagratuito igual ao tamanho do volume de cluster para um dia. Por exemplo, se o seu tamanho decluster for 100 gib, tem um dia de retenção e tem um instantâneo fora do período de retenção, oTotalBackupStorageBilled é 100 gib (100) gib + 100 gib - 100 dob).

• Essas métricas são calculadas de forma independente para cada Amazon DocumentDB cluster.

Pode monitorizar o seu Amazon DocumentDB clusters e elaboram relatórios utilizando CloudWatchmétricas através do CloudWatch consola. Para obter mais informações sobre como usar as métricas doCloudWatch, consulte Monitoramento do Amazon DocumentDB (p. 335).

Despejo, restauração, importação e exportação dedados

Pode utilizar o mongodump, mongorestore, mongoexport, e mongoimport utilitários para mover osdados para dentro e para fora do seu Amazon DocumentDB grupo. Esta seção discute o propósito de cadauma dessas ferramentas e configurações para ajudar você a obter um melhor desempenho.

Tópicos

177



Amazon DocumentDB Guia do desenvolvedormongodump

• mongodump (p. 178)• mongorestore (p. 178)• mongoexport (p. 179)• mongoimport (p. 179)• Tutorial (p. 179)

mongodumpO utilitário mongodump cria um backup binário (BSON) de um banco de dados MongoDB. O mongodumpé o método preferido de dados de dumping da sua origem de distribuição de mongodb, quando tentarestaurá-lo para o seu Amazon DocumentDB cluster devido às eficiências de tamanho atingidas aoarmazenar os dados num formato binário.

Dependendo dos recursos disponíveis na instância ou na máquina que está a utilizar para executar ocomando, pode acelerar o seu mongodump ao aumentar o número de ligações paralelas saltadas dapredefinição 1 utilizando o --numParallelCollections opção. Uma boa regra do polegar é começarcom um trabalhador por vcpu no seu Amazon DocumentDB instância primária do cluster.

Exemplo de usoSegue-se um exemplo de utilização do mongodump utilidade no Amazon DocumentDB cluster, sample-cluster.

mongodump --ssl \ --host="sample-cluster.node.us-east-1.docdb.amazonaws.com:27017" \ --collection=sample-collection \ --db=sample-database \ --out=sample-output-file \ --numParallelCollections 4 \ --username=sample-user \ --password=abc0123 \ --sslCAFile rds-combined-ca-bundle.pem

mongorestoreO mongorestore permite restaurar uma cópia de segurança binária (BSON) de uma base dedados criada com o mongodump utilidade. É possível melhorar o desempenho da restauraçãoaumentando o número de operadores para cada coleção durante a restauração com a opção --numInsertionWorkersPerCollection (o padrão é 1). Uma boa regra do polegar é começar com umtrabalhador por vcpu no seu Amazon DocumentDB instância primária do cluster.

Exemplo de usoSegue-se um exemplo de utilização do mongorestore utilidade no Amazon DocumentDB cluster,sample-cluster.

mongorestore --ssl \ --host="sample-cluster.node.us-east-1.docdb.amazonaws.com:27017" \ --username=sample-user \ --password=abc0123 \ --sslCAFile rds-combined-ca-bundle.pem <fileToBeRestored>

178

Amazon DocumentDB Guia do desenvolvedormongoexport

mongoexportO mongoexport ferramenta exportar dados em Amazon DocumentDB para formatos de ficheiro JSON,CSV ou TSV. A ferramenta mongoexport é o método preferencial para exportar dados que precisam serlegíveis por humanos ou por máquina.

Note

mongoexport não oferece suporte diretamente a exportações paralelas. No entanto, é possívelaumentar o desempenho executando vários trabalhos mongoexport simultaneamente paracoleções diferentes.

Exemplo de usoSegue-se um exemplo de utilização do mongoexport na Amazon DocumentDB cluster, sample-cluster.

mongoexport --ssl \ --host="sample-cluster.node.us-east-1.docdb.amazonaws.com:27017" \ --collection=sample-collection \ --db=sample-database \ --out=sample-output-file \ --username=sample-user \ --password=abc0123 \ --sslCAFile rds-combined-ca-bundle.pem

mongoimportO mongoimport a ferramenta importa o conteúdo dos ficheiros JSON, CSV ou TSV num AmazonDocumentDB grupo. É possível usar o parâmetro -–numInsertionWorkers para paralelizar e acelerar aimportação (o padrão é 1).

Exemplo de usoSegue-se um exemplo de utilização do mongoimport na Amazon DocumentDB cluster, sample-cluster.

mongoimport --ssl \ --host="sample-cluster.node.us-east-1.docdb.amazonaws.com:27017" \ --collection=sample-collection \ --db=sample-database \ --file=<yourFile> \ --numInsertionWorkers 4 --username=sample-user --password=abc0123 \ --sslCAFile rds-combined-ca-bundle.pem

TutorialO tutorial seguinte descreve como utilizar o mongodump, mongorestore, mongoexport, emongoimport utilitários para mover os dados para dentro e fora de um Amazon DocumentDB grupo.

1. Pré-requisitos — Antes de começar, certifique-se de que Amazon DocumentDB o cluster estáprovisionado e tem acesso a Amazon EC2 na mesma VPC como o seu grupo. Para obter maisinformações, consulte Conexão usando Amazon EC2 (p. 398).

Para poder usar as ferramentas do utilitário mongo, é necessário ter o pacote mongodb-org-toolsinstalado na instância do EC2, conforme indicado a seguir.

179

Amazon DocumentDB Guia do desenvolvedorTutorial

sudo yum install mongodb-org-tools-3.6.18

Como o Amazon DocumentDB usa a criptografia Transport Layer Security (TLS) por padrão, tambémé necessário fazer download do arquivo de autoridade de certificação (CA) do Amazon RDS a fim deusar o shell mongo para se conectar, conforme indicado a seguir.


2. Transferir dados da amostra — Para este tutorial, irá transferir alguns dados de amostra que contêminformações sobre restaurantes.

wget https://raw.githubusercontent.com/ozlerhakan/mongodb-json-files/master/datasets/restaurant.json

3. Importar os dados da amostra para Amazon DocumentDB — Uma vez que os dados se encontramnum formato JSON lógico, irá utilizar o mongoimport para importar os dados para o seu AmazonDocumentDB grupo.

mongoimport --ssl \ --host="tutorialCluster.amazonaws.com:27017" \ --collection=restaurants \ --db=business \ --file=restaurant.json \ --numInsertionWorkers 4 \ --username=<yourUsername> \ --password=<yourPassword> \ --sslCAFile rds-combined-ca-bundle.pem

4. Eliminar os dados com mongodump — Agora que tem dados no seu Amazon DocumentDB , podetirar uma descarga binária desses dados utilizando o mongodump utilidade.

mongodump --ssl \ --host="tutorialCluster.us-east-1.docdb.amazonaws.com:27017"\ --collection=restaurants \ --db=business \ --out=restaurantDump.bson \ --numParallelCollections 4 \ --username=<yourUsername> \ --password=<yourPassword> \ --sslCAFile rds-combined-ca-bundle.pem

5. Largue o restaurants coleção — Antes de restaurar o restaurants recolha no business basede dados, tem de primeiro largar a coleção que já existe nessa base de dados, como se segue.

use business

db.restaurants.drop()

6. Restaurar os dados com mongorestore — Com o esvaziamento binário dos dados do Passo 3, podeagora utilizar o mongorestore para restaurar os seus dados Amazon DocumentDB grupo.

mongorestore --ssl \ --host="tutorialCluster.us-east-1.docdb.amazonaws.com:27017" \ --numParallelCollections 4 \ --username=<yourUsername> \ --password=<yourPassword> \ --sslCAFile rds-combined-ca-bundle.pem restaurantDump.bson

180

Amazon DocumentDB Guia do desenvolvedorConsiderações sobre snapshot de cluster

7. Exportar os dados utilizando mongoexport — Para concluir o tutorial, exporte os dados do seu grupono formato de um ficheiro JSON, não diferente do ficheiro que importou no Passo 1.

mongoexport --ssl \ --host="tutorialCluster.node.us-east-1.docdb.amazonaws.com:27017" \ --collection=restaurants \ --db=business \ --out=restaurant2.json \ --username=<yourUsername> \ --password=<yourPassword> \ --sslCAFile rds-combined-ca-bundle.pem

8. Validação — Pode validar que a saída do Passo 5 produz o mesmo resultado do Passo 1 com oscomandos seguintes.

wc -l restaurant.json

Saída desse comando:

2548 restaurant.json

wc -l restaurant2.json

Saída desse comando:

2548 restaurant2.json

Considerações sobre snapshot de clusterAmazon DocumentDB cria instantâneos automáticos diários do seu grupo durante a janela de cópia desegurança do seu grupo. Amazon DocumentDB guarda as capturas automáticas do seu grupo de acordocom o período de retenção de cópia de segurança que especificar. Se necessário, você poderá recuperarseu cluster para qualquer momento determinado durante o período de retenção de backup. Os snapshotsautomáticos não são obtidos enquanto uma operação de cópia está sendo executada na mesma regiãopara o mesmo cluster.

Além de snapshots automáticos de cluster, você também pode criar manualmente um snapshot decluster. É possível copiar os snapshots automáticos e manuais. Para mais informações, consulteCriação de um snapshot manual de cluster (p. 184) e Copiar Amazon DocumentDB Instantâneos deaglomerados (p. 186).

Note

O seu grupo tem de estar no disponível estado para um instantâneo automático a ser tomado.Não pode partilhar um Amazon DocumentDB instantâneo de cluster automatizado. Comoalternativa, crie um snapshot manual copiando o snapshot automatizado e compartilhe essacópia. Para obter mais informações sobre como copiar um snapshot, consulte Copiar AmazonDocumentDB Instantâneos de aglomerados (p. 186). Para obter mais informações sobre arestauração de um cluster com base em um snapshot, consulte Restauração de um snapshot decluster (p. 196).

Armazenamento de backupO armazenamento de backup do Amazon DocumentDB para cada região da AWS é composto peloarmazenamento de backup necessário para o período de retenção de backup, que inclui snapshots

181

Amazon DocumentDB Guia do desenvolvedorJanela de backup

de cluster automáticos e manuais nessa região. O período de retenção de backup padrão é de 1 dia.Para mais informações sobre o preço de armazenamento de cópias de segurança, consulte AmazonDocumentDB Preços.

Quando você exclui um cluster, todos os seus snapshots automáticos são excluídos e não podem serrecuperados. No entanto, os snapshots manuais não são excluídos quando você exclui um cluster.Se preferir que o Amazon DocumentDB crie um snapshot final (snapshot manual) antes do cluster serexcluído, poderá usar o snapshot final para recuperar o cluster.

Para obter mais informações sobre snapshots e armazenamento, consulte Noções básicas do uso doarmazenamento de backup (p. 176).

Janela de backupOs snapshots automáticos são obtidos diariamente durante a janela de backup escolhida. Se o snapshotexigir mais tempo do que o atribuído à janela de backup, o processo de backup continuará até que sejaconcluído, mesmo que a janela de backup tenha terminado. A janela de backup não pode se sobrepor àjanela de manutenção semanal do cluster.

Se você não especificar uma janela de backup preferencial ao criar o cluster, o Amazon DocumentDBatribuirá uma janela de backup de 30 minutos padrão. Essa janela é escolhida aleatoriamente deum bloco de tempo de 8 horas associado à região do cluster. Você pode alterar a janela de backuppreferencial modificando o cluster. Para obter mais informações, consulte Modificar um cluster do AmazonDocumentDB (p. 231).

Região Bloco de tempo UTC

Leste dos EUA (Ohio) 03:00-11:00

Leste dos EUA (Norte da Virgínia) 03:00-11:00

Oeste dos EUA (Oregon) 06:00-14:00

Ásia Pacífico (Mumbai) 17:30-01:30

Ásia-Pacífico (Seul) 13:00-21:00

Ásia-Pacífico (Cingapura) 14:00-22:00

Ásia-Pacífico (Sydney) 12:00–20:00

Ásia-Pacífico (Tóquio) 13:00-21:00

Canadá (Central) 22:00-06:00

Europa (Frankfurt) 23:00-07:00

Europa (Irlanda) 22:00-06:00

Europa (Paris) 22:00-06:00

AWS GovCloud (US) 22:00-06:00

Backup Retention PeriodO período de retenção de cópia de segurança é o número de dias em que uma cópia de segurançaautomática é retida antes de ser automaticamente eliminada. Amazon DocumentDB suporta um período deretenção de cópia de segurança de 1–35 dias.

182



Amazon DocumentDB Guia do desenvolvedorComparação dos snapshots automáticos e manuais

Você pode definir o período de retenção de backup ao criar um cluster. Se você não definir explicitamenteo período de retenção de backup, o período de retenção de backup padrão de 1 dia será atribuído aocluster. Depois de criar um cluster, é possível modificar o período de retenção de backup modificandoo cluster usando o Console de gerenciamento da AWS ou a AWS CLI. Para obter mais informações,consulte Modificar um cluster do Amazon DocumentDB (p. 231).

Comparação dos snapshots automáticos e manuaisAs seguintes são características fundamentais de Amazon DocumentDB (compatível com MongoDB)instantâneos automáticos e manuais.

Amazon DocumentDBOs snapshots automáticos do têm os recursos principais a seguir:

• Nome de captura automática automático — Os nomes de instantâneos automáticos seguem o padrãords:<cluster-name>-yyyy-mm-dd-hh-mm, com yyyy-mm-dd-hh-mm representando a data e ahora em que o instantâneo foi criado.

• Criado automaticamente num horário — Quando criar ou modificar um grupo, pode definir o períodode retenção de cópia de segurança para um valor inteiro de 1 a 35 dias. Por padrão, os novos clusterstêm um período de retenção de backup de 1 dia. O período de retenção de backup define o número dedias que os snapshots automáticos são mantidos antes de serem excluídos automaticamente. Não podedesativar cópias de segurança automáticas em Amazon DocumentDB grupos.

Além de definir o período de retenção de cópia de segurança, também definiu o janela de cópia desegurança, a hora do dia durante o qual são criados capturas automáticas.

• Eliminar instantâneos automáticos — As capturas automáticas são eliminadas quando eliminar o grupode instantâneos automático. Não é possível excluir manualmente um snapshot automático.

• Incremental — Durante o período de retenção de cópias de segurança, as atualizações da base dedados são registadas para que haja um registo incremental das alterações.

• Restaurar a partir de um instantâneo automático — Pode restaurar a partir de um instantâneoautomático utilizando o Console de gerenciamento da AWS ou o AWS CLI. Quando recuperar deum instantâneo utilizando o AWS CLI, tem de adicionar instâncias separadamente após o grupo serdisponível.

• Partilhar — Não pode partilhar um Amazon DocumentDB instantâneo de cluster automatizado. Comoalternativa, crie um snapshot manual copiando o snapshot automatizado e compartilhe essa cópia.Para obter mais informações sobre como copiar um snapshot, consulte Copiar Amazon DocumentDBInstantâneos de aglomerados (p. 186). Para obter mais informações sobre a restauração de um clustercom base em um snapshot, consulte Restauração de um snapshot de cluster (p. 196).

• Pode restaurar a partir de qualquer ponto dentro do período de retenção de cópia de segurança — Umavez que as atualizações da base de dados são incrementalmente registadas, pode restaurar o seu grupoa qualquer momento dentro do período de retenção de cópia de segurança.

Quando restaura a partir de um instantâneo automático ou de uma recuperação pontual utilizando oAWS CLI, tem de adicionar instâncias separadamente após o grupo ser disponível.

Amazon DocumentDBOs snapshots manuais do têm os recursos principais a seguir:

• Criado a pedido — Amazon DocumentDB são criadas capturas manuais mediante pedido utilizando oAmazon DocumentDB Consola de Gestão ou AWS CLI.

• Eliminar um instantâneo manual —Um instantâneo manual só é eliminado quando apagá-loexplicitamente utilizando o Amazon DocumentDB consola ou AWS CLI. Um snapshot manual não éexcluído quando você exclui o cluster.

• Cópias de segurança completas — Quando é efectuada uma captura manual, é criada e armazenadauma cópia de segurança completa dos dados do seu cluster.

183

Amazon DocumentDB Guia do desenvolvedorCriação de um snapshot manual de cluster

• Nome do instantâneo manual — Especifique o nome do instantâneo manual. Amazon DocumentDB nãoadiciona um datetime para o nome, por isso, tem de adicionar essa informação se desejar que o nomeseja incluído no nome.

• Restaurar a partir de um instantâneo manual —Pode restaurar a partir de um instantâneo manualutilizando a consola ou o AWS CLI. Quando recuperar de um instantâneo utilizando o AWS CLI, tem deadicionar instâncias separadamente após o grupo ser disponível.

• Quotas de serviço — Está limitado a um máximo de 100 instantâneos manuais por região AWS.• Partilhar — Pode partilhar instantâneos de cluster manuais, que podem ser copiados por contas

AWS autorizadas. É possível compartilhar snapshots manuais criptografados ou não criptografados.Para obter mais informações sobre como copiar um snapshot, consulte Copiar Amazon DocumentDBInstantâneos de aglomerados (p. 186).

• Restaura para quando o instantâneo manual foi tomado —Quando restaura a partir de um instantâneomanual, restaura para quando o instantâneo manual foi tomado.

Quando recuperar de um instantâneo utilizando o AWS CLI, tem de adicionar instâncias separadamenteapós o grupo ser disponível.

Criação de um snapshot manual de clusterVocê pode criar um snapshot manual usando o Console de gerenciamento da AWS ou a AWS CLI.O tempo necessário para criar um snapshot varia com o tamanho dos bancos de dados. Ao criar umsnapshot, faça o seguinte:

1. Identifique o cluster para fazer backup.2. Atribua um nome ao snapshot. Isso permite que faça restaurações a partir dele mais tarde.

Criar um snapshot de cluster usando a Console degerenciamento da AWSPara criar um snapshot manual usando o Console de gerenciamento da AWS, siga qualquer um dosmétodos abaixo.

1. Método 1:


2. No painel de navegação, escolha Instantâneos.Tip


3. No Instantâneos página, escolher Criar.4. No Criar instantâneo de cluster página:

a. Identificador de cluster — A partir da lista pendente de clusters, escolha o grupo que pretendecriar um instantâneo de.

b. Identificador do instantâneo — Introduza um nome para o seu instantâneo.

Restrições de nomenclatura do snapshot:• O comprimento é de [1–63] letras, números ou hifens.• O primeiro caractere deve ser uma letra.

184


Amazon DocumentDB Guia do desenvolvedorCriar um snapshot de cluster usando a AWS CLI

• Não podem terminar com um hífen ou conter dois hífens consecutivos• Deve ser único para todos os clusters (em Amazon RDS, Amazon Neptune, e Amazon

DocumentDB) por AWS conta, por Região.c. Escolher Criar.

2. Método 2:


2. No painel de navegação, escolha Clusters.

Tip


3. No Clusters , escolha o botão à esquerda do grupo que pretende capturar.4. Desde o Ações menu, escolha Tirar instantâneo.5. No Criar instantâneo de cluster página:

a. Identificador do instantâneo — Introduza um nome para o seu instantâneo.

Restrições de nomenclatura do snapshot:• O comprimento é de [1–63] letras, números ou hifens.• O primeiro caractere deve ser uma letra.• Não podem terminar com um hífen ou conter dois hífens consecutivos• Deve ser único para todos os clusters (em Amazon RDS, Amazon Neptune, e Amazon

DocumentDB) por AWS conta, por Região.b. Escolher Criar.

Criar um snapshot de cluster usando a AWS CLIPara criar um instantâneo de cluster utilizando o AWS CLI, utilize o create-db-cluster-snapshotcom os seguintes parâmetros.

Parameters

• --db-cluster-identifier — Obrigatório. O nome do cluster do qual você está tirando umsnapshot. Este grupo tem de existir e ser disponível.

• --db-cluster-snapshot-identifier — Obrigatório. O nome do snapshot manual que você estácriando.

O exemplo a seguir cria um snapshot chamado sample-cluster-snapshot para um cluster chamadosample-cluster.


aws docdb create-db-cluster-snapshot \ --db-cluster-identifier sample-cluster \ --db-cluster-snapshot-identifier sample-cluster-snapshot

Para Windows:

aws docdb create-db-cluster-snapshot ^

185


Amazon DocumentDB Guia do desenvolvedorCópia de um snapshot de cluster

--db-cluster-identifier sample-cluster ^ --db-cluster-snapshot-identifier sample-cluster-snapshot


{ "DBClusterSnapshot": { "AvailabilityZones": [ "us-east-1a", "us-east-1b", "us-east-1c" ], "DBClusterSnapshotIdentifier": "sample-cluster-snapshot", "DBClusterIdentifier": "sample-cluster", "SnapshotCreateTime": "2020-04-24T04:59:08.475Z", "Engine": "docdb", "Status": "creating", "Port": 0, "VpcId": "vpc-abc0123", "ClusterCreateTime": "2020-01-10T22:13:38.261Z", "MasterUsername": "master-user", "EngineVersion": "3.6.0", "SnapshotType": "manual", "PercentProgress": 0, "StorageEncrypted": true, "KmsKeyId": "arn:aws:kms:us-east-1:<accountID>:key/sample-key", "DBClusterSnapshotArn": "arn:aws:rds:us-east-1:<accountID>:cluster-snapshot:sample-cluster-snapshot" }}

Copiar Amazon DocumentDB Instantâneos deaglomerados

Em Amazon DocumentDB, pode copiar capturas manuais e automáticas na mesma região AWS ou parauma região AWS diferente na mesma conta. Também pode partilhar instantâneos detidos por outrascontas AWS na mesma região AWS. No entanto, não é possível copiar um instantâneo de grupo entre ascontas AWS Regiões e AWS num único passo. Estas acções têm de ser realizadas individualmente.

Como alternativa à cópia, você também pode compartilhar snapshots manuais com outras contasda AWS. Para obter mais informações, consulte Partilhar Amazon DocumentDB Instantâneos deaglomerados (p. 192).

Note

Amazon DocumentDB As faturas com base na quantidade de dados de cópia de segurança einstantâneos que guarda e no período de tempo que o guarda. Para mais informações sobre oarmazenamento associado a Amazon DocumentDB cópias de segurança e capturas de ecrã,consulte Noções básicas do uso do armazenamento de backup (p. 176). Para informaçõessobre o preço sobre Amazon DocumentDB armazenamento, consulte Amazon DocumentDBPreços.

Tópicos• Copiar snapshots compartilhados (p. 187)• Cópia de snapshots entre regiões da AWS (p. 187)• Limitações: (p. 187)

186



Amazon DocumentDB Guia do desenvolvedorCopiar snapshots compartilhados

• Lidar com a criptografia (p. 187)• Considerações sobre o grupo de parâmetros (p. 188)• Cópia de um snapshot de cluster (p. 188)

Copiar snapshots compartilhadosVocê pode copiar snapshots compartilhados com você por outras contas da AWS. Se estiver copiando umsnapshot criptografado que tenha sido compartilhado de outra conta da AWS, você deverá ter acesso àchave de criptografia do AWS KMS usada para criptografar o snapshot.

Só pode copiar um instantâneo partilhado na mesma região AWS, quer o instantâneo esteja encriptado ounão. Para obter mais informações, consulte the section called “ Lidar com a criptografia” (p. 187).

Cópia de snapshots entre regiões da AWSQuando copiar um instantâneo para uma região AWS diferente da região AWS do instantâneo da fonte,cada cópia é um instantâneo completo. Uma cópia completa contém todos os dados e metadadosnecessários para restaurar o Amazon DocumentDB grupo.

Dependendo das regiões da AWS envolvidas e da quantidade de dados a serem copiados, uma cópiade snapshot entre regiões pode levar horas para ser concluída. Em alguns casos, pode haver um grandenúmero de solicitações de cópia de snapshot entre regiões de uma determinada região da AWS de origem.Nesses casos, o Amazon DocumentDB pode colocar novas solicitações de cópia entre regiões daquelaregião da AWS de origem em uma fila até que algumas cópias em andamento sejam concluídas. Nenhumainformação de progresso é exibida sobre solicitações de cópia enquanto elas estão na fila. As informaçõesde progresso são exibidas quando a cópia é iniciada.

Limitações:As seguintes são algumas limitações quando você copia snapshots:

• Se você excluir um snapshot de origem antes que o snapshot de destino fique disponível, a cópia dosnapshot poderá falhar. Verifique se o snapshot de destino possui um status AVAILABLE antes deexcluir um snapshot de origem.

• Você pode ter até cinco solicitações de cópia de snapshot em andamento para uma única região dedestino por conta.

• Dependendo das regiões envolvidas e da quantidade de dados a serem copiados, uma cópia desnapshot entre regiões pode levar horas para ser concluída. Para obter mais informações, consulteCópia de snapshots entre regiões da AWS (p. 187).

Lidar com a criptografiaPode copiar um instantâneo que tenha sido encriptado utilizando um AWS KMS chave de encriptação.Se você copiar um snapshot criptografado, a cópia desse snapshot também deverá ser criptografada. Secopiar um instantâneo encriptado na mesma região AWS, pode encriptar a cópia com o mesmo AWS KMSchave de encriptação como instantâneo original, ou pode especificar um AWS KMS chave de encriptação.Se copiar um instantâneo encriptado entre Regiões, não pode utilizar a mesma chave de encriptação KMSpara a cópia como utilizada para o instantâneo de origem, porque AWS KMS são específicas da região.Em vez disso, tem de especificar um AWS KMS chave válida na região AWS de destino.

O snapshot de origem permanece criptografado ao longo do processo de cópia. Para obter maisinformações, consulte Proteção de dados no Amazon DocumentDB (p. 118).

187

Amazon DocumentDB Guia do desenvolvedorConsiderações sobre o grupo de parâmetros

Note

Para Amazon DocumentDB instantâneos de aglomerados, não pode encriptar um instantâneo decluster não encriptado quando copiar o instantâneo.

Considerações sobre o grupo de parâmetrosQuando copiar um instantâneo em Regiões, a cópia não inclui o grupo de parâmetros utilizado pelo originalAmazon DocumentDB grupo. Quando restaura um instantâneo para criar um novo grupo, esse grupoobtém o grupo de parâmetros predefinido para a região AWS, sendo criado em. Para dar ao novo grupo osmesmos parâmetros que o original, tem de fazer o seguinte:

1. Na região de destino AWS, criar um Amazon DocumentDB grupo de parâmetros de grupo com asmesmas definições do grupo original. Se um já existir na nova Região da AWS, você pode usá-lo.

2. Depois de restaurar o instantâneo na região AWS de destino, modifique o novo Amazon DocumentDBcluster e adicione o grupo de parâmetros novo ou existente a partir do passo anterior. Para obter maisinformações, consulte Modificar um cluster do Amazon DocumentDB (p. 231).

Cópia de um snapshot de clusterPode copiar um Amazon DocumentDB cluster utilizando o Console de gerenciamento da AWS ou o AWSCLI, como se segue.

Copiar um snapshot de cluster usando o Console de gerenciamento da AWS

Para fazer uma cópia de um instantâneo de cluster utilizando o Console de gerenciamento da AWS,complete os seguintes passos. Este procedimento funciona para copiar instantâneos de cluster encriptadosou não encriptados, na mesma região AWS ou em regiões.


2. No painel de navegação, escolha Instantâneos, e depois escolha o botão à esquerda do instantâneoque pretende copiar.

Tip

Se você não visualizar o painel de navegação à esquerda da tela, selecione o ícone do menu( ) no cantosuperior esquerdo da página.

3. Desde o Ações menu, escolha Copiar.4. No resultado Fazer cópia do instantâneo do cluster , preencha o Definições secção.

a. Região de destino — Opcional. Para copiar o instantâneo do cluster para uma região AWSdiferente, escolha essa região AWS para Região de destino.

b. Novo identificador de instantâneo — Introduza um nome para o novo instantâneo.

Restrições de nomenclatura do snapshot de destino:

• Não pode ser o nome de um snapshot existente.• O comprimento é de [1—63] letras, números ou hifens.• O primeiro caractere deve ser uma letra.• Não podem terminar com um hífen ou conter dois hífens consecutivos• Tem de ser único para todos os grupos em Amazon RDS, Neptune, e Amazon DocumentDB

por conta AWS, por Região.

188

https://docs.aws.amazon.com/documentdb/latest/developerguide/cluster_parameter_groups-create.html



c. Copiar etiquetas — Para copiar quaisquer etiquetas que tenha no instantâneo de origem para asua cópia de instantâneo, escolha Copiar etiquetas.

5. Concluir o Encriptação em repouso secção.

a. Encriptação em repouso — Se o seu instantâneo estiver encriptado, estas opções não estãodisponíveis porque não pode criar uma cópia não encriptada de um instantâneo encriptado. Se osnapshot não estiver criptografado, escolha uma das seguintes ações:

• Para encriptar todos os dados do seu cluster, escolha Ativar encriptação em repouso. Seescolher esta opção, tem de designar uma Chave principal.

• Para não encriptar os dados do seu cluster, escolha Desativar encriptação em repouso. Sevocê escolher essa opção, os dados copiados do snapshot não serão criptografados e a seçãode criptografia estará concluída.

b. Chave principal — Na lista pendente, escolha uma das seguintes opções:

• (predefinição) aws/rds — O número de conta e AWS KMS a ID de chave está listada a seguir àseguinte opção.

• <nome-chave> — Se criou uma chave, está listada e disponível para escolher.• Introduzir um chave de ARN — No ARN , introduza o Nome do Recurso Amazon (ARN) para o

seu AWS KMS chave. O formato do ARN é arn:aws:kms:<region>:<accountID>:key/<key-id> .

6. Para fazer uma cópia do instantâneo selecionado, escolha Copiar instantâneo. Em alternativa, podeescolher Cancelar para não fazer uma cópia do instantâneo.

Copiar um Instantâneo de Cluster Não Encriptado Utilizando o AWS CLI

Para fazer uma cópia de um instantâneo de cluster não encriptado utilizando o AWS CLI, utilize o copy-db-cluster-snapshot com os seguintes parâmetros. Se você estiver copiando o snapshot para outraRegião da AWS, execute o comando na Região da AWS para a qual o snapshot será copiado.

• --source-db-cluster-snapshot-identifier — Obrigatório. O identificador do snapshot decluster a ser copiado. O instantâneo do cluster deve existir e estar no disponível estado. Se estiver acopiar o instantâneo para outra região AWS, este identificador tem de estar no formato ARN para aregião AWS de origem. Esse parâmetro não diferencia maiúsculas de minúsculas.

• --target-db-cluster-snapshot-identifier — Obrigatório. O identificador do novo snapshot decluster a ser criado a partir do snapshot de cluster de origem. Esse parâmetro não diferencia maiúsculasde minúsculas.

Restrições de nomenclatura do snapshot de destino:• Não pode ser o nome de um snapshot existente.• O comprimento é de [1—63] letras, números ou hifens.• O primeiro caractere deve ser uma letra.• Não podem terminar com um hífen ou conter dois hífens consecutivos• Tem de ser único para todos os grupos em Amazon RDS, Neptune, e Amazon DocumentDB por conta

AWS, por Região.• --source-region — Se estiver a copiar o instantâneo para outra região AWS, especifique a região

AWS que o instantâneo do cluster encriptado será copiado de.

Se estiver a copiar o instantâneo para outra região AWS e não especificar --source-region, temde especificar o pre-signed-url opção em vez de. O pre-signed-url valor tem de ser um URLque contém um pedido assinado de Assinatura Versão 4 para CopyDBClusterSnapshot ação a serchamada na região AWS da fonte onde o instantâneo do cluster é copiado de. Para saber mais sobre opre-signed-url, consulte copydbclustersnapshot.

189

https://docs.aws.amazon.com/documentdb/latest/developerguide/API_CopyDBClusterSnapshot.html


• --kms-key-id — O identificador de chave KMS para a chave a utilizar para encriptar a cópia doinstantâneo do cluster.

Se estiver a copiar um instantâneo de cluster encriptado para outra região AWS, este parâmetro éobrigatório. Tem de especificar uma tecla KMS para a região AWS de destino.

Se estiver a copiar um instantâneo de cluster encriptado na mesma região AWS, o parâmetro de chaveKMS é opcional. A cópia do instantâneo do cluster é encriptada com a mesma chave KMS que oinstantâneo do cluster de origem. Se pretender especificar uma nova chave de encriptação KMS parautilizar para encriptar a cópia, pode fazê-lo utilizando este parâmetro.

• --copy-tags — Optional. The tags and values to be copied over.

Para cancelar uma operação de cópia quando estiver em curso, pode eliminar o instantâneodo conjunto de alvos identificado por --target-db-cluster-snapshot-identifier ouTargetDBClusterSnapshotIdentifier enquanto o instantâneo do grupo está em copiar estado.

Example

Exemplo: = 1. Copiar um instantâneo não encriptado para a mesma Região

O seguinte AWS CLI exemplo cria uma cópia de sample-cluster-snapshot nomeado sample-cluster-snapshot-copy na mesma região AWS como o instantâneo de origem. Quando a cópia éfeita, todas as tags do snapshot original são copiadas para a cópia do snapshot.


aws docdb copy-db-cluster-snapshot \ --source-db-cluster-snapshot-identifier sample-cluster-snapshot \ --target-db-cluster-snapshot-identifier sample-cluster-snapshot-copy \ --copy-tags

Para Windows:

aws docdb copy-db-cluster-snapshot ^ --source-db-cluster-snapshot-identifier sample-cluster-snapshot ^ --target-db-cluster-snapshot-identifier sample-cluster-snapshot-copy ^ --copy-tags


{ "DBClusterSnapshot": { "AvailabilityZones": [ "us-east-1a", "us-east-1b", "us-east-1c" ], "DBClusterSnapshotIdentifier": "sample-cluster-snapshot-copy", "DBClusterIdentifier": "sample-cluster", "SnapshotCreateTime": "2020-03-27T08:40:24.805Z", "Engine": "docdb", "Status": "copying", "Port": 0, "VpcId": "vpc-abcd0123", "ClusterCreateTime": "2020-01-10T22:13:38.261Z", "MasterUsername": "master-user", "EngineVersion": "3.6.0", "SnapshotType": "manual", "PercentProgress": 0, "StorageEncrypted": true,

190


"KmsKeyId": "arn:aws:kms:us-east-1:111122223333:key/sample-key-id", "DBClusterSnapshotArn": "arn:aws:rds:us-east-1:111122223333:cluster-snapshot:sample-cluster-snapshot-copy", "SourceDBClusterSnapshotArn": "arn:aws:rds:us-east-1:111122223333:cluster-snapshot:sample-cluster-snapshot" }}

Example

Exemplo: = 2. Copiar um instantâneo não encriptado entre regiões AWS

O seguinte AWS CLI exemplo cria uma cópia de sample-cluster-snapshot, que tem o ARNarn:aws:rds:us-east-1:123456789012:cluster-snapshot:sample-cluster-snapshot.Esta cópia é nomeada como nome sample-cluster-snapshot-copy e está na região AWS na qual ocomando é executado.


aws docdb copy-db-cluster-snapshot \ --source-db-cluster-snapshot-identifier arn:aws:rds:us-east-1:123456789012:cluster-snapshot:sample-cluster-snapshot \ --target-db-cluster-snapshot-identifier sample-cluster-snapshot-copy

Para Windows:

aws docdb copy-db-cluster-snapshot ^ --source-db-cluster-snapshot-identifier arn:aws:rds:us-east-1:123456789012:cluster-snapshot:sample-cluster-snapshot ^ --target-db-cluster-snapshot-identifier sample-cluster-snapshot-copy


{ "DBClusterSnapshot": { "AvailabilityZones": [ "us-east-1a", "us-east-1b", "us-east-1c" ], "DBClusterSnapshotIdentifier": "sample-cluster-snapshot-copy", "DBClusterIdentifier": "sample-cluster", "SnapshotCreateTime": "2020-04-29T16:45:51.239Z", "Engine": "docdb", "AllocatedStorage": 0, "Status": "copying", "Port": 0, "VpcId": "vpc-abc0123", "ClusterCreateTime": "2020-04-28T16:43:00.294Z", "MasterUsername": "master-user", "EngineVersion": "3.6.0", "LicenseModel": "docdb", "SnapshotType": "manual", "PercentProgress": 0, "StorageEncrypted": false, "DBClusterSnapshotArn": "arn:aws:rds:us-east-1:111122223333:cluster-snapshot:sample-cluster-snapshot-copy", "SourceDBClusterSnapshotArn": "arn:aws:rds:us-east-1:111122223333:cluster-snapshot:sample-cluster-snapshot", }}

191

Amazon DocumentDB Guia do desenvolvedorCompartilhamento de um snapshot de cluster

Example

Exemplo 3 Copiar um instantâneo encriptado entre regiões AWS

O seguinte AWS CLI exemplo cria uma cópia de sample-cluster-snapshot da região de us-west-2para a região de 1.ª-região. Este comando é denominado na região de us-1-1.


aws docdb copy-db-cluster-snapshot \ --source-db-cluster-snapshot-identifier arn:aws:rds:us-west-2:123456789012:cluster-snapshot:sample-cluster-snapshot \ --target-db-cluster-snapshot-identifier sample-cluster-snapshot-copy \ --source-region us-west-2 \ --kms-key-id sample-us-east-1-key

Para Windows:

aws docdb copy-db-cluster-snapshot ^ --source-db-cluster-snapshot-identifier arn:aws:rds:us-west-2:123456789012:cluster-snapshot:sample-cluster-snapshot ^ --target-db-cluster-snapshot-identifier sample-cluster-snapshot-copy ^ --source-region us-west-2 ^ --kms-key-id sample-us-east-1-key


{ "DBClusterSnapshot": { "AvailabilityZones": [], "DBClusterSnapshotIdentifier": "sample-cluster-snapshot-copy", "DBClusterIdentifier": "ayhu-xrsc-test-ap-southeast-1-small-cluster-kms", "SnapshotCreateTime": "2020-04-29T16:45:53.159Z", "Engine": "docdb", "AllocatedStorage": 0, "Status": "copying", "Port": 0, "ClusterCreateTime": "2020-04-28T16:43:07.129Z", "MasterUsername": "chimera", "EngineVersion": "3.6.0", "LicenseModel": "docdb", "SnapshotType": "manual", "PercentProgress": 0, "StorageEncrypted": true, "KmsKeyId": "arn:aws:kms:us-east-1:111122223333:key/sample-key-id", "DBClusterSnapshotArn": "arn:aws:rds:us-east-1:111122223333:cluster-snapshot:sample-cluster-snapshot-copy", "SourceDBClusterSnapshotArn": "arn:aws:rds:us-west-2:111122223333:cluster-snapshot:sample-cluster-snapshot", }}

Partilhar Amazon DocumentDB Instantâneos deaglomerados

No Amazon DocumentDB, é possível compartilhar snapshots manuais de cluster, que podem ser copiadospor contas autorizadas da AWS. É possível compartilhar snapshots manuais criptografados ou não

192

Amazon DocumentDB Guia do desenvolvedorCompartilhamento de um snapshot criptografado

criptografados. Ao compartilhar um snapshot não criptografado, as contas autorizadas da AWS podemrestaurar o cluster diretamente do snapshot em vez de fazer uma cópia dele e fazer a restauração a partirdaí. No entanto, não é possível restaurar um cluster a partir de um snapshot que seja compartilhado ecriptografado. Em vez disso, é possível fazer uma cópia do cluster e restaurar o cluster dessa cópia.Para obter mais informações sobre como copiar um snapshot, consulte Copiar Amazon DocumentDBInstantâneos de aglomerados (p. 186).

Note

Não pode partilhar um Amazon DocumentDB instantâneo de cluster automatizado. Comoalternativa, crie um snapshot manual copiando o snapshot automatizado e compartilhe essacópia. Para obter mais informações sobre como copiar um snapshot, consulte Copiar AmazonDocumentDB Instantâneos de aglomerados (p. 186). Para obter mais informações sobre arestauração de um cluster com base em um snapshot, consulte Restauração de um snapshot decluster (p. 196).

Você pode compartilhar um snapshot manual com até 20 outras contas da AWS. Também é possívelcompartilhar um snapshot manual não criptografado como público, disponibilizando-o para todas ascontas. Ao compartilhar um snapshot como público, verifique se as informações privadas não estãoincluídas nos snapshots públicos.

Ao partilhar capturas manuais com outras contas AWS, e restaurar um grupo de um instantâneo partilhadoutilizando o AWS CLI ou o Amazon DocumentDB API, tem de especificar o Nome do Recurso Amazon(ARN) do instantâneo partilhado como identificador de instantâneo.

Compartilhamento de um snapshot criptografadoAs seguintes restrições se aplicam ao compartilhamento de snapshots criptografados:

• Não é possível compartilhar snapshots criptografados como públicos.• Não é possível compartilhar um snapshot que foi criptografado usando a chave de criptografia padrão do

AWS KMS da conta que compartilhou o snapshot.

Siga estas etapas para compartilhar snapshots criptografados.

1. Partilhar o AWS Key Management Service (AWS KMS) chave de encriptação utilizada para encriptar oinstantâneo com quaisquer contas que pretenda que possam aceder ao instantâneo.

Pode partilhar AWS KMS chaves de encriptação com outras contas AWS adicionando as outrascontas ao AWS KMS política chave. Para mais detalhes sobre a atualização de uma política-chave,consulte Utilizar políticas-chave no AWS KMS no AWS Key Management Service Developer Guide.Para ver um exemplo de como criar uma política de chaves, consulte Criação de uma política do IAMpara permitir a cópia do snapshot criptografado (p. 194), mais adiante neste tópico.

2. Utilize o AWS CLI, conforme mostrado abaixo (p. 195), para partilhar o instantâneo encriptado comas outras contas.

Permitir acesso a um AWS KMS Chave de EncriptaçãoPara que outra conta da AWS possa copiar um snapshot criptografado compartilhado a partir de suaconta, a conta com a qual você compartilha seu snapshot deverá ter acesso à chave do AWS KMS quecriptografou o snapshot. Para permitir o acesso de outra conta a um AWS KMS chave, atualize a política-chave para o AWS KMS chave com o ARN da conta em que está a partilhar como principal na AWS KMSpolítica chave. Depois, permita que kms:CreateGrant ação.

Depois de dar um acesso à conta ao seu AWS KMS chave de encriptação, para copiar o seu instantâneoencriptado, essa conta deve criar uma AWS Identity and Access Management (IAM) utilizador se ainda não

193

https://docs.aws.amazon.com/kms/latest/developerguide/key-policies.html

Amazon DocumentDB Guia do desenvolvedorCompartilhamento de um snapshot criptografado

tiver um. Além disso, essa conta também deve anexar um IAM da IAM utilizador que permite ao utilizadorcopiar um instantâneo encriptado utilizando o seu AWS KMS chave. A conta deve ser uma IAM utilizador enão pode ser uma identidade de conta AWS raiz devido a AWS KMS restrições de segurança.

No exemplo de política principal seguinte, o utilizador 123451234512 é o proprietário do AWS KMSchave de encriptação. O usuário 123456789012 é a conta com a qual a chave está sendo compartilhada.Esta política-chave atualizada dá ao acesso à conta AWS KMS chave. Faz isto, incluindo o ARN paraa identidade de conta da raiz AWS para o utilizador 123456789012 como principal para a política e aopermitir a kms:CreateGrant ação.

{ "Id": "key-policy-1", "Version": "2012-10-17", "Statement": [ { "Sid": "Allow use of the key", "Effect": "Allow", "Principal": {"AWS": [ "arn:aws:iam::123451234512:user/KeyUser", "arn:aws:iam::123456789012:root" ]}, "Action": [ "kms:CreateGrant", "kms:Encrypt", "kms:Decrypt", "kms:ReEncrypt*", "kms:GenerateDataKey*", "kms:DescribeKey" ], "Resource": "*"}, { "Sid": "Allow attachment of persistent resources", "Effect": "Allow", "Principal": {"AWS": [ "arn:aws:iam::123451234512:user/KeyUser", "arn:aws:iam::123456789012:root" ]}, "Action": [ "kms:CreateGrant", "kms:ListGrants", "kms:RevokeGrant" ], "Resource": "*", "Condition": {"Bool": {"kms:GrantIsForAWSResource": true}} } ]}

Criação de uma política do IAM para permitir a cópia do snapshotcriptografadoQuando a conta AWS externa tem acesso ao seu AWS KMS chave, o proprietário dessa conta pode criaruma política para permitir IAM utilizador criado para a conta copiar um instantâneo encriptado que estáencriptado com esse AWS KMS chave.

O exemplo a seguir mostra uma política que pode ser anexada a um usuário do IAM para a contada AWS 123456789012. A política permite o IAM utilizador para copiar um instantâneo partilhado daconta 123451234512 que foi encriptado com o AWS KMS chave c989c1dd-a3f2-4a5d-8d96-e793d082ab26 na região-oeste-2.

{

194

Amazon DocumentDB Guia do desenvolvedorCompartilhar um snapshot

"Version": "2012-10-17", "Statement": [ { "Sid": "AllowUseOfTheKey", "Effect": "Allow", "Action": [ "kms:Encrypt", "kms:Decrypt", "kms:ReEncrypt*", "kms:GenerateDataKey*", "kms:DescribeKey", "kms:CreateGrant", "kms:RetireGrant" ], "Resource": ["arn:aws:kms:us-west-2:123451234512:key/c989c1dd-a3f2-4a5d-8d96-e793d082ab26"] }, { "Sid": "AllowAttachmentOfPersistentResources", "Effect": "Allow", "Action": [ "kms:CreateGrant", "kms:ListGrants", "kms:RevokeGrant" ], "Resource": ["arn:aws:kms:us-west-2:123451234512:key/c989c1dd-a3f2-4a5d-8d96-e793d082ab26"], "Condition": { "Bool": { "kms:GrantIsForAWSResource": true } } } ]}

Para mais detalhes sobre a atualização de uma política-chave, consulte Utilizar políticas-chave em AWSKMS no AWS Key Management Service Developer Guide.

Compartilhar um snapshotPara partilhar um instantâneo, utilize o Amazon DocumentDB modify-db-snapshot-attributeoperação. Use o parâmetro --values-to-add para adicionar uma lista dos IDs das contas da AWSautorizadas a restaurar o snapshot manual.

O exemplo seguinte permite dois identificadores de conta AWS, 123451234512 e 123456789012, pararestaurar o instantâneo nomeado manual-snapshot1. Também remove o all valor do atributo paraassinalar o instantâneo como privado.


aws docdb modify-db-cluster-snapshot-attribute \ --db-cluster-snapshot-identifier sample-cluster-snapshot \ --attribute-name restore \ --values-to-add '["123451234512","123456789012"]'

Para Windows:

aws docdb modify-db-cluster-snapshot-attribute ^ --db-cluster-snapshot-identifier sample-cluster-snapshot ^ --attribute-name restore ^

195



Amazon DocumentDB Guia do desenvolvedorRestauração de um snapshot de cluster

--values-to-add '["123451234512","123456789012"]'


{ "DBClusterSnapshotAttributesResult": { "DBClusterSnapshotIdentifier": "sample-cluster-snapshot", "DBClusterSnapshotAttributes": [ { "AttributeName": "restore", "AttributeValues": [ "123451234512", "123456789012" ] } ] }}

Para remover um identificador de conta AWS da lista, utilize o --values-to-remove parâmetro. Oexemplo a seguir impede que o ID 123456789012 da conta da AWS restaure o snapshot.


aws docdb modify-db-cluster-snapshot-attribute \ --db-cluster-snapshot-identifier sample-cluster-snapshot \ --attribute-name restore \ --values-to-remove '["123456789012"]'

Para Windows:

aws docdb modify-db-cluster-snapshot-attribute ^ --db-cluster-snapshot-identifier sample-cluster-snapshot ^ --attribute-name restore ^ --values-to-remove '["123456789012"]'


{ "DBClusterSnapshotAttributesResult": { "DBClusterSnapshotIdentifier": "sample-cluster-snapshot", "DBClusterSnapshotAttributes": [ { "AttributeName": "restore", "AttributeValues": [ "123451234512" ] } ] }}

Restauração de um snapshot de clusterAmazon DocumentDB (compatível com MongoDB)O cria um snapshot de cluster de seu volume dearmazenamento. Você pode criar um novo cluster com a restauração de um snapshot de cluster. Ao

196

Amazon DocumentDB Guia do desenvolvedorRestaurar de um snapshot de cluster usando

a Console de gerenciamento da AWS

restaurar o cluster, você fornece o nome do snapshot do cluster do qual restaurar e um nome para o novocluster criado pela restauração. Não é possível restaurar de um snapshot para um cluster existente, poisum novo cluster é criado quando você restaura.

Quando você estiver restaurando um cluster a partir de um snapshot de cluster:

• Essa ação restaura apenas o cluster, e não as instâncias desse cluster. Tem de invocar o create-db-instance ação para criar instâncias para o grupo restaurado, especificando o identificador doconjunto restaurado em --db-cluster-identifier. Só pode criar instâncias depois de o grupo serdisponível.

• Você não pode restaurar um snapshot criptografado para um cluster descriptografado. No entanto, poderestaurar um instantâneo não encriptado para um grupo encriptado especificando o AWS KMS chave.

• Para restaurar um grupo de um instantâneo encriptado, tem de ter acesso ao AWS KMS chave.

Restaurar de um snapshot de cluster usando aConsole de gerenciamento da AWSO procedimento seguinte mostra como restaurar um Amazon DocumentDB cluster a partir de uminstantâneo de cluster utilizando o Amazon DocumentDB Consola de Gestão.


2. No painel de navegação, escolha Instantâneos, e depois seleccione o botão à esquerda doinstantâneo que pretende utilizar para restaurar um grupo.

Tip


3. No Ações menu, escolha Restaurar.4. No Restaurar instantâneo , preencha o Configuração secção.

a. Identificador de cluster — O nome do novo grupo. É possível aceitar o nome do AmazonDocumentDB fornecido ou digitar o nome que preferir. O Amazon DocumentDB o nome fornecidoestá no formato de docdb- além de um carimbo de hora UTC; por exemplo, docdb-yyyy-mm-dd-hh-mm-ss.

b. Classe de instância — A classe de instância para o novo grupo. É possível aceitar a classe deinstância padrão ou escolher uma classe de instância na lista suspensa.

c. Número de ocorrências — O número de ocorrências que pretende criar com este grupo. Épossível aceitar o padrão de 3 instâncias (1 réplica de leitura/gravação e 2 réplicas somenteleitura) ou escolher o número de instâncias na lista suspensa.

5. Se estiver satisfeito com a configuração do grupo, escolha Restaurar grupo e aguarde enquanto o seugrupo é restaurado.

6. Se preferir alterar algumas configurações, como especificar uma predefinição Amazon VPC ou grupode segurança, escolha Mostrar definições avançadas a partir do canto inferior esquerdo da página e,em seguida, continue com os passos seguintes.

a. Concluir o Definições de rede secção.

• Nuvem Privada Virtual (VPC) — Aceite o VPC atual ou escolha um VPC a partir da listapendente.

• Grupo Subnet — Aceitar o default grupo de sub-rede ou escolha uma na lista pendente.

197


Amazon DocumentDB Guia do desenvolvedorRestaurar de um snapshot de cluster usando a AWS CLI

• Grupos de segurança VPC — Aceitar o default (VPC) grupo de segurança ou escolha umada lista.

b. Concluir o Opções de cluster secção.

• Porta da base de dados — Aceitar a porta predefinida, 27017, ou utilize a seta para cima oupara baixo para definir a porta que pretende utilizar para as ligações da aplicação.

c. Concluir o Encriptação secção.

• Encriptação em repouso — Se o seu instantâneo estiver encriptado, estas opções não estãodisponíveis para si. Se não estiver criptografado, você pode escolher uma das seguintes ações:• Para encriptar todos os dados do seu cluster, escolha Ativar encriptação em repouso. Se

escolher esta opção, tem de designar uma Chave principal.• Para não encriptar os dados do seu cluster, escolha Desativar encriptação em repouso. Se

escolher essa opção, você concluiu a seção de criptografia.• Chave principal — Escolha uma das seguintes opções a partir da lista pendente:

• (predefinição) aws/rds — O número de conta e AWS KMS a ID de chave está listada a seguirà seguinte opção.

• Chave gerida pelo cliente — Esta opção só está disponível se criou um IAM chave deencriptação no AWS Identity and Access Management (IAM) consola. Você pode escolher achave para criptografar seu cluster.

• Introduzir um chave de ARN — No ARN , introduza o Nome do RecursoAmazon (ARN) para o seu AWS KMS chave. O formato do ARN éarn:aws:kms:<region>:<accountID>:key/<key-id>.

d. Concluir o Exportar exportações secção.

• Selecione os tipos de registo a publicar para CloudWatch — Escolha uma das seguintesopções:• Ativado — Permite ao seu grupo exportar o registo DML para Amazon CloudWatch Logs.• Desativado — Impede o seu grupo de exportar registos DML para Amazon CloudWatch Logs.

Desativado é a predefinição.• IAM função—Na lista, escolha Função ligada ao serviço RDS.

e. Concluir o Etiquetas secção.

• Adicionar etiqueta — No Chave , introduza o nome para a etiqueta do seu grupo. No Valor ,introduza opcionalmente o valor da etiqueta. As etiquetas são utilizadas com AWS Identity andAccess Management (IAM) políticas para gerir o acesso a Amazon DocumentDB recursos epara controlar que acções podem ser aplicadas aos recursos.

f. Concluir o Proteção contra eliminação secção.

• Ativar proteção de eliminação — Protege o grupo de ser eliminado acidentalmente. Quandoessa opção estiver habilitada, não será possível excluir o cluster.

7. Escolher Restaurar grupo.

Restaurar de um snapshot de cluster usando a AWSCLIPara restaurar um grupo de um instantâneo utilizando o AWS CLI, utilize o restore-db-cluster-from-snapshot com os seguintes parâmetros. Para obter mais informações, consulteRestoreDBClusterFromSnapshot (p. 521).

• --db-cluster-identifier — Obrigatório. O nome do cluster que é criado pela operação. Umcluster com este nome não pode existir antes dessa operação.

198


Restrições de nomeação de cluster:• O comprimento é de [1—63] letras, números ou hifens.• O primeiro caractere deve ser uma letra.• Não podem terminar com um hífen ou conter dois hífens consecutivos• Tem de ser único para todos os grupos em Amazon RDS, Neptune, e Amazon DocumentDB por conta

AWS, por Região.• --snapshot-identifier — Obrigatório. O nome do snapshot usado para restauração. Tem de existir

um instantâneo por este nome e estar no disponível estado.• --engine — Obrigatório. Deve ser docdb.• --kms-key-id — Opcional. O ARN do identificador de chave do AWS KMS a ser usado ao restaurar

um snapshot criptografado ou criptografar um cluster restaurado de um snapshot não criptografado.Fornecer o AWS KMS ID de chave no conjunto restaurado a ser encriptado com o AWS KMS chave,quer o instantâneo esteja ou não encriptado.

O formato do --kms-key-id é arn:aws:kms:<region>:<accountID>:key/<key-id>. Se nãoespecificar um valor para o --kms-key-id parâmetro, o seguinte ocorre:• Se o instantâneo for --snapshot-identifier é encriptada, depois o cluster restaurado é

encriptado utilizando o mesmo AWS KMS chave utilizada para encriptar o instantâneo.• Se o snapshot em --snapshot-identifier não estiver criptografado, o cluster restaurado não

será criptografado.


aws docdb restore-db-cluster-from-snapshot \ --db-cluster-identifier sample-cluster-restore \ --snapshot-identifier sample-cluster-snapshot \ --engine docdb \ --kms-key-id arn:aws:kms:us-east-1:123456789012:key/SAMPLE-KMS-KEY-ID

Para Windows:

aws docdb restore-db-cluster-from-snapshot ^ --db-cluster-identifier sample-cluster-restore ^ --snapshot-identifier sample-cluster-snapshot ^ --engine docdb ^ --kms-key-id arn:aws:kms:us-east-1:123456789012:key/SAMPLE-KMS-KEY-ID


{ "DBCluster": { "AvailabilityZones": [ "us-east-1c", "us-east-1b", "us-east-1a" ], "BackupRetentionPeriod": 1, "DBClusterIdentifier": "sample-cluster-restore", "DBClusterParameterGroup": "default.docdb3.6", "DBSubnetGroup": "default", "Status": "creating", "Endpoint": "sample-cluster-restore.cluster-node.us-east-1.docdb.amazonaws.com", "ReaderEndpoint": "sample-cluster-restore.cluster-node.us-east-1.docdb.amazonaws.com", "MultiAZ": false, "Engine": "docdb",

199


"EngineVersion": "3.6.0", "Port": 27017, "MasterUsername": "<master-user>", "PreferredBackupWindow": "02:00-02:30", "PreferredMaintenanceWindow": "tue:09:50-tue:10:20", "DBClusterMembers": [], "VpcSecurityGroups": [ { "VpcSecurityGroupId": "sg-abcdefgh", "Status": "active" } ], "HostedZoneId": "ABCDEFGHIJKLM", "StorageEncrypted": true, "KmsKeyId": "arn:aws:kms:us-east-1:<accountID>:key/<sample-key-id>", "DbClusterResourceId": "cluster-ABCDEFGHIJKLMNOPQRSTUVWXYZ", "DBClusterArn": "arn:aws:rds:us-east-1:<accountID>:cluster:sample-cluster-restore", "AssociatedRoles": [], "ClusterCreateTime": "2020-04-01T01:43:40.871Z", "DeletionProtection": true }}

Após o estado do cluster ser disponível, crie pelo menos uma instância para o grupo.


aws docdb create-db-instance \ --db-cluster-identifier sample-cluster-restore \ --db-instance-identifier sample-cluster-restore-instance \ --availability-zone us-east-1b \ --promotion-tier 2 \ --db-instance-class db.r5.large \ --engine docdb

Para Windows:

aws docdb create-db-instance ^ --db-cluster-identifier sample-cluster-restore ^ --db-instance-identifier sample-cluster-restore-instance ^ --availability-zone us-east-1b ^ --promotion-tier 2 ^ --db-instance-class db.r5.large ^ --engine docdb


{ "DBInstance": { "DBInstanceIdentifier": "sample-cluster-restore-instance", "DBInstanceClass": "db.r5.large", "Engine": "docdb", "DBInstanceStatus": "creating", "PreferredBackupWindow": "02:00-02:30", "BackupRetentionPeriod": 1, "VpcSecurityGroups": [ { "VpcSecurityGroupId": "sg-abcdefgh", "Status": "active" } ], "AvailabilityZone": "us-west-2b", "DBSubnetGroup": {

200

Amazon DocumentDB Guia do desenvolvedorRestauração point-in-time

"DBSubnetGroupName": "default", "DBSubnetGroupDescription": "default", "VpcId": "vpc-6242c31a", "SubnetGroupStatus": "Complete", "Subnets": [ { "SubnetIdentifier": "subnet-abcdefgh", "SubnetAvailabilityZone": { "Name": "us-west-2a" }, "SubnetStatus": "Active" }, { ... } ] }, "PreferredMaintenanceWindow": "fri:09:43-fri:10:13", "PendingModifiedValues": {}, "EngineVersion": "3.6.0", "AutoMinorVersionUpgrade": true, "PubliclyAccessible": false, "DBClusterIdentifier": "sample-cluster-restore", "StorageEncrypted": true, "KmsKeyId": "arn:aws:kms:us-east-1:<accountID>:key/<sample-key-id>", "DbiResourceId": "db-ABCDEFGHIJKLMNOPQRSTUVWXYZ", "CACertificateIdentifier": "rds-ca-2019", "PromotionTier": 2, "DBInstanceArn": "arn:aws:rds:us-east-1:<accountID>:db:sample-cluster-restore-instance" }}

Restauração point-in-timeVocê pode restaurar um cluster para qualquer momento determinado que esteja dentro do período deretenção de backup de cluster usando o Console de gerenciamento da AWS ou a AWS Command LineInterface (AWS CLI).

Lembre-se do seguinte ao restaurar um cluster para um momento determinado.

• O novo cluster é criado com a mesma configuração do cluster de origem, exceto pelo fato de que onovo cluster é criado com o grupo de parâmetros padrão. Para definir o grupo de parâmetros do novogrupo para o grupo de parâmetros do grupo de origem, modifique o cluster depois de ser disponível.Para obter mais informações sobre como modificar um cluster, consulte Modificar um cluster do AmazonDocumentDB (p. 231).

Restaurar para um point-in-time usando o Console degerenciamento da AWSÉ possível restaurar um cluster para um point-in-time que esteja dentro do período de retenção de backupconcluindo o seguinte usando o Console de gerenciamento da AWS.


2. No painel de navegação, escolha Clusters. Na lista de clusters, escolha o botão à esquerda do clusterque você deseja restaurar.

201


Amazon DocumentDB Guia do desenvolvedorRestaurar para um point-in-time usandoo Console de gerenciamento da AWS

Tip


3. No Ações menu, escolha Restaurar para apontar no tempo.4. Concluir o Repor tempo , que especifica a data e a hora para restaurar para.

a. Data de restauro—Escolha ou introduza uma data entre Tempo de restauro mais cedo e o Horade restauro mais recente.

b. Repor tempo—Escolha ou introduza a hora, o minuto e os segundos entre o Tempo de restauromais cedo e o Hora de restauro mais recente.

5. Concluir o Configuração secção.

a. Identificador de cluster — Aceite o identificador predefinido ou introduza um identificador quepreferir.

Restrições de nomeação de cluster:

• O comprimento é de [1—63] letras, números ou hifens.• O primeiro caractere deve ser uma letra.• Não podem terminar com um hífen ou conter dois hífens consecutivos• Tem de ser único para todos os grupos em Amazon RDS, Neptune e Amazon DocumentDB por

conta AWS, por Região.b. Classe de instância — Na lista pendente, escolha a classe de instância que pretende para as

instâncias do grupo.c. Número de ocorrências — Na lista pendente, escolha o número de ocorrências que pretende criar

quando o grupo é restaurado.6. : Optional. Para configurar as definições de rede, opções de agrupamento e activar exportações de

registos, escolha Mostrar definições avançadas, e depois preencha as secções seguintes. Casocontrário, siga para a próxima etapa.

• Network settings (Configurações de rede)1. Nuvem Privada Virtual (VPC) — Na lista pendente, escolha o VPC que pretende utilizar para este

grupo.2. Grupo subnet — Na lista pendente, escolha o grupo de sub-rede para este grupo.3. Grupos de segurança VPC — A partir da lista pendente, escolha os grupos de segurança VPC

para este grupo.

• Cluster options (Opções do cluster)

1. Porta — Aceite a porta predefinida (27017) ou utilize as setas para cima e para baixo para definira porta para comunicar com este grupo.

• Exportações de log

1. Registos de auditoria — Seleccione esta opção para activar os registos de auditoria para AmazonCloudWatch Logs. Se você selecionar essa opção, será necessário habilitar audit_logs nogrupo de parâmetros personalizado do cluster. Para obter mais informações, consulte Auditoriade eventos do Amazon DocumentDB (p. 168).

2. Registos de bigodes — Seleccione esta opção para activar os registos de perfil de operaçãode exportação para Amazon CloudWatch Logs. Se você selecionar essa opção, também seránecessário modificar os seguintes parâmetros no grupo de parâmetros personalizado do cluster:

202

Amazon DocumentDB Guia do desenvolvedorRestaurar para um point-in-time usando a AWS CLI

• profiler — Definir para enabled.• profiler_threshold_ms — Definir para um valor [0-INT_MAX] para definir o limiar para

operações de perfil.• profiler_sampling_rate — Definir para um valor [0.0-1.0] para definir a percentagem

de operações lentas para o perfil.

Para obter mais informações, consulte Profiling Amazon DocumentDB Operations (p. 352).3. Registos de bigodes — Exportar registos de perfil para o relógio da Amazon4. IAM função — Na lista pendente, escolha Função ligada ao serviço RDS.

• Tags1. Adicionar etiqueta — No Chave , introduza o nome para a etiqueta do seu grupo. No Valor ,

introduza opcionalmente o valor da etiqueta. As etiquetas são utilizadas com AWS Identity andAccess Management (IAM) políticas para gerir o acesso a Amazon DocumentDB recursos e paracontrolar que acções podem ser aplicadas aos recursos.

• Proteção contra exclusão1. Ativar proteção de eliminação — Protege o grupo de ser eliminado acidentalmente. Quando essa

opção estiver habilitada, não será possível excluir o cluster.7. Para restaurar o grupo, escolha Criar grupo. Em alternativa, pode escolher Cancelar para cancelar a

operação.

Restaurar para um point-in-time usando a AWS CLIPara restaurar um cluster para um momento determinado usando o período de retenção de backup dosnapshot, use a operação restore-db-cluster-to-point-in-time com os parâmetros a seguir.

• --db-cluster-identifier — Obrigatório. O nome do novo cluster a ser criado. Esse cluster nãopode existir antes da operação. O valor do parâmetro deve atender às seguintes restrições.

Restrições de nomeação de cluster:• O comprimento é de [1—63] letras, números ou hifens.• O primeiro caractere deve ser uma letra.• Não podem terminar com um hífen ou conter dois hífens consecutivos• Tem de ser único para todos os grupos em Amazon RDS, Neptune e Amazon DocumentDB por conta

AWS, por Região.• --restore-to-time — A data e hora UTC para restaurar o grupo para. Por exemplo,2018-06-07T23:45:00Z.

Restrições de tempo:• Devem ser anteriores ao último momento restaurável do cluster.• Devem ser especificadas se o parâmetro --use-latest-restorable-time não for especificado.• Não podem ser especificadas se o parâmetro --use-latest-restorable-time for true.• Não podem ser especificadas se o valor do parâmetro --restore-type for copy-on-write.

• --source-db-cluster-identifier — O nome do grupo de origem a partir do qual pretenderestaurar. Esse cluster deve existir e estar disponível.

• --use-latest-restorable-time ou --no-use-latest-restorable-time — Restaurar parao tempo de cópia de segurança mais recente possível. Não pode ser especificado se o parâmetro --restore-to-time não for especificado.

O AWS CLI operação restore-db-cluster-to-point-in-time apenas restaura o cluster e nãoas instâncias para esse grupo. Tem de invocar o create-db-instance operação para criar instâncias

203

Amazon DocumentDB Guia do desenvolvedorRestaurar para um point-in-time usando a AWS CLI

para o grupo restaurado, especificando o identificador do conjunto restaurado em --db-cluster-identifier. Só pode criar instâncias depois do restore-db-cluster-to-point-in-time aoperação foi concluída e o grupo restaurado é disponível.

Example

O exemplo seguinte cria sample-cluster-restored do instantâneo sample-cluster-snapshotpara o tempo mais recente possível.


aws docdb restore-db-cluster-to-point-in-time \ --db-cluster-identifier sample-cluster-restored \ --source-db-cluster-identifier sample-cluster-snapshot \ --use-latest-restorable-time

Para Windows:

aws docdb restore-db-cluster-to-point-in-time ^ --db-cluster-identifier sample-cluster-restored ^ --source-db-cluster-identifier sample-cluster-snapshot ^ --use-latest-restorable-time

Example

O exemplo seguinte cria sample-cluster-restored do instantâneo sample-cluster-snapshot às03:15 de 11 de dezembro de 2018 (UTC), que se encontra dentro do período de retenção de reserva desample-cluster.


aws docdb restore-db-cluster-to-point-in-time \ --db-cluster-identifier sample-cluster-restore \ --source-db-cluster-identifier sample-cluster \ --restore-to-time 2020-05-12T03:15:00Z

Para Windows:

aws docdb restore-db-cluster-to-point-in-time ^ --db-cluster-identifier sample-cluster-restore ^ --source-db-cluster-identifier sample-cluster ^ --restore-to-time 2020-05-12T03:15:00Z


{ "DBCluster": { "AvailabilityZones": [ "us-east-1c", "us-west-2b", "us-west-2a" ], "BackupRetentionPeriod": 1, "DBClusterIdentifier": "sample-cluster-restored", "DBClusterParameterGroup": "sample-parameter-group", "DBSubnetGroup": "default", "Status": "creating", "Endpoint": "sample-cluster-restored.node.us-east-1.docdb.amazonaws.com",

204

Amazon DocumentDB Guia do desenvolvedorExclusão de um snapshot de cluster

"ReaderEndpoint": "sample-cluster-restored.node.us-east-1.docdb.amazonaws.com", "MultiAZ": false, "Engine": "docdb", "EngineVersion": "3.6.0", "Port": 27017, "MasterUsername": "master-user", "PreferredBackupWindow": "02:00-02:30", "PreferredMaintenanceWindow": "tue:09:50-tue:10:20", "DBClusterMembers": [], "VpcSecurityGroups": [ { "VpcSecurityGroupId": "sg-abc0123", "Status": "active" } ], "HostedZoneId": "ABCDEFGHIJKLM", "StorageEncrypted": true, "KmsKeyId": "arn:aws:kms:us-east-1:<accountID^>:key/sample-key", "DbClusterResourceId": "cluster-ABCDEFGHIJKLMNOPQRSTUVWXYZ", "DBClusterArn": "arn:aws:rds:us-east-1:<accountID>:cluster:sample-cluster-restored", "AssociatedRoles": [], "ClusterCreateTime": "2020-04-24T20:14:36.713Z", "DeletionProtection": false }}

Exclusão de um snapshot de clusterUm snapshot manual é um backup completo que é excluído somente quando você o exclui manualmenteusando o Console de gerenciamento da AWS ou a AWS CLI. Não é possível excluir manualmente umsnapshot automático porque os snapshots automáticos são excluídos apenas quando o período deretenção do snapshot expira ou quando você exclui o cluster do snapshot.

Excluir um snapshot de cluster usando o Console degerenciamento da AWSPara excluir um snapshot de cluster manual usando o Console de gerenciamento da AWS, execute asetapas a seguir.


2. No painel de navegação, escolha Instantâneos.

Tip


3. Na lista de snapshots, escolha o botão à esquerda do snapshot que você deseja excluir. O tipo deinstantâneo tem de ser manual.

1. Pode verificar se o tipo de instantâneo é manual verificando se está listado como manual ouautomatic sob o Tipo coluna.

4. Desde o Ações menu, escolha Eliminar. Se o Eliminar opção não está disponível, provavelmenteescolheu um instantâneo automático.

205


Amazon DocumentDB Guia do desenvolvedorExcluir um snapshot de cluster usando o AWS CLI

5. No ecrã de confirmação de eliminação, para eliminar o instantâneo, escolha Eliminar. Para manter oinstantâneo, escolha Cancelar.

Excluir um snapshot de cluster usando o AWS CLIUm snapshot de cluster manual do Amazon DocumentDB é um backup completo que você pode excluirmanualmente usando a AWS CLI. Não é possível excluir manualmente um snapshot automático.

Para eliminar um instantâneo de agrupamento manual utilizando o AWS CLI, utilize o delete-db-cluster-snapshot com os seguintes parâmetros.

Parameters

• --db-cluster-snapshot-identifier — Obrigatório. O nome do snapshot manual a ser excluído.

O exemplo a seguir exclui o snapshot de cluster sample-cluster-snapshot.


aws docdb delete-db-cluster-snapshot \ --db-cluster-snapshot-identifier sample-cluster-snapshot

Para Windows:

aws docdb delete-db-cluster-snapshot ^ --db-cluster-snapshot-identifier sample-cluster-snapshot

A saída desta operação lista os detalhes do snapshot do cluster excluído.

206

Amazon DocumentDB Guia do desenvolvedorVisão geral de tarefas operacionais

Gerenciamento de recursos doAmazon DocumentDB

Essas seções abrangem os vários componentes e suas tarefas relacionadas para gerenciar suaimplementação do Amazon DocumentDB (compatível com MongoDB).

Tópicos• Visão geral de tarefas operacionais do Amazon DocumentDB (p. 207)• Gerenciar clusters do Amazon DocumentDB (p. 212)• Managing Amazon DocumentDB Instances (p. 247)• Gerir Amazon DocumentDB Grupos Sublíquidos (p. 266)• Amazon DocumentDBAlta disponibilidade e replicação do (p. 276)• Gerenciamento de eventos do Amazon DocumentDB (p. 281)• Escolher regiões e zonas de disponibilidade (p. 286)• Managing Amazon DocumentDB Cluster Parameter Groups (p. 287)• Noções básicas sobre endpoints do Amazon DocumentDB (p. 312)• Noções básicas de Nomes de recurso da Amazon (ARNs) do Amazon DocumentDB (p. 317)• Marcar recursos do Amazon DocumentDB (p. 321)• Manutenção do Amazon DocumentDB (p. 325)• Noções básicas das funções vinculadas ao serviço (p. 331)

Visão geral de tarefas operacionais do AmazonDocumentDB

Esta seção aborda as tarefas operacionais do seu cluster do Amazon DocumentDB (compatível comMongoDB) e como realizar essas tarefas usando a AWS CLI.

Tópicos• Adicionar uma réplica a um cluster do Amazon DocumentDB (p. 207)• Descrever clusters e instâncias (p. 208)• Criação de um snapshot de cluster (p. 209)• Restauração a partir de um snapshot (p. 210)• Remoção de uma instância de um cluster (p. 211)• Exclusão de um cluster (p. 211)

Adicionar uma réplica a um cluster do AmazonDocumentDBDepois de criar a instância principal para seu cluster do Amazon DocumentDB, você pode adicionar umaou mais réplicas. Uma réplica é uma instância somente leitura que serve a duas finalidades:

207

Amazon DocumentDB Guia do desenvolvedorDescrever clusters e instâncias

• Escalabilidade — se houver um grande número de clientes que exigem acesso simultâneo, você poderáadicionar mais réplicas para escalabilidade de leitura.

• Alta disponibilidade — se a instância principal falhar, o Amazon DocumentDB executará um failoverautomaticamente em uma instância de réplica e a designará como a nova principal. Se uma réplicafalhar, outras instâncias no cluster ainda poderão atender às solicitações até que o nó com falha possaser recuperado.

Cada cluster do Amazon DocumentDB pode oferecer suporte a até 15 réplicas.Note

Para obter a máxima tolerância a falhas, você deve implantar as réplicas em zonas dedisponibilidade separadas. Isso ajuda a garantir que seu cluster do Amazon DocumentDB possacontinuar a funcionar, mesmo que toda uma zona de disponibilidade fique indisponível.

O exemplo da AWS CLI a seguir mostra como adicionar uma nova réplica. O parâmetro --availability-zone coloca a réplica na zona de disponibilidade especificada.

aws docdb create-db-instance \ --db-instance-identifier sample-instance \ --db-cluster-identifier sample-cluster \ --engine docdb \ --db-instance-class db.r5.large \ --availability-zone us-east-1a

Descrever clusters e instânciasO exemplo da AWS CLI a seguir lista todos os clusters do Amazon DocumentDB em uma região. Paradeterminados recursos de gerenciamento, como o gerenciamento do ciclo de vida de clusters e instâncias,o Amazon DocumentDB aproveita a tecnologia operacional que é compartilhada com o Amazon RDS. Ofiltro filterName=engine,Values=docdb retorna somente clusters do Amazon DocumentDB.

Para obter mais informações sobre como descrever e modificar clusters, consulte ??? (p. 216).

aws docdb describe-db-clusters --filter Name=engine,Values=docdb


{ "DBClusters": [ { "AvailabilityZones": [ "us-east-1c", "us-east-1b", "us-east-1a" ], "BackupRetentionPeriod": 1, "DBClusterIdentifier": "sample-cluster-1", "DBClusterParameterGroup": "sample-parameter-group", "DBSubnetGroup": "default", "Status": "available", ... }, { "AvailabilityZones": [ "us-east-1c", "us-east-1b", "us-east-1a"

208

Amazon DocumentDB Guia do desenvolvedorCriação de um snapshot de cluster

], "BackupRetentionPeriod": 1, "DBClusterIdentifier": "sample-cluster-2", "DBClusterParameterGroup": "sample-parameter-group", "DBSubnetGroup": "default", "Status": "available", ... }, { "AvailabilityZones": [ "us-east-1c", "us-east-1b", "us-east-1a" ], "BackupRetentionPeriod": 1, "DBClusterIdentifier": "sample-cluster-3", "DBClusterParameterGroup": "sample-parameter-group", "DBSubnetGroup": "default", "Status": "available", ... } ]}

O exemplo da AWS CLI a seguir lista as instâncias em um cluster do Amazon DocumentDB. Para obtermais informações sobre como descrever e modificar clusters, consulte ??? (p. 251).

aws docdb describe-db-clusters \ --db-cluster-identifier sample-cluster \ --query 'DBClusters[*].[DBClusterMembers]'

A saída é semelhante à seguinte. Nesta saída, há duas instâncias. A instância principal é sample-instance-1 ("IsClusterWriter": true). Há também uma instância de réplica, sample-instance2 ("IsClusterWriter: false").

[ [ [ { "DBInstanceIdentifier": "sample-instance-1", "IsClusterWriter": true, "DBClusterParameterGroupStatus": "in-sync", "PromotionTier": 1 }, { "DBInstanceIdentifier": "sample-cluster-2", "IsClusterWriter": false, "DBClusterParameterGroupStatus": "in-sync", "PromotionTier": 1 } ] ]]

Criação de um snapshot de clusterUm snapshot de cluster é um backup completo dos dados no seu cluster do Amazon DocumentDB.Quando o snapshot estiver sendo criado, o Amazon DocumentDB lê os dados diretamente do volumede cluster. Por causa disso, você pode criar um snapshot mesmo que seu cluster não tenha nenhumainstância em execução no momento. O tempo necessário para criar um snapshot depende do tamanho dovolume do cluster.

209

Amazon DocumentDB Guia do desenvolvedorRestauração a partir de um snapshot

O Amazon DocumentDB oferece suporte a backups automáticos, que ocorrem diariamente durante ajanela de backup preferencial — um período de 30 minutos durante o dia. O exemplo da AWS CLI a seguirmostra como visualizar a janela de backup do cluster:

aws docdb describe-db-clusters \ --db-cluster-identifier sample-cluster \ --query 'DBClusters[*].PreferredBackupWindow'

A saída mostra a janela de backup (em UTC):

[ "00:18-00:48"]

Você pode definir a janela de backup ao criar o cluster do Amazon DocumentDB. Você também podealterar a janela de backup, conforme mostrado no exemplo a seguir. Se você não definir uma janela debackup, o Amazon DocumentDB atribuirá uma automaticamente ao cluster.

aws docdb modify-db-cluster \ --db-cluster-identifier sample-cluster \ --preferred-backup-window "02:00-02:30"

Além dos backups automáticos, você pode criar manualmente um snapshot de cluster a qualquermomento. Ao fazer isso, você especifica o cluster do qual deseja fazer backup e um nome exclusivo para osnapshot, para que você possa restaurar a partir dele posteriormente.

O exemplo da AWS CLI a seguir mostra como criar um snapshot dos dados.

aws docdb create-db-cluster-snapshot \ --db-cluster-identifier sample-cluster \ --db-cluster-snapshot-identifier sample-cluster-snapshot

Restauração a partir de um snapshotVocê pode restaurar um snapshot de cluster em um novo cluster do Amazon DocumentDB. Para fazerisso, forneça o nome do snapshot e o nome de um novo cluster. Não é possível restaurar de um snapshotpara um cluster existente; em vez disso, o Amazon DocumentDB cria um cluster quando você faz arestauração e o preenche com os dados do snapshot.

O exemplo a seguir mostra todos os snapshots de um determinado cluster sample-cluster.

aws docdb describe-db-cluster-snapshots \ --db-cluster-identifier sample-cluster \ --query 'DBClusterSnapshots[*].[DBClusterSnapshotIdentifier,SnapshotType,Status]'

A saída é semelhante à seguinte. Um snapshot manual é aquele que você criou manualmente, enquantoum snapshot automatizado é criado pelo Amazon DocumentDB dentro da janela de backup do cluster.

[ "sample-cluster-snapshot", "manual", "available" ], [ "rds:sample-cluster", "automated", "available"

210

Amazon DocumentDB Guia do desenvolvedorRemoção de uma instância de um cluster

]]

O exemplo a seguir mostra como restaurar um cluster do Amazon DocumentDB de um snapshot.

aws docdb restore-db-cluster-from-snapshot \ --engine docdb \ --db-cluster-identifier new-sample-cluster \ --snapshot-identifier sample-cluster-snapshot

O novo cluster não tem nenhuma instância associada a ele; portanto, para interagir com o cluster, adicioneuma instância a ele.

aws docdb create-db-instance \ --db-instance-identifier new-sample-instance \ --db-instance-class db.r5.large \ --engine docdb \ --db-cluster-identifier new-sample-cluster

É possível usar as seguintes operações da AWS CLI para monitorar o andamento da criação do cluster eda instância: Quando os status do cluster e da instância estiverem disponíveis, você poderá se conectar aoendpoint do novo cluster e acessar seus dados.

aws docdb describe-db-clusters \ --db-cluster-identifier new-sample-cluster \ --query 'DBClusters[*].[Status,Endpoint]'

aws docdb describe-db-instances \ --db-instance-identifier new-sample-instance \ --query 'DBInstances[*].[DBInstanceStatus]'

Remoção de uma instância de um clusterO Amazon DocumentDB armazena todos os dados no volume do cluster. Os dados persistem nessevolume de cluster, mesmo se você remover todas as instâncias do cluster. Se precisar acessar os dadosnovamente, adicione uma instância ao cluster a qualquer momento e continue de onde parou.

O exemplo a seguir mostra como remover uma instância de seu cluster do Amazon DocumentDB.

aws docdb delete-db-instance \ --db-instance-identifier sample-instance

Exclusão de um clusterPara excluir um cluster do Amazon DocumentDB, é necessário primeiro remover todas as instâncias. Oexemplo da AWS CLI a seguir retorna informações sobre as instâncias em um cluster. Se essa operaçãoretornar qualquer identificador de instância, você terá que excluir cada uma das instâncias. Para obter maisinformações, consulte Remoção de uma instância de um cluster (p. 211).

aws docdb describe-db-clusters \ --db-cluster-identifier sample-cluster \ --query 'DBClusters[*].DBClusterMembers[*].DBInstanceIdentifier'

Quando não houver mais instâncias restantes, você poderá excluir o cluster. Nesse momento, você deveescolher uma das seguintes opções:

211

Amazon DocumentDB Guia do desenvolvedorGerenciar clusters do

• Criar um snapshot final — capture todos os dados do cluster em um snapshot para poder recriar umainstância com esses dados posteriormente. O exemplo a seguir mostra como fazer isso:

aws docdb delete-db-cluster \ --db-cluster-identifier sample-cluster \ --final-db-snapshot-identifier sample-cluster-snapshot

• Ignore o snapshot final — descarte permanentemente todos os dados do cluster. Essa ação não podeser revertida. O exemplo a seguir mostra como fazer isso:

aws docdb delete-db-cluster \ --db-cluster-identifier sample-cluster \ --skip-final-snapshot

Gerenciar clusters do Amazon DocumentDBPara gerenciar um cluster do Amazon DocumentDB, é necessário ter uma política do IAM com aspermissões de plano de controle apropriadas do Amazon DocumentDB. Essas permissões permitemcriar, modificar e excluir clusters e instâncias. A política AmazonDocDBFullAccess fornece todas aspermissões necessárias para administrar um cluster do Amazon DocumentDB.

Os tópicos a seguir mostram como executar várias tarefas ao trabalhar com clusters do AmazonDocumentDB, incluindo a criação, a exclusão, a modificação, a conexão e a visualização de clusters.

Tópicos• Noções básicas dos clusters (p. 212)• Configurações do cluster do Amazon DocumentDB (p. 214)• Determinar o status de um cluster (p. 215)• Ciclo de vida de clusters do Amazon DocumentDB (p. 216)• Dimensionar clusters do Amazon DocumentDB (p. 244)• Noções básicas de tolerância a falhas do cluster do Amazon DocumentDB (p. 246)

Noções básicas dos clustersO Amazon DocumentDB separa computação e armazenamento e transfere a replicação de dados e obackup para o volume do cluster. Um volume de cluster fornece uma camada de armazenamento durável,confiável e altamente disponível que replica dados de seis maneiras em três zonas de disponibilidade.As réplicas permitem maior disponibilidade de dados e escalabilidade de leitura. Cada cluster pode serexpandido para 15 réplicas.

Substantivo Description (Descrição) Operações de API (verbos)

Cluster Consiste em uma ou maisinstâncias e em um volume dearmazenamento de cluster quegerencia os dados para essasinstâncias.

create-db-cluster

delete-db-cluster

describe-db-clusters

modify-db-cluster

Instância A leitura e a gravação de dadosno volume de armazenamentodo cluster são feitas por

create-db-instance

delete-db-instance

212

Amazon DocumentDB Guia do desenvolvedorNoções básicas dos clusters

Substantivo Description (Descrição) Operações de API (verbos)meio de instâncias. Em umdeterminado cluster, há doistipos de instâncias: principal e deréplica. Um cluster sempre temuma instância principal e pode ter0 – 15 réplicas.

describe-db-instances

modify-db-instance

describe-orderable-db-instance-options

reboot-db-instance

Volume do cluster Um volume de armazenamentode banco de dados virtualque abrange três zonas dedisponibilidade, no qual cadazona de disponibilidade contacom duas cópias dos dados docluster.

N/A

Instância principal Oferece suporte a operaçõesde leitura e gravação, além derealizar todas as modificaçõesde dados no volume do cluster.Cada cluster tem uma instânciaprincipal.

N/A

Instância de réplica É compatível apenas comoperações de leitura. Cadacluster do Amazon DocumentDBpode ter até 15 instânciasde réplica além da instânciaprincipal. Várias réplicasdistribuem a carga de trabalhode leitura. Ao localizar réplicasem zonas de disponibilidadeseparadas, você também podeaumentar a disponibilidade dobanco de dados.

N/A

Endpoint do cluster Um endpoint para um clusterdo Amazon DocumentDB quese conecta à instância principalatual do cluster. Cada clusterdo Amazon DocumentDB temum endpoint de cluster e umainstância principal.

N/A

Endpoint de leitor Um endpoint para um clusterdo Amazon DocumentDBque se conecta a uma dasréplicas disponíveis para essecluster. Cada cluster do AmazonDocumentDB tem um endpointde leitor. Se houver mais deuma réplica, o endpoint de leitordirecionará cada solicitação deconexão para uma das réplicasdo Amazon DocumentDB.

N/A

213

Amazon DocumentDB Guia do desenvolvedorConfigurações do cluster

Substantivo Description (Descrição) Operações de API (verbos)

Endpoint da instância Um endpoint para umainstância em um cluster doAmazon DocumentDB quese conecta a uma instância.Cada instância em um cluster,independentemente do tipo deinstância, tem o próprio endpointde instância exclusivo.

N/A

Configurações do cluster do Amazon DocumentDBAo criar ou modificar um cluster, é importante entender quais parâmetros são imutáveis e quais podem sermodificados após o cluster ser criado. A tabela a seguir lista todos as configurações ou os parâmetros quesão específicos de um cluster. Conforme especificado na tabela, alguns são modificáveis, outros não.

Note

Essas configurações não devem ser confundidas com grupos de parâmetros de cluster doAmazon DocumentDB e seus parâmetros. Para obter mais informações sobre parameter groupsde cluster, consulte Managing Amazon DocumentDB Cluster Parameter Groups (p. 287).

Parâmetro Permitemodificação

Observações

DBClusterIdentifier Sim Restrições de nomenclatura:

• O comprimento é de [1 a 63] letras, números ouhifens.

• O primeiro caractere deve ser uma letra.• Não podem terminar com um hífen ou conter

dois hífens consecutivos.• Deve ser exclusivo para todos os clusters no

Amazon RDS, Amazon Neptune e AmazonDocumentDB por conta da AWS, por região.

Engine Não Deve ser docdb.

BackupRetentionPeriod Sim Defina um período entre [1 e 35] dias.

DBClusterParameterGroupName Sim Restrições de nomenclatura:

• O tamanho é de [1 a 255] caracteresalfanuméricos.

• O primeiro caractere deve ser uma letra.• Não podem terminar com um hífen ou conter

dois hífens consecutivos.

DBSubnetGroupName Não Depois que um cluster for criado, você não poderámodificar a sub-rede do cluster.

EngineVersion Não Deve ser 3.6.0.

214

Amazon DocumentDB Guia do desenvolvedorDeterminar o status de um cluster

Parâmetro Permitemodificação

Observações

KmsKeyId Não Se você optar por criptografar seu cluster, nãopoderá alterar a chave do AWS KMS que vocêusou para criptografar o cluster.

MasterUsername Não Depois que um cluster for criado, você não poderámodificar o MasterUsername.

Restrições de nomenclatura:

• O tamanho é de [1 a 63] caracteresalfanuméricos.

• O primeiro caractere deve ser uma letra.• Não pode ser uma palavra reservada pelo

mecanismo de banco de dados.

MasterUserPassword Sim Restrições:

• O comprimento é de [8 a 100] caracteres ASCIIimprimíveis.

• Pode usar caracteres ASCII imprimíveis, excetoo seguinte:• / (barra)• " (aspas duplas)• @ (arroba)

Port Sim O número da porta se aplica a todas as instânciasno cluster.

PreferredBackupWindow Sim

PreferredMaintenanceWindow Sim

StorageEncrypted Não Se você optar por criptografar seu cluster, ele nãopoderá ser descriptografado.

Tags Sim

VpcSecurityGroupIds Não Depois que um cluster for criado, você não poderámodificar a VPC em que o cluster reside.

Determinar o status de um clusterVocê pode determinar o status de um cluster usando o Console de gerenciamento da AWS ou a AWS CLI.

Uso do Console de gerenciamento da AWSUse o procedimento a seguir para ver o status do cluster do Amazon DocumentDB usando o Console degerenciamento da AWS



215


Amazon DocumentDB Guia do desenvolvedorCiclo de vida de clusters

3. Na coluna Cluster identifier (Identificador de cluster), encontre o nome do cluster desejado. Depois,para encontrar o status do cluster, leia essa linha até a coluna Status, conforme mostrado a seguir.

Uso do AWS CLIUse a operação describe-db-clusters para ver o status do cluster do Amazon DocumentDB usando aAWS CLI.

O código a seguir verifica o status do cluster sample-cluster.


aws docdb describe-db-clusters \ --db-cluster-identifier sample-cluster \ --query 'DBClusters[*].[DBClusterIdentifier,Status]'

Para Windows:

aws docdb describe-db-clusters ^ --db-cluster-identifier sample-cluster ^ --query 'DBClusters[*].[DBClusterIdentifier,Status]'


[ [ "sample-cluster", "available" ]]

Ciclo de vida de clusters do Amazon DocumentDBO ciclo de vida de um cluster do Amazon DocumentDB inclui a criação, a descrição, a modificação e aexclusão do cluster. Esta seção fornece informações sobre como concluir esses processos.

Tópicos• Criação de um cluster do Amazon DocumentDB (p. 217)• Descrição dos clusters do Amazon DocumentDB (p. 227)• Modificar um cluster do Amazon DocumentDB (p. 231)• Determinação de manutenção pendente (p. 234)• Atualizar a versão de mecanismo do cluster (p. 235)• Interromper e iniciar um cluster do Amazon DocumentDB (p. 237)• Excluir um cluster do Amazon DocumentDB (p. 240)

216


Criação de um cluster do Amazon DocumentDBUm cluster do Amazon DocumentDB consiste em instâncias e um volume de cluster que representa osdados para o cluster. O volume do cluster é replicado de seis maneiras em três zonas de disponibilidadecomo volume único e virtual. O cluster contém uma instância principal e, como opção, até 15 instâncias deréplica.

As seções a seguir mostram como criar um cluster do Amazon DocumentDB usando o Console degerenciamento da AWS ou a AWS CLI. Em seguida, você pode adicionar instâncias de réplica adicionaispara esse cluster. Quando o console é usado para criar o cluster do Amazon DocumentDB, uma instânciaprimária é criada automaticamente para você ao mesmo tempo. Se você usar a AWS CLI para criar ocluster do Amazon DocumentDB, após o status do cluster estar disponível, também é necessário criar ainstância primária para esse cluster.

PrerequisitesVeja a seguir os pré-requisitos para a criação de um cluster do Amazon DocumentDB.



1. Abra https://aws.amazon.com/ e escolha Create an AWS Account.2. Siga as instruções online.

Pré-requisitos do VPC

Você só pode criar um cluster do Amazon DocumentDB em uma Amazon Virtual Private Cloud (AmazonVPC) que abrange três zonas de disponibilidade. Cada zona de disponibilidade deve conter pelo menosuma sub-rede. Ao distribuir suas instâncias de cluster em pelo menos três zonas de disponibilidade, vocêgarante que as instâncias estão disponíveis em seu cluster no caso improvável de ocorrer uma falha nazona de disponibilidade. O volume do cluster de seu cluster do Amazon DocumentDB sempre abrange trêszonas de disponibilidade para fornecer um armazenamento durável com possibilidade mínima de perda dedados.

Se você estiver usando o console para criar seu cluster do Amazon DocumentDB, por padrão, o consolecriará o cluster no padrão Amazon VPC da sua conta. Como alternativa, você pode escolher qualquer VPCna qual criar o cluster do Amazon DocumentDB. A VPC deve ter pelo menos uma sub-rede em pelo menostrês das zonas de disponibilidade para você usá-la com um cluster do Amazon DocumentDB.

Pré-requisitos da sub-rede

Ao criar um cluster do Amazon DocumentDB, você deve escolher uma VPC e um grupo de sub-rede correspondente dentro dessa VPC para iniciar o seu cluster. Sub-redes determinam a zona dedisponibilidade e o intervalo de IP dentro da zona de disponibilidade que você deseja usar para executaruma instância. Para fins desta discussão, usaremos os termos sub-rede e zona de disponibilidadealternadamente. Um grupo de sub-redes é um conjunto nomeado de sub-redes (ou zonas dedisponibilidade). Um grupo de sub-redes permite que você especifique as zonas de disponibilidade quedeseja usar para executar instâncias do Amazon DocumentDB. Por exemplo, em um cluster com trêsinstâncias, a fim de manter a disponibilidade alta, é recomendável que cada uma dessas instâncias sejaprovisionada em zonas de disponibilidade separadas. Assim, se uma única zona de disponibilidade éreduzida, ela só afeta uma única instância.

As instâncias do Amazon DocumentDB podem ser provisionadas atualmente em até três zonas dedisponibilidade. Mesmo que um grupo de sub-redes tenha mais de três sub-redes, você só pode usartrês dessas sub-redes para criar um cluster do Amazon DocumentDB. Como resultado, é recomendávelque, ao criar um grupo de sub-redes, você escolha somente as três sub-redes nas quais deseja implantarsuas instâncias. Na Leste dos EUA (Norte da Virgínia), o grupo da sua sub-rede pode ter seis sub-redes

217



(ou zonas de disponibilidade). No entanto, quando um cluster do Amazon DocumentDB é provisionado,o Amazon DocumentDB escolhe três dessas zonas de disponibilidade, que ele usa para provisionarinstâncias.

Por exemplo, suponha que, ao criar um cluster, o Amazon DocumentDB escolhe as zonas dedisponibilidade {1A, 1B e 1C}. Se você tentar criar uma instância na zona de disponibilidade {1D},a chamada de API não será bem-sucedida. No entanto, se você optar por criar uma instância semespecificar uma zona de disponibilidade específica, o Amazon DocumentDB escolherá uma zona dedisponibilidade em seu nome. O Amazon DocumentDB usa um algoritmo para balancear a carga dasinstâncias em todas as zonas de disponibilidade para ajudar você a obter alta disponibilidade. Porexemplo, se três instâncias forem provisionadas, por padrão, elas serão provisionadas em três zonas dedisponibilidade e não serão provisionadas todas em uma única zona de disponibilidade.

Recomendações:

• A menos que você tenha um motivo específico, sempre crie um grupo de sub-rede com três sub-redes.Isso ajuda a garantir que clusters com três ou mais instâncias alcancem maior disponibilidade, pois asinstâncias são provisionadas em três zonas de disponibilidade.

• Sempre distribua instâncias em várias zonas de disponibilidade para obter alta disponibilidade. Nuncacoloque todas as instâncias de um cluster em uma única zona de disponibilidade.

• Como os eventos de failover podem acontecer em qualquer momento, você não deve presumir que umainstância primária ou de réplica sempre estará em uma determinada zona de disponibilidade.

Pré-requisitos adicionais

Veja a seguir alguns pré-requisitos adicionais para criar um cluster do Amazon DocumentDB:

• Quando você se conecta à AWS usando credenciais do AWS Identity and Access Management (IAM),sua conta do IAM deve ter políticas do IAM que concedam as permissões que são necessárias pararealizar operações do Amazon DocumentDB.

Se você estiver usando uma conta do IAM para acessar o console do Amazon DocumentDB, primeirovocê deve fazer login no Console de gerenciamento da AWS com a sua conta do IAM. Depois acesse oconsole do Amazon DocumentDB no https://console.aws.amazon.com/docdb.

• Se quiser personalizar os parâmetros de configuração do seu cluster, você deverá especificar um grupode parâmetros do cluster e um grupo de parâmetros com as configurações de parâmetro obrigatórias.Para obter informações sobre como criar ou modificar um grupo de parâmetros de cluster ou um grupode parâmetros, consulte Managing Amazon DocumentDB Cluster Parameter Groups (p. 287).

• Você deve determinar o número de porta de TCP/IP que deseja especificar para seu cluster. Emalgumas empresas, os firewalls bloqueiam conexões com as portas padrão do Amazon DocumentDB.Se o firewall da sua empresa bloquear a porta padrão, escolha outra porta para o cluster. Todas asinstâncias em um cluster usam a mesma porta.

Criar um cluster e instância primária usando o Console de gerenciamento daAWSOs procedimentos a seguir descrevem como usar o console para iniciar um cluster do AmazonDocumentDB com uma ou mais instâncias.

Criar um Grupo: Utilizar as predefinições

Para criar um cluster com instâncias usando as configurações padrão com o Console degerenciamento da AWS


218




2. Se você deseja criar seu cluster em uma região da AWS diferente da região Leste dos EUA (Norte daVirgínia), escolha a região na lista exibida na seção superior direita do console.

3. No painel de navegação, selecione Clusters e, em seguida, Create (Criar).

Tip


4. Na página Create Amazon DocumentDB cluster, complete o painel Configuration (Configuração).

a. Cluster identifier (Identificador de cluster) — aceite o nome fornecido pelo Amazon DocumentDBou insira um nome para o cluster, por exemplo, sample-cluster.


• Length is [1—63] letters, numbers, or hyphens.• First character must be a letter.• Cannot end with a hyphen or contain two consecutive hyphens.• Must be unique for all clusters across Amazon RDS, Neptune, and Amazon DocumentDB per

AWS account, per Region.b. Instance class (Classe da instância) — aceite o padrão db.r5.large ou escolha a classe da

instância que deseja usar na lista.c. Number of instances (Número de instâncias) — na lista, escolha o número de instâncias que

você deseja criar com esse cluster. A primeira instância é a instância primária e todas as outrasinstâncias são instâncias de réplica somente leitura. Você pode adicionar e excluir instânciasposteriormente, se necessário. Por padrão, um cluster do Amazon DocumentDB é executado comtrês instâncias (uma primária e duas réplicas).

5. Complete o painel Authentication (Autenticação).

a. Master username (Nome de usuário mestre) — insira um nome para o usuário mestre. Para fazerlogin no cluster, você deve usar o nome do usuário mestre.

Restrições de nomenclatura do usuário mestre:

• Length is [1—63] alphanumeric characters.• First character must be a letter.• Cannot be a word reserved by the database engine.

b. Master password (Senha mestre) — insira uma senha para o usuário mestre e, em seguida,confirme-a. Para fazer login no cluster, você deve usar a senha mestre.

Restrições da senha mestre:

• Length is [8-100] printable ASCII characters.• Can use any printable ASCII characters except for the following:

• / (forward slash)• " (double quotation mark)• @ (at symbol)

6. Na parte inferior da tela, escolha uma das seguintes opções:• Para criar o cluster agora, escolha Create cluster (Criar cluster).• Para não criar o cluster, escolha Cancel (Cancelar).• Para continuar a configurar o cluster antes de criá-lo, escolha Show additional configurations

(Mostrar configurações adicionais) e, em seguida, Criar um Grupo: Configuraçõesadicionais (p. 221). 219


As configurações incluídas na seção Additional Configurations (Configurações adicionais) sãoestas:

• Network settings—The default is to use the default VPC security group.• Cluster options—The default is to use port is 27017 and the default parameter group.• Encryption—The default is to enable encryption using the (default) aws/rds key.

Important

After a cluster is encrypted, it cannot be unencrypted.• Backup—The default is to retain backups for 1 day and let Amazon DocumentDB choose the

backup window.• Log exports—The default is to not export audit logs to CloudWatch Logs.• Maintenance—The default is to let Amazon DocumentDB choose the maintenance window.• Deletion protection—Protect your cluster from accidental deletion. Default for cluster created

using the console is enabled.

Se você aceitar os configurações padrão agora, poderá alterar a maioria delas posteriormentemodificando o cluster.

7. Habilite a conexão de entrada para o grupo de segurança do cluster.

Se não alterou as configurações padrão do seu cluster, você criou um cluster usando o grupode segurança padrão para a VPC padrão na região determinada. Para conectar-se ao AmazonDocumentDB, você deve habilitar conexões de entrada na porta 27017 (ou na porta de sua escolha)para o grupo de segurança do cluster.

To add an inbound connection to your cluster's security group

a. Faça login no Console de gerenciamento da AWS e abra o console do Amazon EC2 em https://console.aws.amazon.com/ec2/.

b. Na seção Resources (Recursos) da janela principal, escolha Security groups (Grupos desegurança).

c. A partir da lista de grupos de segurança, localize o grupo de segurança que utilizou ao criar o seugrupo (é mais provável que o default grupo de segurança) e escolha a caixa à esquerda do nomedo grupo de segurança.

d. No menu Actions (Ações), escolha Edit inbound rules (Editar regras de entrada) e escolha ouinsira as restrições de regras.

i. Type—Na lista, escolha o protocolo para abrir para tráfego de rede.ii. Protocol—Na lista, escolha o tipo de protocolo.

220

https://console.aws.amazon.com/ec2/

https://console.aws.amazon.com/ec2/


iii. Port Range—Para uma regra personalizada, introduza um número de porta ou um intervalode porta. Certifique-se de que o número ou o intervalo de portas inclua a porta que vocêespecificou quando criou o cluster (padrão: 27017).

iv. Source—Especifica o tráfego que pode chegar à sua instância. Na lista, escolha a origem dotráfego. Se você escolher Custom (Personalizado), especifique um único endereço IP ou umintervalo de endereços IP em notação CIDR (por exemplo, 203.0.113.5/32).

v. Description—Introduza uma descrição para esta regra.vi. Quando terminar de criar a regra, escolha Save (Salvar).

Criar um Grupo: Configurações adicionais

Se você deseja aceitar as configurações padrão para o seu cluster, pode ignorar as etapas a seguir eescolher Create cluster (Criar cluster).

1. Conclua o painel Network settings (Configurações de rede).

a. Virtual Private Cloud (VPC) (Nuvem privada virtual (VPC)) — na lista, escolha a Amazon VPC naqual você deseja executar esse cluster.

b. Subnet group (Grupo de sub-redes) — na lista, escolha o grupo de sub-redes que você desejausar para esse cluster.

c. VPC security groups (Grupos de segurança da VPC) — na lista, escolha o grupo de segurança daVPC para esse cluster.

2. Conclua o painel Cluster options (Opções do cluster).

a. Data base port — Use as setas para cima e para baixo para definir a porta TCP/IP que osaplicativos usarão para se conectar à sua instância.

b. Cluster parameter group (Grupo de parâmetros do cluster) — na lista de grupos de parâmetros,escolha o grupo de parâmetros do cluster para esse cluster.

3. Preencha o painel Encryption (Criptografia).

221


a. Encryption-at-rest (Criptografia em repouso) — Escolha uma das seguintes opções:• Habilitar criptografia — padrão. Todos os dados em repouso são criptografados. Se optar por

criptografar seus dados, você não poderá desfazer essa ação.• Desabilitar criptografia — seus dados não estão criptografados.

b. Master key (Chave mestre) — Ela está disponível somente se você estiver criptografando seusdados. Na lista, escolha a chave que você deseja usar para criptografar os dados desse cluster. Opadrão é (default) aws/rds.

Se você escolher Enter a key ARN (Inserir o ARN da chave), deverá inserir o nome de recurso daAmazon (ARN) da chave.

Backup retention period (Período de retenção de backup) — na lista, selecione o número de dias quevocê deseja que os backups automáticos sejam mantidos.

4. Preencha o painel Backup.

a. Backup retention period (Período de retenção de backup) — na lista, selecione o número de diaspara manter os backups automáticos desse cluster antes de excluí-los.

b. Backup window (Janela de backup) — defina o tempo e a duração diários durante os quais oAmazon DocumentDB fará backups desse cluster.

i. Start time — Na primeira lista, escolha a hora de início (UTC) para iniciar seus backupsautomáticos. Na segunda lista, escolha o minuto da hora em que você deseja que osbackups automáticos sejam iniciados.

ii. Duration (Duração) — na lista, selecione a quantidade de horas a serem alocadas na criaçãode backups automáticos.

5. Preencha o painel Log exports (Exportações de logs) selecionando os tipos de logs que desejaexportar para o CloudWatch Logs.

222


• Audit logs (Logs de auditoria) — selecione esta opção para habilitar a exportação de logs deauditoria para o Amazon CloudWatch Logs. Se você selecionar Audit logs (Logs de auditoria),deverá habilitar audit_logs no grupo de parâmetros personalizado do cluster. Para obter maisinformações, consulte Auditoria de eventos do Amazon DocumentDB (p. 168).

• Profiler logs (Logs do profiler) — selecione esta opção para habilitar a operação de exportaçãode logs do profiler para o Amazon CloudWatch Logs. Se você selecionar Profiler logs (Logsdo profiler), deverá também modificar os seguintes parâmetros no grupo de parâmetrospersonalizado do cluster:

• profiler—Definir para enabled.• profiler_threshold_ms — defina como um valor [0-INT_MAX] para configurar o limite

para operações de criação de perfil.• profiler_sampling_rate — defina como um valor [0.0-1.0] para configurar a

porcentagem de operações lentas para perfilar.

Para obter mais informações, consulte Profiling Amazon DocumentDB Operations (p. 352).6. Complete o painel Maintenance (Manutenção).

• Selecione uma das seguintes opções

• Select window (Selecionar janela) — você pode especificar o dia da semana, a hora de inícioem UTC e a duração do Amazon DocumentDB para executar a manutenção do seu cluster.

a. Start day (Dia de início) — na lista, escolha o dia da semana do início da manutenção docluster.

b. Start time (Hora de início) — nas listas, escolha a hora e minuto, em UTC, para iniciar amanutenção.

c. Duration (Duração) — na lista, escolha quanto tempo alocar para a manutenção docluster. Se a manutenção não puder ser concluída no horário especificado, o processo demanutenção continuará após o horário especificado, até que seja concluída.

• No preference (Sem preferência) — o Amazon DocumentDB seleciona o dia da semana, ohorário de início e a duração para executar a manutenção.

7. Se quiser adicionar uma ou mais tags a esse cluster, preencha o painel Tags.

223


Para cada tag que quiser adicionar ao cluster, repita as etapas a seguir. Você pode ter até 10 em umcluster.

a. Selecione Add Tags (Adicionar tags).b. Digite a Key (Chave) da tag.c. Opcionalmente, digite o Value (Valor) da tag.

Para remover uma tag, selecione Remove tag (Remover tag).8. Deletion Protection (Proteção contra exclusão) está habilitada por padrão ao criar um cluster usando o

console. Para desabilitar a proteção contra exclusão, desmarque Enable deletion protection (Habilitarproteção contra exclusão). Quando habilitada, a proteção contra exclusão impede que um cluster sejaexcluído. Para excluir um cluster protegido contra a exclusão, primeiro é necessário modificar o clusterpara desabilitar a proteção contra exclusão.

Para obter mais informações sobre a proteção contra exclusão, consulte Excluir um cluster do AmazonDocumentDB (p. 240).

9. Para criar o cluster, escolha Create cluster (Criar cluster). Caso contrário, escolha Cancel (Cancelar).

Para executar um cluster do Amazon DocumentDB usando a AWS CLI

Os procedimentos a seguir descrevem como usar o AWS CLI para iniciar um cluster do AmazonDocumentDB e criar uma réplica do Amazon DocumentDB.

Parameters

• --db-cluster-identifier—Obrigatório. Uma string com letras minúsculas que identifica essecluster.


• O comprimento é de [1–63] letras, números ou hifens.• O primeiro caractere deve ser uma letra.• Não podem terminar com um hífen ou conter dois hífens consecutivos.• Deve ser exclusivo para todos os clusters (no Amazon RDS, Amazon Neptune, e Amazon

DocumentDB) por conta da AWS, por região.

• --engine—Obrigatório. Deve ser docdb.• --deletion-protection | --no-deletion-protection—Opcional. Quando a proteção contra

exclusão estiver habilitada, ela impede que um cluster seja excluído. Ao usar a AWS CLI, a configuraçãopadrão é ter a proteção contra exclusão desabilitada.

224


Para obter mais informações sobre a proteção contra exclusão, consulte Excluir um cluster do AmazonDocumentDB (p. 240).

• --master-username—Obrigatório. O nome do usuário usado para autenticar o usuário.

Restrições de nomenclatura do usuário mestre:

• O comprimento é de [1–63] caracteres alfanuméricos.• O primeiro caractere deve ser uma letra.• Não pode ser uma palavra reservada pelo mecanismo de banco de dados.

• --master-user-password—Obrigatório. A senha do usuário usada para autenticar o usuário.

Restrições da senha mestre:

• O comprimento é de [8 a 100] caracteres ASCII imprimíveis.• Pode usar caracteres ASCII imprimíveis, exceto o seguinte:

• / (barra)• " (aspas duplas)• @ (arroba)

Para ver parâmetros adicionais, consulte CreateDBCluster (p. 441).

Para criar um Amazon DocumentDB conjunto, ligue para o create-db-cluster AWS CLI. O seguinteAWS CLI cria um comando Amazon DocumentDB cluster com nome sample-cluster com proteçãocontra eliminação ativada. Para obter mais informações sobre a proteção contra deleção, consulte??? (p. 240)

Além disso, --engine-version é um parâmetro opcional que assume a predefinição para a versão maisrecente do motor. A versão atual do principal motor é 3.6.0. Quando são lançadas novas versões principaisdo motor, a versão predefinida do motor para --engine-version serão atualizados para refletir a versãoprincipal do motor mais recente. Como resultado, para volumes de trabalho de produção, e especialmenteaqueles que dependem de scripting, automatização ou AWS CloudFormation modelos, recomendamosque especifique explicitamente o --engine-version para a versão principal pretendida.

Note

Se um db-subnet-group-name ou vpc-security-group-id não está especificado, AmazonDocumentDB usará o grupo de subrede padrão e Amazon VPC grupo de segurança para a regiãoem questão.


aws docdb create-db-cluster \ --db-cluster-identifier sample-cluster \ --engine docdb \ --engine-version 3.6.0 \ --deletion-protection \ --master-username master-user \ --master-user-password password

Para Windows:

aws docdb create-db-cluster ^

225


--db-cluster-identifier sample-cluster ^ --engine docdb ^ --engine-version 3.6.0 ^ --deletion-protection ^ --master-username master-user ^ --master-user-password password


{ "DBCluster": { "StorageEncrypted": false, "DBClusterMembers": [], "Engine": "docdb", "DeletionProtection" : "enabled", "ClusterCreateTime": "2018-11-26T17:15:19.885Z", "DBSubnetGroup": "default", "EngineVersion": "3.6.0", "MasterUsername": "master-user", "BackupRetentionPeriod": 1, "DBClusterArn": "arn:aws:rds:us-east-1:123456789012:cluster:sample-cluster", "DBClusterIdentifier": "sample-cluster", "MultiAZ": false, "DBClusterParameterGroup": "default.docdb3.6", "PreferredBackupWindow": "09:12-09:42", "DbClusterResourceId": "cluster-KQSGI4MHU4NTDDRVNLNTU7XVAY", "PreferredMaintenanceWindow": "tue:04:17-tue:04:47", "Port": 27017, "Status": "creating", "ReaderEndpoint": "sample-cluster.cluster-ro-sfcrlcjcoroz.us-east-1.docdb.amazonaws.com", "AssociatedRoles": [], "HostedZoneId": "ZNKXTT8WH85VW", "VpcSecurityGroups": [ { "VpcSecurityGroupId": "sg-77186e0d", "Status": "active" } ], "AvailabilityZones": [ "us-east-1a", "us-east-1c", "us-east-1e" ], "Endpoint": "sample-cluster.cluster-sfcrlcjcoroz.us-east-1.docdb.amazonaws.com" }}

Leva alguns minutos para criar o cluster. Você pode usar o Console de gerenciamento da AWS ou a AWSCLI para monitorar o status do seu cluster. Para obter mais informações, consulte Monitorar o status de umcluster do Amazon DocumentDB (p. 336).

Important

Quando você usa a AWS CLI para criar um cluster do Amazon DocumentDB, nenhuma instânciaé criada. Consequentemente, é necessário criar explicitamente uma instância principal e qualquerinstância de réplica de que precise. Você pode usar o console ou a AWS CLI para criar asinstâncias. Para obter mais informações, consulte Adding an Amazon DocumentDB Instance to aCluster (p. 252).

Para obter mais informações, consulte CreateDBCluster na Referência da API do AmazonDocumentDB.

226

https://docs.aws.amazon.com/documentdb/latest/developerguide/API_CreateDBCluster.html


Descrição dos clusters do Amazon DocumentDBVocê pode usar o Console de gerenciamento do Amazon DocumentDB ou a AWS CLI para ver detalhes,como endpoints de conexão, grupos de segurança, VPCs e grupos de parâmetros pertencentes aosclusters do Amazon DocumentDB.

Para obter mais informações, consulte as informações a seguir:

• Monitorar o status de um cluster do Amazon DocumentDB (p. 336)• Localizar os endpoints de um cluster (p. 312)


Use o procedimento a seguir para visualizar os detalhes de um cluster especificado do AmazonDocumentDB usando o console.



Tip


3. Na lista de clusters, escolha o nome do cluster do qual você deseja ver os detalhes. As informaçõessobre o cluster estão organizadas nos seguintes agrupamentos:

• Resumo — informações gerais sobre o cluster, incluindo a versão do mecanismo, o status docluster, a manutenção pendente e o status do grupo de parâmetros.

• Connectivity & Security (Conectividade e segurança) — a seção Connect (Conectar-se) lista osendpoints de conexão para conectar-se a este cluster com o shell do mongo ou com um aplicativo.A seção Security Groups (Grupos de segurança) lista os grupos de segurança associados a essecluster e suas descrições e ID da VPC.

• Configuration (Configuração) a seção Cluster details (Detalhes do cluster) — lista detalhes sobreo cluster, incluindo o nome de recurso da Amazon (ARN), o endpoint e o grupo de parâmetros docluster. Ela também lista as informações de backup do cluster, os detalhes de manutenção e asconfigurações de segurança e de rede. A seção Cluster instances (Instâncias de cluster) lista asinstâncias que pertencem a esse cluster com a função de cada instância e o status do grupo deparâmetros do cluster.

• Monitoring (Monitorar) — as métricas do Amazon CloudWatch Logs deste cluster. Para obter maisinformações, consulte Monitoramento do Amazon DocumentDB com o CloudWatch (p. 341).

• Events & tags (Eventos e tags) — a seção Recent events (Eventos recentes) lista os eventosrecentes deste cluster. O Amazon DocumentDB mantém um registro dos eventos relacionados aclusters, instâncias, snapshots, grupos de segurança e grupos de parâmetros do cluster. Essasinformações incluem a data, a hora e a mensagem associadas a cada evento. A seção Tags lista astags anexadas a este cluster.

Uso do AWS CLI

Para visualizar os detalhes de seus clusters do Amazon DocumentDB usando a AWS CLI, use o comandodescribe-db-clusters, conforme mostrado nos exemplos abaixo. Para obter mais informações,consulte DescribeDBClusters na Referência da API de gerenciamento de recursos do AmazonDocumentDB.

227


https://docs.aws.amazon.com/documentdb/latest/developerguide/API_DescribeDBClusters.html


Note

Para determinados recursos de gerenciamento, como o gerenciamento do ciclo de vidade clusters e instâncias, o Amazon DocumentDB aproveita a tecnologia operacional que écompartilhada com o Amazon RDS. O filtro filterName=engine,Values=docdb retornasomente clusters do Amazon DocumentDB.

Example

Exemplo 1: Listar todos Amazon DocumentDB em clusters

O código da AWS CLI a seguir lista os detalhes de todos os clusters do Amazon DocumentDB em umaregião.

aws docdb describe-db-clusters --filter Name=engine,Values=docdb


{ "DBClusters": [ { "AvailabilityZones": [ "us-east-1c", "us-east-1b", "us-east-1a" ], "BackupRetentionPeriod": 1, "DBClusterIdentifier": "sample-cluster-1", "DBClusterParameterGroup": "sample-parameter-group", "DBSubnetGroup": "default", "Status": "available", ... }, { "AvailabilityZones": [ "us-east-1c", "us-east-1b", "us-east-1a" ], "BackupRetentionPeriod": 1, "DBClusterIdentifier": "sample-cluster-2", "DBClusterParameterGroup": "sample-parameter-group", "DBSubnetGroup": "default", "Status": "available", ... }, { "AvailabilityZones": [ "us-east-1c", "us-east-1b", "us-east-1a" ], "BackupRetentionPeriod": 1, "DBClusterIdentifier": "sample-cluster-3", "DBClusterParameterGroup": "sample-parameter-group", "DBSubnetGroup": "default", "Status": "available", ... } ]}

228


Example

Exemplo 2: Listar todos os detalhes para um especificado Amazon DocumentDB cluster

O código da AWS CLI a seguir lista os detalhes do cluster sample-cluster.


aws docdb describe-db-clusters \ --filter Name=engine,Values=docdb \ --db-cluster-identifier sample-cluster

Para Windows:

aws docdb describe-db-clusters ^ --filter Name=engine,Values=docdb ^ --db-cluster-identifier sample-cluster


{ "DBClusters": [ { "AvailabilityZones": [ "us-east-1c", "us-east-1b", "us-east-1a" ], "BackupRetentionPeriod": 1, "DBClusterIdentifier": "sample-cluster", "DBClusterParameterGroup": "sample-parameter-group", "DBSubnetGroup": "default", "Status": "available", "EarliestRestorableTime": "2020-03-09T00:04:26.844Z", "Endpoint": "sample-cluster.node.us-east-1.docdb.amazonaws.com", "ReaderEndpoint": "sample-cluster.node.us-east-1.docdb.amazonaws.com", "MultiAZ": false, "Engine": "docdb", "EngineVersion": "3.6.0", "LatestRestorableTime": "2020-03-10T20:38:17.456Z", "Port": 27017, "MasterUsername": "<user-name>", "PreferredBackupWindow": "00:00-00:30", "PreferredMaintenanceWindow": "tue:09:50-tue:10:20", "DBClusterMembers": [ { "DBInstanceIdentifier": "sample-instance-1", "IsClusterWriter": true, "DBClusterParameterGroupStatus": "in-sync", "PromotionTier": 1 }, { "DBInstanceIdentifier": "sample-instance-2", "IsClusterWriter": false, "DBClusterParameterGroupStatus": "in-sync", "PromotionTier": 1 }, ], "VpcSecurityGroups": [ { "VpcSecurityGroupId": "sg-abcd0123", "Status": "active"

229


} ], "HostedZoneId": "ABCDEFGHIJKLMN", "StorageEncrypted": true, "KmsKeyId": "arn:aws:kms:us-east-1:123456789012:key/wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY", "DbClusterResourceId": "cluster-ABCDEFGHIJKLMNOPQRSTUVWXYZ", "DBClusterArn": "arn:aws:rds:us-east-1:123456789012:cluster:sample-cluster", "AssociatedRoles": [], "ClusterCreateTime": "2020-01-10T22:13:38.261Z", "EnabledCloudwatchLogsExports": [ "profiler" ], "DeletionProtection": true } ]}

Example

Exemplo 3: Indique detalhes específicos para um Amazon DocumentDB cluster

Para listar um subconjunto dos detalhes dos clusters usando a AWS CLI, adicione um --query queespecifica quais membros do cluster a operação describe-db-clusters deve listar. O parâmetro --db-cluster-identifier é o identificador do cluster específico do qual você deseja exibir os detalhes.Para obter mais informações, consulte Como filtrar a saída com a opção --query no Guia do usuário doAWS Command Line Interface.

O exemplo a seguir lista as instâncias em um cluster do Amazon DocumentDB.


aws docdb describe-db-clusters \ --filter Name=engine,Values=docdb \ --db-cluster-identifier sample-cluster \ --query 'DBClusters[*].[DBClusterMembers]'

Para Windows:

aws docdb describe-db-clusters ^ --filter Name=engine,Values=docdb ^ --db-cluster-identifier sample-cluster ^ --query 'DBClusters[*].[DBClusterMembers]'


[ [ [ { "DBInstanceIdentifier": "sample-instance-1", "IsClusterWriter": true, "DBClusterParameterGroupStatus": "in-sync", "PromotionTier": 1 }, { "DBInstanceIdentifier": "sample-instance-2", "IsClusterWriter": false, "DBClusterParameterGroupStatus": "in-sync", "PromotionTier": 1

230

https://docs.aws.amazon.com/cli/latest/userguide/cli-usage-output.html#controlling-output-filter


} ] ]]

Modificar um cluster do Amazon DocumentDBPara modificar um cluster, ele deve estar no estado available (disponível). Você não pode modificarum cluster interrompido. Se o cluster for interrompido, primeiro inicie-o, aguarde até que fique available(disponível) e faça as modificações desejadas. Para obter mais informações, consulte Interromper e iniciarum cluster do Amazon DocumentDB (p. 237).


Use o procedimento a seguir para modificar um cluster específico do Amazon DocumentDB usando oconsole.

Para modificar um cluster do Amazon DocumentDB



Tip


3. Especifique o cluster que você deseja modificar escolhendo o botão à esquerda do nome do cluster.4. Escolha Actions (Ações) e, em seguida, Modify (Modificar).5. No painel Modify Cluster: <cluster-name> (Modificar cluster: <nome-do-cluster>), faça as alterações

desejadas. Você pode fazer alterações nas seguintes áreas:

• Especificações do cluster — o nome, os grupos de segurança e a senha do cluster.• Opções do cluster — a porta e o grupo de parâmetros do cluster.• Backup — o período de retenção do backup e a janela de backup do cluster.• Exportações de log — habilite ou desabilite os logs de auditoria ou de profiler.• Manutenção — defina a janela de manutenção do cluster.• Proteção contra exclusão — habilite ou desabilite a proteção contra exclusão no cluster. Por padrão,

a proteção contra exclusão está habilitada.6. Ao concluir, escolha Continue (Continuar) para ver um resumo das alterações.7. Se estiver satisfeito com suas alterações, poderá escolher Modify cluster (Modificar cluster) para

modificar o cluster. Como alternativa, você pode escolher Back (Voltar) ou Cancel (Cancelar) paraeditar ou cancelar as alterações, respectivamente.

Leva alguns minutos para que suas alterações sejam aplicadas. Você pode usar o cluster somente quandoseu status for disponível. Você pode monitorar o status do cluster usando o console ou a AWS CLI. Paraobter mais informações, consulte Monitorar o status de um cluster do Amazon DocumentDB (p. 336).

Uso do AWS CLI

Use a operação modify-db-cluster para modificar o cluster especificado usando a AWS CLI. Paraobter mais informações, consulte ModifyDBCluster na Referência da API do Amazon DocumentDB.

231


https://docs.aws.amazon.com/documentdb/latest/developerguide/API_ModifyDBCluster.html


Parameters

• --db-cluster-identifier—Obrigatório. O identificador do cluster do Amazon DocumentDB quevocê modificará.

• --backup-retention-period—Opcional. O número de dias durante os quais os backupsautomatizados são retidos. Os valores válidos são 1–35.

• --db-cluster-parameter-group-name—Opcional. O nome do grupo de parâmetros do cluster aser usado para o cluster.

• --master-user-password—Opcional. A nova senha para o usuário mestre do banco de dados.

Restrições de senha:• O comprimento é de [8 a 100] caracteres ASCII imprimíveis.• Pode usar caracteres ASCII imprimíveis, exceto o seguinte:

• / (barra)• " (aspas duplas)• @ (arroba)

• --new-db-cluster-identifier—Opcional. O novo identificador do cluster durante a renomeaçãode um cluster. Esse valor é armazenado como uma string em minúsculas.

Restrições de nomenclatura:• O comprimento é de [1 a 63] letras, números ou hifens.• O primeiro caractere deve ser uma letra.• Não podem terminar com um hífen ou conter dois hífens consecutivos.• Deve ser exclusivo para todos os clusters no Amazon RDS, Amazon Neptune e Amazon DocumentDB

por conta da AWS, por região.• --preferred-backup-window—Opcional. O período diário durante o qual backups automatizados

serão criados, em formato Tempo Universal Coordenado (UTC).• Formato: hh24:mm-hh24:mm

• --preferred-maintenance-window—Opcional. O intervalo de tempo semanal durante o qual podeocorrer manutenção do sistema, em UTC.• Formato: ddd:hh24:mm-ddd:hh24:mm• Dias válidos: Sun, Mon, Tue, Wed, Thu, Frie Sat.

• --deletion-protection ou --no-deletion-protection—Opcional. Se a proteção contraexclusão deve ser habilitada neste cluster. A proteção contra exclusão impede que um cluster sejaexcluído acidentalmente até que o cluster seja modificado para desabilitar a proteção contra exclusão.Para obter mais informações, consulte Excluir um cluster do Amazon DocumentDB (p. 240).

• --apply-immediately ou --no-apply-immediately — use --apply-immediately paraaplicar a alteração imediatamente. Use --no-apply-immediately para aplicar a alteração durante apróxima janela de manutenção do cluster.

Example

O código a seguir altera o período de retenção de backup para o cluster sample-cluster.


aws docdb modify-db-cluster \ --db-cluster-identifier sample-cluster \ --apply-immediately \ --backup-retention-period 7

Para Windows:

232


aws docdb modify-db-cluster ^ --db-cluster-identifier sample-cluster ^ --apply-immediately ^ --backup-retention-period 7


{ "DBCluster": { "BackupRetentionPeriod": 7, "DbClusterResourceId": "cluster-VDP53QEWST7YHM36TTXOPJT5YE", "Status": "available", "DBClusterMembers": [ { "PromotionTier": 1, "DBClusterParameterGroupStatus": "in-sync", "DBInstanceIdentifier": "sample-cluster-instance", "IsClusterWriter": true } ], "ReadReplicaIdentifiers": [], "AvailabilityZones": [ "us-east-1b", "us-east-1c", "us-east-1a" ], "ReaderEndpoint": "sample-cluster.cluster-ro-ctevjxdlur57.us-east-1.rds.amazonaws.com", "DBClusterArn": "arn:aws:rds:us-east-1:123456789012:cluster:sample-cluster", "PreferredMaintenanceWindow": "sat:09:51-sat:10:21", "EarliestRestorableTime": "2018-06-17T00:06:19.374Z", "StorageEncrypted": false, "MultiAZ": false, "AssociatedRoles": [], "MasterUsername": "<your-master-user-name>", "DBClusterIdentifier": "sample-cluster", "VpcSecurityGroups": [ { "Status": "active", "VpcSecurityGroupId": "sg-77186e0d" } ], "HostedZoneId": "Z2SUY0A1719RZT", "LatestRestorableTime": "2018-06-18T21:17:05.737Z", "AllocatedStorage": 1, "Port": 27017, "Engine": "docdb", "DBClusterParameterGroup": "default.docdb3.4", "Endpoint": "sample-cluster.cluster-ctevjxdlur57.us-east-1.rds.amazonaws.com", "DBSubnetGroup": "default", "PreferredBackupWindow": "00:00-00:30", "EngineVersion": "3.4", "ClusterCreateTime": "2018-06-06T19:25:47.991Z", "IAMDatabaseAuthenticationEnabled": false }}

Leva alguns minutos para que suas alterações sejam aplicadas. Você pode usar o cluster somente quandoseu status for disponível. Você pode monitorar o status do cluster usando o console ou a AWS CLI. Paraobter mais informações, consulte Monitorar o status de um cluster do Amazon DocumentDB (p. 336).

233


Determinação de manutenção pendenteVocê pode determinar se você tem a versão mais recente do mecanismo do Amazon DocumentDBdeterminando se você tem a manutenção de cluster pendente.


Use o Console de gerenciamento da AWS para determinar se um cluster tem manutenção pendente



Tip


3. Localize a coluna Maintenance (Manutenção) para determinar se um cluster tem manutençãopendente.

None (Nenhum) indica que o cluster está executando a versão mais recente do mecanismo. Available(Disponível) indica que o cluster tem manutenção pendente, o que pode significar que é necessáriauma atualização do mecanismo.

4. Se o seu cluster tiver a manutenção pendente, prossiga para as etapas em Atualizar a versão demecanismo do cluster (p. 235).

Uso do AWS CLI

Você pode usar a AWS CLI para determinar se um cluster tem a versão mais recente do mecanismousando a operação describe-pending-maintenance-actions com os seguintes parâmetros.

Parameters

• --resource-identifier—Opcional. O ARN do recurso (cluster). Se esse parâmetro for omitido,ações de manutenção pendentes para todos os clusters serão listadas.

• --region—Opcional. A região da AWS na qual você deseja executar essa operação, por exemplo, us-east-1.

Example


aws docdb describe-pending-maintenance-actions \ --resource-identifier arn:aws:rds:us-east-1:123456789012:cluster:sample-cluster \ --region us-east-1

234



Para Windows:

aws docdb describe-pending-maintenance-actions ^ --resource-identifier arn:aws:rds:us-east-1:123456789012:cluster:sample-cluster ^ --region us-east-1


{ "PendingMaintenanceActions": [ { "ResourceIdentifier": "arn:aws:rds:us-east-1:123456789012:cluster:sample-cluster", "PendingMaintenanceActionDetails": [ { "Description": "New feature", "Action": "db-upgrade", "ForcedApplyDate": "2019-02-25T21:46:00Z", "AutoAppliedAfterDate": "2019-02-25T07:41:00Z", "CurrentApplyDate": "2019-02-25T07:41:00Z" } ] } ]}

Se o seu cluster tiver a manutenção pendente, prossiga para as etapas em Atualizar a versão demecanismo do cluster (p. 235).

Atualizar a versão de mecanismo do clusterSe você estiver executando uma versão anterior do mecanismo, atualize a versão do mecanismo docluster usando o Console de gerenciamento da AWS ou a AWS CLI. Você pode atualizá-la imediatamenteou durante a próxima janela de manutenção do cluster. Quando você atualizar a versão do mecanismo,seu cluster ficará inativo durante um tempo. Para determinar se seu mecanismo precisa de umaatualização, consulte Determinação de manutenção pendente (p. 234).

Para atualizar a versão de mecanismo do cluster:

• O status do cluster precisa ser disponível.• O cluster deve estar executando uma versão de mecanismo mais antiga.


O procedimento a seguir atualiza a versão de mecanismo do cluster para a versão mais recente usandoo console. Você tem a opção de atualizar imediatamente ou durante a próxima janela de manutenção docluster.


2. No painel de navegação, escolha Clusters. Na lista de clusters, escolha o botão à esquerda do clusterque você deseja atualizar. O status do cluster precisa ser disponível.

235



Tip


3. No menu Actions (Ações), escolha uma das opções a seguir. Essas opções de menu sãoselecionáveis somente se o cluster que você escolheu não está executando a versão mais recente domecanismo.

• Upgrade now (Atualizar agora) — inicia imediatamente o processo de atualização. Seu clusterficará offline por um momento, enquanto ele é atualizado para a versão mais recente domecanismo.

• Upgrade at next window (Atualizar na próxima janela) — inicia o processo de atualização durantea próxima janela de manutenção do cluster. O cluster ficará offline por um momento, enquanto éatualizado para a versão mais recente do mecanismo.

4. Quando a janela de confirmação for aberta, escolha uma das seguintes opções:• Upgrade (Atualizar) — para atualizar seu cluster para a versão mais recente do mecanismo de

acordo com a programação escolhida na etapa anterior.• Cancel (Cancelar) — para cancelar a atualização do mecanismo do cluster e continuar com a

versão do mecanismo atual do cluster.

Uso do AWS CLIVocê pode atualizar seu cluster para uma versão mais recente do mecanismo usando a AWS CLI e aoperação apply-pending-maintenance-action com os seguintes parâmetros.

Parameters

• --resource-identifier—Obrigatório. O ARN do cluster do Amazon DocumentDB que você vaiatualizar.

• --apply-action—Obrigatório. Os valores a seguir são permitidos. Para atualizar a versão demecanismo do cluster, use db-upgrade.• db-upgrade

• system-update

• --opt-in-type—Obrigatório. Os valores a seguir são permitidos.• immediate — Aplique a ação de manutenção imediatamente.• next-maintenance — aplique a ação de manutenção durante a próxima janela de manutenção.• undo-opt-in — Cancele todas as solicitações de inclusão next-maintenance existentes.

Example

O exemplo a seguir atualiza a versão do mecanismo sample-cluster para a versão 3.6.0.

236



aws docdb apply-pending-maintenance-action \ --resource-identifier arn:aws:rds:us-east-1:123456789012\:cluster:sample-cluster \ --apply-action db-upgrade \ --opt-in-type immediate

Para Windows:

aws docdb apply-pending-maintenance-action ^ --resource-identifier arn:aws:rds:us-east-1:123456789012:cluster:sample-cluster ^ --apply-action db-upgrade ^ --opt-in-type immediate


{ "ResourcePendingMaintenanceActions": { "ResourceIdentifier": "arn:aws:rds:us-east-1:444455556666:cluster:docdb-2019-01-09-23-55-38", "PendingMaintenanceActionDetails": [ { "CurrentApplyDate": "2019-02-20T20:57:06.904Z", "Description": "Bug fixes", "ForcedApplyDate": "2019-02-25T21:46:00Z", "OptInStatus": "immediate", "Action": "db-upgrade", "AutoAppliedAfterDate": "2019-02-25T07:41:00Z" } ] }}

Interromper e iniciar um cluster do Amazon DocumentDBInterromper e iniciar os clusters do Amazon DocumentDB pode ajudar a gerenciar os custos dos ambientesde teste e desenvolvimento. Em vez de criar e excluir clusters e instâncias toda vez que você usar oAmazon DocumentDB, você pode interromper temporariamente todas as instâncias em seu cluster quandonão forem necessárias. Depois, é possível iniciá-las novamente ao retomar os testes.

Tópicos• Visão geral de como interromper e iniciar um cluster (p. 237)• Uso do Console de gerenciamento da AWS (p. 238)• Uso do AWS CLI (p. 239)• Operações que podem ser realizadas em um cluster interrompido (p. 240)

Visão geral de como interromper e iniciar um cluster

Durante os períodos em que você não precisa de um cluster do Amazon DocumentDB, você podeinterromper todas as instâncias nesse cluster de uma só vez. Depois, você pode iniciar o clusternovamente a qualquer momento, sempre que precisar usá-lo. Iniciar e interromper simplifica os processosde configuração e destruição dos clusters usados em desenvolvimento, teste ou atividades afins quenão exijam disponibilidade contínua. Você pode interromper e iniciar um cluster usando o Console degerenciamento da AWS ou a AWS CLI com uma única ação, independentemente de quantas instânciasestão no cluster.

237


Enquanto o cluster estiver interrompido, o volume de armazenamento do cluster permanece inalterado.Serão cobrados somente o armazenamento, os snapshots manuais e o armazenamento do backupautomatizado dentro da janela de retenção especificada. As horas de instância não serão cobradas. OAmazon DocumentDB inicia automaticamente seu cluster após sete dias para que ele não atrase asatualizações de manutenção necessárias. Quando o cluster iniciar após sete dias, você começará aser cobrado pelas instâncias no cluster novamente. Enquanto o cluster é interrompido, não é possívelconsultar o volume de armazenamento porque a consulta requer que as instâncias estejam no estadodisponível.

Quando um cluster do Amazon DocumentDB é interrompido, nem o cluster nem suas instâncias podem sermodificados de maneira alguma. Isso inclui adicionar ou remover instâncias, ou excluir o cluster.

Uso do Console de gerenciamento da AWSO procedimento a seguir mostra como interromper um cluster com uma ou mais instâncias no estadodisponível ou iniciar um cluster interrompido.

Como interromper ou iniciar um cluster do Amazon DocumentDB


2. No painel de navegação, escolha Clusters.Tip


3. Na lista de clusters, escolha o botão à esquerda do nome do cluster que você deseja interromper ouiniciar.

4. Escolha Actions (Ações) e selecione a ação que deseja executar no cluster.• Se você quiser interromper o cluster e o cluster estiver disponível:

a. Escolha Stop (Interromper).

Para evitar a ativação do mecanismo de failover, a operação de interrupção interrompeprimeiro as instâncias de réplica e, depois, a instância primária.

b. Na caixa de diálogo de confirmação, confirme se deseja interromper o cluster, escolhendoStop cluster (Interromper cluster) ou, para manter o cluster em execução, escolha Cancel(Cancelar).

238



• Se quiser iniciar o cluster e o cluster estiver interrompido, escolha Start (Iniciar).

5. Monitore o status do cluster e suas instâncias. Se você iniciou o cluster, poderá retomar o uso docluster quando ele e suas instâncias estiverem disponíveis. Para obter mais informações, consulteDeterminar o status de um cluster (p. 215).

Uso do AWS CLI

Os exemplos de código a seguir mostram como interromper um cluster com uma ou mais instâncias noestado disponível ou iniciar um cluster interrompido.

Para interromper um cluster com uma ou mais instâncias disponíveis usando a AWS CLI, use a operaçãostop-db-cluster. Para iniciar um cluster interrompido, use a operação start-db-cluster. Ambas asoperações usam o parâmetro --db-cluster-identifier.

Parâmetro:

• --db-cluster-identifier—Obrigatório. O nome do cluster a ser interrompido ou iniciado.

Example — para interromper um cluster usando a AWS CLI

O código seguinte pára o cluster sample-cluster. O grupo tem de ter uma ou mais instâncias no estadodisponível.


aws docdb stop-db-cluster \ --db-cluster-identifier sample-cluster

Para Windows:

aws docdb stop-db-cluster ^ --db-cluster-identifier sample-cluster

Example — para iniciar um cluster usando a AWS CLI

O código seguinte inicia o cluster sample-cluster. O cluster tem de estar parado de momento.

239



aws docdb start-db-cluster \ --db-cluster-identifier sample-cluster

Para Windows:

aws docdb start-db-cluster ^ --db-cluster-identifier sample-cluster

Operações que podem ser realizadas em um cluster interrompidoCom um cluster de banco de dados do Amazon DocumentDB interrompido, você pode executar umarestauração point-in-time para qualquer ponto dentro da janela de retenção especificada para o backupautomático. Para obter detalhes sobre como realizar uma restauração point-in-time, consulte Restauraçãopoint-in-time (p. 201).

Não é possível modificar a configuração de um cluster do Amazon DocumentDB, ou de qualquer uma desuas instâncias, enquanto o cluster estiver interrompido. Também não é possível adicionar ou removerinstâncias do cluster ou excluir o cluster, caso ainda tenha alguma instância associada. Você deverá iniciaro cluster antes de realizar uma dessas ações administrativas.

O Amazon DocumentDB aplicará as manutenções programadas em seu cluster interrompido somentedepois que ele for reiniciado. Após sete dias, o Amazon DocumentDB inicia automaticamente um clusterinterrompido para que não fique muito atrasado em seu status de manutenção. Quando o cluster forreiniciado, você começará a ser cobrado pelas instâncias no cluster novamente.

Enquanto um cluster estiver interrompido, o Amazon DocumentDB não executa quaisquer backupsautomatizados nem estende o período de retenção de backup.

Excluir um cluster do Amazon DocumentDBÉ possível excluir um cluster do Amazon DocumentDB usando o Console de gerenciamento da AWS oua AWS CLI. Para excluir um cluster, o cluster deve estar no estado disponível e não deve ter nenhumainstância associada a ele. Se o cluster foi interrompido, primeiro inicie-o, aguarde até que fique available(disponível) e exclua-o. Para obter mais informações, consulte Interromper e iniciar um cluster do AmazonDocumentDB (p. 237).

Proteção contra exclusãoPara proteger seu cluster contra a exclusão acidental, você pode habilitar a proteção contra exclusão. Aproteção contra exclusão está habilitada por padrão ao criar um cluster usando o console. No entanto, aproteção contra exclusão será desabilitada por padrão, se você criar um cluster usando a AWS CLI.

O Amazon DocumentDB aplicará a proteção contra exclusão para um cluster se você executar a operaçãode exclusão usando o console ou a AWS CLI. Se a proteção contra exclusão estiver habilitada, não serápossível excluir um cluster. Para excluir um cluster com a projeção contra exclusão habilitada, primeiro énecessário modificar o cluster e desabilitar a proteção contra exclusão.

Ao usar o console com a proteção contra exclusão habilitada em um cluster, não será possível excluir aúltima instância do cluster, pois isso também excluirá o cluster. Você pode excluir a última instância deum cluster protegido contra exclusão usando a AWS CLI. No entanto, o cluster em si ainda existirá e seusdados serão preservados. Você pode acessar os dados criando novas instâncias para o cluster. Para obtermais informações sobre como habilitar e desabilitar a proteção contra exclusão, consulte:

• Criação de um cluster do Amazon DocumentDB (p. 217)• Modificar um cluster do Amazon DocumentDB (p. 231)

240


Excluir um cluster do Amazon DocumentDB usando a Console de gerenciamentoda AWSPara excluir um cluster usando o Console de gerenciamento da AWS, a proteção contra exclusão deveráestar desabilitada.

Para determinar se um cluster está com a proteção contra exclusão habilitada:


2. No painel de navegação, escolha Clusters.Tip


3. Escolha o nome do cluster e selecione a guia Configuration (Configuração). Na seção Cluster details(Detalhes do cluster) localize Deletion protection (Proteção contra exclusão). Se a proteção contraexclusão estiver habilitada, modifique o cluster para desabilitar a proteção contra exclusão. Paraobter informações sobre como modificar um cluster, consulte Modificar um cluster do AmazonDocumentDB (p. 231).

Após desabilitar a Deletion protection (Proteção contra exclusão), você estará pronto para excluir ocluster.

Para excluir um cluster:

1. No painel de navegação, escolha Clusters.2. Determine se o cluster tem alguma instância verificando a coluna Instances (Instâncias). Para excluir

um cluster, é necessário excluir todas as instâncias. Para obter mais informações, consulte Deletingan Amazon DocumentDB Instance (p. 263).

3. Dependendo de o cluster ter ou não instâncias, realize uma das seguintes etapas.• Se o cluster não tiver instâncias, selecione o botão à esquerda do nome do cluster e escolha

Actions (Ações). No menu suspenso, escolha Delete (Excluir). Preencha a caixa de diálogo Delete<cluster-name> (Excluir <nome-cluster>) e escolha Delete (Excluir).

• Se o cluster tiver uma ou mais instâncias, faça o seguinte:

a. No painel de navegação, escolha Instances (Instâncias).b. Exclua cada uma das instâncias do cluster. Ao excluir a última instância, o cluster também

será excluído. Para obter informações sobre como excluir instâncias, consulte Deleting anAmazon DocumentDB Instance (p. 263).

A exclusão do cluster demora alguns minutos. Para monitorar o status do cluster, consulte Monitorar ostatus de um cluster do Amazon DocumentDB (p. 336).

Excluir um cluster do Amazon DocumentDB usando a AWS CLINão é possível excluir um cluster que tenha instâncias associadas a ele. Para determinar quais instânciasestão associadas ao cluster, execute o comando describe-db-clusters e exclua todas as instânciasdo cluster. Depois, se necessário, desabilite a proteção contra exclusão no cluster e, finalmente, exclua ocluster.

1. Primeiro, exclua todas as instâncias do cluster.

Para determinar quais instâncias você precisa excluir, execute o comando a seguir.

241



aws docdb describe-db-clusters \ --db-cluster-identifier sample-cluster \ --query 'DBClusters[*].[DBClusterIdentifier,DBClusterMembers[*].DBInstanceIdentifier]'


[ [ "sample-cluster", [ "sample-instance-1", "sample-instance-2" ] ]]

Se o cluster que você deseja excluir tiver uma instância, exclua-a antes de continuar.

aws docdb delete-db-instance \ --db-instance-identifier sample-instance

2. Depois, desabilite a proteção contra exclusão.

Usar a AWS CLI para excluir todas as instâncias de um cluster não excluirá o cluster. Tambémé necessário excluir o cluster, mas isso só poderá ser feito se a proteção contra exclusão estiverdesabilitada.

Para determinar se o cluster está com a proteção contra exclusão habilitada, execute o comando aseguir.

Tip

Para ver o status da proteção contra exclusão de todos os clusters do Amazon DocumentDB,omita o parâmetro --db-cluster-identifier.

aws docdb describe-db-clusters \ --db-cluster-identifier sample-cluster \ --query 'DBClusters[*].[DBClusterIdentifier,DeletionProtection]'


[ [ "sample-cluster", "true" ]]

Se o cluster estiver com a proteção contra exclusão habilitada, modifique o cluster e desabilite aproteção contra exclusão. Para desabilitar a proteção contra exclusão no cluster, use o comando aseguir.

aws docdb modify-db-cluster \ --db-cluster-identifier sample-cluster \

242


--no-deletion-protection \ --apply-immediately

3. Finalmente, exclua o cluster.

Após desabilitar a proteção contra exclusão, você estará pronto para excluir o cluster. Para excluir umcluster, use a operação delete-db-cluster com os parâmetros a seguir.

• --db-cluster-identifier—Obrigatório. O identificador do cluster que deseja excluir.• --final-db-snapshot-identifier—Opcional. Se você desejar um snapshot final, inclua

esse parâmetro com um nome para o snapshot final. Você deve incluir --final-db-snapshot-identifier ou --skip-final-snapshot.

Restrições de nomenclatura:• O comprimento é de [1 a 63] letras, números ou hifens.• O primeiro caractere deve ser uma letra.• Não podem terminar com um hífen ou conter dois hífens consecutivos.• Deve ser exclusivo para todos os clusters no Amazon RDS, Amazon Neptune e Amazon

DocumentDB por conta da AWS, por região.• --skip-final-snapshot—Opcional. Use esse parâmetro somente se você não quiser obter um

snapshot final antes de excluir seu cluster. A configuração padrão é obter um snapshot final. Vocêdeve incluir --final-db-snapshot-identifier ou --skip-final-snapshot.

O seguinte código da AWS CLI exclui o cluster sample-cluster com um snapshot final. Aoperação falhará se houver instâncias associadas ao cluster ou se a proteção contra exclusão estiverdesabilitada.

Example


aws docdb delete-db-cluster \ --db-cluster-identifier sample-cluster \ --final-db-snapshot-identifier sample-cluster-final-snapshot

Para Windows:

aws docdb delete-db-cluster ^ --db-cluster-identifier sample-cluster ^ --final-db-snapshot-identifier sample-cluster-final-snapshot

Example

O seguinte código da AWS CLI exclui o cluster sample-cluster sem realizar um snapshot final.


aws docdb delete-db-cluster \ --db-cluster-identifier sample-cluster \ --skip-final-snapshot

Para Windows:

aws docdb delete-db-cluster ^ 243

Amazon DocumentDB Guia do desenvolvedorDimensionar clusters do Amazon DocumentDB

--db-cluster-identifier sample-cluster ^ --skip-final-snapshot

A saída da operação delete-db-cluster é o cluster que você está excluindo.

A exclusão do cluster demora alguns minutos. Para monitorar o status do cluster, consulte Monitorar ostatus de um cluster (p. 336).

Dimensionar clusters do Amazon DocumentDBO Amazon DocumentDB permite dimensionar o armazenamento e a computação nos clusters com baseem suas necessidades. Esta seção descreve como você pode usar a escalabilidade de armazenamento, aescalabilidade de instâncias e a escalabilidade de leitura para gerenciar o desempenho e a escalabilidadedos clusters e das instâncias do Amazon DocumentDB.

Tópicos• Escalabilidade de armazenamento (p. 244)• Escalabilidade de instâncias (p. 244)• Escalabilidade de leitura (p. 244)• Escalabilidade de gravação (p. 245)

Escalabilidade de armazenamentoO armazenamento do Amazon DocumentDB escala automaticamente com os dados no volume do cluster.À medida que seu volume de dados aumenta, o armazenamento do volume do cluster aumentará emincrementos de 10 GiB, até 64 TiB.

Escalabilidade de instânciasVocê pode dimensionar o cluster do Amazon DocumentDB conforme o necessário modificando a classeda instância para cada instância no cluster. O Amazon DocumentDB oferece suporte a diversas classes dainstância que são otimizadas para o Amazon DocumentDB.

Para obter mais informações, consulte Modifying an Amazon DocumentDB Instance (p. 259).

Escalabilidade de leituraVocê pode obter uma escalabilidade de leitura para o cluster do Amazon DocumentDB criando até 15réplicas do Amazon DocumentDB no cluster. Cada réplica do Amazon DocumentDB retorna os mesmosdados do volume de cluster com atraso de réplica mínimo — geralmente inferior a 100 milissegundosapós a instância principal ter gravado uma atualização. À medida que o tráfego de leitura aumenta, vocêpode criar réplicas adicionais do Amazon DocumentDB e conectar-se a elas diretamente para distribuir acarga de leitura para o cluster. As réplicas do Amazon DocumentDB não precisam ser da mesma classe deinstância que a instância principal.

Para obter mais informações, consulte Adding an Amazon DocumentDB Instance to a Cluster (p. 252).

Para o dimensionamento da leitura com o Amazon DocumentDB, recomendamos estabelecer a conexãocom o cluster como um conjunto de réplicas e distribuir as leituras para as instâncias de réplica usando osrecursos internos de preferência de leitura do driver. Para obter mais informações, consulte Conectar-se aoAmazon DocumentDB como um conjunto de réplicas (p. 384).

244

Amazon DocumentDB Guia do desenvolvedorDimensionar clusters do Amazon DocumentDB

Escalabilidade de gravaçãoÉ possível dimensionar a capacidade de gravação no cluster do Amazon DocumentDB aumentando otamanho da instância principal do cluster. Esta seção fornece dois métodos para dimensionar a instânciaprincipal do cluster com base em suas necessidades. A primeira opção procura minimizar o impacto noaplicativo, mas exige que mais etapas sejam concluídas. A segunda opção otimiza a simplicidade, pois temmenos etapas, mas, em compensação, o possível impacto no aplicativo é maior.

Dependendo do aplicativo, você pode escolher qual abordagem a seguir é a melhor para você. Para obtermais informações sobre custos e tamanhos de instância disponíveis, consulte a página Definição de preçodo Amazon DocumentDB.

1. Otimizar para alta disponibilidade e desempenho — Se estiver se conectando ao cluster no modo deconjunto de réplicas (p. 384) (recomendado), você poderá usar o processo a seguir para minimizaro impacto no aplicativo ao dimensionar a instância principal. Esse método minimiza o impacto porquemantém o cluster em ou acima da alta disponibilidade, e os destinos de escalabilidade de leitura sãoadicionados ao cluster como instâncias, em vez de serem atualizados no local.

a. Adicione uma ou mais réplicas do tipo de instância maior ao cluster (consulte ??? (p. 252)).Recomendamos que todas as réplicas sejam do mesmo tipo de instância ou maior que a principal.Isso evita que uma redução não intencional no desempenho de gravação execute failover paraum tipo de instância menor. Para a maioria dos clientes, isso significa duplicar temporariamenteo número de instâncias no cluster e, depois, remover as réplicas menores após a conclusão daescalabilidade.

b. Defina o nível de failover em todas as réplicas novas como prioridade zero, garantindo queuma réplica do tipo de instância menor tenha a maior prioridade de failover. Para obter maisinformações, consulte ??? (p. 278).

c. Inicie um failover manual, o que promoverá uma das novas réplicas a instância principal. Paraobter mais informações, consulte ??? (p. 279).

Note

Isso incorrerá em aproximadamente 30 segundos de tempo de inatividade para o cluster.Planeje adequadamente.

d. Remova do cluster todas as réplicas de um tipo de instância menor que a nova principal.e. Defina o nível de failover de todas as instâncias de volta para a mesma prioridade (geralmente,

isso significa defini-las de volta para 1).

Como exemplo, vamos supor que você tenha um cluster com três instâncias r5.large (umaprincipal e duas réplicas) e que deseja dimensionar para um tipo de instância r5.xlarge. Parafazer isso, primeiro adicione três instâncias de réplica r5.xlarge ao cluster e defina o nível defailover das novas réplicas r5.xlarge como zero. Depois, inicie um failover manual (considerandoque o aplicativo terá aproximadamente 30 segundos de tempo de inatividade). Quando o failoverfor concluído, remova todas as três instâncias r5.large do cluster, deixando-o dimensionado parainstâncias r5.xlarge.

Para otimizar os custos, as instâncias do Amazon DocumentDB são cobradas em incrementos de umsegundo, com uma cobrança mínima de dez minutos, após uma alteração no status faturável, comocriação, modificação ou exclusão de uma instância. Para obter mais informações, consulte Otimizaçãode custo (p. 57) na documentação de melhores práticas.

2. Otimizar para maior simplicidade — Essa abordagem otimiza em termos de simplicidade. Ela nãoexpande e contrai o cluster, mas pode reduzir temporariamente a sua capacidade de leitura.

É possível que a alteração da classe de instância de uma réplica resulte nessa instância que não sirvapedidos durante um breve período de tempo, de alguns segundos para menos de 30 segundos. Seestiver a ligar ao seu cluster em modo de configuração de réplicas (p. 384) (recomendado), isso

245



Amazon DocumentDB Guia do desenvolvedorNoções básicas de tolerância a falhas

reduziria a sua capacidade de leitura em uma réplica (por exemplo, para 66% de capacidade emum cluster de 3 nós, ou 75% de capacidade em um cluster de 4 nós, etc.) durante a operação dedimensionamento.

a. Escalar uma das instâncias réplica no seu cluster. Para obter mais informações, consulteManaging Instance Classes (p. 247).

b. Aguarde até a instância estar disponível (consulte Monitorar o status de uma instância do AmazonDocumentDB (p. 338)).

Note

Isso incorrerá em aproximadamente 30 segundos de tempo de inatividade para o cluster.Planeje adequadamente.

c. Continue a executar os passos 1 e 2 até que todas as réplicas tenham sido escaladas, uma auma.

d. Iniciar uma ativação pós-falha manual. Isto irá promover uma das réplicas para queseja a instância principal. Para obter mais informações, consulte Failover do AmazonDocumentDB (p. 278).

Note

Isto irá incorrer em até 30 segundos de tempo de inatividade do seu cluster, mas muitasvezes demora menos tempo do que isso. Planeje adequadamente.

e. Escalar a instância primária anterior (agora uma réplica).

Noções básicas de tolerância a falhas do cluster doAmazon DocumentDBOs clusters do Amazon DocumentDB são tolerantes a falhas por projeto. O volume de cada clusterabrange várias zonas de disponibilidade em uma única região da AWS, e cada zona de disponibilidadecontém uma cópia dos dados de volume do cluster. Esta funcionalidade significa que seu cluster podetolerar a falha de uma zona de disponibilidade sem perder dados, apenas uma breve interrupção doserviço.

Se a instância primária num cluster falhar, Amazon DocumentDB executa automaticamente uma ativaçãopós-falha para uma nova instância primária de duas formas:

• Ao promover um Amazon DocumentDB réplica para a nova instância primária escolhida com base nadefinição de Nível de Promoção de cada réplica e, em seguida, criando um substituto para o primeiroprincipal. Uma ativação pós-falha para a instância réplica demora normalmente menos de 30 segundos.As operações de leitura e escrita podem sofrer uma breve interrupção durante este período. Paraaumentar a disponibilidade do seu cluster, recomendamos que você crie pelo menos uma ou maisréplicas do Amazon DocumentDB em duas ou mais zonas de disponibilidade diferentes.

• Criando uma nova instância principal. Isto só acontece se não tiver uma instância réplica no seu clustere pode demorar alguns minutos a concluir.

Se o cluster tiver uma ou mais réplicas do Amazon DocumentDB, uma réplica do Amazon DocumentDBserá promovida à instância principal durante um evento de falha. Um evento de falha resulta em umabreve interrupção, durante a qual as operações de leitura e gravação falham com uma exceção. Noentanto, o serviço é restaurado normalmente em menos de 120 segundos e muitas vezes em menos de 60segundos. Para aumentar a disponibilidade do seu cluster, recomendamos que você crie pelo menos umaou mais réplicas do Amazon DocumentDB em duas ou mais zonas de disponibilidade diferentes.

Você pode personalizar a ordem em que suas réplicas do Amazon DocumentDB são promovidas àinstância primária após uma falha, atribuindo uma prioridade a cada réplica. As prioridades variam de 0

246

Amazon DocumentDB Guia do desenvolvedorManaging Instances

para a prioridade mais alta a 15 para a prioridade mais baixa. Se a instância principal falhar, a réplica doAmazon DocumentDB com a prioridade mais alta será promovida à nova instância principal. É possívelmodificar a prioridade de uma réplica do Amazon DocumentDB a qualquer momento. Modificar a prioridadenão desencadeia um failover. Você pode usar a operação modify-db-instance com o parâmetro --promotion-tier. Para obter mais informações sobre como personalizar a prioridade de failover de umainstância, consulte Failover do Amazon DocumentDB (p. 278).

A mesma prioridade pode ser compartilhada por mais de uma réplica do Amazon DocumentDB, resultandoem níveis de promoção. Se duas ou mais réplicas do Amazon DocumentDB compartilharem a mesmaprioridade, a réplica que for maior será promovida à principal. Se duas ou mais réplicas do AmazonDocumentDB compartilharem a mesma prioridade e o mesmo tamanho, será promovida uma réplicaarbitrária no mesmo nível de promoção.

Se o cluster não contiver quaisquer réplicas do Amazon DocumentDB, a instância principal será recriadadurante um evento de falha. Um evento de falha resulta em uma interrupção durante a qual as operaçõesde leitura e gravação falham com uma exceção. O serviço é reestabelecido quando a nova instânciaprimária é criada, o que normalmente leva menos de 10 minutos. Promover uma réplica do AmazonDocumentDB à instância primária é muito mais rápido do que criar uma nova instância primária.

Managing Amazon DocumentDB InstancesOs tópicos a seguir fornecem informações para ajudar a gerenciar as instâncias do Amazon DocumentDB.Eles incluem detalhes sobre classes e status de instâncias e como criar, excluir e modificar uma instância.

Tópicos• Managing Instance Classes (p. 247)• Determining an Instance's Status (p. 251)• Amazon DocumentDB Instance Lifecycle (p. 251)

Managing Instance ClassesA classe de instância determina a capacidade de computação e de memória de uma instância do AmazonDocumentDB (compatível com MongoDB). A classe de instância da qual você precisa depende dosrequisitos de energia e memória de processamento.

Amazon DocumentDB suporta as classes de casos R4, R5 e T3. Essas classes são de instânciasda geração atual que são otimizadas para aplicativos com uso intensivo de memória. Para obter asespecificações dessas classes, consulte Instance Class Specifications (p. 250).

Tópicos• Determining an Instance's Class (p. 247)• Changing an Instance's Class (p. 249)• Supported Instance Classes by Region (p. 249)• Instance Class Specifications (p. 250)

Determining an Instance's ClassPara determinar a classe de uma instância, você pode usar a operação describe-db-instances daAWS CLI ou o Console de gerenciamento da AWS.

247

Amazon DocumentDB Guia do desenvolvedorManaging Instance Classes


Para determinar a classe de instância para as instâncias do seu grupo, realize os seguintes passos naconsola.


2. No painel de navegação, escolha Instâncias para encontrar a instância em que está interessado em.Tip


3. Na lista de instâncias, localize a instância desejada. Depois, observe o Classe coluna da linha dainstância para ver a classe de instância.

Na imagem a seguir, a classe da instância docdb-2019-05-13-20-51-52 é db.r5.4xlarge.

Using the AWS CLI

Para determinar a classe de uma instância com a AWS CLI, use a operação describe-db-instancescom os seguintes parâmetros.

• --db-instance-identifier — Optional. Specifies the instance that you want to find the instanceclass for. If this parameter is omitted, describe-db-instances returns a description for up to 100 ofyour instances.

• --query — Optional. Specifies the members of the instance to include in the results. If this parameter isomitted, all instance members are returned.

Example

O exemplo seguinte encontra o nome da instância e classe para a instância sample-instance-1.


aws docdb describe-db-instances \ --query 'DBInstances[*].[DBInstanceIdentifier,DBInstanceClass]' \ --db-instance-identifier sample-instance-1

Para Windows:

248



aws docdb describe-db-instances ^ --query 'DBInstances[*].[DBInstanceIdentifier,DBInstanceClass]' ^ --db-instance-identifier sample-instance-1


[ [ "sample-instance-1", "db.r5.large" ]

Example

O exemplo seguinte encontra o nome da instância e a turma até 100 Amazon DocumentDB instâncias.


aws docdb describe-db-instances \ --query 'DBInstances[*].[DBInstanceIdentifier,DBInstanceClass]' \ --filter Name=engine,Values=docdb

Para Windows:

aws docdb describe-db-instances ^ --query 'DBInstances[*].[DBInstanceIdentifier,DBInstanceClass]' ^ --filter Name=engine,Values=docdb


[ [ "sample-instance-1", "db.r5.large" ], [ "sample-instance-2", "db.r5.large" ], [ "sample-instance-3", "db.r5.4xlarge" ], [ "sample-instance-4", "db.r5.4xlarge" ]]

Para obter mais informações, consulte Describing Amazon DocumentDB Instances (p. 256).

Changing an Instance's ClassVocê pode alterar a classe de instância da sua instância usando o Console de gerenciamento da AWS oua AWS CLI. Para obter mais informações, consulte Modifying an Amazon DocumentDB Instance (p. 259).

Supported Instance Classes by RegionO Amazon DocumentDB oferece suporte às classes de instância a seguir:

249


• R5—Latest generation of memory-optimized instances that provide up to 100% better performance overR4 instances for the same instance cost.

• R4—Previous generation of memory-optimized instances.• T3—Latest-generation low cost burstable general-purpose instance type that provides a baseline level of

CPU performance with the ability to burst CPU usage at any time for as long as required.

Para obter especificações dessas classes de instância, consulte Instance Class Specifications (p. 250).

Uma classe de instância específica pode ou não ser suportada numa determinada Região. A tabelaseguinte especifica que classes de instância são suportadas por Amazon DocumentDB em cada Região.

Classes de instância compatíveis por região

Região R5 R4 T3

Leste dos EUA (Ohio) Compatível Compatível Compatível

Leste dos EUA (Norte daVirgínia)

Compatível Compatível Compatível

Oeste dos EUA (Oregon) Compatível Compatível Compatível

Ásia Pacífico (Mumbai) Compatível Compatível

Ásia-Pacífico (Seul) Compatível Compatível

Ásia-Pacífico (Sydney) Compatível Compatível

Ásia-Pacífico (Cingapura) Compatível Compatível

Ásia-Pacífico (Tóquio) Compatível Compatível

Canadá (Central) Compatível Compatível

Europa (Frankfurt) Compatível Compatível

Europa (Irlanda) Compatível Compatível Compatível

Europa (Londres) Compatível Compatível

Europa (Paris) Compatível Compatível

AWS GovCloud (US) Compatível Compatível

Instance Class SpecificationsA tabela a seguir fornece detalhes das classes de instância do Amazon DocumentDB. Você podeencontrar explicações para cada coluna da tabela abaixo da tabela.

Classes de instância do Amazon DocumentDB compatíveis

Instance class vCPU1 ECU2 Memória (GiB)3 Largura de bandamáx. (Mbps)4

Desempenho darede5

R5 – Current Generation Memory-Optimized Instance Class

db.r5.large 2. 10 16 Até 3.500 Até 10 Gbps

db.r5.xlarge 4. 19 32 Até 3.500 Até 10 Gbps

250

Amazon DocumentDB Guia do desenvolvedorDetermining an Instance's Status

Instance class vCPU1 ECU2 Memória (GiB)3 Largura de bandamáx. (Mbps)4

Desempenho darede5

db.r5.2xlarge 8. 38 : 64 Até 3.500 Até 10 Gbps

db.r5.4xlarge 16 71 128 3.500 Até 10 Gbps

db.r5.12xlarge 48 173 384 7.000 10 Gbps

db.r5.24xlarge 96 347 768 14.000 25 Gbps

R4 – Current Generation Memory-Optimized Instance Class

db.r4.large 2. 7 15,25 437 Até 10 Gbps

db.r4.xlarge 4. 13,5 30,5 875 Até 10 Gbps

db.r4.2xlarge 8. 27 61 875 Até 10 Gbps

db.r4.4xlarge 16 53 122 875 Até 10 Gbps

db.r4.8xlarge 32 99 244 875 10 Gbps

db.r4.16xlarge : 64 195 488 14,000 25 Gbps

T3 – Latest Generation Burstable Performance Instance Classes

db.t3.medium 2. Variável 4. Até 1.536 Até 5 Gbps

1. vCPU — O número de unidades de processamento central (cpus). CPU virtual é uma unidadede capacidade que pode ser usada para comparar classes de instância. Em vez de comprar oualugar um determinado processador para usar durante vários meses ou anos, você está alugando acapacidade de acordo com a hora. Nossa meta é fornecer uma quantidade consistente de capacidadeda CPU independentemente do hardware subjacente real.

2. ECU — A medida relativa da potência de processamento inteiro de um Amazon Elastic ComputeCloud (Amazon EC2) instância. Para que os desenvolvedores tenham facilidade ao comparar acapacidade da CPU entre diferentes classes de instância, definimos uma unidade computacional doAmazon EC2. A quantidade de CPU que é alocada para determinada instância é expressa em termosdessas unidades computacionais (ECUs) do EC2. No momento, uma ECU fornece a capacidade deCPU equivalente a de um processador 2007 Xeon ou 2007 Opteron de 1,1 a 1,2 GHz.

3. Memory (GiB) — A RAM, em gigabytes, que é atribuída à instância. Geralmente, há uma proporçãoconsistente entre a memória e a vCPU.

4. Max. bandwidth (Mbps) — A largura de banda máxima em megabits por segundo. Divida em oito paraobter a taxa de transferência esperada em megabytes por segundo.

5. Network performance — A velocidade da rede relativamente a outras classes de instância.

Determining an Instance's StatusPara ver os status válidos da instância, seus significados e como determinar o status de suas instâncias,consulte Monitorar o status de uma instância do Amazon DocumentDB (p. 338).

Amazon DocumentDB Instance LifecycleO ciclo de vida de uma instância do Amazon DocumentDB inclui a criação, a modificação, a manutenção ea atualização, a realização de backups e restaurações, a reinicialização e a exclusão dessa instância. Estaseção fornece informações sobre como concluir esses processos.

251

Amazon DocumentDB Guia do desenvolvedorInstance Lifecycle

Tópicos• Adding an Amazon DocumentDB Instance to a Cluster (p. 252)• Describing Amazon DocumentDB Instances (p. 256)• Modifying an Amazon DocumentDB Instance (p. 259)• Rebooting an Amazon DocumentDB Instance (p. 261)• Deleting an Amazon DocumentDB Instance (p. 263)

Adding an Amazon DocumentDB Instance to a ClusterVocê pode criar uma nova instância do Amazon DocumentDB usando o Console de gerenciamento daAWS ou a AWS CLI. Para adicionar uma instância a um cluster, o grupo deve estar num available estado.Não é possível adicionar uma instância a um cluster que foi interrompido. Se o grupo for parado, comeceprimeiro o grupo, aguarde que o grupo se torne availablee depois adicione uma instância. Para obter maisinformações, consulte Interromper e iniciar um cluster do Amazon DocumentDB (p. 237).

Note

Se você criar um cluster do Amazon DocumentDB usando o console, uma instância será criadaautomaticamente para você ao mesmo tempo. Se você deseja criar instâncias adicionais, use umdos procedimentos a seguir.

Adding an Instance Using the Console de gerenciamento da AWS

Use o procedimento a seguir para criar uma instância para o cluster usando o console do AmazonDocumentDB.



Tip


3. Para escolher o cluster ao qual você deseja adicionar uma instância, selecione o botão à esquerda donome do cluster.

4. Escolha Actions (Ações) e escolha Add instances (Adicionar instâncias).5. Na página Add instance to: (Adicionar instância a:)<cluster-name>, repita as etapas a seguir para cada

instância a ser adicionada ao cluster. Você pode ter até 15.

a. Instance identifier (Identificador da instância) — você pode inserir um identificador exclusivo paraessa instância ou permitir que o Amazon DocumentDB forneça o identificador da instância combase no identificador do cluster.

Restrições de nomenclatura da instância:

• Length is [1—63] letters, numbers, or hyphens.• First character must be a letter.• Cannot end with a hyphen or contain two consecutive hyphens.• Must be unique for all instances across Amazon RDS, Neptune, and Amazon DocumentDB per

AWS account, per Region.b. Instance class (Classe da instância) — na lista suspensa, escolha o tipo de instância desejado

para essa instância.

252



c. Nível de promoção — Na lista pendente, escolha o nível de promoção para a sua instância ouescolha No preference para permitir Amazon DocumentDB para definir o nível de promoção paraa sua instância. Números mais baixos significam maior prioridade. Para obter mais informações,consulte Como controlar o destino de failover (p. 278).

d. Para adicionar mais instâncias, escolha Add additional instances (Adicionar outras instâncias) erepita as etapas a, b e c.

6. Conclua a operação.

• To add the instances to your cluster, choose Create.• To cancel the operation, choose Cancel.

Leva alguns minutos para criar uma instância. Você pode usar o console ou a AWS CLI para visualizar ostatus da instância. Para obter mais informações, consulte Monitorar o status de uma instância (p. 338).

Adding an Instance Using the AWS CLI

Use a operação create-db-instance da AWS CLI com os seguintes parâmetros para criar a instânciaprimária para o cluster.

• --db-instance-class — Required. The compute and memory capacity of the instance, for example,db.m4.large. Not all instance classes are available in all AWS Regions.

• --db-instance-identifier — Required. A string that identifies the instance.

Instance Naming Constraints:• Length is [1—63] letters, numbers, or hyphens.• First character must be a letter.• Cannot end with a hyphen or contain two consecutive hyphens.• Must be unique for all instances across Amazon RDS, Neptune, and Amazon DocumentDB per AWS

account, per Region.• --engine — Required. Must be docdb.• --availability-zone — Optional. The Availability Zone that you want this instance to be created in.

Use this parameter to locate your instances in different Availability Zones to increase fault tolerance. Formore information, see Amazon DocumentDBAlta disponibilidade e replicação do (p. 276).

• --promotion-tier — Optional. The failover priority tier for this instance. Must be between 0 and15 with lower numbers being higher priority. For more information, see Como controlar o destino defailover (p. 278).

1. First, determine what Availability Zones you can create your instance in.

Se quiser especificar a zona de disponibilidade antes de criar a instância, execute o seguintecomando para determinar quais zonas de disponibilidade estão disponíveis para o cluster do AmazonDocumentDB.


aws docdb describe-db-clusters \ --query 'DBClusters[*].[DBClusterIdentifier,AvailabilityZones[*]]'

Para Windows:

aws docdb describe-db-clusters ^ --query 'DBClusters[*].[DBClusterIdentifier,AvailabilityZones[*]]'

253



[ [ "sample-cluster", [ "us-east-1c", "us-east-1b", "us-east-1a" ] ]]

2. Second, determine what instance classes you can create in your Region.

Para determinar quais classes de instância estão disponíveis na sua região, execute o seguintecomando. Na saída, escolha uma classe de instância para a instância que deseja adicionar ao clusterdo Amazon DocumentDB.


aws docdb describe-orderable-db-instance-options \ --engine docdb \ --query 'OrderableDBInstanceOptions[*].DBInstanceClass'

Para Windows:

aws docdb describe-orderable-db-instance-options ^ --engine docdb ^ --query 'OrderableDBInstanceOptions[*].DBInstanceClass'


[ "db.r5.16xlarge", "db.r5.2xlarge", "db.r5.4xlarge", "db.r5.8xlarge", "db.r5.large", "db.r5.xlarge"]

3. Finally, add an instance to your Amazon DocumentDB cluster.

Para adicionar uma instância ao cluster do Amazon DocumentDB, execute o seguinte comando.


aws docdb create-db-instance \ --db-cluster-identifier sample-cluster \ --db-instance-identifier sample-instance-2 \ --availability-zone us-east-1b \ --promotion-tier 2 \ --db-instance-class db.r5.xlarge \ --engine docdb

Para Windows:

254


aws docdb create-db-instance ^ --db-cluster-identifier sample-cluster ^ --db-instance-identifier sample-instance-2 ^ --availability-zone us-east-1b ^ --promotion-tier 2 ^ --db-instance-class db.r5.xlarge ^ --engine docdb


{ "DBInstance": { "DBInstanceIdentifier": "sample-instance-2", "DBInstanceClass": "db.r5.xlarge", "Engine": "docdb", "DBInstanceStatus": "creating", "PreferredBackupWindow": "02:00-02:30", "BackupRetentionPeriod": 1, "VpcSecurityGroups": [ { "VpcSecurityGroupId": "sg-abcd0123", "Status": "active" } ], "AvailabilityZone": "us-east-1b", "DBSubnetGroup": { "DBSubnetGroupName": "default", "DBSubnetGroupDescription": "default", "VpcId": "vpc-6242c31a", "SubnetGroupStatus": "Complete", "Subnets": [ { "SubnetIdentifier": "subnet-abcd0123", "SubnetAvailabilityZone": { "Name": "us-west-2a" }, "SubnetStatus": "Active" }, { "SubnetIdentifier": "subnet-wxyz0123", "SubnetAvailabilityZone": { "Name": "us-west-2b" }, "SubnetStatus": "Active" } ] }, "PreferredMaintenanceWindow": "sun:11:35-sun:12:05", "PendingModifiedValues": {}, "EngineVersion": "3.6.0", "AutoMinorVersionUpgrade": true, "PubliclyAccessible": false, "DBClusterIdentifier": "sample-cluster", "StorageEncrypted": true, "KmsKeyId": "arn:aws:kms:us-east-1:<accountID>:key/sample-key", "DbiResourceId": "db-ABCDEFGHIJKLMNOPQRSTUVWXYZ", "CACertificateIdentifier": "rds-ca-2019", "PromotionTier": 2, "DBInstanceArn": "arn:aws:rds:us-east-1:<accountID>:db:sample-instance-2" }}

255


Leva alguns minutos para criar a instância. Você pode usar o console ou a AWS CLI para visualizar ostatus da instância. Para obter mais informações, consulte Monitorar o status de uma instância do AmazonDocumentDB (p. 338).

Describing Amazon DocumentDB InstancesVocê pode usar o Console de gerenciamento do Amazon DocumentDB ou a AWS CLI para ver detalhescomo endpoints de conexão, VPCs de grupos de segurança, autoridade de certificação e grupos deparâmetros pertencentes às suas instâncias do Amazon DocumentDB.


Para visualizar os detalhes de suas instâncias usando o Console de gerenciamento da AWS, siga asetapas abaixo.


2. No painel de navegação, escolha Instances (Instâncias).

Tip


3. Na lista de instâncias, escolha o nome da instância da qual você deseja ver os detalhes. Asinformações sobre a instância são organizadas nos seguintes agrupamentos:

• Summary—General information about the instance, including the engine version, class, status, andany pending maintenance.

• Connectivity & Security —The Connect section lists the connection endpoints to connect to thisinstance with the mongo shell or with an application. The Security Groups section lists the securitygroups associated with this instance and their VPC ID and descriptions.

• Configuration—The Details section lists the configurations and status of the instance, including theinstance's Amazon Resource Name (ARN), endpoint, role, class, and certificate authority. It also liststhe instance's security and network settings, and backup information. The Cluster details sectionlists the details of the cluster that this instance belongs to. The Cluster instances section lists all theinstances that belong to your cluster with each instance's role and cluster parameter group status.

Note

You can modify the cluster associated with your instance by selecting Modify next tothe Cluster details header. For more information, see Modificar um cluster do AmazonDocumentDB (p. 231).

• Monitoring—The CloudWatch Logs metrics for this instance. For more information, seeMonitoramento do Amazon DocumentDB com o CloudWatch (p. 341).

• Events & tags —The Recent events section lists the recent events for this instance. AmazonDocumentDB keeps a record of events that relate to your clusters, instances, snapshots, securitygroups, and cluster parameter groups. This information includes the date, time, and messageassociated with each event. The<guilablel>Tags</guilablel>section lists the tags attached to this cluster. For more information, see Marcar recursos do AmazonDocumentDB (p. 321).

256



Using the AWS CLI

Para visualizar os detalhes de suas instâncias do Amazon DocumentDB usando a AWS CLI, use ocomando describe-db-clusters conforme mostrado nos exemplos abaixo. Para mais informações,consulte DescribeDBInstances no Amazon DocumentDB Resource Management API Reference.

1. List all Amazon DocumentDB instances.

O código da AWS CLI a seguir lista os detalhes de todas as instâncias do Amazon DocumentDB emuma região.


aws docdb describe-db-instances \ --filter Name=engine,Values=docdb

Para Windows:

aws docdb describe-db-instances \ --filter Name=engine,Values=docdb

2. List all details for a specified Amazon DocumentDB instance

O código seguinte lista os detalhes para sample-cluster-instance. Incluindo o --db-instance-identifier o parâmetro com o nome de uma instância restringe a saída parainformação nessa instância específica.


aws docdb describe-db-instances \ --db-instance-identifier sample-cluster-instance

Para Windows:

aws docdb describe-db-instances \ --db-instance-identifier sample-cluster-instance


{ "DBInstances": [ { "DbiResourceId": "db-BJKKB54PIDV5QFKGVRX5T3S6GM", "DBInstanceArn": "arn:aws:rds:us-east-1:012345678901:db:sample-cluster-instance-00", "VpcSecurityGroups": [ { "VpcSecurityGroupId": "sg-77186e0d", "Status": "active" } ], "DBInstanceClass": "db.r5.large", "DBInstanceStatus": "creating", "AutoMinorVersionUpgrade": true, "PreferredMaintenanceWindow": "fri:09:32-fri:10:02", "BackupRetentionPeriod": 1, "StorageEncrypted": true, "DBClusterIdentifier": "sample-cluster", "EngineVersion": "3.6.0",

257

https://docs.aws.amazon.com/documentdb/latest/developerguide/API_DescribeDBInstances.html


"AvailabilityZone": "us-east-1a", "Engine": "docdb", "PromotionTier": 2, "DBInstanceIdentifier": "sample-cluster-instance", "PreferredBackupWindow": "00:00-00:30", "PubliclyAccessible": false, "DBSubnetGroup": { "DBSubnetGroupName": "default", "Subnets": [ { "SubnetIdentifier": "subnet-4e26d263", "SubnetAvailabilityZone": { "Name": "us-east-1a" }, "SubnetStatus": "Active" }, { "SubnetIdentifier": "subnet-afc329f4", "SubnetAvailabilityZone": { "Name": "us-east-1c" }, "SubnetStatus": "Active" }, { "SubnetIdentifier": "subnet-b3806e8f", "SubnetAvailabilityZone": { "Name": "us-east-1e" }, "SubnetStatus": "Active" }, { "SubnetIdentifier": "subnet-53ab3636", "SubnetAvailabilityZone": { "Name": "us-east-1d" }, "SubnetStatus": "Active" }, { "SubnetIdentifier": "subnet-991cb8d0", "SubnetAvailabilityZone": { "Name": "us-east-1b" }, "SubnetStatus": "Active" }, { "SubnetIdentifier": "subnet-29ab1025", "SubnetAvailabilityZone": { "Name": "us-east-1f" }, "SubnetStatus": "Active" } ], "VpcId": "vpc-91280df6", "DBSubnetGroupDescription": "default", "SubnetGroupStatus": "Complete" }, "PendingModifiedValues": {}, "KmsKeyId": "arn:aws:kms:us-east-1:012345678901:key/0961325d-a50b-44d4-b6a0-a177d5ff730b" } ]}

258


Modifying an Amazon DocumentDB InstanceVocê pode modificar a instância do Amazon DocumentDB usando o Console de gerenciamento daAWS ou a AWS CLI. Para modificar uma instância, a instância deve estar no available estado. Vocênão pode modificar uma instância que foi interrompida. Se o grupo for parado, comece primeiro o grupo,aguarde que a instância se torne available, e depois efectue as modificações pretendidas. Para obter maisinformações, consulte Interromper e iniciar um cluster do Amazon DocumentDB (p. 237).

Using the Console de gerenciamento da AWSPara modificar uma Amazon DocumentDB em caso de utilização da consola, realize os seguintes passos.


2. No painel de navegação, escolha Instances (Instâncias).Tip


3. Especifique a instância que você deseja modificar escolhendo o botão à esquerda do nome dainstância.

4. Escolha Actions (Ações) e, em seguida, Modify (Modificar).5. No painel Modify instance: <instance-name> (Modificar instância: <nome-da-instância>), faça as

alterações desejadas. Você pode fazer as alterações a seguir:

• Instance specifications — The instance identifier and class. Instance identifier naming constraints:• Instance identifier — Enter a name that is unique for all instances owned by your AWS account

in the current region. The instance identifier must contain [1—63] alphanumeric charactersor hyphens, have a letter as the first character, and cannot end with a hyphen or contain twoconsecutive hyphens.

• Instance class — From the drop-down menu, select an instance class for your AmazonDocumentDB instance. For more information, see Managing Instance Classes (p. 247).

• Certificate authority — Server certificate for this instance. For more information, see Updating YourAmazon DocumentDB TLS Certificates (p. 158).

• Failover — During failover, the instance with the highest promotion tier will be promoted to primary.For more information, see Failover do Amazon DocumentDB (p. 278).

• Maintenance — The maintenance window in which pending modifications or patches are applied toinstances in the cluster.

6. Ao concluir, escolha Continue (Continuar) para ver um resumo das alterações.7. Depois de verificar suas alterações, é possível aplicá-las imediatamente ou durante a próxima janela

de manutenção em Scheduling of modifications (Programação de modificações). Selecione Modifyinstance (Modificar instância) para salvar as alterações. Como alternativa, você pode escolher Cancel(Cancelar) para descartar as alterações.

Leva alguns minutos para que suas alterações sejam aplicadas. Pode utilizar a instância apenas quandoo seu estado é available. Pode monitorizar o estado da instância utilizando a consola ou AWS CLI. Paraobter mais informações, consulte Monitorar o status de uma instância do Amazon DocumentDB (p. 338).

Using the AWS CLIPara modificar uma Amazon DocumentDB instância utilizando o AWS CLI, utilize o modify-db-instance com os seguintes parâmetros. Para mais informações, consulte modificar instância. O código aseguir modifica a classe de instância para db.r5.large para a instância sample-instance.

259


https://docs.aws.amazon.com/documentdb/latest/developerguide/API_ModifyDBInstance.html


Parameters

• --db-instance-identifier — Required. The identifier for the instance to be modified.• --db-instance-class — Optional. The new compute and memory capacity of the instance; for

example, db.r5.large. Not all instance classes are available in all AWS Regions. If you modify theinstance class, an outage occurs during the change. The change is applied during the next maintenancewindow, unless ApplyImmediately is specified as true for this request.

• --apply-immediately or --no-apply-immediately — Optional. Specifies whether thismodification should be applied immediately or wait until the next maintenance window. If this parameter isomitted, the modification is performed during the next maintenance window.

Example


aws docdb modify-db-instance \ --db-instance-identifier sample-instance \ --db-instance-class db.r5.large \ --apply-immediately

Para Windows:

aws docdb modify-db-instance ^ --db-instance-identifier sample-instance ^ --db-instance-class db.r5.large ^ --apply-immediately


{ "DBInstances": [ { "DBInstanceIdentifier": "sample-instance-1", "DBInstanceClass": "db.r5.large", "Engine": "docdb", "DBInstanceStatus": "modifying", "Endpoint": { "Address": "sample-instance-1.node.us-east-1.docdb.amazonaws.com", "Port": 27017, "HostedZoneId": "ABCDEFGHIJKLM" }, "InstanceCreateTime": "2020-01-10T22:18:55.921Z", "PreferredBackupWindow": "02:00-02:30", "BackupRetentionPeriod": 1, "VpcSecurityGroups": [ { "VpcSecurityGroupId": "sg-abcd0123", "Status": "active" } ], "AvailabilityZone": "us-east-1a", "DBSubnetGroup": { "DBSubnetGroupName": "default", "DBSubnetGroupDescription": "default", "VpcId": "vpc-abcd0123", "SubnetGroupStatus": "Complete", "Subnets": [ { "SubnetIdentifier": "subnet-abcd0123",

260


"SubnetAvailabilityZone": { "Name": "us-east-1a" }, "SubnetStatus": "Active" }, { "SubnetIdentifier": "subnet-abcd0123", "SubnetAvailabilityZone": { "Name": "us-east-1b" }, "SubnetStatus": "Active" } ] }, "PreferredMaintenanceWindow": "sun:10:57-sun:11:27", "PendingModifiedValues": { "DBInstanceClass": "db.r5.large" }, "EngineVersion": "3.6.0", "AutoMinorVersionUpgrade": true, "PubliclyAccessible": false, "DBClusterIdentifier": "sample-cluster", "StorageEncrypted": true, "KmsKeyId": "arn:aws:kms:us-east-1:123456789012:key/wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY", "DbiResourceId": "db-ABCDEFGHIJKLMNOPQRSTUVWXYZ", "CACertificateIdentifier": "rds-ca-2019", "PromotionTier": 1, "DBInstanceArn": "arn:aws:rds:us-east-1:123456789012:db:sample-instance-1", "EnabledCloudwatchLogsExports": [ "profiler" ] } ]}

Leva alguns minutos para que suas modificações sejam aplicadas. Pode utilizar a instância apenasquando o seu estado é available. Pode monitorizar o estado da instância utilizando o Console degerenciamento da AWS ou AWS CLI. Para obter mais informações, consulte Monitorar o status de umainstância do Amazon DocumentDB (p. 338).

Rebooting an Amazon DocumentDB InstanceOcasionalmente, você pode precisar reinicializar sua instância do Amazon DocumentDB, geralmente pormotivos de manutenção. Se você fizer determinadas alterações, como alterar o grupo de parâmetros decluster associado a um cluster, será necessário reinicializar as instâncias no cluster para que as alteraçõessejam implantadas. Você pode reinicializar uma instância específica usando o Console de gerenciamentoda AWS ou a AWS CLI.

Reinicializar uma instância reinicia o serviço de mecanismo de banco de dados. Reiniciar resultados numainterrupção momentânea, durante a qual o estado da instância é definido para rebooting. Um AmazonDocumentDB o evento é criado quando a reinicialização estiver concluída.

A reinicialização de uma instância não resulta em um failover. Para despertar um Amazon DocumentDBcluster, utilize o Console de gerenciamento da AWS ou o AWS CLI operação failover-db-cluster.Para mais informações, consulte Failover do Amazon DocumentDB (p. 278).

Você não pode reinicializar sua instância se ela não estiver no estado available. Seu banco de dados podese tornar indisponível por vários motivos, como uma modificação solicitada anteriormente ou uma ação nointervalo de manutenção. Para obter mais informações sobre os estados da instância, consulte Monitorar ostatus de uma instância do Amazon DocumentDB (p. 338).

261


Rebooting an Instance Using the Console de gerenciamento da AWSO procedimento a seguir reinicializa uma instância especificada usando o console.




3. Para especificar a reinicialização de uma instância, localize a instância na lista de instâncias e escolhao botão à esquerda de seu nome.

4. Escolha Actions (Ações), escolha Reboot (Reinicializar) e depois Reboot (Reinicializar) para confirmara reinicialização.

Demora alguns minutos para sua instância reinicializar. Pode utilizar a instância apenas quando o seuestado é available. Pode monitorizar o estado da instância utilizando a consola ou o AWS CLI. Para obtermais informações, consulte Monitorar o status de uma instância do Amazon DocumentDB (p. 338).

Rebooting an Instance Using the AWS CLIPara reinicializar uma instância do Amazon DocumentDB, use a operação reboot-db-instance com oparâmetro --db-instance-identifier. Esse parâmetro especifica o identificador da instância a serreinicializada.

O código a seguir reinicializa a instância sample-instance.

Example


aws docdb reboot-db-instance \ --db-instance-identifier sample-instance

Para Windows:

aws docdb reboot-db-instance ^ --db-instance-identifier sample-instance


{ "DBInstance": { "DBInstanceIdentifier": "sample-instance", "DBInstanceClass": "db.r5.large", "Engine": "docdb", "DBInstanceStatus": "rebooting", "Endpoint": { "Address": "sample-instance.node.us-east-1.docdb.amazonaws.com", "Port": 27017, "HostedZoneId": "ABCDEFGHIJKLM" }, "InstanceCreateTime": "2020-03-27T08:05:56.314Z", "PreferredBackupWindow": "02:00-02:30", "BackupRetentionPeriod": 1, "VpcSecurityGroups": [

262



{ "VpcSecurityGroupId": "sg-abcd0123", "Status": "active" } ], "AvailabilityZone": "us-east-1c", "DBSubnetGroup": { "DBSubnetGroupName": "default", "DBSubnetGroupDescription": "default", "VpcId": "vpc-abcd0123", "SubnetGroupStatus": "Complete", "Subnets": [ { "SubnetIdentifier": "subnet-abcd0123", "SubnetAvailabilityZone": { "Name": "us-east-1a" }, "SubnetStatus": "Active" }, { "SubnetIdentifier": "subnet-wxyz0123", "SubnetAvailabilityZone": { "Name": "us-east-1b" }, "SubnetStatus": "Active" } ] }, "PreferredMaintenanceWindow": "sun:06:53-sun:07:23", "PendingModifiedValues": {}, "EngineVersion": "3.6.0", "AutoMinorVersionUpgrade": true, "PubliclyAccessible": false, "DBClusterIdentifier": "sample-cluster", "StorageEncrypted": true, "KmsKeyId": "arn:aws:kms:us-east-1:<accountID>:key/sample-key", "DbiResourceId": "db-ABCDEFGHIJKLMNOPQRSTUVWXYZ", "CACertificateIdentifier": "rds-ca-2019", "PromotionTier": 1, "DBInstanceArn": "arn:aws:rds:us-east-1:<accountID>:db:sample-instance", "EnabledCloudwatchLogsExports": [ "profiler" ] }}

Demora alguns minutos para sua instância reinicializar. Pode utilizar a instância apenas quando o seuestado é available. Pode monitorizar o estado da instância utilizando a consola ou AWS CLI. Para obtermais informações, consulte Monitorar o status de uma instância do Amazon DocumentDB (p. 338).

Deleting an Amazon DocumentDB InstanceVocê pode excluir a instância do Amazon DocumentDB usando o Console de gerenciamento da AWSou a AWS CLI. Para eliminar uma instância, a instância deve estar no available estado. Você nãopode excluir uma instância que foi interrompida. Se o Amazon DocumentDB o grupo que contém a suainstância é parado, comece primeiro o grupo, aguarde que a instância se torne availablee, em seguida,elimine a instância. Para obter mais informações, consulte Interromper e iniciar um cluster do AmazonDocumentDB (p. 237).

Note

O Amazon DocumentDB armazena todos os dados no volume do cluster. Os dados persistemnesse volume de cluster, mesmo se você remover todas as instâncias do cluster. Se precisar

263


acessar os dados novamente, adicione uma instância ao cluster a qualquer momento e continuede onde parou.

Deletion ProtectionExcluir a última instância de um cluster do Amazon DocumentDB também excluirá o cluster, bem como ossnapshots automáticos e os backups contínuos associados ao cluster. O Amazon DocumentDB impõe aproteção contra exclusão para um cluster independentemente se você executar a operação de exclusãousando o Console de gerenciamento da AWS ou a AWS CLI. Se a proteção contra exclusão estiverhabilitada, não será possível excluir um cluster.

Para excluir um cluster com a projeção contra exclusão habilitada, primeiro é necessário modificar o clustere desabilitar a proteção contra exclusão. Para obter mais informações, consulte Excluir um cluster doAmazon DocumentDB (p. 240).

Deleting an Instance Using the Console de gerenciamento da AWSO procedimento a seguir excluir uma instância do Amazon DocumentDB especificada usando o console.




3. Escolha o botão à esquerda do nome da instância que você deseja excluir.4. Selecione Actions (Ações) e escolha Delete (Excluir).

1. Se você estiver excluindo a última instância no cluster:• Create final cluster snapshot? — Choose Yes if you want to create a final snapshot before the

cluster is deleted. Otherwise, choose No.• Final snapshot name — If you choose to create a final snapshot, enter the cluster snapshot

identifier of the new cluster snapshot created.• Delete <instance-name> instance? — Enter the phrase delete entire cluster into the field to

confirm the deletion.2. Se você não estiver excluindo a última instância no cluster:

• Delete <instance-name> instance? — Enter the phrase delete me into the field to confirm thedeletion.

5. Selecione Delete (Excluir) para excluir a instância.

Leva alguns minutos para uma instância ser excluída. Para monitorar o status de uma instância, consulteMonitorar o status de uma instância do Amazon DocumentDB (p. 338).

Deleting an Instance Using the AWS CLIO procedimento a seguir exclui uma instância do Amazon DocumentDB usando a AWS CLI.

1. First, determine how many instances are in your Amazon DocumentDB cluster:

Para determinar quantas instâncias estão no cluster, execute o comando describe-db-clusters daseguinte forma.

aws docdb describe-db-clusters \

264



--db-cluster-identifier sample-cluster \ --query 'DBClusters[*].[DBClusterIdentifier,DBClusterMembers[*].DBInstanceIdentifier]'


[ [ "sample-cluster", [ "sample-instance-1", "sample-instance-2" ] ]]

2. If there are more than one instances in your Amazon DocumentDB cluster:

Para excluir uma instância do Amazon DocumentDB especificada, use o comando delete-db-instance com o parâmetro --db-instance-identifier, conforme mostrado abaixo. Leva algunsminutos para uma instância ser excluída. Para monitorar o status de uma instância, consulte Monitorar ostatus de uma instância do Amazon DocumentDB (p. 338).

aws docdb delete-db-instance \ --db-instance-identifier sample-instance-2


{ "DBInstance": { "DBInstanceIdentifier": "sample-instance-2", "DBInstanceClass": "db.r5.large", "Engine": "docdb", "DBInstanceStatus": "deleting", "Endpoint": { "Address": "sample-instance-2.node.us-east-1.docdb.amazonaws.com", "Port": 27017, "HostedZoneId": "ABCDEFGHIJKLM" }, "InstanceCreateTime": "2020-03-27T08:05:56.314Z", "PreferredBackupWindow": "02:00-02:30", "BackupRetentionPeriod": 1, "VpcSecurityGroups": [ { "VpcSecurityGroupId": "sg-abcd0123", "Status": "active" } ], "AvailabilityZone": "us-east-1c", "DBSubnetGroup": { "DBSubnetGroupName": "default", "DBSubnetGroupDescription": "default", "VpcId": "vpc-6242c31a", "SubnetGroupStatus": "Complete", "Subnets": [ { "SubnetIdentifier": "subnet-abcd0123", "SubnetAvailabilityZone": { "Name": "us-east-1a" }, "SubnetStatus": "Active" },

265

Amazon DocumentDB Guia do desenvolvedorGerenciamento de grupos de sub-redes do

{ "SubnetIdentifier": "subnet-wxyz0123", "SubnetAvailabilityZone": { "Name": "us-east-1b" }, "SubnetStatus": "Active" } ] }, "PreferredMaintenanceWindow": "sun:06:53-sun:07:23", "PendingModifiedValues": {}, "EngineVersion": "3.6.0", "AutoMinorVersionUpgrade": true, "PubliclyAccessible": false, "DBClusterIdentifier": "sample-cluster", "StorageEncrypted": true, "KmsKeyId": "arn:aws:kms:us-east-1:<accountID>:key/sample-key", "DbiResourceId": "db-ABCDEFGHIJKLMNOPQRSTUVWXYZ", "CACertificateIdentifier": "rds-ca-2019", "PromotionTier": 1, "DBInstanceArn": "arn:aws:rds:us-east-1:<accountID>:db:sample-instance-2", "EnabledCloudwatchLogsExports": [ "profiler" ] }}

3. If the instance your want to delete is the last instance in your Amazon DocumentDB cluster:

Se você excluir a última instância em um cluster do Amazon DocumentDB, você também excluirá essecluster e os snapshots automáticos e backups contínuos associados a ele.

Para excluir a última instância no cluster, é possível excluí-lo e opcionalmente criar um snapshot final.Para obter mais informações, consulte Excluir um cluster do Amazon DocumentDB (p. 240).

Gerir Amazon DocumentDB Grupos SublíquidosUma virtual private cloud (VPC) é uma rede virtual dedicada à sua conta da AWS Ela é isolada de maneiralógica das outras redes virtuais na Nuvem AWS. Você pode iniciar os recursos da AWS, como clusters doAmazon DocumentDB, em sua Amazon VPC. Você pode especificar um intervalo de endereços IP para aVPC, adicionar sub-rede, associar security groups e configurar tabelas de rota.

Uma sub-rede é um intervalo de endereços IP em sua Amazon VPC. Você pode executar recursosda AWS em uma sub-rede especificada. Utilizar um público subrede para recursos que têm de estarligados à Internet. Utilizar um privado subrede para recursos que não serão ligados à Internet. Para maisinformações sobre as subredes públicas e privadas, consulte Fundamentos de VPC e Subnet no AmazonVirtual Private Cloud Guia do utilizador.

Um grupo de sub-redes de banco de dados é uma coleção de sub-redes que você cria em uma VPC edesigna para seus clusters. Um grupo de sub-redes permite que você especifique uma VPC específica aocriar clusters. Se você usar o grupo de sub-redes default, ele abrangerá todas as sub-redes na VPC.

Cada grupo de sub-redes de banco de dados deve ter sub-redes em pelo menos duas Zonas dedisponibilidade em uma determinada região. Ao criar um cluster de banco de dados em uma VPC,selecione um grupo de sub-redes de banco de dados. O Amazon DocumentDB usa esse grupo de sub-redes de banco de dados e sua zona de disponibilidade preferencial para selecionar uma sub-rede e umendereço IP dentro dessa sub-rede para associar ao cluster. Se a instância principal falhar, o AmazonDocumentDB poderá promover uma instância de réplica correspondente para ser a nova instância

266

https://docs.aws.amazon.com/vpc/latest/userguide/VPC_Subnets.html#vpc-subnet-basics

Amazon DocumentDB Guia do desenvolvedorCriação de um grupo de sub-redes

principal. Ela pode criar uma nova instância de réplica usando um endereço IP da sub-rede em que ainstância principal anterior foi localizada.

Quando o Amazon DocumentDB cria uma instância em uma VPC, ele atribui uma interface de redeao seu cluster usando um endereço IP selecionado do seu grupo de sub-redes de banco de dados.Recomendamos que você use o nome DNS, pois o endereço IP subjacente poderá mudar durante ofailover. Para obter mais informações, consulte Amazon DocumentDBEndpoints do (p. 8).

Para mais informações sobre a criação de VPC e subredes, consulte Trabalhar com vãos e subredes noAmazon Virtual Private Cloud Guia do utilizador.

Tópicos• Criar uma Amazon DocumentDB Grupo Subnet (p. 267)• Descrever um Amazon DocumentDB Grupo Subnet (p. 271)• Modificar um Amazon DocumentDB Grupo Subnet (p. 273)• Eliminar um Amazon DocumentDB Grupo Subnet (p. 275)

Criar uma Amazon DocumentDB Grupo SubnetAo criar um Amazon DocumentDB cluster, tem de escolher um Amazon VPC e o grupo subnetcorrespondente dentro desse Amazon VPC para lançar o seu grupo. As subredes determinam a zona dedisponibilidade e o intervalo IP dentro da zona de disponibilidade que pretende utilizar para lançar umainstância.

Um grupo de sub-rede é um conjunto de subredes (ou azs) designado que lhe permite especificar aszonas de disponibilidade que pretende utilizar para iniciar Amazon DocumentDB instâncias. Por exemplo,num grupo com três instâncias, recomenda-se que cada uma dessas instâncias seja provisionada em azsseparados, o que optimiza para uma elevada disponibilidade. Assim, se uma única AZ falhar, só afetaráuma instância única.

Atualmente, Amazon DocumentDB podem ser aprovisionadas em até três azs. Mesmo que um gruposub-rede tenha mais de três subredes, só poderá utilizar três dessas subredes para criar uma AmazonDocumentDB grupo. Por conseguinte, recomendamos que quando cria um grupo de sub-rede que apenasescolha as três subredes das quais pretende implementar as suas instâncias.

Por exemplo, . É criado um cluster e Amazon DocumentDB escolher azs {1A, 1B e 1C}. Se você tentarcriar uma instância na AZ {1D} a chamada de API não será bem-sucedida. Contudo, se optar por criaruma instância, sem especificar a AZ em particular, então Amazon DocumentDB irá escolher uma AZ emseu nome. Amazon DocumentDB utiliza um algoritmo para carregar o equilíbrio dos casos em azs para oajudar a obter uma elevada disponibilidade. Se forem provisionadas três instâncias, por predefinição, estasserão provisionadas em três azs e não serão provisionadas num único AZ.

Práticas recomendadas

• Unless you have a specific reason, always create a subnet group with three subnets. This ensuresthat clusters with three or more instances will be able to achieve higher availability as instances will beprovisioned across three AZs.

• Always spread instances across multiple AZs to achieve high availability. Never place all instances for acluster in a single AZ.

• Because failover events can happen at any time, you should not assume that a primary instance orreplica instances will always be in a particular AZ.

267

https://docs.aws.amazon.com/vpc/latest/userguide/working-with-vpcs.html


Como criar um grupo de sub-redePode utilizar o Console de gerenciamento da AWS ou AWS CLI para criar um Amazon DocumentDB gruposubnet.

Tópicos• Uso do Console de gerenciamento da AWS (p. 268)• Uso do AWS CLI (p. 269)


Utilize os passos seguintes para criar uma Amazon DocumentDB grupo subnet.

Para criar um Amazon DocumentDB grupo subnet


2. No painel de navegação, escolha Grupos sublíquidos, depois escolha Criar.

Tip


3. No Criar grupo de subrede página:

a. No Detalhes do grupo subnet secção:

i. Nome—Introduza um nome significativo para o grupo de sub-rede.ii. Descrição—Introduza uma descrição para o grupo de sub-rede.

b. No Adicionar subredes secção:

i. VPC—Na lista, escolha um VPC para este grupo de sub-rede.ii. Execute um destes procedimentos:

• Para incluir todas as sub-redes no VPC escolhido, escolha Adicionar todas as sub-redesrelacionadas com este VPC.

• Para especificar sub-redes para esse grupo de sub-redes, faça o seguinte para cadazona de disponibilidade na qual você deseja incluir sub-redes. Você deve incluir pelomenos duas zonas de disponibilidade.

A. Zona de disponibilidade—Na lista, escolha uma Zona de disponibilidade.B. Subrede—Na lista, escolha uma subrede da Zona de disponibilidade escolhida para

este grupo de sub-rede.C. Escolher Adicionar subrede.

4. Escolher Criar. Quando o grupo de sub-rede é criado, ele é listado com seus outros grupos de sub-redes.

268



Uso do AWS CLIAntes de criar um grupo de sub-redes usando a AWS CLI, você deve determinar quais sub-redes estãodisponíveis. Execute a seguinte operação de AWS CLI para listar as zonas de disponibilidade e as sub-redes.

Parâmetros:

• --db-subnet-group—Opcional. A especificação de um determinado grupo de sub-redes listaas zonas de disponibilidade e as sub-redes para esse grupo. Omitir esse parâmetro lista zonas dedisponibilidade e as sub-redes para todos os seus grupos de sub-redes. A especificação do grupo desub-redes default lista todas as sub-redes da VPC.

Example


aws docdb describe-db-subnet-groups \ --db-subnet-group-name default \ --query 'DBSubnetGroups[*].[DBSubnetGroupName,Subnets[*].[SubnetAvailabilityZone.Name,SubnetIdentifier]]'

Para Windows:

aws docdb describe-db-subnet-groups ^ --db-subnet-group-name default ^ --query 'DBSubnetGroups[*].[DBSubnetGroupName,Subnets[*].[SubnetAvailabilityZone.Name,SubnetIdentifier]]'


[ [ "default", [ [ "us-east-1a", "subnet-4e26d263" ], [ "us-east-1c", "subnet-afc329f4" ], [ "us-east-1e", "subnet-b3806e8f" ], [ "us-east-1d", "subnet-53ab3636" ], [ "us-east-1b", "subnet-991cb8d0" ], [ "us-east-1f", "subnet-29ab1025" ] ] ]

269


]

Usando a saída da operação anterior, você pode criar um novo grupo de sub-redes. O novo grupo de sub-redes deve incluir sub-redes em pelo menos duas zonas de disponibilidade.

Parâmetros:

• --db-subnet-group-name—Obrigatório. O nome para esse grupo de sub-redes.• --db-subnet-group-description—Obrigatório. A descrição do grupo de sub-redes.• --subnet-ids—Obrigatório. Uma lista de sub-redes a serem incluídas no grupo de sub-redes.

Exemplo: subnet-53ab3636.• --Etiquetas—Opcional. Uma lista de tags (pares de chave/valor) a serem anexadas a esse grupo de sub-

redes.

O código seguinte cria o grupo de sub-rede sample-subnet-group com três subredes,subnet-4e26d263, subnet-afc329f4, e subnet-b3806e8f.


aws docdb create-db-subnet-group \ --db-subnet-group-name sample-subnet-group \ --db-subnet-group-description "A sample subnet group" \ --subnet-ids subnet-4e26d263 subnet-afc329f4 subnet-b3806e8f \ --tags Key=tag1,Value=One Key=tag2,Value=2

Para Windows:

aws docdb create-db-subnet-group ^ --db-subnet-group-name sample-subnet-group ^ --db-subnet-group-description "A sample subnet group" ^ --subnet-ids subnet-4e26d263 subnet-afc329f4 subnet-b3806e8f ^ --tags Key=tag1,Value=One Key=tag2,Value=2


{ "DBSubnetGroup": { "DBSubnetGroupDescription": "A sample subnet group", "DBSubnetGroupName": "sample-subnet-group", "Subnets": [ { "SubnetAvailabilityZone": { "Name": "us-east-1a" }, "SubnetIdentifier": "subnet-4e26d263", "SubnetStatus": "Active" }, { "SubnetAvailabilityZone": { "Name": "us-east-1c" }, "SubnetIdentifier": "subnet-afc329f4", "SubnetStatus": "Active" }, { "SubnetAvailabilityZone": { "Name": "us-east-1e" }, "SubnetIdentifier": "subnet-b3806e8f", "SubnetStatus": "Active"

270

Amazon DocumentDB Guia do desenvolvedorComo descrever um grupo de sub-redes

} ], "VpcId": "vpc-91280df6", "DBSubnetGroupArn": "arn:aws:rds:us-east-1:123SAMPLE012:subgrp:sample-subnet-group", "SubnetGroupStatus": "Complete" }}

Descrever um Amazon DocumentDB Grupo SubnetPode utilizar o Console de gerenciamento da AWS ou o AWS CLI para obter os detalhes de um AmazonDocumentDB grupo subnet.

Uso do Console de gerenciamento da AWSO procedimento seguinte mostra como obter os detalhes de um Amazon DocumentDB grupo subnet.

Para localizar os detalhes de um grupo de sub-redes


2. No painel de navegação, escolha Grupos sublíquidos.

Tip


3. Para ver os detalhes de um grupo de sub-redes, escolha o nome do grupo de sub-redes.

Uso do AWS CLIPara encontrar os detalhes de um Amazon DocumentDB grupo de sub-rede, utilize o describe-db-subnet-groups operação com o seguinte parâmetro.

271


Amazon DocumentDB Guia do desenvolvedorComo descrever um grupo de sub-redes

Parameter

• --db-subnet=group-name—Opcional. Se incluído, os detalhes do grupo de sub-redes chamadoserão listados. Se omitido, os detalhes para até 100 grupos de sub-redes serão listados.

Example

O código seguinte indica detalhes para o sample-subnet-group grupo subnet que criámos no Criaruma Amazon DocumentDB Grupo Subnet (p. 267) secção.


aws docdb describe-db-subnet-groups \ --db-subnet-group-name sample-subnet-group

Para Windows:

aws docdb describe-db-subnet-groups ^ --db-subnet-group-name sample-subnet-group


{ "DBSubnetGroup": { "DBSubnetGroupArn": "arn:aws:rds:us-east-1:123SAMPLE012:subgrp:sample-subnet-group", "VpcId": "vpc-91280df6", "SubnetGroupStatus": "Complete", "DBSubnetGroupName": "sample-subnet-group", "Subnets": [ { "SubnetAvailabilityZone": { "Name": "us-east-1a" }, "SubnetStatus": "Active", "SubnetIdentifier": "subnet-4e26d263" }, { "SubnetAvailabilityZone": { "Name": "us-east-1c" }, "SubnetStatus": "Active", "SubnetIdentifier": "subnet-afc329f4" }, { "SubnetAvailabilityZone": { "Name": "us-east-1e" }, "SubnetStatus": "Active", "SubnetIdentifier": "subnet-b3806e8f" } ], "DBSubnetGroupDescription": "A sample subnet group" }}

272

Amazon DocumentDB Guia do desenvolvedorComo modificar um grupo de sub-redes

Modificar um Amazon DocumentDB Grupo SubnetPode utilizar o Console de gerenciamento da AWS ou AWS CLI para modificar a descrição de um gruposubnet ou para adicionar ou remover subredes de um Amazon DocumentDB grupo subnet. No entanto,não pode modificar o default grupo subnet.


Uso do Console de gerenciamento da AWSVocê pode usar a Console de gerenciamento da AWS para alterar a descrição de um grupo de sub-redesou para adicionar e remover sub-redes. Lembre-se de que, ao terminar, você deve ter pelo menos duaszonas de disponibilidade associadas ao seu grupo de sub-redes.

Para modificar o grupo de sub-redes


2. No painel de navegação, escolha Grupos sublíquidos. Em seguida, escolha o botão à esquerda donome do grupo de sub-redes. Lembre-se de que não pode modificar o default grupo subnet.

Tip


3. Escolher Ações, e depois escolha Modificar.4. Descrição—Para alterar a descrição do seu grupo de sub-rede, introduza uma nova descrição.5. Para alterar as subredes associadas ao seu grupo de sub-rede, no Adicionar subredes , faça uma ou

mais das seguintes:• Para remover todas as sub-redes deste grupo de sub-rede, escolha Remover todos.• Para remover as sub-redes específicas deste grupo de sub-rede, escolha Remover para cada

subrede que pretende remover.• Para adicionar todas as subredes associadas a este VPC, escolha Adicionar todas as sub-redes

relacionadas com este VPC.• Para adicionar sub-redes específicas a esse grupo de sub-redes, faça o seguinte para cada zona

de disponibilidade à qual você deseja adicionar uma sub-rede.

a. Zona de disponibilidade—Na lista, escolha uma nova Zona de disponibilidade.b. Subrede—Na lista, escolha uma subrede da Zona de disponibilidade escolhida para este

grupo de sub-rede.c. Escolher Adicionar subrede.

6. Na caixa de diálogo de confirmação:• Para fazer estas alterações ao grupo de sub-rede, escolha Modificar.• Para manter o grupo de sub-rede inalterado, escolha Cancelar.

273


Amazon DocumentDB Guia do desenvolvedorComo modificar um grupo de sub-redes

Uso do AWS CLIVocê pode usar a AWS CLI para alterar a descrição de um grupo de sub-redes ou para adicionare remover sub-redes. Lembre-se de que, ao terminar, você deve ter pelo menos duas zonas dedisponibilidade associadas ao seu grupo de sub-redes. Não pode modificar o default grupo subnet.

Parâmetros:

• --db-subnet-group-name—Obrigatório. O nome do grupo de sub-redes do Amazon DocumentDBque você está modificando.

• --subnet-ids—Obrigatório. Uma lista de todas as sub-redes que você deseja no grupo de sub-redesapós essa alteração é feita.

Important

Todas as sub-redes que estiverem no grupo, mas não estiverem nessa lista serão removidasdo grupo de sub-redes. Se você desejar manter qualquer uma das sub-redes que estiverematualmente no grupo, inclua-as nessa lista.

• --db-subnet-group-description—Opcional. A descrição do grupo de sub-redes.

Example

O código seguinte modifica a descrição e substitui as sub-redes existentes com as subredessubnet-991cb8d0, subnet-53ab3636, e subnet-29ab1025.


aws docdb modify-db-subnet-group \ --db-subnet-group-name sample-subnet-group \ --subnet-ids subnet-991cb8d0 subnet-53ab3636 subnet-29ab1025 \ --db-subnet-group-description "Modified subnet group"

Para Windows:

aws docdb modify-db-subnet-group ^ --db-subnet-group-name sample-subnet-group ^ --subnet-ids subnet-991cb8d0 subnet-53ab3636 subnet-29ab1025 ^ --db-subnet-group-description "Modified subnet group"

A saída dessa operação é semelhante ao seguinte (formato JSON). Repare que este é o mesmo grupo desub-rede que foi criado no Criar uma Amazon DocumentDB Grupo Subnet (p. 267) secção. No entanto,as sub-redes no grupo de sub-rede são substituídas pelas indicadas no modify-db-subnet-groupoperação.

{ "DBSubnetGroup": { "DBSubnetGroupArn": "arn:aws:rds:us-east-1:123SAMPLE012:subgrp:sample-subnet-group", "DBSubnetGroupDescription": "Modified subnet group", "SubnetGroupStatus": "Complete", "Subnets": [ { "SubnetAvailabilityZone": { "Name": "us-east-1d" }, "SubnetStatus": "Active", "SubnetIdentifier": "subnet-53ab3636" },

274

Amazon DocumentDB Guia do desenvolvedorExclusão de um grupo de sub-redes

{ "SubnetAvailabilityZone": { "Name": "us-east-1b" }, "SubnetStatus": "Active", "SubnetIdentifier": "subnet-991cb8d0" }, { "SubnetAvailabilityZone": { "Name": "us-east-1f" }, "SubnetStatus": "Active", "SubnetIdentifier": "subnet-29ab1025" } ], "VpcId": "vpc-91280df6", "DBSubnetGroupName": "sample-subnet-group" }}

Eliminar um Amazon DocumentDB Grupo SubnetPode utilizar o Console de gerenciamento da AWS ou AWS CLI para eliminar um Amazon DocumentDBgrupo subnet. No entanto, não pode eliminar o default grupo subnet.


Uso do Console de gerenciamento da AWSVocê pode usar o Console de gerenciamento da AWS para excluir um grupo de sub-redes. Mas não podeeliminar o default grupo subnet.

Para excluir um grupo de sub-redes


2. No painel de navegação, escolha Grupos sublíquidos. Em seguida, escolha o botão à esquerda donome do grupo de sub-redes. Lembre-se de que não pode eliminar o default grupo subnet.

Tip


3. Escolher Ações, e depois escolha Eliminar.4. Na caixa de diálogo de confirmação:

• Para eliminar o grupo de sub-rede, escolha Eliminar.• Para manter o grupo de sub-rede, escolha Cancelar.

Uso do AWS CLIPara eliminar um Amazon DocumentDB grupo subnet utilizando o AWS CLI, utilize o delete-db-subnet-group operação com o seguinte parâmetro.

275


Amazon DocumentDB Guia do desenvolvedorAlta disponibilidade e replicação

Parameter

• --db-subnet-group-name—Obrigatório. O nome do grupo de sub-redes do Amazon DocumentDB aser excluído. Lembre-se de que não pode eliminar o default grupo subnet.

Example

O código a seguir exclui sample-subnet-group.


aws docdb delete-db-subnet-group \ --db-subnet-group-name sample-subnet-group

Para Windows:

aws docdb delete-db-subnet-group ^ --db-subnet-group-name sample-subnet-group

A operação não produzirá uma saída.

Amazon DocumentDBAlta disponibilidade ereplicação do

Você pode obter alta disponibilidade e escalabilidade de leitura no Amazon DocumentDB (compatível comMongoDB) usando instâncias de réplica. Um único Amazon DocumentDB o cluster suporta uma únicainstância primária e até 15 réplica de instâncias. Essas instâncias podem ser distribuídas em zonas dedisponibilidade dentro da região do cluster. A instância principal aceita o tráfego de leitura e de gravação eas instâncias de réplica aceitam somente solicitações de leitura.

O volume do cluster é composto por várias cópias dos dados do cluster. Contudo, os dados no volumedo cluster são representados como um volume lógico, único, para a instância principal e para réplicas doAmazon DocumentDB no cluster. No final, as instâncias de réplica tornam-se consistentes. Elas retornamos resultados da consulta com atraso de réplica mínimo, geralmente muito inferior a 100 milissegundosapós a instância principal ter gravado uma atualização. O atraso da réplica varia de acordo com a taxa demudança no banco de dados. Ou seja, durante os períodos em que um grande número de operações degravação ocorre para o banco de dados, você pode ver um aumento no atraso da réplica.

Escalabilidade de leituraAmazon DocumentDBAs réplicas do funcionam bem para a escalabilidade de leitura porque são totalmentededicadas a operações de leitura no seu volume de cluster. As operações de gravação são gerenciadaspela instância principal. O volume do cluster é compartilhado com todas as instâncias em seu cluster.Portanto, não tem de replicar e manter uma cópia dos dados para cada Amazon DocumentDB réplica.

Alta disponibilidadeQuando cria uma Amazon DocumentDB grupo, dependendo do número de Zonas de Disponibilidadeno grupo de sub-rede (deve existir pelo menos dois), Amazon DocumentDB instâncias de disposiçõesnas Zonas de disponibilidade. Quando você cria instâncias no cluster, o Amazon DocumentDB distribuiautomaticamente as instâncias entre as zonas de disponibilidade em um grupo de sub-redes parabalancear o cluster. Essa ação também impede que todas as instâncias estejam localizadas na mesmazona de disponibilidade.

276

Amazon DocumentDB Guia do desenvolvedorComo adicionar réplicas

Example

Para ilustrar o ponto, considere um exemplo em que crie um grupo que tenha um grupo sub-rede com trêszonas de disponibilidade: AZ1, AZ2, e AZ3.

Quando a primeira instância no cluster é criada, é a instância principal e é localizada em uma das zonasde disponibilidade. Neste exemplo, está em AZ1. A segunda instância criada é uma instância de réplicae está localizada numa das duas outras zonas de disponibilidade, diga AZ2. A terceira instância criada éuma instância de réplica e está localizada na restante Zona de disponibilidade, AZ3. Se você criar maisinstâncias, elas serão distribuídas entre as zonas de disponibilidade para alcançar o equilíbrio no cluster.

Se ocorrer uma falha na instância principal (AZ1), um failover será acionado, e uma das réplicas existentesserá promovida a principal. Quando a instância principal antiga for recuperada, ela se tornará uma réplicana mesma zona de disponibilidade na qual ela foi provisionada (AZ1). Quando fornece um grupo detrês ocorrências, Amazon DocumentDB continua a preservar esse grupo de três ocorrências. AmazonDocumentDB processa automaticamente a deteção, o failover e a recuperação de falhas de instância semqualquer intervenção manual.

Quando o Amazon DocumentDB executar um failover e recuperar uma instância, a instância recuperadapermanecerá na zona de disponibilidade na qual ela foi originalmente provisionada. No entanto, a funçãoda instância pode mudar de principal para réplica. Isso impede o cenário em que uma série de failoverspode resultar em todas as instâncias estando na mesma zona de disponibilidade.

Você pode especificar réplicas do Amazon DocumentDB como destinos de failover. Ou seja, se ocorreruma falha na instância principal, a réplica especificada do Amazon DocumentDB ou a réplica de umacamada será promovida a instância principal. Há uma breve interrupção durante a qual as solicitações deleitura e gravação feitas na instância principal falharão com uma exceção. Se o seu Amazon DocumentDBo cluster não inclui qualquer Amazon DocumentDB réplicas, quando a instância primária falhar, é recriada.Promover uma réplica do Amazon DocumentDB é muito mais rápido do que recriar a instância principal.

Para cenários de alta disponibilidade, recomendamos que crie um ou mais Amazon DocumentDB réplicas.Estas réplicas devem ser da mesma classe de instância como instância primária e em diferentes Zonas dedisponibilidade para o seu Amazon DocumentDB grupo.

Para obter mais informações, consulte o seguinte: .

• Noções básicas de tolerância a falhas do cluster do Amazon DocumentDB (p. 246)• Failover do Amazon DocumentDB (p. 278)

• Como controlar o destino de failover (p. 278)

Como adicionar réplicasA primeira instância adicionada ao cluster é a instância principal. Todas instância adicionada após aprimeira instância é uma instância de réplica. Um cluster pode ter até 15 instâncias de réplica, além dainstância principal.

Quando você cria um cluster usando o Console de gerenciamento da AWS, uma instância principalé criada automaticamente ao mesmo tempo. Para criar uma réplica ao mesmo tempo que cria ogrupo e a instância primária, escolha Criar réplica numa zona diferente. Para obter mais informações,consulte a etapa 4.d em Criação de um cluster do Amazon DocumentDB (p. 217). Para adicionar maisréplicas a um cluster do Amazon DocumentDB, consulte Adding an Amazon DocumentDB Instance to aCluster (p. 252).

Ao usar a AWS CLI para criar seu cluster, você deve criar explicitamente suas instâncias principal e deréplica. Para obter mais informações, consulte a seção "Usar a AWS CLI" dos seguintes tópicos:

• Criação de um cluster do Amazon DocumentDB (p. 217)• Adding an Amazon DocumentDB Instance to a Cluster (p. 252)

277

Amazon DocumentDB Guia do desenvolvedorFailover

Failover do Amazon DocumentDBEm alguns casos, como determinados tipos de manutenção programada, ou no caso improvável de umafalha de nó primário ou zona de disponibilidade, o Amazon DocumentDB (compatível com MongoDB)detecta a falha e substitui o nó primário. Durante um failover, o tempo de gravação é minimizado. Issoocorre porque a função do nó primário fará failover em uma das réplicas de leitura, em vez de ter quecriar e provisionar um novo nó primário. A detecção de falhas e a promoção de réplica garantem que vocêpossa continuar a gravar no novo primário assim que a promoção estiver concluída.

Para que o failover funcione, o cluster deve ter pelo menos duas instâncias — uma instância principal epelo menos uma réplica.

Como controlar o destino de failoverO Amazon DocumentDB fornece níveis de failover para controlar qual instância de réplica é promovida ainstância principal quando ocorre um failover.

Níveis de failover

Cada instância de réplica é associada a um nível de failover (0 – 15). Quando ocorre um failover devido àmanutenção ou a uma falha de hardware improvável, a instância principal executa failover em uma réplicacom o menor nível de prioridade numerado. Se várias réplicas tiverem o mesmo nível de prioridade, aprincipal executará failover na réplica do nível que é mais próximo em tamanho da principal.

Ao definir o nível de failover de um grupo de réplicas selecionadas como 0 (a prioridade mais alta), vocêpode garantir que um failover promova uma das réplicas desse grupo. Você pode impedir efetivamenteque as réplicas específicas sejam promovidas a principal no caso de um failover, atribuindo um nível debaixa prioridade (número alto) a essas réplicas. Isso é útil em casos em que réplicas específicas são muitousadas por um aplicativo, e o failover em um deles teria um impacto negativo em um aplicativo crítico.

Você pode definir o nível de failover de uma instância ao criá-la ou posteriormente, modificando-o.Definir um nível de failover da instância modificando a instância não aciona um failover. Para obter maisinformações, consulte os tópicos a seguir:

• Adding an Amazon DocumentDB Instance to a Cluster (p. 252)• Modifying an Amazon DocumentDB Instance (p. 259)

Ao iniciar manualmente um failover, você tem dois meios de controlar qual instância de réplica é promovidaa principal: o nível de failover, conforme descrito anteriormente, e o parâmetro --target-db-instance-identifier.

--target-db-instance-identifier

Para testar, você pode forçar um evento de failover usando a operação failover-db-cluster. Vocêpode usar o parâmetro --target-db-instance-identifier para especificar qual réplica deve serpromovida à principal. O uso do parâmetro --target-db-instance-identifier substitui o nível deprioridade de failover. Se você não especificar o parâmetro --target-db-instance-identifier, ofailover primário estará de acordo com o nível de prioridade de failover.

O que acontece durante um failoverO failover é automaticamente controlado pelo Amazon DocumentDB para que seus aplicativos possamretomar operações de banco de dados o mais rápido possível e sem intervenção administrativa.

• Se você tiver uma réplica do Amazon DocumentDB na mesma zona de disponibilidade ou em outra,ao fazer o failover, o Amazon DocumentDB alterará o registro de nome canônico (CNAME) dainstância para apontar para a réplica íntegra que, por sua vez, é promovida e se torna a nova principal.Normalmente, o failover é concluído em 30 segundos do início ao fim.

278


• Se você não tiver uma instância de réplica do Amazon DocumentDB (por exemplo, um cluster deinstância única): o Amazon DocumentDB tentará criar uma instância na mesma zona de disponibilidadeque a instância original. O melhor possível é feito para realizar essa substituição da instância original,mas pode ser que isso não tenha êxito se, por exemplo, ocorrer um problema que afete amplamente azona de disponibilidade.

Seu aplicativo deve tentar novamente fazer as conexões do banco de dados em caso de uma perda deconexão.

Testes de failoverUm failover para um cluster promove que uma das réplicas do Amazon DocumentDB (instâncias somenteleitura) no cluster seja a instância principal (o gravador do cluster).

Quando a instância principal falhar, o Amazon DocumentDB executará failover automaticamente em umaréplica do Amazon DocumentDB, se houver. Você pode forçar um failover quando quiser simular umafalha de uma instância principal para testes. Cada instância em um cluster tem seu próprio endereço deendpoint. Portanto, você precisa limpar e restabelecer as conexões existentes que usam os endereços deendpoint quando o failover é concluído.

Para forçar um failover, use a operação failover-db-cluster com esses parâmetros.

• --db-cluster-identifier—Obrigatório. O nome do cluster no qual executar failover.• --target-db-instance-identifier—Optional. O nome da instância a ser promovida à instância

principal.

Example

A operação a seguir força um failover do cluster sample-cluster. Ela não especifica qual instância setornará a nova instância principal, portanto o Amazon DocumentDB escolhe a instância de acordo com aprioridade do nível de failover.


aws docdb failover-db-cluster \ --db-cluster-identifier sample-cluster

Para Windows:

aws docdb failover-db-cluster ^ --db-cluster-identifier sample-cluster

A operação a seguir força um failover do cluster sample-cluster, especificando a sample-cluster-instance que será promovida à função principal. (Observe "IsClusterWriter": true na saída.)


aws docdb failover-db-cluster \ --db-cluster-identifier sample-cluster \ --target-db-instance-identifier sample-cluster-instance

Para Windows:

aws docdb failover-db-cluster ^ --db-cluster-identifier sample-cluster ^

279


--target-db-instance-identifier sample-cluster-instance


{ "DBCluster": { "HostedZoneId": "Z2SUY0A1719RZT", "Port": 27017, "EngineVersion": "3.6.0", "PreferredMaintenanceWindow": "thu:04:05-thu:04:35", "BackupRetentionPeriod": 1, "ClusterCreateTime": "2018-06-28T18:53:29.455Z", "AssociatedRoles": [], "DBSubnetGroup": "default", "MasterUsername": "master-user", "Engine": "docdb", "ReadReplicaIdentifiers": [], "EarliestRestorableTime": "2018-08-21T00:04:10.546Z", "DBClusterIdentifier": "sample-cluster", "ReaderEndpoint": "sample-cluster.node.us-east-1.docdb.amazonaws.com", "DBClusterMembers": [ { "DBInstanceIdentifier": "sample-cluster-instance", "DBClusterParameterGroupStatus": "in-sync", "PromotionTier": 1, "IsClusterWriter": true }, { "DBInstanceIdentifier": "sample-cluster-instance-00", "DBClusterParameterGroupStatus": "in-sync", "PromotionTier": 1, "IsClusterWriter": false }, { "DBInstanceIdentifier": "sample-cluster-instance-01", "DBClusterParameterGroupStatus": "in-sync", "PromotionTier": 1, "IsClusterWriter": false } ], "AvailabilityZones": [ "us-east-1b", "us-east-1c", "us-east-1a" ], "DBClusterParameterGroup": "default.docdb3.6", "Endpoint": "sample-cluster.node.us-east-1.docdb.amazonaws.com", "IAMDatabaseAuthenticationEnabled": false, "AllocatedStorage": 1, "LatestRestorableTime": "2018-08-22T21:57:33.904Z", "PreferredBackupWindow": "00:00-00:30", "StorageEncrypted": false, "MultiAZ": true, "Status": "available", "DBClusterArn": "arn:aws:rds:us-east-1:123456789012:cluster:sample-cluster", "VpcSecurityGroups": [ { "Status": "active", "VpcSecurityGroupId": "sg-12345678" } ], "DbClusterResourceId": "cluster-ABCDEFGHIJKLMNOPQRSTUVWXYZ" }}

280

Amazon DocumentDB Guia do desenvolvedorAtraso de replicação

Atraso de replicaçãoO intervalo de replicação é normalmente 50 ms ou menos. Os motivos mais comuns para o aumento daréplica são:

• Uma taxa de escrita elevada no primário que faz com que os replicados de leitura caiam por trás doprimário.

• A afirmação sobre o replicado de leitura entre consultas de longo prazo (por exemplo, grandesdigitalizações sequenciais, consultas de agregação) e a conversão de escrita recebida.

• Número muito grande de consultas simultâneas nos replicados de leitura.

Para minimizar o atraso da replicação, experimente estas técnicas de resolução de problemas:

• Se tiver uma taxa de escrita elevada ou uma utilização de CPU elevada, recomendamos que aumenteas instâncias no seu grupo.

• Se existirem consultas de longo prazo sobre as suas réplicas lidas e atualizações muito frequentes paraos documentos a serem consultados, considere alterar as suas consultas de longo prazo ou executá-lascontra a réplica primária/escrita para evitar a afirmação nos replicados de leitura.

• Se existir um número muito grande de consultas simultâneas ou de CPU elevado apenas nos replicadosde leitura, outra opção é dimensionar o número de réplicas lidas para espalhar a carga de trabalho.

• Uma vez que o atraso de replicação é resultado de uma produção de escrita elevada e de consultasde longo prazo, recomendamos a resolução de problemas da desfasamento de replicação utilizandoa dbclusterreplicalagagagagência de CW em combinação com o registador de consultas lento eWriteThroughput/WriteIOPS métricas.

Em geral, recomendamos que todos os seus replicados sejam do mesmo tipo de instância, para que umafalha de grupo não cause uma degradação no desempenho.

Se estiver a escolher entre o aumento e a escala de escala (por ex. seis instâncias mais pequenas vs. trêsinstâncias maiores), recomendamos geralmente que tentem escalar primeiro (instâncias maiores) antes defazer o escalonamento, uma vez que irá obter uma cache de tampão maior por instância de BD.

Proativamente, deve definir um alarme de atraso de replicação e definir o seu limiar para um valor queconsidera ser o limite superior para o quão longe (ou "impróprio") os seus dados em circunstâncias deréplica podem ser antes de começar a afectar a funcionalidade da sua aplicação. Em geral, aconselhamosque o limiar de desfasamento de replicação seja excedido para vários pontos de dados antes de alargar,devido a cargas de trabalho transitórias.

Note

Além disso, recomendamos que defina outro alarme para a duplicação de valores inferiores a 10segundos. Se ultrapassar este limiar para vários pontos de dados, recomendamos que aumenteas suas instâncias ou reduza o seu rendimento de escrita na instância primária.

Gerenciamento de eventos do AmazonDocumentDB

O Amazon DocumentDB (compatível com MongoDB) mantém um registro de eventos que se relacionama seus clusters, instâncias, snapshots, grupos de segurança e grupos de parâmetros do cluster. Essasinformações incluem a data e a hora do evento, o nome e o tipo de origem do evento, além de umamensagem que está associada ao evento.

281

Amazon DocumentDB Guia do desenvolvedorExibição de categorias de eventos

Important

Para determinados recursos de gerenciamento, o Amazon DocumentDB usa tecnologiaoperacional compartilhada com o Amazon RDS e o Amazon Neptune. Os limites deregião, limites que são governados no nível da Região, são compartilhados entre AmazonDocumentDB, Amazon RDS e Amazon Neptune. Para obter mais informações, consulte Cotasregionais (p. 407).

Tópicos• Exibição de categorias de eventos do Amazon DocumentDB (p. 282)• Exibição de eventos do Amazon DocumentDB (p. 284)

Exibição de categorias de eventos do AmazonDocumentDBCada tipo de recurso do Amazon DocumentDB tem tipos específicos de eventos que podem serassociados a ele. Você pode usar a operação de AWS CLI describe-event-categories paravisualizar o mapeamento entre os tipos de evento e os tipos de recursos do Amazon DocumentDB.

Parâmetros

• --source-type—Opcional. Use o parâmetro --source-type para ver as categorias de evento paraum determinado tipo de origem. Os seguintes valores são permitidos:• db-cluster

• db-instance

• db-parameter-group

• db-security-group

• db-snapshot

• db-cluster-snapshot

• --filters—Opcional. Para visualizar as categorias de eventos para apenas o Amazon DocumentDB,use o filtro --filter Name=engine,Values=docdb.

Example

O código a seguir lista as categorias de eventos associadas aos clusters.


aws docdb describe-event-categories \ --filter Name=engine,Values=docdb \ --source-type db-cluster

Para Windows:

aws docdb describe-event-categories ^ --filter Name=engine,Values=docdb ^ --source-type db-cluster


{

282

Amazon DocumentDB Guia do desenvolvedorExibição de categorias de eventos

"EventCategoriesMapList": [ { "EventCategories": [ "notification", "failure", "maintenance", "failover" ], "SourceType": "db-cluster" } ]}

O código a seguir lista as categorias de eventos associadas a cada tipo de origem do AmazonDocumentDB.

aws docdb describe-event-categories


{ "EventCategoriesMapList": [ { "SourceType": "db-instance", "EventCategories": [ "notification", "failure", "creation", "maintenance", "deletion", "recovery", "restoration", "configuration change", "read replica", "backtrack", "low storage", "backup", "availability", "failover" ] }, { "SourceType": "db-security-group", "EventCategories": [ "configuration change", "failure" ] }, { "SourceType": "db-parameter-group", "EventCategories": [ "configuration change" ] }, { "SourceType": "db-snapshot", "EventCategories": [ "notification", "creation", "deletion", "restoration" ] },

283

Amazon DocumentDB Guia do desenvolvedorExibição de eventos do Amazon DocumentDB

{ "SourceType": "db-cluster", "EventCategories": [ "notification", "failure", "maintenance", "failover" ] }, { "SourceType": "db-cluster-snapshot", "EventCategories": [ "backup" ] } ]}

Exibição de eventos do Amazon DocumentDBVocê pode recuperar eventos para seus recursos do Amazon DocumentDB pelo console do AmazonDocumentDB, que mostra eventos das últimas 24 horas. Você também pode recuperar eventos para seusrecursos do Amazon DocumentDB usando o comando describe-events da AWS CLI ou a operação de APIDescribeEvents do Amazon DocumentDB. Se você usar a AWS CLI ou a API do Amazon DocumentDBpara visualizar eventos, poderá recuperar eventos até os últimos 14 dias.

Tópicos• Usar o Console de gerenciamento da AWS (p. 284)• Usar a AWS CLI (p. 284)

Usar o Console de gerenciamento da AWSPara exibir todos os eventos de instâncias do Amazon DocumentDB nas últimas 24 horas


2. No painel de navegação, selecione Events. Os eventos disponíveis aparecem em uma lista.3. Use a lista Filter (Filtro) para filtrar os eventos por tipo. Insira um termo na caixa de texto para filtrar os

resultados. Por exemplo, a captura de tela a seguir mostra a filtragem de todos os eventos do AmazonDocumentDB para eventos de snapshot.

Usar a AWS CLIPara exibir todos os eventos de instâncias do Amazon DocumentDB nos últimos 7 dias

Você pode ver todos os eventos de instâncias do Amazon DocumentDB dos últimos 7 dias, executandoa operação describe-events da AWS CLI com o parâmetro --duration definido como 10080 (10.080minutos).

284

https://docs.aws.amazon.com/cli/latest/reference/docdb/describe-events.html

https://docs.aws.amazon.com/documentdb/latest/developerguide/API_DescribeEvents.html


https://docs.aws.amazon.com/cli/latest/reference/docdb/describe-events.html

Amazon DocumentDB Guia do desenvolvedorExibição de eventos do Amazon DocumentDB

aws docdb describe-events --duration 10080

Filtragem para eventos do Amazon DocumentDBPara ver os eventos específicos do Amazon DocumentDB, use a operação describe-events com osseguintes parâmetros.

Parâmetros

• --filter — obrigatório para limitar os valores retornados para os eventos do Amazon DocumentDB.Use Name=engine,Values=docdb para filtrar todos os eventos apenas para o Amazon DocumentDB.

• --source-identifier—Opcional. O identificador da origem do evento para o qual os eventos sãoretornados. Se omitido, os eventos de todas as origens são incluídos nos resultados.

• --source-type — opcional, a menos que --source-identifier seja fornecido; nesse caso, seráobrigatório. Se --source-identifier for fornecido, --source-type deve estar de acordo com otipo do --source-identifier. Os seguintes valores são permitidos:• db-cluster

• db-instance

• db-parameter-group

• db-security-group

• db-snapshot

• db-cluster-snapshot

O exemplo a seguir lista todos os seus eventos do Amazon DocumentDB.

aws docdb describe-events --filters Name=engine,Values=docdb


{ "Events": [ { "SourceArn": "arn:aws:rds:us-east-1:123SAMPLE012:db:sample-cluster-instance3", "Message": "instance created", "SourceType": "db-instance", "Date": "2018-12-11T21:17:40.023Z", "SourceIdentifier": "sample-cluster-instance3", "EventCategories": [ "creation" ] }, { "SourceArn": "arn:aws:rds:us-east-1:123SAMPLE012:db:docdb-2018-12-11-21-08-23", "Message": "instance shutdown", "SourceType": "db-instance", "Date": "2018-12-11T21:25:01.245Z", "SourceIdentifier": "docdb-2018-12-11-21-08-23", "EventCategories": [ "availability" ] }, { "SourceArn": "arn:aws:rds:us-east-1:123SAMPLE012:db:docdb-2018-12-11-21-08-23", "Message": "instance restarted", "SourceType": "db-instance", "Date": "2018-12-11T21:25:11.441Z", "SourceIdentifier": "docdb-2018-12-11-21-08-23",

285

Amazon DocumentDB Guia do desenvolvedorEscolher regiões e zonas de disponibilidade

"EventCategories": [ "availability" ] } ]}

Para obter mais informações, consulte Auditoria de eventos do Amazon DocumentDB (p. 168).

Escolher regiões e zonas de disponibilidadeOs recursos de computação em nuvem da Amazon são hospedados em vários locais no mundo todo.Esses locais consistem em regiões da AWS e zonas de disponibilidade. Cada região da AWS é uma áreageográfica separada. Cada região possui vários locais isolados conhecidos como zonas de disponibilidade.O Amazon DocumentDB oferece a você a possibilidade de colocar recursos, como instâncias e dadosem vários locais. Os recursos não são replicados entre as diversas regiões da AWS, a menos que vocêespecifique isso.

A Amazon opera datacenters avançados e altamente disponíveis. Embora sejam raras, podem ocorrerfalhas que afetam a disponibilidade das instâncias que estão no mesmo local. Se você hospeda todas assuas instâncias em um único local afetado por tal falha, nenhuma delas ficará disponível. O diagrama aseguir mostra uma região da AWS com três zonas de disponibilidade.

É importante lembrar que cada região é totalmente independente. Qualquer atividade do AmazonDocumentDB que você iniciar, por exemplo, criar instâncias ou listar instâncias disponíveis, será executaraapenas na sua região da AWS padrão atual. Você também pode alterar a região padrão no console,definindo a variável de ambiente EC2_REGION. Ou pode substituí-la usando o parâmetro --region naAWS CLI. Para obter mais informações, consulte Configurar a interface de linha de comando da AWS,especificamente as seções sobre variáveis de ambiente e opções de linha de comando.

Quando você cria um cluster usando o console do Amazon DocumentDB e escolhe criar uma réplica emuma zona de disponibilidade diferente, o Amazon DocumentDB cria duas instâncias. A instância principalé criada em uma zona de disponibilidade e a instância de réplica em uma outra zona de disponibilidade. Ovolume do cluster é sempre replicado em três zonas de disponibilidade.

Para criar ou trabalhar com uma instância do Amazon DocumentDB em uma região da AWS específica,use o endpoint de serviço regional correspondente.

286

https://docs.aws.amazon.com/cli/latest/userguide/cli-chap-getting-started.html

Amazon DocumentDB Guia do desenvolvedorDisponibilidade da região

Disponibilidade da regiãoO Amazon DocumentDB está disponível nas seguintes regiões da AWS.

Regiões compatíveis com o Amazon DocumentDB




us-east-1 6.


us-west-2 4.




ap-southeast-1 3.









Por padrão, o fuso horário de um cluster do Amazon DocumentDB é o Tempo Universal Coordenado(UTC).

Para obter informações sobre como localizar endpoints de conexão para clusters e instâncias em umaregião específica, consulte Noções básicas sobre endpoints do Amazon DocumentDB (p. 312).

Managing Amazon DocumentDB Cluster ParameterGroups

Você pode gerir a configuração do mecanismo do Amazon DocumentDB usando parâmetros em um grupode parâmetros de cluster. Um cluster parameter group é uma coleção de Amazon DocumentDB valoresde configuração que facilitam a gestão dos parâmetros do seu Amazon DocumentDB grupos. Parametergroups de cluster atuam como contêiner de valores de configuração de mecanismo que são aplicados atodas as instâncias no cluster.

Esta seção descreve como criar, exibir e modificar grupos de parâmetros de cluster. Ele também mostracomo é possível determinar qual grupo de parâmetros de cluster está associado a um determinado cluster.

287

Amazon DocumentDB Guia do desenvolvedorDescribing Cluster Parameter Groups

Tópicos• Describing Amazon DocumentDB Cluster Parameter Groups (p. 288)• Creating Amazon DocumentDB Cluster Parameter Groups (p. 293)• Modifying Amazon DocumentDB Cluster Parameter Groups (p. 295)• Modifying Amazon DocumentDB Clusters to Use Customized Cluster Parameter Groups (p. 298)• Copying Amazon DocumentDB Cluster Parameter Groups (p. 299)• Resetting Amazon DocumentDB Cluster Parameter Groups (p. 301)• Deleting Amazon DocumentDB Cluster Parameter Groups (p. 303)• Amazon DocumentDB Cluster Parameters Reference (p. 305)

Describing Amazon DocumentDB Cluster ParameterGroupsAo criar um cluster do Amazon DocumentDB, um grupo de parâmetros de cluster default.docdb3.6é criado automaticamente para esse cluster. É possível exibir os detalhes desse grupo de parâmetrosde cluster padrão ou quaisquer grupos de parâmetros de cluster adicionais que você tenha. Também épossível determinar qual grupo de parâmetros está associado a um cluster específico.

Tópicos• Describing the Details of an Amazon DocumentDB Cluster Parameter Group (p. 288)• Determining an Amazon DocumentDB Cluster's Parameter Group (p. 291)

Describing the Details of an Amazon DocumentDB ClusterParameter GroupPara descrever os detalhes de um determinado grupo de parâmetros de cluster, conclua as etapas aseguir usando o Console de gerenciamento da AWS ou a AWS Command Line Interface (AWS CLI).



2. No painel de navegação, selecione Parameter groups (Grupos de parâmetros).

Tip


3. No painel Cluster parameter groups (Grupos de parâmetros de cluster), escolha o nome do grupo deparâmetros de cluster do qual deseja visualizar os detalhes.

4. A página resultante exibe os parâmetros do grupo de parâmetros, a atividade recente e as tags.

• Under Cluster parameters, you can see the parameter's name, current value, allowed values,whether the parameter is modifiable, its apply type, data type, and description. You can modifyindividual parameters by selecting the parameter and then choosing Edit in the Cluster parameterssection. For more information, see Modifying Amazon DocumentDB Cluster Parameters (p. 307).

• Under Recent events, you can see the most recent events for this parameter group. You can filterthrough these events using the search bar in this section. For more information, see Gerenciamentode eventos do Amazon DocumentDB (p. 281).

288



• Under Tags, you can see the tags that are on this cluster parameter group. You can add or removetags by choosing Edit in the Tags section. For more information, see Marcar recursos do AmazonDocumentDB (p. 321).

Using the AWS CLI

É possível usar o comando describe-db-cluster-parameter-groups da AWS CLI para visualizaro nome de recurso da Amazon (ARN), a família, a descrição e o nome de um único grupo de parâmetrosde cluster ou de todos os grupos de parâmetros de cluster que você tem para o Amazon DocumentDB.Também é possível usar o comando describe-db-cluster-parameters da AWS CLI para exibir osparâmetros e seus detalhes em um único grupo de parâmetros de cluster.

• --describe-db-cluster-parameter-groups — To see a listing of all your cluster parametergroups and their details.• --db-cluster-parameter-group-name — Optional. The name of the cluster parameter group

that you want described. If this parameter is omitted, all cluster parameter groups are described.• --describe-db-cluster-parameters — To list all the parameters inside a parameter group and

their values.• --db-cluster-parameter-group name — Required. The name of the cluster parameter group

that you want described.

Example

O código a seguir lista até 100 grupos de parâmetros de cluster e seu ARN, família, descrição e nome.

aws docdb describe-db-cluster-parameter-groups


{ "DBClusterParameterGroups": [ { "DBClusterParameterGroupArn": "arn:aws:rds:us-east-1:012345678912:cluster-pg:default.docdb3.6", "DBParameterGroupFamily": "docdb3.6", "Description": "Default cluster parameter group for docdb3.6", "DBClusterParameterGroupName": "default.docdb3.6" }, { "DBClusterParameterGroupArn": "arn:aws:rds:us-east-1:012345678912:cluster-pg:sample-parameter-group", "DBParameterGroupFamily": "docdb3.6", "Description": "Custom docdb3.6 parameter group", "DBClusterParameterGroupName": "sample-parameter-group" } ]}

Example

O código a seguir lista o ARN, a família, a descrição e o nome do sample-parameter-group.


aws docdb describe-db-cluster-parameter-groups \

289


--db-cluster-parameter-group-name sample-parameter-group

Para Windows:

aws docdb describe-db-cluster-parameter-groups ^ --db-cluster-parameter-group-name sample-parameter-group


{ "DBClusterParameterGroups": [ { "DBClusterParameterGroupArn": "arn:aws:rds:us-east-1:123456789012:cluster-pg:sample-parameter-group", "Description": "Custom docdb3.6 parameter group", "DBParameterGroupFamily": "docdb3.6", "DBClusterParameterGroupName": "sample-parameter-group" } ]}

Example

O código a seguir lista os valores dos parâmetros no sample-parameter-group.


aws docdb describe-db-cluster-parameters \ --db-cluster-parameter-group-name sample-parameter-group

Para Windows:

aws docdb describe-db-cluster-parameters ^ --db-cluster-parameter-group-name sample-parameter-group


{ "Parameters": [ { "ParameterName": "audit_logs", "ParameterValue": "disabled", "Description": "Enables auditing on cluster.", "Source": "system", "ApplyType": "dynamic", "DataType": "string", "AllowedValues": "enabled,disabled", "IsModifiable": true, "ApplyMethod": "pending-reboot" }, { "ParameterName": "change_stream_log_retention_duration", "ParameterValue": "17777",

290


"Description": "Duration of time in seconds that the change stream log is retained and can be consumed.", "Source": "user", "ApplyType": "dynamic", "DataType": "integer", "AllowedValues": "3600-86400", "IsModifiable": true, "ApplyMethod": "pending-reboot" } ]}

Determining an Amazon DocumentDB Cluster's Parameter GroupPara determinar qual grupo de parâmetros está associado a um cluster específico, conclua as etapas aseguir usando o Console de gerenciamento da AWS ou a AWS CLI.



2. No painel de navegação à esquerda, escolha Clusters.3. Na lista de clusters, selecione o nome do cluster desejado.4. A página resultante exibe os detalhes do cluster selecionado. Role para baixo até Cluster details

(Detalhes do cluster). Na parte inferior dessa seção, localize o nome do grupo de parâmetros sobCluster parameter group (Grupo de parâmetros de cluster).

291



292

Amazon DocumentDB Guia do desenvolvedorCreating Cluster Parameter Groups

Using the AWS CLI

O código de AWS CLI a seguir determina qual grupo de parâmetros está regendo o cluster sample-cluster.

aws docdb describe-db-clusters \ --db-cluster-identifier sample-cluster \ --query 'DBClusters[*].[DBClusterIdentifier,DBClusterParameterGroup]'


[ [ "sample-cluster", "sample-parameter-group" ]]

Creating Amazon DocumentDB Cluster ParameterGroupsAmazon DocumentDB fornece um grupo de parâmetros de grupo predefinido com base no docdb3.6familiar nomeado default.docdb3.6. You cannot modify the default.docdb3.6 cluster parametergroup directly. Para personalizar os parâmetros dentro de um grupo de parâmetros de grupo e associá-los à sua Amazon DocumentDB , tem primeiro de criar um novo grupo de parâmetros de grupo nãopredefinido. Depois, pode modificar os parâmetros dentro desse novo grupo de parâmetros personalizadose associá-los à sua Amazon DocumentDB grupo.

O procedimento a seguir orienta você na criação de um grupo de parâmetros de cluster personalizado combase na família docdb3.6. Depois disso, é possível modificar os parâmetros nesse grupo de parâmetros.

Note

Depois de modificar um grupo de parâmetros de cluster, é necessário esperar pelo menos5 minutos antes de usar esse grupo de parâmetros de cluster. Isso permite que o AmazonDocumentDB conclua a ação create antes que o grupo de parâmetros de cluster seja usadopara um novo cluster. É possível usar o Console de gerenciamento da AWS ou a operaçãodescribe-db-cluster-parameter-groups da AWS CLI para verificar se o grupo deparâmetros de cluster foi criado. Para obter mais informações, consulte Describing AmazonDocumentDB Cluster Parameter Groups (p. 288).


Para criar um parameter group de cluster



Tip


3. No painel Cluster parameter groups (Grupos de parâmetros de cluster), escolha Create (Criar).

293

https://docs.aws.amazon.com//documentdb/latest/developerguide/cluster_parameter_groups-modify.html


Amazon DocumentDB Guia do desenvolvedorCreating Cluster Parameter Groups

4. No painel Create cluster parameter group (Criar grupo de parâmetros do cluster) insira o seguinte:

a. Group name (Nome do grupo) — digite um nome para o grupo de parâmetros de cluster. Porexemplo, sample-parameter-group. Os grupos de parâmetros do cluster têm as seguintesrestrições de nomenclatura:

• Length is [1–255] alphanumeric characters.• First character must be a letter.• Cannot end with a hyphen or contain two consecutive hyphens.

b. Description (Descrição) — fornece uma descrição para este grupo de parâmetros de cluster.5. Para criar o parameter group de cluster, escolha Create (Criar). Para cancelar a operação, escolha

Cancel (Cancelar).6. Depois de escolher Create (Criar), o texto a seguir será exibido na parte superior da página para

verificar se o grupo de parâmetros de cluster foi criado com êxito:

Successfully created cluster parameter group 'sample-parameter-group'.

Using the AWS CLI

Para criar um novo grupo de parâmetros de cluster, use a operação create-db-cluster-parameter-group da AWS CLI, com os seguintes parâmetros:

• --db-cluster-parameter-group-name — The name of the custom cluster parameter group. Forexample, sample-parameter-group.

• --db-cluster-parameter-group-family — The cluster parameter group family that is used as thetemplate for the custom cluster parameter group. Currently, this must be docdb3.6.

• --description — The user-provided description for this cluster parameter group. The followingexample uses "Custom docdb3.6 parameter group".


Example

aws docdb create-db-cluster-parameter-group \ --db-cluster-parameter-group-name sample-parameter-group \ --db-parameter-group-family docdb3.6 \ --description "Custom docdb3.6 parameter group"

Para Windows:

aws docdb create-db-cluster-parameter-group ^ --db-cluster-parameter-group-name sample-parameter-group ^ --db-parameter-group-family docdb3.6 ^ --description "Custom docdb3.6 parameter group"


{ "DBClusterParameterGroup": { "DBClusterParameterGroupName": "sample-parameter-group", "DBParameterGroupFamily": "docdb3.6", "Description": "Custom docdb3.6 parameter group", "DBClusterParameterGroupArn": "sample-parameter-group-arn" }

294

Amazon DocumentDB Guia do desenvolvedorModifying Cluster Parameter Groups

}

Modifying Amazon DocumentDB Cluster ParameterGroupsEsta secção explica como modificar uma custom Amazon DocumentDB grupo de parâmetros. NoAmazon DocumentDB, não é possível fazer modificações diretamente no grupo de parâmetros de clusterdefault.docdb3.6. Se o cluster do Amazon DocumentDB estiver usando o grupo de parâmetros decluster padrão, e você desejar modificar um valor nele, primeiro será necessário criar um novo grupo deparâmetros ou copiar um grupo de parâmetros existente, modificá-lo e aplicar o grupo de parâmetrosmodificado ao seu cluster.

Conclua as etapas a seguir para modificar um grupo de parâmetros de cluster não padrão. Depois demodificar um grupo de parâmetros de cluster, é necessário esperar pelo menos 5 minutos antes de usá-lo. Isso permite que o Amazon DocumentDB conclua a ação modify antes que o grupo de parâmetros decluster seja usado. É possível usar o Console de gerenciamento da AWS ou a operação describe-db-cluster-parameters da AWS CLI para verificar se o grupo de parâmetros de cluster foi modificado.Para obter mais informações, consulte Describing Cluster Parameter Groups (p. 288).

Using the Console de gerenciamento da AWSSiga estas etapas para modificar um grupo de parâmetros do Amazon DocumentDB personalizado. Nãoé possível modificar um grupo de parâmetros default. Se você deseja modificar um valor no grupo deparâmetros default, você pode copiar o grupo de parâmetros de cluster padrão, modificá-lo e aplicar ogrupo de parâmetros modificado ao cluster. Para obter mais informações sobre como aplicar grupos deparâmetros ao cluster, consulte Modificar um cluster do Amazon DocumentDB (p. 231).

Para modificar um parameter group de cluster personalizado


2. No painel de navegação, no lado esquerdo do console, selecione Parameter groups (Grupos deparâmetros). Na lista de parameter groups, escolha o nome do parameter group que você desejamodificar.

Tip


3. Para cada parâmetro no parameter group que você deseja modificar, faça o seguinte:

a. Localize o parâmetro que você deseja modificar e verifique se ele é modificável, verificando se eleestá listado como true na coluna Modifiable (Modificável).

b. Se for modificável, selecione o parâmetro e escolha Edit (Editar) no canto superior direito dapágina do console.

c. Na caixa de diálogo Modify <parameter-name>(Modificar <parameter-name>), faça asalterações que você deseja. Depois disso, escolha Modify cluster parameter (Modificar parâmetrode cluster) ou escolha Cancel (Cancelar) para descartar as alterações.

Using the AWS CLIÉ possível modificar o ParameterValue, a Description ou o ApplyMethod de qualquer parâmetromodificável em um grupo de parâmetros de cluster do Amazon DocumentDB usando a AWS CLI. Não épossível fazer modificações diretamente em um grupo de parâmetros de cluster.

295

https://docs.aws.amazon.com//documentdb/latest/developerguide/cluster_parameter_groups-create.html


https://docs.aws.amazon.com//documentdb/latest/developerguide/cluster_parameter_groups-copy.html

https://docs.aws.amazon.com//documentdb/latest/developerguide/cluster_parameter_groups-copy.html



Para modificar os parâmetros de um grupo de parâmetros de cluster personalizado, use a operaçãomodify-db-cluster-parameter-group com os parâmetros a seguir.

• --db-cluster-parameter-group-name — Required. The name of the cluster parameter group thatyou are modifying.

• --parameters — Required. The parameters that you are modifying. For a list of the parametersthat apply to all instances in an Amazon DocumentDB cluster, see the Amazon DocumentDB ClusterParameters Reference (p. 305). Each parameter entry must include the following:• ParameterName — The name of the parameter that you are modifying.• ParameterValue — The new value for this parameter.• ApplyMethod — How you want changes to this parameter applied. Permitted values are immediate

and pending-reboot.

Note

Parameters with the ApplyType of static must have an ApplyMethod of pending-reboot.

Example - Modificar o valor de um parâmetro

Neste exemplo, você lista os valores de parâmetro de sample-parameter-group e modifica oparâmetro tls. Em seguida, após esperar 5 minutos, você listará novamente os valores dos parâmetrosdo sample-parameter-group para ver os valores dos parâmetros alterados.

1. Liste os parâmetros e os valores do sample-parameter-group.



Para Windows:



{ "Parameters": [ { "Source": "system", "ApplyType": "static", "AllowedValues": "disabled,enabled", "ParameterValue": "enabled", "ApplyMethod": "pending-reboot", "DataType": "string", "ParameterName": "tls", "IsModifiable": true, "Description": "Config to enable/disable TLS" }, { "Source": "user", "ApplyType": "dynamic", "AllowedValues": "disabled,enabled", "ParameterValue": "enabled", "ApplyMethod": "pending-reboot", "DataType": "string",

296


"ParameterName": "ttl_monitor", "IsModifiable": true, "Description": "Enables TTL Monitoring" } ]}

2. Modifique o parâmetro tls para que seu valor seja disabled.

Não é possível modificar o ApplyMethod porque o ApplyType é static.


aws docdb modify-db-cluster-parameter-group \ --db-cluster-parameter-group-name sample-parameter-group \ --parameters "ParameterName"=tls,"ParameterValue"=disabled,"ApplyMethod"=pending-reboot

Para Windows:

aws docdb modify-db-cluster-parameter-group ^ --db-cluster-parameter-group-name sample-parameter-group ^ --parameters "ParameterName"=tls,"ParameterValue"=disabled,"ApplyMethod"=pending-reboot


{ "DBClusterParameterGroupName": "sample-parameter-group" }

3. Aguarde pelo menos 5 minutos.4. Liste os valores de parâmetros de sample-parameter-group para verificar se o parâmetro tls foi

modificado.



Para Windows:



{ "Parameters": [ { "ParameterValue": "false", "ParameterName": "enable_audit_logs", "ApplyType": "dynamic", "DataType": "string", "Description": "Enables auditing on cluster.", "AllowedValues": "true,false", "Source": "system", "IsModifiable": true,

297

Amazon DocumentDB Guia do desenvolvedorModifying Clusters to Use Customized

Cluster Parameter Groups

"ApplyMethod": "pending-reboot" }, { "ParameterValue": "disabled", "ParameterName": "tls", "ApplyType": "static", "DataType": "string", "Description": "Config to enable/disable TLS", "AllowedValues": "disabled,enabled", "Source": "system", "IsModifiable": true, "ApplyMethod": "pending-reboot" } ]}

Modifying Amazon DocumentDB Clusters to UseCustomized Cluster Parameter GroupsAo criar um cluster do Amazon DocumentDB, um grupo de parâmetros default.docdb3.6 é criadoautomaticamente para esse cluster. Não é possível modificar o grupo de parâmetros de cluster default.Em vez disso, é possível modificar seu cluster do Amazon DocumentDB para associar um novo grupo deparâmetros personalizado a ele.

Esta seção explica como modificar um cluster do Amazon DocumentDB existente para usar um grupo deparâmetros de cluster personalizado, usando o Console de gerenciamento da AWS e a AWS CommandLine Interface (AWS CLI).


Como modificar um cluster do Amazon DocumentDB para usar um novo grupo de parâmetros decluster não padrão

1. Antes de começar, lembre-se de criar um cluster do Amazon DocumentDB e um grupo de parâmetrosde cluster. Consulte Criação de um cluster do Amazon DocumentDB (p. 217) e Creating AmazonDocumentDB Cluster Parameter Groups (p. 293) para obter mais instruções.

2. Depois de criar o grupo de parâmetros de cluster, abra o console do Amazon DocumentDB em https://console.aws.amazon.com/docdb. No painel de navegação, escolha Clusters para adicionar o novogrupo de parâmetros a um cluster.

3. Escolha o cluster ao qual você deseja associar seu grupo de parâmetros. Escolha Actions (Ações) eModify (Modificar) para modificar seu cluster.

4. Em Cluster options (Opções de cluster), escolha o novo grupo de parâmetros ao qual você desejaassociar o cluster.

5. Escolha Continue (Continuar) para exibir um resumo das modificações.6. Depois de verificar suas alterações, é possível aplicá-las imediatamente ou durante a próxima janela

de manutenção em Scheduling of modifications (Programação de modificações).7. Escolha Modify cluster (Modificar cluster) para atualizar seu cluster com o novo grupo de parâmetros.

Using the AWS CLI

Antes de começar, lembre-se de criar um cluster do Amazon DocumentDB e um grupo de parâmetros decluster. É possível criar um cluster do Amazon DocumentDB usando a operação create-db-cluster daAWS CLI. É possível criar um grupo de parâmetros de cluster personalizado usando a operação create-db-cluster-parameter-group da AWS CLI.

298



https://docs.aws.amazon.com//documentdb/latest/developerguide/db-cluster-create.html


Amazon DocumentDB Guia do desenvolvedorCopying Cluster Parameter Groups

Para adicionar o novo grupo de parâmetros de cluster ao cluster, use a operação modify-db-clusterda AWS CLI com os seguintes parâmetros.

• --db-cluster-identifier — The name of your cluster (for example, sample-cluster).• --db-cluster-parameter-group-name — The name of the parameter group that you want to associate your

cluster with (for example, sample-parameter-group).

Example

aws docdb modify-db-cluster \ --db-cluster-identifier sample-cluster --db-cluster-parameter-group-name sample-parameter-group


"DBCluster": { "AvailabilityZones": [ "us-west-2c", "us-west-2b", "us-west-2a" ], "BackupRetentionPeriod": 1, "DBClusterIdentifier": "sample-cluster", "DBClusterParameterGroup": "sample-parameter-group", "DBSubnetGroup": "default", ...}

Copying Amazon DocumentDB Cluster ParameterGroupsÉ possível fazer uma cópia de um grupo de parâmetros de cluster no Amazon DocumentDB usando oConsole de gerenciamento da AWS ou aAWS Command Line Interface (AWS CLI).

Using the Console de gerenciamento da AWSO procedimento a seguir orienta você durante a criação de um novo grupo de parâmetros de clusterfazendo uma cópia de um grupo de parâmetros de cluster existente.

Como copiar um grupo de parâmetros de cluster


2. No painel de navegação, selecione Parameter groups (Grupos de parâmetros).3. No painel Cluster parameter groups (Grupos de parâmetros de cluster), escolha o nome do grupo de

parâmetros de cluster que você deseja copiar.4. Escolha Actions (Ações) e Copy (Copiar) para copiar esse grupo de parâmetros.5. Em Copy options (Opções de cópia), insira um nome e uma descrição para o novo grupo de

parâmetros de cluster. Depois disso, escolha Copy (Copiar) para salvar as alterações.

Using the AWS CLIPara fazer uma cópia de um parameter group de cluster, use a operação copy-db-cluster-parameter-group com os parâmetros a seguir.

299


Amazon DocumentDB Guia do desenvolvedorCopying Cluster Parameter Groups

• --source-db-cluster-parameter-group-identifier — Required. The name or AmazonResource Name (ARN) of the cluster parameter group that you want to make a copy of.

If the source and target cluster parameter groups are in the same AWS Region, the identifier can beeither a name or an ARN.

If the source and target cluster parameter groups are in different AWS Regions, the identifier must be anARN.

• --target-db-cluster-parameter-group-identifier — Required. The name or ARN of thecluster parameter group copy.

Constraints:• Cannot be null, empty, or blank.• Must contain 1–255 letters, numbers, or hyphens.• First character must be a letter.• Cannot end with a hyphen or contain two consecutive hyphens.

• --target-db-cluster-parameter-group-description — Required. A user-supplied descriptionfor the cluster parameter group copy.

Example

O código a seguir faz uma cópia de sample-parameter-group, nomeando a cópia sample-parameter-group-copy.


aws docdb copy-db-cluster-parameter-group \ --source-db-cluster-parameter-group-identifier sample-parameter-group \ --target-db-cluster-parameter-group-identifier sample-parameter-group-copy \ --target-db-cluster-parameter-group-description "Copy of sample-parameter-group"

Para Windows:

aws docdb copy-db-cluster-parameter-group ^ --source-db-cluster-parameter-group-identifier sample-parameter-group ^ --target-db-cluster-parameter-group-identifier sample-parameter-group-copy ^ --target-db-cluster-parameter-group-description "Copy of sample-parameter-group"


{ "DBClusterParameterGroup": { "DBClusterParameterGroupArn": "arn:aws:rds:us-east-1:123456789012:cluster-pg:sample-parameter-group-copy", "DBClusterParameterGroupName": "sample-parameter-group-copy", "DBParameterGroupFamily": "docdb3.6", "Description": "Copy of sample-parameter-group" }}

300

Amazon DocumentDB Guia do desenvolvedorResetting Cluster Parameter Groups

Resetting Amazon DocumentDB Cluster ParameterGroupsÉ possível redefinir alguns ou todos os valores de parâmetro de um grupo de parâmetros de cluster doAmazon DocumentDB como seus valores padrão usando o Console de gerenciamento da AWS ou a AWSCommand Line Interface (AWS CLI) para redefinir o grupo de parâmetros de cluster.

Using the Console de gerenciamento da AWSSiga estas etapas para redefinir alguns ou todos os valores de parâmetros de um grupo de parâmetros decluster como seus valores padrão.

Como redefinir os valores de parâmetros de um grupo de parâmetros de cluster


2. No painel de navegação, no lado esquerdo do console, selecione Parameter groups (Grupos deparâmetros).

3. No painel Cluster parameter groups (Grupos de parâmetros de cluster), escolha o nome do grupo deparâmetros de cluster que você deseja redefinir.

4. Escolha Actions (Ações) e Reset (Redefinir) para redefinir esse grupo de parâmetros.5. Na página Cluster parameter group reset confirmation (Confirmação de redefinição do grupo de

parâmetros de cluster) resultante, confirme se você deseja redefinir todos os parâmetros de clusterpara esse grupo de parâmetros como seus padrões. Depois disso, escolha Reset (Redefinir) pararedefinir o grupo de parâmetros. Também é possível escolher Cancel (Cancelar) para cancelar asalterações.

Using the AWS CLIPara redefinir alguns ou todos os valores de parâmetro do parameter group de cluster para seus valorespadrão, use a operação reset-db-cluster-parameter-group com os parâmetros a seguir.

• --db-cluster-parameter-group-name — Required. The name of the cluster parameter group toreset.

• --parameters — Optional. A list of ParameterName and ApplyMethod in the cluster parametergroup to reset to their default values. Static parameters must be set to pending-reboot to take effecton the next instance restart or reboot-db-instance request. You must call reboot-db-instancefor every instance in your cluster that you want the updated static parameter to apply to.

This parameter and --reset-all-parameters are mutually exclusive: you can use either one but notboth.

• --reset-all-parameters or --no-reset-all-parameters — Optional. Specifies whether toreset all parameters (--reset-all-parameters or only some of the parameters (--no-reset-all-parameters) to their default values. The --reset-all-parameters parameter and --parametersare mutually exclusive: you can use either one but not both.

When you reset the entire group, dynamic parameters are updated immediately. Static parameters areset to pending-reboot to take effect on the next instance restart or reboot-db-instance request.You must call reboot-db-instance for every instance in your cluster that you want the updated staticparameter applied to.

Example

Exemplo: = 1. Repor todos os parâmetros para os valores predefinidos

301


Amazon DocumentDB Guia do desenvolvedorResetting Cluster Parameter Groups

O código a seguir redefine todos os parâmetros no parameter group de cluster sample-parameter-group para os valores padrão.


aws docdb reset-db-cluster-parameter-group \ --db-cluster-parameter-group-name sample-parameter-group \ --reset-all-parameters

Para Windows:

aws docdb reset-db-cluster-parameter-group ^ --db-cluster-parameter-group-name sample-parameter-group ^ --reset-all-parameters

Exemplo: = 2. Repor parâmetros especificados para os valores predefinidos

O código a seguir redefine o parâmetro tls no parameter group de cluster sample-parameter-grouppara seu valor padrão.


aws docdb reset-db-cluster-parameter-group \ --db-cluster-parameter-group-name sample-parameter-group \ --no-reset-all-parameters \ --parameters ParameterName=tls,ApplyMethod=pending-reboot

Para Windows:

aws docdb reset-db-cluster-parameter-group ^ --db-cluster-parameter-group-name sample-parameter-group ^ --no-reset-all-parameters ^ --parameters ParameterName=tls,ApplyMethod=pending-reboot


{ "DBClusterParameterGroupName": "sample-parameter-group" }

Reinicializar uma instância de cluster

Antes que o valor de um parâmetro estático seja alterado, a instância do cluster deve ser reinicializada.Reinicialize cada instância no cluster à qual você deseja que o parâmetro estático atualizado seja aplicado.


aws docdb reboot-db-instance \ --db-instance-identifier sample-cluster-instance

Para Windows:

aws docdb reboot-db-instance ^ --db-instance-identifier sample-cluster-instance

302

Amazon DocumentDB Guia do desenvolvedorDeleting Cluster Parameter Groups

Deleting Amazon DocumentDB Cluster ParameterGroupsÉ possível excluir um grupo de parâmetros de cluster personalizado do Amazon DocumentDB usando oConsole de gerenciamento da AWS ou a AWS Command Line Interface (AWS CLI). Não é possível excluiro grupo de parâmetros de cluster default.docdb3.6.


Para excluir um parameter group de cluster


2. No painel de navegação, selecione Parameter groups (Grupos de parâmetros).Tip


3. No painel Parameter groups, escolha o botão de opção à esquerda do parameter group de cluster quedeseja excluir.

4. Escolha Actions (Ações) e escolha Delete (Excluir).5. No painel de confirmação Delete (Excluir), escolha Delete (Excluir) para excluir o grupo de parâmetros

de cluster. Para manter o grupo de parâmetros de cluster, escolha Cancel (Cancelar).

Using the AWS CLIPara excluir um parameter group de cluster, use a operação delete-db-cluster-parameter-groupcom o parâmetro a seguir.

• --db-cluster-parameter-group-name — Required. The name of the cluster parameter group todelete. This must be an existing cluster parameter group. You cannot delete the default.docdb3.6cluster parameter group.

Example - Excluir um parameter group de cluster

O exemplo a seguir mostra as três etapas para excluir um parameter group de cluster:

1. Localizar o nome do parameter group de cluster que você deseja excluir.2. Excluir o parameter group de cluster especificado.3. Verificar se o parameter group de cluster foi excluído.

1 Localize o nome do parameter group de cluster que você deseja excluir.

O código a seguir lista os nomes de todos os parameter groups de cluster.


aws docdb describe-db-cluster-parameter-groups \ --query 'DBClusterParameterGroups[*].[DBClusterParameterGroupName]'

Para Windows:

303


Amazon DocumentDB Guia do desenvolvedorDeleting Cluster Parameter Groups

aws docdb describe-db-cluster-parameter-groups ^ --query 'DBClusterParameterGroups[*].[DBClusterParameterGroupName]'

A saída da operação anterior é uma lista dos nomes dos grupos de parâmetros de cluster semelhantes àseguinte (formato JSON).

[ [ "default.docdb3.6" ], [ "sample-parameter-group" ], [ "sample-parameter-group-copy" ] ]

2. Exclua um parameter group de cluster específico.

O código a seguir exclui o parameter group de cluster sample-parameter-group-copy.


aws docdb delete-db-cluster-parameter-group \ --db-cluster-parameter-group-name sample-parameter-group-copy

Para Windows:

aws docdb delete-db-cluster-parameter-group ^ --db-cluster-parameter-group-name sample-parameter-group-copy

Não há saída dessa operação.

3. Verifique se o parameter group de cluster especificado foi excluído.

O código a seguir lista os nomes de todos os parameter groups de cluster restantes.


aws docdb describe-db-cluster-parameter-groups \ --query 'DBClusterParameterGroups[*].[DBClusterParameterGroupName]'

Para Windows:

aws docdb describe-db-cluster-parameter-groups ^ --query 'DBClusterParameterGroups[*].[DBClusterParameterGroupName]'

A saída da operação anterior é uma lista dos parameter groups de cluster semelhantes ao seguinte(formato JSON). O parameter group de cluster que você acabou de excluir não deve estar na lista.


[ [ "default.docdb3.6" ], [

304

Amazon DocumentDB Guia do desenvolvedorCluster Parameters Reference

"sample-parameter-group" ] ]

Amazon DocumentDB Cluster Parameters ReferenceAo alterar um parâmetro dinâmico e salvar o grupo de parâmetros de cluster, a alteração é aplicadaimediatamente, independentemente da configuração Apply immediately. Quando você altera um parâmetroestático e salva o parameter group do cluster, a alteração do parâmetro entra em vigor depois que vocêreinicia manualmente a instância do cluster. Você pode reiniciar uma instância usando o console doAmazon DocumentDB ou chamando explicitamente reboot-db-instance.

A tabela a seguir mostra os parâmetros que se aplicam a todas as instâncias em um cluster do AmazonDocumentDB.

Parâmetros no nível do cluster do Amazon DocumentDB

Parâmetro: Valor padrão Valores válidosPermitemodificação

Aplicar tipo Tipo dedados

Description(Descrição)

audit_logs disabled ativado,desativado

Sim. Dinâmico String. Define seos logs deauditoriado AWSCloudTrailestãoativados.

• enabled—CloudTrailauditlogs areenabled.

• disabled—CloudTrailauditlogs aredisabled.

change_stream_log_retention_duration10800 3600-86400 Sim. Dinâmico : inteiro Define aduração dotempo (emsegundos)em que olog do fluxode alteraçãoé retido epode serconsumido.

profiler disabled ativado,desativado

Sim. Dinâmico String. Permite acriação doperfil paraoperaçõeslentas.

• enabled—operations

305





that takelongerthan acustomer-definedthresholdvalue(e.g.,100ms)are loggedtoAmazonCloudWatchLogs.

• disabled—slowoperationsare notlogged toCloudWatchLogs.

profiler_sampling_rate1.0 0.0-1.0 Sim. Dinâmico Float Define ataxa deamostragemdeoperaçõesregistradas.

profiler_threshold_ms-100 50-2147483646 Sim. Dinâmico : inteiro Define olimite paraprofiler

• Alloperationsgreaterthanprofiler_threshold_msarelogged toCloudWatchLogs.

306





tls enabled ativado,desativado

Sim. Estático String. Define se asconexõesTransportLayerSecurity(TLS) sãonecessárias.

• enabled—TLSconnectionsarerequired toconnect.

• disabled—TLSconnectionscannot beused toconnect.

ttl_monitor enabled ativado,desativado

Sim. Dinâmico String. Define se omonitoramentode Time toLive (TTL –Tempo devida) estáhabilitadopara ocluster.

• enabled—TTLmonitoringis enabled.

• disabled—TTLmonitoringisdisabled.

Modifying Amazon DocumentDB Cluster ParametersEm Amazon DocumentDB, cluster parameter groups consiste em parameters que se aplicam a todas asinstâncias criadas no grupo. Para grupos de parâmetros de cluster personalizados, é possível modificar umvalor de parâmetro a qualquer momento ou redefinir todos os valores de parâmetro como seus padrõespara os grupos de parâmetros criados. Esta seção descreve como visualizar os parâmetros e valores deum grupo de parâmetros de cluster do Amazon DocumentDB e como é possível alterar ou atualizar essesvalores.

Os parâmetros podem ser dynamic ou static. Quando altera um parâmetro dinâmico e guarda ogrupo de parâmetros do grupo, a alteração é aplicada imediatamente, independentemente do ApplyImmediately definição. Quando você altera um parâmetro estático e salva o grupo de parâmetros do

307


cluster, a alteração do parâmetro entra em vigor depois que você reinicia manualmente a instância docluster.

Viewing an Amazon DocumentDB Cluster Parameter Group's ParametersVocê pode ver os parâmetros de um cluster do Amazon DocumentDB e seus valores usando o Console degerenciamento da AWS ou a AWS CLI.


Para visualizar os detalhes de um parameter group de cluster




3. No painel Parameter groups, escolha o nome do parameter group do cluster do qual deseja visualizaros detalhes.

4. A página resultante exibe os seguintes valores para cada parâmetro: o nome do parâmetro, o valoratual, os valores permitidos, se o parâmetro é modificável, o tipo de aplicação, o tipo de dados e adescrição.

Using the AWS CLI

Para ver os parâmetros de um parameter group de cluster e seus valores, use a operação describe-db-cluster-parameters com os seguintes parâmetros.

• --db-cluster-parameter-group-name — Required. The name of the cluster parameter group forwhich you want a detailed parameter list.

• --source — Optional. If supplied, returns only parameters for a specific source. Parameter sources canbe engine-default, system, or user.

Example

O código a seguir lista os parâmetros e seus valores para o grupo de parâmetros custom3-6-param-grp. Para obter mais informações sobre o grupo de parâmetros, omita a linha --query. Para obterinformações sobre todos os grupos de parâmetros, omita a linha --db-cluster-parameter-group-name.


aws docdb describe-db-cluster-parameters \ --db-cluster-parameter-group-name custom3-6-param-grp \ --query 'Parameters[*].[ParameterName,ParameterValue]'

308



Para Windows:

aws docdb describe-db-cluster-parameters ^ --db-cluster-parameter-group-name custom3-6-param-grp ^ --query 'Parameters[*].[ParameterName,ParameterValue]'


[ [ "audit_logs", "disabled" ], [ "tls", "enabled" ], [ "ttl_monitor", "enabled" ]]

Modifying an Amazon DocumentDB Cluster Parameter Group's ParametersÉ possível modificar os parâmetros de um grupo de parâmetros usando o Console de gerenciamento daAWS ou a AWS CLI.


Como atualizar os parâmetros de um grupo de parâmetros de cluster




3. No painel Parameter groups (Grupos de parâmetros), selecione um grupo de parâmetros do cluster doqual deseja atualizar os parâmetros.

4. A página resultante mostra os parâmetros e os detalhes correspondentes para este grupo deparâmetros do cluster. Selecione um parâmetro para atualizar.

5. No canto superior direito da página, selecione Edit (Editar) para alterar o valor do parâmetro. Paraobter mais informações sobre os tipos de parâmetros de cluster, consulte Amazon DocumentDBCluster Parameters Reference (p. 305).

6. Faça a alteração e escolha Modify cluster parameter (Modificar parâmetro de cluster) para salvar asalterações. Para descartar as alterações, escolha Cancel (Cancelar).

Using the AWS CLI

Para modificar os parâmetros de um grupo de parâmetros de cluster, use a operação modify-db-cluster-parameter-group com os parâmetros a seguir:

• --db-cluster-parameter-group-name — Required. The name of the cluster parameter group thatyou are modifying.

309



• --parameters — Required. The parameter or parameters that you are modifying. Each parameterentry must include the following:• ParameterName — The name of the parameter that you are modifying.• ParameterValue — The new value for this parameter.• ApplyMethod — How you want changes to this parameter applied. Permitted values are immediate

and pending-reboot.

Note

Parameters with the ApplyType of static must have an ApplyMethod of pending-reboot.

Como alterar os valores dos parâmetros de um grupo de parâmetros de cluster (AWS CLI)

O exemplo a seguir altera o parâmetro tls.

1. List the parameters and their values of sample-parameter-group



Para Windows:



{ "Parameters": [ { "Source": "system", "ApplyType": "static", "AllowedValues": "disabled,enabled", "ParameterValue": "enabled", "ApplyMethod": "pending-reboot", "DataType": "string", "ParameterName": "tls", "IsModifiable": true, "Description": "Config to enable/disable TLS" }, { "Source": "user", "ApplyType": "dynamic", "AllowedValues": "disabled,enabled", "ParameterValue": "enabled", "ApplyMethod": "pending-reboot", "DataType": "string", "ParameterName": "ttl_monitor", "IsModifiable": true, "Description": "Enables TTL Monitoring" } ]}

2. Modify the tls parameter so that its value is disabled. Não pode modificar o ApplyMethod porqueo ApplyType é static.

310



aws docdb modify-db-cluster-parameter-group \ --db-cluster-parameter-group-name sample-parameter-group \ --parameters "ParameterName"=tls,ParameterValue=disabled,ApplyMethod=pending-reboot"

Para Windows:

aws docdb modify-db-cluster-parameter-group ^ --db-cluster-parameter-group-name sample-parameter-group ^ --parameters "ParameterName=tls,ParameterValue=disabled,ApplyMethod=pending-reboot"


{ "DBClusterParameterGroupName": "sample-parameter-group"}

3. Wait at least 5 minutes.4. List the parameter values of sample-parameter-group.



Para Windows:



{ "Parameters": [ { "ParameterName": "audit_logs", "ParameterValue": "disabled", "Description": "Enables auditing on cluster.", "Source": "system", "ApplyType": "dynamic", "DataType": "string", "AllowedValues": "enabled,disabled", "IsModifiable": true, "ApplyMethod": "pending-reboot" }, { "ParameterName": "tls", "ParameterValue": "disabled", "Description": "Config to enable/disable TLS", "Source": "user", "ApplyType": "static", "DataType": "string", "AllowedValues": "disabled,enabled", "IsModifiable": true, "ApplyMethod": "pending-reboot" }

311

Amazon DocumentDB Guia do desenvolvedorNoções básicas sobre endpoints

]}

Noções básicas sobre endpoints do AmazonDocumentDB

Você pode usar os endpoints do Amazon DocumentDB (compatível com MongoDB) para se conectar a umcluster ou uma instância. O Amazon DocumentDB tem três tipos diferentes de endpoints, cada um comsua própria finalidade.

Tópicos• Localizar os endpoints de um cluster (p. 312)• Localizar o endpoint de uma instância (p. 314)• Conexão a endpoints (p. 316)

Endpoint do cluster

Um endpoint de cluster é um endpoint para um cluster do Amazon DocumentDB que se conecta àinstância principal atual do cluster. Cada cluster do Amazon DocumentDB tem um único endpoint decluster e uma instância principal. No caso de um failover, o endpoint do cluster é remapeado para anova instância principal.

Endpoint de leitor

Um endpoint de leitor é o endpoint de um cluster do Amazon DocumentDB que se conecta a uma dasréplicas disponíveis para esse cluster. Cada cluster do Amazon DocumentDB tem um endpoint deleitor. Se houver mais de uma réplica, o endpoint de leitor direcionará cada solicitação de conexãopara uma das réplicas do Amazon DocumentDB.

Endpoint de instância

Um endpoint de instância é um endpoint que se conecta a uma instância específica. Cada instânciaem um cluster, independentemente de ser uma instância principal ou de réplica, tem seu próprioendpoint de instância exclusivo. É melhor não usar endpoints de instância no seu aplicativo. Issoocorre porque eles podem alterar funções no caso de um failover, exigindo alterações de código emseu aplicativo.

Localizar os endpoints de um clusterVocê pode localizar o endpoint do cluster e o endpoint do leitor usando o console ou a AWS CLI doAmazon DocumentDB.

Como usar o consolePara localizar os endpoints de um cluster usando o console


2. No painel de navegação, escolha clusters.3. Na lista de clusters, escolha o nome do cluster desejado.4. Role para baixo até a seção Details (Detalhes) e localize o endpoint do cluster e o endpoint do leitor.

312


Amazon DocumentDB Guia do desenvolvedorLocalizar os endpoints de um cluster

5. Para se conectar a esse cluster, role até a seção Connect (Conectar). Localize a string de conexãopara o shell mongo e uma string de conexão que pode ser usada no código do aplicativo para seconectar ao cluster.

Usar a AWS CLIPara localizar os endpoints do cluster e do leitor para seu cluster usando a AWS CLI, execute o seguintecomando describe-db-clusters com esses parâmetros.

Parâmetros

• --db-cluster-identifier—Opcional. Especifica o cluster para o qual retornar os endpoints. Seomitido, retorna endpoints para até 100 dos seus clusters.

• --query—Opcional. Especifica os campos a serem exibidos. Isso é útil ao reduzir a quantidade dedados que você precisa visualizar para localizar os endpoints. Se omitido, todas as informações sobreum cluster serão retornadas.

• --region— opcional. Use o parâmetro --region para especificar a região à qual deseja aplicar ocomando. Se omitido, sua região padrão será usada.

Example

O exemplo a seguir retorna o DBClusterIdentifier, o endpoint (endpoint de cluster) e oReaderEndpoint para o sample-cluster.


aws docdb describe-db-clusters \

313

Amazon DocumentDB Guia do desenvolvedorLocalizar o endpoint de uma instância

--region us-east-1 \ --db-cluster-identifier sample-cluster \ --query 'DBClusters[*].[DBClusterIdentifier,Port,Endpoint,ReaderEndpoint]'

Para Windows:

aws docdb describe-db-clusters ^ --region us-east-1 ^ --db-cluster-identifier sample-cluster ^ --query 'DBClusters[*].[DBClusterIdentifier,Port,Endpoint,ReaderEndpoint]'


[ [ "sample-cluster", 27017, "sample-cluster.cluster-corlsfccjozr.us-east-1.docdb.amazonaws.com", "sample-cluster.cluster-ro-corlsfccjozr.us-east-1.docdb.amazonaws.com" ]]

Agora que você tem o endpoint de cluster, é possível se conectar ao cluster usando o mongo ou omongodb. Para obter mais informações, consulte Conexão a endpoints (p. 316).

Localizar o endpoint de uma instânciaVocê pode localizar o endpoint de uma instância usando o console do Amazon DocumentDB ou a AWSCLI.

Como usar o consolePara localizar o endpoint de uma instância usando o console


2. No painel de navegação, escolha instances (instâncias).3. Na lista de instâncias, escolha o nome da instância desejada.4. Role para baixo até a seção Details (Detalhes), em seguida, localize o endpoint da instância.

314


Amazon DocumentDB Guia do desenvolvedorLocalizar o endpoint de uma instância

5. Para se conectar a essa instância, role até a seção Connect (Conectar). Localize a string de conexãopara o shell mongo e uma string de conexão que pode ser usada no código do aplicativo para seconectar à instância.

Usar a AWS CLIPara localizar o endpoint da instância usando a AWS CLI, execute o seguinte comando com essesargumentos.

Argumentos

• --db-instance-identifier—Opcional. Especifica a instância para a qual retornar o endpoint. Seomitido, retorna o endpoint para até 100 das suas instâncias.

• --query—Opcional. Especifica os campos a serem exibidos. Isso é útil ao reduzir a quantidade dedados que você precisa visualizar para localizar os endpoints. Se omitido, todas as informações emuma instância serão retornadas. O campo Endpoint tem três membros, portanto, listá-lo na consulta,como no exemplo a seguir, retorna todos os três membros. Se você quiser apenas alguns dos membrosEndpoint, substitua Endpoint na consulta pelos membros desejados, como no segundo exemplo.

• --region— opcional. Use o parâmetro --region para especificar a região à qual deseja aplicar ocomando. Se omitido, sua região padrão será usada.

Example


aws docdb describe-db-instances \ --region us-east-1 \ --db-instance-identifier sample-cluster-instance \ --query 'DBInstances[*].[DBInstanceIdentifier,Endpoint]'

Para Windows:

aws docdb describe-db-instances ^ --region us-east-1 ^ --db-instance-identifier sample-cluster-instance ^ --query 'DBInstances[*].[DBInstanceIdentifier,Endpoint]'


[ [ "sample-cluster-instance", { "Port": 27017, "Address": "sample-cluster-instance.corcjozrlsfc.us-east-1.docdb.amazonaws.com", "HostedZoneId": "Z2R2ITUGPM61AM" } ]]

315

Amazon DocumentDB Guia do desenvolvedorConexão a endpoints

Reduzindo a saída para eliminar o HostedZoneIddo endpoint, você pode modificar sua consultaespecificando Endpoint.Port e Endpoint.Address.


aws docdb describe-db-instances \ --region us-east-1 \ --db-instance-identifier sample-cluster-instance \ --query 'DBInstances[*].[DBInstanceIdentifier,Endpoint.Port,Endpoint.Address]'

Para Windows:

aws docdb describe-db-instances ^ --region us-east-1 ^ --db-instance-identifier sample-cluster-instance ^ --query 'DBInstances[*].[DBInstanceIdentifier,Endpoint.Port,Endpoint.Address]'


[ [ "sample-cluster-instance", 27017, "sample-cluster-instance.corcjozrlsfc.us-east-1.docdb.amazonaws.com" ]]

Agora que você tem o endpoint de instância, é possível se conectar à instância usando o mongo ou omongodb. Para obter mais informações, consulte Conexão a endpoints (p. 316).

Conexão a endpointsQuando você tiver o endpoint, seja de cluster ou instância, você pode se conectar a ele usando o shellmongo ou uma string de conexão.

Conexão usando o shell do MongoUse a seguinte estrutura para construir a string que você precisa para se conectar ao cluster ou à instânciausando o shell mongo:

mongo \ --ssl \ --host Endpoint:Port \ --sslCAFile rds-combined-ca-bundle.pem \ --username UserName \ --password Password

Exemplos de shell mongo

Conecte-se a um cluster:

mongo \ --ssl \ --host sample-cluster.corcjozrlsfc.us-east-1.docdb.amazonaws.com:27017 \ --sslCAFile rds-combined-ca-bundle.pem \ --username UserName \ --password Password

316

Amazon DocumentDB Guia do desenvolvedorNoções básicas de ARNs do Amazon DocumentDB

Conecte-se a uma instância:

mongo \ --ssl \ --host sample-cluster-instance.corcjozrlsfc.us-east-1.docdb.amazonaws.com:27017 \ --sslCAFile rds-combined-ca-bundle.pem \ --username UserName \ --password Password

Conexão usando uma string de conexãoUse a seguinte estrutura para construir a string de conexão que você precisa para se conectar ao clusterou à instância.

mongodb://UserName:Password@endpoint:port?replicaSet=rs0&ssl_ca_certs=rds-combined-ca-bundle.pem

Exemplos de string de conexão

Conecte-se a um cluster:

mongodb://UserName:Password@sample-cluster.cluster-corlsfccjozr.us-east-1.docdb.amazonaws.com:27017?replicaSet=rs0&ssl_ca_certs=rds-combined-ca-bundle.pem

Conecte-se a uma instância:

mongodb://UserName:Password@sample-cluster-instance.cluster-corlsfccjozr.us-east-1.docdb.amazonaws.com:27017?replicaSet=rs0&ssl_ca_certs=rds-combined-ca-bundle.pem

Noções básicas de Nomes de recurso da Amazon(ARNs) do Amazon DocumentDB

Os recursos que você cria na AWS são identificados de forma exclusiva com um nome de recurso daAmazon (ARN). Para determinadas operações do Amazon DocumentDB (compatível com MongoDB), vocêprecisará identificar exclusivamente um recurso do Amazon DocumentDB especificando seu ARN. Porexemplo, quando você adiciona uma tag a um recurso, deve fornecer o ARN do recurso.

Tópicos• Criação de um ARN para um recurso do Amazon DocumentDB (p. 317)• Localizar um ARN de recurso do Amazon DocumentDB (p. 319)

Criação de um ARN para um recurso do AmazonDocumentDBVocê pode criar um ARN para um recurso do Amazon DocumentDB usando a sintaxe a seguir. O AmazonDocumentDB compartilha o formato de ARNs do Amazon Relational Database Service (Amazon RDS). OsARNs do Amazon DocumentDB contêm rds, e não docdb.

arn:aws:rds:region:account_number:resource_type:resource_id

317

Amazon DocumentDB Guia do desenvolvedorCriação de um ARN




us-east-1 6.


us-west-2 4.




ap-southeast-1 3.









Note

A arquitetura do Amazon DocumentDB separa armazenamento e computação. Para a camadade armazenamento, o Amazon DocumentDB replica seis cópias de seus dados em três zonasde disponibilidade (AZs) da AWS. As zonas de disponibilidade listadas na tabela acima são onúmero de AZs que você pode usar em uma determinada região para provisionar instâncias decomputação. Por exemplo, se você estiver executando um cluster Amazon DocumentDB em ap-northeast-1, seu armazenamento será replicado de seis maneiras em três AZs, mas as instânciasde computação só estarão disponíveis em duas AZs.

A tabela a seguir mostra o formato que deve ser usado para criar um ARN para um recurso específico doAmazon DocumentDB. O Amazon DocumentDB compartilha o formato de ARNS do Amazon RDS. OsARNs do Amazon DocumentDB contêm rds, e não docdb.

Tipo de recurso Formato/exemplo de ARN

Instância (db) arn:aws:rds:region:account_number:db:resource_id

arn:aws:rds:us-east-1:1234567890:db:sample-db-instance

Cluster (cluster) arn:aws:rds:region:account_number:cluster:resource_id

arn:aws:rds:us-east-1:1234567890:cluster:sample-db-cluster

318

Amazon DocumentDB Guia do desenvolvedorLocalizar um ARN

Tipo de recurso Formato/exemplo de ARN

Grupo de parâmetros do cluster(cluster-pg)

arn:aws:rds:region:account_number:cluster-pg:resource_id

arn:aws:rds:us-east-1:1234567890:cluster-pg:sample-db-cluster-parameter-group

Grupo de segurança (secgrp) arn:aws:rds:region:account_number:secgrp:resource_id

arn:aws:rds:us-east-1:1234567890:secgrp:sample-public-secgrp

Snapshot de cluster (cluster-snapshot)

arn:aws:rds:region:account_number:cluster-snapshot:resource_id

arn:aws:rds:us-east-1:1234567890:cluster-snapshot:sample-db-cluster-snapshot

Grupo de sub-rede (subgrp) arn:aws:rds:region:account_number:subgrp:resource_id

arn:aws:rds:us-east-1:1234567890:subgrp:sample-subnet-10

Localizar um ARN de recurso do AmazonDocumentDBVocê pode localizar o ARN de um recurso do Amazon DocumentDB usando o Console de gerenciamentoda AWS ou a AWS CLI.

Como usar o Console de gerenciamento da AWSPara localizar um ARN usando o console, navegue até o recurso para o qual deseja um ARN e veja osdetalhes desse recurso.

Por exemplo, você pode obter o ARN de um cluster no painel Details (Detalhes) do cluster, como mostradona captura de tela a seguir.

Como usar a AWS CLIPara obter um ARN usando a AWS CLI para um recurso específico do Amazon DocumentDB, usea operação describe para esse recurso. A tabela a seguir mostra cada operação da AWS CLI e apropriedade do ARN usada com a operação para obter um ARN.

319

Amazon DocumentDB Guia do desenvolvedorLocalizar um ARN

Comando AWS CLI Propriedade do ARN

describe-db-instances DBInstanceArn

describe-db-clusters DBClusterArn

describe-db-parameter-groups DBParameterGroupArn

describe-db-cluster-parameter-groups DBClusterParameterGroupArn

describe-db-security-groups DBSecurityGroupArn

describe-db-snapshots DBSnapshotArn

describe-db-cluster-snapshots DBClusterSnapshotArn

describe-db-subnet-groups DBSubnetGroupArn

Example - Localização do ARN de um cluster

A operação da AWS CLI a seguir localiza o ARN para o cluster sample-cluster.


aws docdb describe-db-clusters \ --db-cluster-identifier sample-cluster \ --query 'DBClusters[*].DBClusterArn'

Para Windows:

aws docdb describe-db-clusters ^ --db-cluster-identifier sample-cluster \ --query 'DBClusters[*].DBClusterArn'


[ "arn:aws:rds:us-east-1:123456789012:cluster:sample-cluster"]

Example - Localização de ARNs para vários grupos de parâmetros


aws docdb describe-db-cluster-parameter-groups \ --query 'DBClusterParameterGroups[*].DBClusterParameterGroupArn'

Para Windows:

aws docdb describe-db-cluster-parameter-groups ^ --query 'DBClusterParameterGroups[*].DBClusterParameterGroupArn'


[

320

Amazon DocumentDB Guia do desenvolvedorMarcação de recursos

"arn:aws:rds:us-east-1:123456789012:cluster-pg:custom3-6-param-grp", "arn:aws:rds:us-east-1:123456789012:cluster-pg:default.aurora5.6", "arn:aws:rds:us-east-1:123456789012:cluster-pg:default.docdb3.6"]

Marcar recursos do Amazon DocumentDBVocê pode usar tags do Amazon DocumentDB (compatível com MongoDB) para adicionar metadadosaos recursos do Amazon DocumentDB. Essas tags podem ser usadas com políticas do AWS Identity andAccess Management (IAM) para gerenciar o acesso aos recursos do Amazon DocumentDB e controlar asações que podem ser aplicadas a esses recursos. Você também pode usar as tags para monitorar custosagrupando despesas de recursos marcados com tags semelhantes.

Você pode marcar os recursos do Amazon DocumentDB a seguir:

• Clusters• Instâncias• Snapshots• Snapshots do cluster• Grupos de parâmetros• Parameter groups de cluster• Grupos de segurança• Grupos de sub-rede

Visão geral de tags de recurso do AmazonDocumentDBUma tag do Amazon DocumentDB é um par de nome/valor que você define e associa a um recursodo Amazon DocumentDB. O nome é referido como chave. Fornecer um valor para a chave é opcional.É possível usar tags para atribuir informações arbitrárias a um domínio do Amazon DocumentDB. Épossível usar uma chave de tag, por exemplo, para definir uma categoria, e o valor da tag pode ser umitem nessa categoria. Por exemplo, você pode definir uma chave de tag como project e um valor detag como Salix, indicando que o recurso do Amazon DocumentDB é atribuído ao projeto Salix. As tagstambém podem ser usadas para designar recursos do Amazon DocumentDB como sendo usados paratestes ou produção, usando uma chave como environment=test ou environment=production.Recomendamos que você use um conjunto consistente de chaves de tags para facilitar o monitoramentode metadados associados aos recursos do Amazon DocumentDB.

Você pode usar tags para organizar sua conta AWS e refletir sua própria estrutura de custos. Para isso,inscreva-se para obter sua conta da AWS com os valores de chave de tags incluídos. Então, para ver ocusto de recursos combinados, organize suas informações de faturamento de acordo com recursos comos mesmos valores de chave de tags. Por exemplo, você pode etiquetar vários recursos com um nome deaplicação específico, e depois organizar suas informações de faturamento para ver o custo total daquelaaplicação em vários serviços. Para obter mais informações, consulte Como usar tags de alocação decustos no Guia do usuário do Gerenciamento de custos e faturamento da AWS.

Cada recurso do Amazon DocumentDB tem um conjunto que contém todas as tags atribuídas a ele.Um conjunto de tags pode conter até 10 tags ou estar vazio. Se você adicionar uma tag a um recursodo Amazon DocumentDB que tenha a mesma chave que uma tag existente no recurso, o novo valorsubstituirá o antigo.

321

https://docs.aws.amazon.com/awsaccountbilling/latest/aboutv2/cost-alloc-tags.html

https://docs.aws.amazon.com/awsaccountbilling/latest/aboutv2/cost-alloc-tags.html

Amazon DocumentDB Guia do desenvolvedorRestrições de tag

O AWS não aplica nenhum significado semântico a suas tags; as tags são interpretadas estritamente comostrings de caracteres. O Amazon DocumentDB pode definir tags em uma instância ou outros recursos doAmazon DocumentDB, de acordo com as configurações que você usa ao criar o recurso. Por exemplo, oAmazon DocumentDB pode adicionar uma tag indicando que uma instância é para produção ou teste.

Você pode adicionar uma tag a um snapshot, mas sua conta não refletirá esse agrupamento.

Você pode usar o Console de gerenciamento da AWS ou a AWS CLI para adicionar, listar e excluir tagsdos recursos do Amazon DocumentDB. Ao usar a AWS CLI, você deve fornecer o nome de recurso daAmazon (ARN) para o recurso com o qual deseja trabalhar. Para obter mais informações sobre ARNs doAmazon DocumentDB, consulte Noções básicas de Nomes de recurso da Amazon (ARNs) do AmazonDocumentDB (p. 317).

Restrições de tagAs restrições a seguir se aplicam às tags do Amazon DocumentDB:

• Número máximo de tags por recurso - 10• Comprimento máximo da chave - 128 caracteres Unicode• Comprimento máximo de valor - 256 caracteres Unicode• Caracteres válidos para Chave e Valor - letras maiúsculas e minúsculas no conjunto de caracteres

UTF-8, dígitos, espaço e os seguintes caracteres: _ . : / = + - e @ (Java regex: "^([\\p{L}\\p{Z}\\p{N}_.:/=+\\-]*)$")

• As chaves e os valores de tags diferenciam maiúsculas de minúsculas.• O prefixo aws: não pode ser usado para chaves ou valores de tag; ele é reservado para a AWS.

Adição e atualização de tags em um recurso doAmazon DocumentDBÉ possível adicionar até 10 tags a um recurso usando o Console de gerenciamento da AWS ou a AWSCLI.

Como usar o Console de gerenciamento da AWSO processo de adicionar uma tag a um recurso é semelhante, independentemente do recurso ao qual vocêestá adicionando a tag. Neste exemplo, você adiciona uma tag a um cluster.

Para adicionar ou atualizar tags a um cluster usando o console


2. No painel de navegação, escolha clusters.3. Escolha o nome do cluster ao qual você deseja adicionar tags.4. Role para baixo até a seção Tags e depois escolha Edit (Editar).5. Para cada tag que você deseja adicionar a este recurso, faça o seguinte:

a. Para adicionar uma nova tag, insira o nome da tag na caixa Key (Chave). Para alterar o valor deuma tag, localize o nome da tag na coluna Key (Chave).

b. Para atribuir um valor novo ou atualizado à tag, insira um valor para a tag na caixa Value (Valor).c. Se você tiver mais tags para adicionar, escolha Add (Adicionar). Caso contrário, quando terminar,

escolha Save (Salvar).

322


Amazon DocumentDB Guia do desenvolvedorListar tags

Como usar a AWS CLIO processo de adicionar uma tag a um recurso é semelhante, independentemente do recurso ao qual vocêestá adicionando as tags. Neste exemplo, você adiciona três tags a um cluster. A segunda tag, key2, nãotem valor.

Use a operação add-tags-to-resource da AWS CLI com esses parâmetros.

Parâmetros

• --resource-name — o ARN do recurso do Amazon DocumentDB ao qual você deseja adicionar astags.

• --tags — uma lista das tags (par de chave/valor) que você deseja adicionar a esse recurso no formatoKey=key-name,Value=tag-value.

Example


aws docdb add-tags-to-resource \ --resource-name arn:aws:rds:us-east-1:1234567890:cluster:sample-cluster \ --tags Key=key1,Value=value1 Key=key2 Key=key3,Value=value3

Para Windows:

aws docdb add-tags-to-resource ^ --resource-name arn:aws:rds:us-east-1:1234567890:cluster:sample-cluster \ --tags Key=key1,Value=value1 Key=key2 Key=key3,Value=value3

A operação add-tags-to-resource não produzirá uma saída. Para ver os resultados da operação, usea operação list-tags-for-resource.

Listar tags em um recurso do Amazon DocumentDBVocê pode usar o Console de gerenciamento da AWS ou a AWS CLI para obter uma lista das tags paraum recurso do Amazon DocumentDB.

Como usar o Console de gerenciamento da AWSO processo de listar tags em um recurso é semelhante, independentemente do recurso ao qual você estáadicionando a tag. Neste exemplo, você lista as tags para um cluster.

Para listar as tags em um cluster usando o console

1. Abra o console do Amazon DocumentDB em https://console.aws.amazon.com/docdb.2. No painel de navegação, escolha clusters.3. Escolha o nome do cluster para o qual você deseja listar tags.4. Para ver uma lista das tags nesse recurso, role para baixo até a seção Tags.

Como usar a AWS CLIO processo de listar as tags em um recurso é semelhante, independentemente do recurso para o qualvocê está listando a tag. Neste exemplo, você lista as tags em um cluster.

323


Amazon DocumentDB Guia do desenvolvedorRemover tags

Use a operação list-tags-for-resource da AWS CLI com esses parâmetros.

Parâmetros

• --resource-name — obrigatório. O ARN do recurso do Amazon DocumentDB para o qual você desejalistar as tags.

Example


aws docdb list-tags-for-resource \ --resource-name arn:aws:rds:us-east-1:1234567890:cluster:sample-cluster

Para Windows:

aws docdb list-tags-for-resource ^ --resource-name arn:aws:rds:us-east-1:1234567890:cluster:sample-cluster


{ "TagList": [ { "Key": "key1", "Value": "value1" }, { "Key": "key2", "Value": "" }, { "Key": "key3", "Value": "value3" } ]}

Remoção de tags de um recurso do AmazonDocumentDBVocê pode usar o Console de gerenciamento da AWS ou a AWS CLI para remover tags de recursos doAmazon DocumentDB.

Como usar o Console de gerenciamento da AWSO processo de remover tags de um recurso é semelhante, independentemente do recurso do qual vocêestá removendo a tag. Neste exemplo, você remove as tags de um cluster.

Para remover tags de um cluster usando o console

1. Abra o console do Amazon DocumentDB em https://console.aws.amazon.com/docdb.2. No painel de navegação, escolha clusters.3. Escolha o nome do cluster do qual você deseja remover as tags.4. Role para baixo até a seção Tags e depois escolha Edit (Editar).

324


Amazon DocumentDB Guia do desenvolvedorManutenção do Amazon DocumentDB

5. Se você deseja remover todas as tags desse recurso, escolha Remove all (Remover todas). Casocontrário, para cada tag que você deseja remover deste recurso, faça o seguinte:

a. Localize o nome da tag na coluna Key (Chave).b. Escolha Remove (Remover) na mesma linha que a chave de tag.c. Quando terminar, escolha Save (Salvar).

Como usar a AWS CLIO processo de remover uma tag de um recurso é semelhante, independentemente do recurso do qualvocê está removendo a tag. Neste exemplo, você remove a tag de um cluster.

Use a operação remove-tags-from-resource da AWS CLI com esses parâmetros.

• --resource-name — obrigatório. O ARN do recurso do Amazon DocumentDB do qual você desejaremover as tags.

• --tag-keys — obrigatório. Uma lista das chaves de tag que você deseja remover deste recurso.

Example


aws docdb remove-tags-from-resource \ --resource-name arn:aws:rds:us-east-1:1234567890:cluster:sample-cluster \ --tag-keys key1 key3

Para Windows:

aws docdb remove-tags-from-resource ^ --resource-name arn:aws:rds:us-east-1:1234567890:cluster:sample-cluster \ --tag-keys key1 key3

A operação removed-tags-from-resource não produzirá uma saída. Para ver os resultados daoperação, use a operação list-tags-for-resource.

Manutenção do Amazon DocumentDBPeriodicamente, o Amazon DocumentDB realiza a manutenção em seus recursos. Geralmente, amanutenção envolve atualizações do mecanismo de banco de dados (manutenção do cluster) ou dosistema operacional (SO) subjacente da instância (manutenção da instância).

Alguns itens de manutenção exigem que o Amazon DocumentDB coloque a instância offline por umcurto período. Entre os itens de manutenção que exigem que uma instância esteja offline estão sistemaoperacional obrigatório ou patches de mecanismo. A aplicação obrigatória de patches é automaticamenteprogramada somente para patches relacionados à segurança e à confiabilidade da instância. Essasaplicações de patches não ocorrem com frequência (geralmente uma vez a cada dois meses) e raramenteexigem mais do que uma fração de sua janela de manutenção. Você deve esperar que, quando amanutenção for realizada em seu cluster ou na instância, se a instância for principal, ocorrerá o failover.Para obter mais informações, consulte Failover do Amazon DocumentDB (p. 278).

A manutenção do cluster e de instâncias tem suas próprias janelas de manutenção. Por padrão, quandovocê cria um cluster, o Amazon DocumentDB atribui uma janela de manutenção para um cluster e cadainstância. Você pode escolher a janela de manutenção ao criar um cluster ou uma instância. Você também

325

Amazon DocumentDB Guia do desenvolvedorDeterminação de ações de manutenção pendentes

pode modificar as janelas de manutenção a qualquer momento para atender às suas programaçõesou práticas comerciais. Em geral, é recomendável escolher janelas de manutenção que minimizem oimpacto da manutenção em seu aplicativo (por exemplo, em noites ou fins de semana). Essa orientação éaltamente contextual sobre o tipo de aplicativo e os padrões de uso que você experimenta.

Tópicos• Determinação de ações de manutenção pendentes do Amazon DocumentDB (p. 326)• Aplicação de atualizações do Amazon DocumentDB (p. 327)• Atualizações iniciadas pelo usuário (p. 329)• Gerenciamento de janelas de manutenção do Amazon DocumentDB (p. 330)

Determinação de ações de manutenção pendentes doAmazon DocumentDBVocê pode ver se uma atualização de manutenção está disponível para o cluster usando o Console degerenciamento da AWS ou a AWS CLI.

Se uma atualização estiver disponível, você poderá executar uma das seguintes ações:

• Adiar as ações de manutenção.• Aplicar as ações de manutenção imediatamente.• Agendar as ações de manutenção para serem iniciadas durante a próxima janela de manutenção.• Não tome nenhuma ação.

Important

Determinadas atualizações de SO são marcadas como Required (Obrigatórias). Se você adiaruma atualização necessária, receberá um aviso do Amazon DocumentDB indicando quando aatualização será realizada na instância ou no cluster. Outras atualizações estão Available. Vocêpode adiar essas atualizações indefinidamente.

A janela de manutenção determina quando as operações pendentes começam, mas não limita o tempototal de execução dessas operações. Não há garantia de que as operações de manutenção terminemantes de a janela de manutenção se encerrar, podendo continuar além do tempo de encerramentoespecificado.

Usar o Console de gerenciamento da AWSSe uma atualização estiver disponível, ela será indicada pela palavra Available (Disponível) ou Required(Obrigatória) na coluna Maintenance (Manutenção) do cluster no console do Amazon DocumentDB,conforme mostrado aqui:

326

Amazon DocumentDB Guia do desenvolvedorAplicação de atualizações

Usar a AWS CLIUse a seguinte operação de AWS CLI para determinar quais ações de manutenção estão pendentes. Asaída aqui mostra que não há ações de manutenção pendentes.

aws docdb describe-pending-maintenance-actions


{ "PendingMaintenanceActions": []}

Aplicação de atualizações do Amazon DocumentDBCom o Amazon DocumentDB, você pode escolher quando aplicar operações de manutenção. Você podedecidir quando o Amazon DocumentDB deve aplicar as atualizações usando o Console de gerenciamentoda AWS ou a AWS CLI.

Use os procedimentos neste tópico para atualizar imediatamente ou programar uma atualização para a suainstância.

Usar o Console de gerenciamento da AWSVocê pode usar o console para gerenciar atualizações para as instâncias e os clusters do AmazonDocumentDB.

Para gerenciar uma atualização de uma instância ou um cluster


2. No painel de navegação, escolha clusters.3. Na lista de clusters, escolha o botão ao lado do nome do cluster ao qual você deseja aplicar a

operação de manutenção.4. No menu Actions (Ações), escolha uma das opções a seguir:

• Upgrade now (Atualizar agora) para executar imediatamente as tarefas de manutenção pendentes.• Upgrade at next window (Atualizar na próxima janela) para executar as tarefas de manutenção

pendentes durante a próxima janela de manutenção do cluster.

Note

Se não houver tarefas de manutenção pendentes, as duas opções anteriores estarãoinativas.

Usar a AWS CLIPara aplicar uma atualização pendente a uma instância ou cluster, use a operação apply-pending-maintenance-action da AWS CLI.

Parâmetros

• --resource-identifier — o nome de recurso da Amazon (ARN) do Amazon DocumentDB dorecurso ao qual a ação de manutenção pendente se aplica.

327


Amazon DocumentDB Guia do desenvolvedorAplicação de atualizações

• --apply-action — a ação de manutenção pendente a ser aplicada a esse recurso.

Valores válidos: system-update e db-upgrade.• --opt-in-type — um valor que especifica o tipo de solicitação de inclusão ou desfaz uma solicitação

de inclusão. Uma solicitação de inclusão do tipo immediate não pode ser desfeita.

Valores válidos:• immediate — Aplique a ação de manutenção imediatamente.• next-maintenance — Aplique a ação de manutenção durante a próxima janela de manutenção do

recurso.• undo-opt-in — Cancele todas as solicitações de inclusão next-maintenance existentes.

Example


aws docdb apply-pending-maintenance-action \ --resource-identifier arn:aws:rds:us-east-1:123456789012:db:docdb \ --apply-action system-update \ --opt-in-type immediate

Para Windows:

aws docdb apply-pending-maintenance-action ^ --resource-identifier arn:aws:rds:us-east-1:123456789012:db:docdb ^ --apply-action system-update ^ --opt-in-type immediate

Para retornar uma lista de recursos que tenham pelo menos uma atualização pendente, use a operaçãodescribe-pending-maintenance-actions da AWS CLI.

Example


aws docdb describe-pending-maintenance-actions \ --resource-identifier arn:aws:rds:us-east-1:001234567890:db:docdb

Para Windows:

aws docdb describe-pending-maintenance-actions ^ --resource-identifier arn:aws:rds:us-east-1:001234567890:db:docdb


{ "PendingMaintenanceActions": [ { "ResourceIdentifier": "arn:aws:rds:us-east-1:001234567890:cluster:sample-cluster", "PendingMaintenanceActionDetails": [ { "Action": "system-update", "CurrentApplyDate": "2019-01-11T03:01:00Z", "Description": "db-version-upgrade",

328

Amazon DocumentDB Guia do desenvolvedorAtualizações iniciadas pelo usuário

"ForcedApplyDate": "2019-01-18T03:01:00Z", "AutoAppliedAfterDate": "2019-01-11T03:01:00Z" } ] } ]}

Você também pode retornar uma lista de recursos para uma instância ou um cluster, especificando oparâmetro --filters da operação describe-pending-maintenance-actions da AWS CLI. Oformato da operação --filters é Name=filter-name,Values=resource-id,....

Os valores a seguir são os valores aceitáveis para o parâmetro Name do filtro:

• db-cluster-id — Aceita uma lista de identificadores de cluster ou ARNs. A lista retornada incluiapenas ações de manutenção pendentes para os clusters identificados por esses identificadores ouARNs.

• db-instance-id — Aceita uma lista de identificadores de instância ou ARNs. A lista retornada incluiapenas ações de manutenção pendentes para as instâncias identificadas por esses identificadores ouARNs.

O exemplo a seguir retorna as ações de manutenção pendentes para os clusters sample-cluster1 esample-cluster2.

Example


aws docdb describe-pending-maintenance-actions \ --filters Name=db-cluster-id,Values=sample-cluster1,sample-cluster2

Para Windows:

aws docdb describe-pending-maintenance-actions ^ --filters Name=db-cluster-id,Values=sample-cluster1,sample-cluster2

Aplicar datasCada ação de manutenção tem uma respectiva data de aplicação que você pode encontrar ao descreveras ações de manutenção pendentes. Quando você ler a saída de ações de manutenção pendentes daAWS CLI, três datas estarão listadas:

• CurrentApplyDate— a data em que a ação de manutenção será aplicada imediatamente ou durantea próxima janela de manutenção. Se a manutenção for opcional, esse valor poderá ser null.

• ForcedApplyDate— a data em que a manutenção será aplicada automaticamente, independente desua janela de manutenção.

• AutoAppliedAfterDate— a data depois da qual a manutenção será aplicada durante a janela demanutenção do cluster.

Atualizações iniciadas pelo usuárioComo usuário do Amazon DocumentDB, você pode iniciar atualizações para seus clusters ou instâncias.Por exemplo, você pode modificar a classe de uma instância para uma com mais ou menos memória oualterar o grupo de parâmetros de um cluster. O Amazon DocumentDB visualiza essas alterações de forma

329

Amazon DocumentDB Guia do desenvolvedorGerenciamento de janelas de manutenção

diferente das atualizações iniciadas pelo Amazon DocumentDB. Para obter mais informações sobre comomodificar um cluster ou uma instância, consulte o seguinte:

• Modificar um cluster do Amazon DocumentDB (p. 231)• Modifying an Amazon DocumentDB Instance (p. 259)

Para ver uma lista de modificações pendentes iniciadas pelo usuário, execute o comando a seguir.

Example

Para ver as alterações pendentes iniciados pelo usuário para suas instâncias


aws docdb describe-db-instances \ --query 'DBInstances[*].[DBClusterIdentifier,DBInstanceIdentifier,PendingModifiedValues]'

Para Windows:

aws docdb describe-db-instances ^ --query 'DBInstances[*].[DBClusterIdentifier,DBInstanceIdentifier,PendingModifiedValues]'


Nesse caso, sample-cluster-instance tem uma alteração pendente em uma classe de instânciadb.r5.xlarge e sample-cluster-instance-2 não tem alterações pendentes.

[ [ "sample-cluster", "sample-cluster-instance", { "DBInstanceClass": "db.r5.xlarge" } ], [ "sample-cluster", "sample-cluster-instance-2", {} ]]

Gerenciamento de janelas de manutenção do AmazonDocumentDBCada instância e cluster têm uma janela de manutenção semanal durante a qual todas as alteraçõespendentes são aplicadas. A janela de manutenção é uma oportunidade para controlar quando ocorrerãoas modificações e aplicações de patches de software, caso elas sejam solicitadas ou exigidas. Se umevento de manutenção estiver programado para uma determinada semana, ele é iniciado durante a janelade manutenção de 30 minutos que você identificar. A maioria dos eventos de manutenção também éconcluída durante a janela de manutenção de 30 minutos, embora os eventos de manutenção mais longospossam levar mais de 30 minutos para serem concluídos.

A janela de manutenção de 30 minutos é selecionada aleatoriamente de um bloco de tempo de 8 horaspor região. Se você não especificar uma janela de manutenção preferencial ao criar ou modificar uma

330

Amazon DocumentDB Guia do desenvolvedorNoções básicas das funções vinculadas ao serviço

instância ou cluster, o Amazon DocumentDB atribuirá uma janela de manutenção de 30 minutos em um diada semana selecionado aleatoriamente.

Região Bloco de tempo UTC

Leste dos EUA (Ohio) 03:00-11:00

Leste dos EUA (Norte da Virgínia) 03:00-11:00

Oeste dos EUA (Oregon) 06:00-14:00

Ásia Pacífico (Mumbai) 17:30-01:30

Ásia-Pacífico (Seul) 13:00-21:00

Ásia-Pacífico (Cingapura) 14:00-22:00

Ásia-Pacífico (Sydney) 12:00–20:00

Ásia-Pacífico (Tóquio) 13:00-21:00

Canadá (Central) 22:00-06:00

Europa (Frankfurt) 23:00-07:00

Europa (Irlanda) 22:00-06:00

Europa (Paris) 22:00-06:00

AWS GovCloud (US) 22:00-06:00

Alteração de uma janela de manutençãoA janela de manutenção deve ser definida no horário de menor utilização e, portanto, talvez precise seralterada de vez em quando. Seu cluster ou a instância estará indisponível durante esse tempo somente seas alterações do sistema (como uma operação de armazenamento em escala ou uma alteração da classede instância) estiverem sendo aplicadas e exigirem uma interrupção. E, depois, estará indisponível apenaspelo intervalo mínimo de tempo necessário para fazer as alterações necessárias.

Para atualizações no mecanismo de banco de dados, o Amazon DocumentDB usa a janela demanutenção preferencial do cluster e não a janela de manutenção para instâncias individuais.

Para alterar a janela de manutenção

• Para um cluster: consulte Modificar um cluster do Amazon DocumentDB (p. 231).• Para uma instância: consulte Modifying an Amazon DocumentDB Instance (p. 259).

Noções básicas das funções vinculadas ao serviçoO Amazon DocumentDB (compatível com MongoDB) usa as funções vinculadas ao serviço do AWSIdentity and Access Management (IAM). A função vinculada ao serviço é um tipo exclusivo de função doIAM vinculada diretamente ao Amazon DocumentDB. As funções vinculadas a serviços são predefinidaspelo Amazon DocumentDB e incluem todas as permissões que o serviço requer para chamar outrosserviços da AWS em seu nome.

Uma função vinculada ao serviço facilita o uso de Amazon DocumentDB porque você não precisaadicionar as permissões necessárias manualmente. Amazon DocumentDB define as permissões de suas

331

https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_terms-and-concepts.html#iam-term-service-linked-role

Amazon DocumentDB Guia do desenvolvedorPermissões de função vinculada ao serviço

funções vinculadas ao serviço e, a menos que definido em contrário, somente Amazon DocumentDB podeassumir suas funções. As permissões definidas incluem a política de confiança e a política de permissões,e essa política não pode ser anexada a nenhuma outra entidade do IAM.

Você pode excluir as funções somente depois de primeiro excluir seus recursos relacionados. Isso protegeseus recursos do Amazon DocumentDB, pois você não pode remover por engano as permissões paraacessar os recursos.

Para obter informações sobre outros serviços que oferecem suporte às funções vinculadas a serviço,consulte Serviços da AWS compatíveis com o IAM e procure os serviços que apresentam Sim na colunaFunção vinculada a serviços. Escolha um Sim com um link para exibir a documentação da funçãovinculada a serviço desse serviço.

Permissões de função vinculada ao serviço doAmazon DocumentDBO Amazon DocumentDB (compatível com MongoDB) usa a função vinculada ao serviço chamadaAWSServiceRoleForRDS para permitir que o Amazon DocumentDB chame serviços da AWS em nome deseus clusters.

A função vinculada ao serviço AWSServiceRoleForRDS confia nos seguintes serviços para assumir afunção:

• docdb.amazonaws.com

A política de permissões da função permite que o Amazon DocumentDB conclua as seguintes ações nosrecursos especificados:

• Ações em ec2:• AssignPrivateIpAddresses

• AuthorizeSecurityGroupIngress

• CreateNetworkInterface

• CreateSecurityGroup

• DeleteNetworkInterface

• DeleteSecurityGroup

• DescribeAvailabilityZones

• DescribeInternetGateways

• DescribeSecurityGroups

• DescribeSubnets

• DescribeVpcAttribute

• DescribeVpcs

• ModifyNetworkInterfaceAttribute

• RevokeSecurityGroupIngress

• UnassignPrivateIpAddresses

• Ações em sns:• ListTopic

• Publish

• Ações em cloudwatch:• PutMetricData

• GetMetricData

• CreateLogStream

332

https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_aws-services-that-work-with-iam.html

Amazon DocumentDB Guia do desenvolvedorCriar uma função vinculada ao serviço

• PullLogEvents

• DescribeLogStreams

• CreateLogGroup

Note

Você deve configurar permissões para que uma entidade do IAM (por exemplo, um usuário, grupoou função) crie, edite ou exclua uma função vinculada ao serviço. Você pode encontrar a seguintemensagem de erro:Impossível criar o recurso. Você se você tem permissão para criar a função vinculada ao serviço.Caso contrário, aguarde e tente novamente mais tarde.Se você vir esse erro, verifique se você tem as seguintes permissões:

{ "Action": "iam:CreateServiceLinkedRole", "Effect": "Allow", "Resource": "arn:aws:iam::*:role/aws-service-role/rds.amazonaws.com/AWSServiceRoleForRDS", "Condition": { "StringLike": { "iam:AWSServiceName":"rds.amazonaws.com" } }}

Para obter mais informações, consulte Permissões da função vinculada ao serviço no Guia do usuário doIAM.

Criar uma função vinculada ao serviço do AmazonDocumentDBVocê não precisa criar manualmente uma função vinculada a serviço. Quando você cria um cluster, oAmazon DocumentDB cria uma função vinculada ao serviço para você.

Se você excluir essa função vinculada ao serviço e precisar criá-la novamente, poderá usar esse mesmoprocesso para recriar a função em sua conta. Quando você cria um cluster, o Amazon DocumentDB criauma função vinculada ao serviço para você novamente.

Modificar uma função vinculada ao serviço do AmazonDocumentDBO Amazon DocumentDB não permite a modificação da função vinculada ao serviçoAWSServiceRoleForRDS. Depois que criar uma função vinculada ao serviço, você não poderá alterar onome da função, pois várias entidades podem fazer referência a ela. No entanto, você poderá modificara descrição da função usando o IAM. Para obter mais informações, consulte Edição de uma funçãovinculada a serviço no Guia do usuário do IAM.

Excluir uma função vinculada ao serviço do AmazonDocumentDBSe você não precisar mais usar um recurso ou serviço que requer uma função vinculada a serviço, érecomendável excluí-la. Dessa forma, você não tem uma entidade não utilizada que não seja monitorada

333

https://docs.aws.amazon.com/IAM/latest/UserGuide/using-service-linked-roles.html#service-linked-role-permissions

https://docs.aws.amazon.com/IAM/latest/UserGuide/using-service-linked-roles.html#edit-service-linked-role

https://docs.aws.amazon.com/IAM/latest/UserGuide/using-service-linked-roles.html#edit-service-linked-role

Amazon DocumentDB Guia do desenvolvedorRegiões com suporte para funções

vinculadas ao serviço Amazon DocumentDB

ativamente ou mantida. Contudo, você deve excluir todos os seus clusters para poder excluir a funçãovinculada ao serviço.

Limpeza de uma função vinculada a serviço do AmazonDocumentDBAntes de você poder usar o IAM para excluir uma função vinculada ao serviço, você deve primeiroconfirmar que a função não tem sessões ativas e remover quaisquer recursos usados pela função.

Para verificar se a função vinculada ao serviço tem uma sessão ativa usando o console

1. Faça login no Console de gerenciamento da AWS e abra o console do IAM em https://console.aws.amazon.com/iam/.

2. No painel de navegação do console do IAM, escolha Roles (Funções) e, em seguida, escolha o nome(não a caixa de verificação) da função AWSServiceRoleForRDS.

3. Na página Resumo para a função selecionada, escolha a guia Consultor de Acesso.4. Na guia Access Advisor (Consultor de acesso), revise a atividade recente para a função vinculada ao

serviço.

Note

Se não tiver certeza se o Amazon DocumentDB está usando a funçãoAWSServiceRoleForRDS, você poderá tentar excluir a função. Se o serviço está usandoa função, a exclusão falha e você pode visualizar as regiões em que a função está sendousada. Se a função está sendo usada, você deve aguardar a sessão final antes de excluir afunção. Você não pode revogar a sessão para uma função vinculada a serviço.

Se deseja remover a função AWSServiceRoleForRDS, você deve primeiro excluir todas as instâncias eclusters. Para obter informações sobre como excluir instâncias e clusters, consulte os seguintes tópicos:

• Deleting an Amazon DocumentDB Instance (p. 263)• Excluir um cluster do Amazon DocumentDB (p. 240)

Regiões com suporte para funções vinculadas aoserviço Amazon DocumentDBO Amazon DocumentDB oferece suporte a funções vinculadas a serviços em todas as regiões em que oserviço está disponível. Para obter mais informações, consulte https://docs.aws.amazon.com/documentdb/latest/developerguide/regions-and-azs.html#regions-and-azs-availability.

334

https://console.aws.amazon.com/iam/

https://console.aws.amazon.com/iam/

https://docs.aws.amazon.com/documentdb/latest/developerguide/regions-and-azs.html#regions-and-azs-availability

https://docs.aws.amazon.com/documentdb/latest/developerguide/regions-and-azs.html#regions-and-azs-availability


Monitoramento do AmazonDocumentDB

Monitorar seus serviços da AWS é uma parte importante para manter seus sistemas íntegros efuncionando de maneira ideal. Convém coletar dados de monitoramento de todas as partes de sua soluçãoda AWS para que você possa depurar e corrigir mais facilmente as falhas ou degradações caso elasocorram. Antes de começar a monitorar suas soluções da AWS, recomendamos que você considere eformule respostas para as seguintes perguntas:

• Quais são seus objetivos de monitoramento?• Você fará o monitoramento de quais recursos?• Com que frequência você fará o monitoramento desses recursos?• Quais ferramentas de monitoramento você usará?• Quem é responsável por fazer o monitoramento?• Quem deve ser notificado e por quais meios se algo der errado?

Para entender os padrões de desempenho atuais, identificar anomalias de desempenho e elaborarmétodos para a solução de problemas, você deverá estabelecer métricas de desempenho de linha debase para vários momentos e sob diferentes condições de carga. Ao monitorar sua solução da AWS,recomendamos que você armazene seus dados históricos de monitoramento para referência futura e paraestabelecer as linhas de base.

Em geral, os valores aceitáveis para as métricas de desempenho dependem do aspecto da linha de basee do que o aplicativo está fazendo. Investigue variações consistentes ou tendenciais de sua linha de base.Veja a seguir uma instrução sobre os tipos específicos de métricas:

• Alto uso de CPU ou RAM — valores altos de uso de CPU ou RAM podem ser adequados, desde queestejam de acordo com seus objetivos em relação ao seu aplicativo (como taxa de transferência ousimultaneidade) e sejam esperados.

• Consumo de volume de armazenamento — investigue o consumo de armazenamento(VolumeBytesUsed) se o espaço utilizado for consistentemente igual ou superior a 85% doespaço total do volume de armazenamento. Determine se você pode excluir dados do volume dearmazenamento ou dados de arquivamento em outro sistema para liberar mais espaço. Para obter maisinformações, consulte Amazon DocumentDBArmazenamento do (p. 11) e Cotas e limites do AmazonDocumentDB (p. 406).

• Tráfego de rede — em relação ao tráfego de rede, fale com o administrador do sistema para entenderqual taxa de transferência é esperada para sua rede de domínio e conexão com a Internet. Inspecione otráfego de rede caso a taxa de transferência seja consistentemente menor do que a esperada.

• Conexões do banco de dados — considere restringir as conexões do banco de dados caso perceba umalto número de conexões de usuários em conjunto com uma diminuição no desempenho da instância eno tempo de resposta. O melhor número de conexões de usuários para sua instância varia conforme aclasse da instância e a complexidade das operações sendo executadas.

• Métricas de IOPS — Os valores esperados para as métricas de IOPS dependem da especificaçãodo disco e da configuração do servidor, por isso, use sua linha de base para saber os valores típicos.Inspecione caso os valores sejam consistentemente diferentes da sua linha de base. Para obter omelhor desempenho de IOPS, confira se o seu conjunto de trabalho típico se adéqua à memória paraminimizar as operações de leitura e gravação.

O Amazon DocumentDB (compatível com MongoDB) fornece uma variedade de métricas do AmazonCloudWatch que você pode monitorar para determinar a integridade e o desempenho dos clusters e

335

Amazon DocumentDB Guia do desenvolvedorMonitorar o status de um cluster

instâncias do Amazon DocumentDB. Você pode visualizar as métricas do Amazon DocumentDB usandovárias ferramentas, incluindo o console do Amazon DocumentDB, a AWS CLI e a API do CloudWatch.

Tópicos• Monitorar o status de um cluster do Amazon DocumentDB (p. 336)• Monitorar o status de uma instância do Amazon DocumentDB (p. 338)• Monitoramento do Amazon DocumentDB com o CloudWatch (p. 341)• Registro em log de chamadas da API do Amazon DocumentDB com o AWS CloudTrail (p. 351)• Profiling Amazon DocumentDB Operations (p. 352)

Monitorar o status de um cluster do AmazonDocumentDB

O status de um cluster indica a integridade do cluster. Você pode visualizar o status de um cluster usandoo console do Amazon DocumentDB ou o comando describe-db-clusters da AWS CLI.

Tópicos• Valores de status do cluster (p. 336)• Monitorar o status de um cluster usando o Console de gerenciamento da AWS (p. 337)• Monitorar o status de um cluster usando a AWS CLI (p. 337)

Valores de status do clusterA tabela a seguir lista os valores válidos para o status de um cluster.

Status do cluster Descrição

available O cluster está íntegro edisponível.

backing-up O backup do cluster está sendoexecutado no momento.

creating O cluster está sendo criado. Elefica inacessível enquanto estásendo criado.

deleting O cluster está sendo excluído.Ele fica inacessível enquanto estásendo excluído.

failing-over Um failover da instância principalpara uma réplica do AmazonDocumentDB está sendoexecutado.

inaccessible-encryption-credentials A chave do AWS KMSusada para criptografar oudescriptografar o cluster não podeser acessada.

336

Amazon DocumentDB Guia do desenvolvedorMonitorar o status de um cluster usando

o Console de gerenciamento da AWS

Status do cluster Descrição

maintenance Uma atualização de manutençãoestá sendo aplicada ao cluster.Esse status é usado para amanutenção em nível de clusterque o Amazon DocumentDBprograma com antecedência.

migrating Um snapshot do cluster estásendo restaurado em um cluster.

migration-failed Ocorreu uma falha na migração.

modifying O cluster está sendo modificadodevido a uma solicitação docliente para modificá-lo.

renaming O cluster está sendo renomeadodevido a uma solicitação docliente para renomeá-lo.

resetting-master-credentials As credenciais principais docluster estão sendo redefinidasdevido a uma solicitação docliente para redefini-las.

upgrading A versão do mecanismo docluster está sendo atualizada.

Monitorar o status de um cluster usando o Console degerenciamento da AWSAo usar a AWS CLI para determinar o status de um cluster, use o procedimento a seguir.


2. No painel de navegação, escolha Clusters.3. Na coluna Cluster identifier (Identificador de cluster), encontre o nome do cluster desejado. Depois,

para encontrar o status do cluster, leia essa linha até a coluna Status, conforme mostrado a seguir.

Monitorar o status de um cluster usando a AWS CLIAo usar a AWS CLI para determinar o status de um cluster, use a operação describe-db-clusters. Ocódigo a seguir verifica o status do cluster sample-cluster.


337


Amazon DocumentDB Guia do desenvolvedorMonitorar o status de uma instância

aws docdb describe-db-clusters \ --db-cluster-identifier sample-cluster \ --query 'DBClusters[*].[DBClusterIdentifier,Status]'

Para Windows:

aws docdb describe-db-clusters ^ --db-cluster-identifier sample-cluster ^ --query 'DBClusters[*].[DBClusterIdentifier,Status]'


[ [ "sample-cluster", "available" ]]

Monitorar o status de uma instância do AmazonDocumentDB

O status de uma instância indica a integridade da instância. Você pode visualizar o status de uma instânciano Amazon DocumentDB (compatível com MongoDB) usando o Console de gerenciamento da AWS ou aoperação describe-db-instances da AWS CLI.

Note

O Amazon DocumentDB também usa outro status chamado status de manutenção, que émostrado na coluna Maintenance (Manutenção) do console do Amazon DocumentDB. Este valorindica o status de todos os patches de manutenção que precisarem ser aplicados a uma instância.O status de manutenção é independente do status da instância do Amazon DocumentDB. Paraobter mais informações sobre o status de manutenção, consulte Aplicação de atualizações doAmazon DocumentDB (p. 327).

Tópicos• Valores de status de instâncias (p. 338)• Monitorar o status de uma instância usando o Console de gerenciamento da AWS (p. 340)• Monitoramento do status de uma instância usando a AWS CLI (p. 340)

Valores de status de instânciasA tabela a seguir lista os possíveis valores de status de instâncias e como cada status é cobrado. Elamostra se você será cobrado pela instância e pelo armazenamento, somente pelo armazenamento ou senão será cobrado. Para todos os status de instância, você sempre será cobrado pelo uso de backup.

Valores válidos de status de instâncias

Status da instância Faturado Descrição

available Faturado A instância está íntegra e disponível.

338

Amazon DocumentDB Guia do desenvolvedorValores de status de instâncias


backing-up Faturado No momento, está sendo feito o backup dainstância.

configuring-log-exports

Faturado A publicação dos arquivos de log no AmazonCloudWatch Logs está sendo habilitada oudesabilitada para essa instância.

creating Não faturado A instância está sendo criada. A instância nãofica inacessível enquanto está sendo criada.

deleting Não faturado A instância está sendo excluída.

failed Não faturado Houve falha na instância e o AmazonDocumentDB não pôde recuperá-la. Pararecuperar os dados, execute uma restauraçãopoint-in-time no último momento restaurável dainstância.

inaccessible-encryption-credentials

Não faturado A chave do AWS KMS que é usada paracriptografar ou descriptografar a instância nãopôde ser acessada.

incompatible-network

Não faturado O Amazon DocumentDB está tentando executaruma ação de recuperação em uma instância,mas não consegue fazer isso porque a VPCestá em um estado que impede a conclusãoda ação. Este status pode ocorrer se, porexemplo, todos os endereços IP disponíveis emuma sub-rede estiverem em uso e o AmazonDocumentDB for incapaz de obter um endereçoIP para a instância.

maintenance Faturado O Amazon DocumentDB está aplicando umaatualização de manutenção na instância. Estestatus é usado para a manutenção de nívelde instância que o Amazon DocumentDBagenda com antecedência. Estamos avaliandomaneiras de expor ações adicionais demanutenção para clientes com este status.

modifying Faturado A instância está sendo alterada devido a umasolicitação.

rebooting Faturado A instância está sendo reinicializada devido auma solicitação ou a um processo do AmazonDocumentDB que exige a reinicialização dainstância.

renaming Faturado A instância está sendo renomeada devido auma solicitação.

resetting-master-credentials

Faturado As credenciais principais da instância estãosendo redefinidas devido a uma solicitação.

restore-error Faturado A instância encontrou um erro ao tentarrestaurar para um determinado point-in-time oude um snapshot.

339

Amazon DocumentDB Guia do desenvolvedorMonitorar o status de uma instância usando

o Console de gerenciamento da AWS


starting Faturado paraarmazenamento

A instância está iniciando.

stopped Faturado paraarmazenamento

A instância está interrompida.

stopping Faturado paraarmazenamento

A instância está sendo interrompida.

storage-full Faturado A instância alcançou sua alocação decapacidade de armazenamento. Esteé um status crítico e deve ser resolvidoimediatamente. Você deve expandir oarmazenamento modificando a instância.Configure os alarmes do Amazon CloudWatchpara adverti-lo quando o espaço dearmazenamento estiver ficando baixo, paraevitar essa situação.

Monitorar o status de uma instância usando o Consolede gerenciamento da AWSAo usar a AWS CLI para determinar o status de um cluster, use o procedimento a seguir.


2. No painel de navegação, escolha Instances (Instâncias).3. Na coluna Instance identifier (Identificador de instância), encontre o nome da instância desejada. Em

seguida, para localizar o status da instância, leia essa linha para a coluna Status, como mostrado aseguir.

Monitoramento do status de uma instância usando aAWS CLIAo usar a AWS CLI para determinar o status de um cluster, use a operação describe-db-instances.O código a seguir verifica o status da instância sample-cluster-instance-01.


340


Amazon DocumentDB Guia do desenvolvedorMonitoramento do Amazon DocumentDB com o CloudWatch

aws docdb describe-db-instances \ --db-instance-identifier sample-cluster-instance-01 \ --query 'DBInstances[*].[DBInstanceIdentifier,DBInstanceStatus]'

Para Windows:

aws docdb describe-db-instances ^ --db-instance-identifier sample-cluster-instance-01 ^ --query 'DBInstances[*].[DBInstanceIdentifier,DBInstanceStatus]'

A saída dessa operação é semelhante a esta.

[ [ "sample-cluster-instance-01", "available" ] ]

Monitoramento do Amazon DocumentDB com oCloudWatch

Amazon DocumentDB (compatível com MongoDB) integra com Amazon CloudWatch para que possareunir e analisar métricas operacionais para os seus grupos. Pode monitorizar estas métricas utilizando oCloudWatch consola, a Amazon DocumentDB consola, a AWS Command Line Interface (AWS CLI) ou oCloudWatch API.

CloudWatchO também permite que você defina alarmes para receber notificações se um valor de métricaviolar um limite especificado por você. Você também pode configurar o Eventos do Amazon CloudWatchpara executar uma ação corretiva caso ocorra uma violação. Para mais informações sobre a utilizaçãoCloudWatch e alarmes, consulte o Documentação do relógio cloudwatch da Amazon.

Tópicos• Amazon DocumentDBMétricas do no (p. 341)• Visualização CloudWatch Dados (p. 346)• Amazon DocumentDBDimensões de do (p. 350)• Contador de monitorização (p. 350)• Monitorar conexões de banco de dados (p. 350)

Amazon DocumentDBMétricas do noMonitorizar a saúde e o desempenho do seu Amazon DocumentDB cluster e instâncias, pode ver asseguintes métricas no Amazon DocumentDB consola.

Métrica Description (Descrição)

Resource Utilization

BackupRetentionPeriodStorageUsed A quantidade total de armazenamento decópias de segurança na gib utilizada parasuportar a funcionalidade de recuperação

341

https://docs.aws.amazon.com/cloudwatch/index.html

Amazon DocumentDB Guia do desenvolvedorAmazon DocumentDBMétricas do no

Métrica Description (Descrição)pontual dentro do Amazon DocumentDBjanelade retenção. Incluído no total reportado peloTotalBackupStorageBilled padrão. Calculadoseparadamente para cada Amazon DocumentDBgrupo.

ChangeStreamLogSize A quantidade de armazenamento usadapelo cluster para armazenar o log do fluxode alterações em megabytes. Esse valor éum subconjunto do armazenamento total docluster (VolumeBytesUsed) e afeta o custodo cluster. Para obter informações sobre opreço de armazenamento, consulte o AmazonDocumentDB página do produto. O tamanho do logdo fluxo de alterações dependerá do número dealterações que ocorrerem no cluster e da duraçãoda retenção do log do fluxo de alterações. Paraobter mais informações sobre fluxos de alterações,consulte Usar fluxos de alterações com o AmazonDocumentDB (p. 377).

CPUUtilization A porcentagem de CPU usada por uma instância.

DatabaseConnections O número de ligações abertas numa instânciatomada numa frequência de um minuto.

DatabaseConnectionsMax O número máximo de ligações de base de dadosabertas numa instância num período de um minuto.

DatabaseCursors O número de cursores abre numa instância tomadanuma frequência de um minuto.

DatabaseCursorsMax O número máximo de cursores abertos numainstância num período de um minuto.

DatabaseCursorsTimedOut O número de cursores que terminaram o períodode tempo de um minuto.

FreeableMemory A quantidade de memória de acesso aleatóriodisponível, em bytes.

FreeLocalStorage Essa métrica informa a quantidade dearmazenamento disponível para cada instânciapara tabelas temporárias e logs. Esse valordepende da classe da instância. Vocêpode aumentar a quantidade de espaço dearmazenamento gratuito de uma instânciaescolhendo uma classe de instância maior paraela.

SnapshotStorageUsed A quantidade total de armazenamento de backupem GiB consumida por todos os snapshots paradeterminado cluster do Amazon DocumentDB forada janela de retenção de backup. Incluído no totalreportado pelo TotalBackupStorageBilledpadrão. Calculado separadamente para cadaAmazon DocumentDB grupo.

342

https://aws.amazon.com//documentdb/pricing




SwapUsage A quantidade de troca usada na instância.

TotalBackupStorageBilled A quantidade total de armazenamento decópias de segurança na gib para a qual éfaturada Amazon DocumentDB grupo. Inclui oarmazenamento de cópia de segurança medidopelo BackupRetentionPeriodStorageUsede SnapshotStorageUsed métricas. Calculadoseparadamente para cada Amazon DocumentDBgrupo.

VolumeBytesUsed A quantidade de armazenamento usada pelocluster em bytes. Esse valor afeta o custo docluster. Para obter informações sobre preços,consulte o Amazon DocumentDB página doproduto.

Latency

DBClusterReplicaLagMaximum A quantidade máxima de atraso, emmilissegundos, entre a instância principal e cadainstância do Amazon DocumentDB no cluster.

DBClusterReplicaLagMinimum A quantidade mínima de atraso, em milissegundos,entre a instância principal e cada instância deréplica no cluster.

DBInstanceReplicaLag O tempo de atraso, em milissegundos, ao replicaratualizações da instância principal para umainstância de réplica.

ReadLatency O tempo médio necessário por operação de I/O dedisco.

WriteLatency O tempo médio necessário, em milissegundos, poroperação de I/O de disco.

Operations

DocumentsDeleted O número de documentos eliminados num períodode um minuto.

DocumentsInserted O número de documentos inseridos num períodode um minuto.

DocumentsReturned O número de documentos devolvidos num períodode um minuto.

DocumentsUpdated O número de documentos atualizados num períodode um minuto.

OpcountersCommand O número de comandos emitidos num período deum minuto.

OpcountersDelete O número de operações de eliminação emitidasnum período de um minuto.

OpcountersGetmore O número de getmores emitidos num período deum minuto.

343





OpcountersInsert O número de operações de inserção emitidas numperíodo de um minuto.

OpcountersQuery O número de consultas emitidas num período deum minuto.

OpcountersUpdate O número de operações de actualização emitidasnum período de um minuto.

TTLDeletedDocuments O número de documentos eliminados por umttlmonitor num período de um minuto.

Throughput

NetworkReceiveThroughput A quantidade de taxa de transferência de rede, embytes por segundo, recebida dos clientes por cadainstância no cluster. Essa taxa de transferência nãoinclui o tráfego de rede entre instâncias no cluster eo volume do cluster.

NetworkThroughput A quantidade de produção de rede, em bytes porsegundo, recebida de e transmitida aos clientespor cada instância no Amazon DocumentDB grupo.Essa taxa de transferência não inclui o tráfegode rede entre instâncias no cluster e o volume docluster.

NetworkTransmitThroughput A quantidade de taxa de transferência de rede, embytes por segundo, enviada aos clientes por cadainstância no cluster. Essa taxa de transferência nãoinclui o tráfego de rede entre instâncias no cluster eo volume do cluster.

ReadIOPS O número médio de operações de I/O de leitura dedisco por segundo. O Amazon DocumentDB relataa IOPS de leitura e gravação separadamente e emintervalos de um minuto.

ReadThroughput O número médio de bytes lidos do disco porsegundo.

344



VolumeReadIOPs O número médio de operações de E/S de leiturafaturadas a partir de um volume de cluster, relatadoem intervalos de 5 minutos. As operações deleitura faturadas são calculadas no nível devolume do cluster, agregadas a partir de todasas instâncias no cluster de banco de dados eposteriormente relatadas em intervalos de 5minutos. O valor é calculado tomando o valor damétrica de operações de leitura em um períodode 5 minutos. Você pode determinar a quantidadede operações de leitura faturadas por segundo,tomando o valor da métrica de operações deleitura faturadas e dividindo por 300 segundos.Por exemplo, se as operações de leitura faturadasretornarem 13.686, as operações de leiturafaturadas por segundo serão 45 (13.686/300= 45,62). Você acumula operações de leiturafaturadas para consultas que solicitam páginas debanco de dados que não estão presentes no cachedo buffer e, portanto, devem ser carregadas a partirdo armazenamento. Você pode perceber picos emoperações de leitura faturadas, pois os resultadosda consulta são lidos a partir do armazenamento edepois são carregados no cache do buffer.

VolumeWriteIOPs O número médio de operações de E/S de gravaçãofaturadas a partir de um volume de cluster, relatadoem intervalos de 5 minutos. As operações degravação faturadas são calculadas no nível devolume do cluster, agregadas a partir de todas asinstâncias no cluster e posteriormente relatadasem intervalos de 5 minutos. O valor é calculadotomando o valor da métrica de operações deleitura em um período de 5 minutos. É possíveldeterminar a quantidade de operações degravação faturadas por segundo, tomando o valorda métrica de operações de gravação faturadase dividindo por 300 segundos. Por exemplo, seas operações de gravação faturadas retornarem13.686, as operações de gravação faturadas porsegundo serão 45 (13.686 / 300 = 45,62).

WriteIOPS O número médio de operações de E/S de gravaçãode disco por segundo. As IOPS de leitura egravação são relatadas separadamente, emintervalos de um minuto.

WriteThroughput O número médio de bytes gravados no disco porsegundo.

System

BufferCacheHitRatio A porcentagem de solicitações atendidas pelocache de buffer.

345

Amazon DocumentDB Guia do desenvolvedorVisualização CloudWatch Dados


DiskQueueDepth O número de solicitações de leitura/gravaçãopendentes aguardando para acessar o disco.

EngineUptime A quantidade de tempo, em segundos, em que ainstância está executando.

IndexBufferCacheHitRatio A percentagem de pedidos de índice que sãoservidos pela cache do tampão. Pode veruma massa de enriquecimento mais alta que100% para a métrica direita depois de largarum índice, recolha ou base de dados. Isto seráautomaticamente corrigido após 60 segundos. Estalimitação será fixada numa futura actualização dopatch.

T3 Instance Metrics

CPUCreditUsage O número de créditos CPU gastos durante operíodo de medição.

CPUCreditBalance O número de créditos CPU que uma instânciaobteve. Esse saldo é esgotado quando a CPUapresenta intermitências e os créditos de CPU sãogastos com mais rapidez do que são ganhos.

CPUSurplusCreditBalance O número de créditos de CPU excedentesdespendidos para sustentar o desempenho daCPU quando o valor do saldo de cpucreditbalanceé zero.

CPUSurplusCreditsCharged O número de créditos de CPU excedentes queexcedem o número máximo de créditos da CPUque podem ser ganhos num período de 24 horase, assim, atraindo uma taxa adicional. Para maisinformações, consulte Monitorizar os seus créditosCPU.

Visualização CloudWatch DadosPode ver Amazon CloudWatch dados utilizando o CloudWatch consola, a Amazon DocumentDB consola,AWS Command Line Interface (AWS CLI) ou o CloudWatch API.

Ver métricas de relógio de visão utilizando o Amazon DocumentDB Consola degestão

Para ver CloudWatch métricas utilizando o Amazon DocumentDB Consola de Gestão, complete os passosseguintes.


2. No painel de navegação, escolha Instâncias. Depois, na lista de instâncias, escolha o nome dainstância para a qual você deseja usar as métricas.

346

https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/burstable-performance-instances-monitoring-cpu-credits.html

https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/burstable-performance-instances-monitoring-cpu-credits.html



Tip


3. Na página de resumo resultante da instância, escolha o Monitorização para ver representaçõesgráficas do seu Amazon DocumentDB métricas da instância. Como um gráfico tem de ser gerado paracada métrica, pode demorar alguns minutos para o relógio cloudwatch gráficos para preencher.

A imagem seguinte mostra as representações gráficas de dois CloudWatch métricas no AmazonDocumentDB consola, WriteIOPS e ReadIOPS.

Ver métricas de relógio de visão utilizando o CloudWatch Consola de gestão

Para visualizar as métricas do relógio de visualização utilizando o CloudWatch Consola de Gestão,complete os passos seguintes.

1. Faça login no Console de Gerenciamento da AWS e abra o console do Amazon DocumentDB emhttps://console.aws.amazon.com/cloudwatch.

2. No painel de navegação, escolha Métricas. Depois, a partir da lista de nomes de serviço, escolhadocdb.

3. Escolha uma dimensão métrica (por exemplo, Métricas de cluster).4. O Todas as métricas mostra todas as métricas para essa dimensão em docdb.

a. Para classificar a tabela, use o cabeçalho da coluna.b. Para criar um gráfico de uma métrica, marque a caixa de seleção ao lado da métrica. Para

selecionar todas as métricas, marque a caixa de seleção na linha de cabeçalho da tabela.c. Para filtrar por métrica, passe o cursor sobre o nome da métrica e seleccione a seta pendente

próximo do nome da métrica. Depois, escolha Adicionar à pesquisa, conforme mostrado naimagem abaixo.

347

https://console.aws.amazon.com/cloudwatch


Ver métricas de relógio de visão utilizando o AWS CLIPara ver CloudWatch dados para Amazon DocumentDB, utilize o CloudWatch get-metric-statisticscom os seguintes parâmetros.

Parameters

• --namespace — Obrigatório. O namespace de serviço cujas métricas do CloudWatch você deseja ver.Para o Amazon DocumentDB, deve ser AWS/DocDB.

• --metric-name — Obrigatório. O nome da métrica cujos dados você deseja ver.• --start-time — Obrigatório. O timestamp que determina o primeiro ponto de dados a ser retornado.

O valor especificado é inclusivo; os resultados incluem pontos de dados com o timestamp especificado.O timestamp deve estar no formato ISO 8601 UTC (por exemplo, 2016-10-03T23:00:00Z).

• --end-time — Obrigatório. O timestamp que determina o último ponto de dados a ser retornado.

O valor especificado é inclusivo; os resultados incluem pontos de dados com o timestamp especificado.O timestamp deve estar no formato ISO 8601 UTC (por exemplo, 2016-10-03T23:00:00Z).

• --period — Obrigatório. A granularidade, em segundos, dos pontos de dados retornados. Paramétricas com resolução regular, um período pode ser tão curto quanto um minuto (60 segundos) e deveser um múltiplo de 60. Para métricas de alta resolução coletadas em intervalos menores que um minuto,o período pode ser 1, 5, 10, 30, 60 ou qualquer múltiplo de 60.

• --dimensions — Opcional. Se a métrica contiver várias dimensões, você deverá incluir um valor paracada dimensão. O CloudWatch trata cada combinação única de dimensões como uma métrica separada.Se uma combinação específica de dimensões não foi publicada, você não poderá recuperar estatísticaspara ela. Você deve especificar as mesmas dimensões usadas ao criar as métricas.

• --statistics — Opcional. As estatísticas da métrica, além do percentil. Para estatísticas de percentil,utilize ExtendedStatistics. Quando ligar GetMetricStatistics, tem de especificar Statisticsou ExtendedStatistics, mas não ambos.

Valores permitidos:• SampleCount

• Average

• Sum

• Minimum

• Maximum

• --extended-statistics — Opcional. O percentile estatísticas. Especifique os valoresentre p0.0 e p100. Quando ligar GetMetricStatistics, tem de especificar Statistics ouExtendedStatistics, mas não ambos.

• --unit — Opcional. A unidade para uma determinada métrica. As métricas podem ser relatadas emvárias unidades. Não fornecer uma unidade resulta em todas as unidades sendo retornadas. Se vocêespecificar apenas uma unidade que a métrica não reporta, os resultados da chamada serão nulos.

Possíveis valores• Seconds

• Microseconds

• Milliseconds

• Bytes

• Kilobytes

• Megabytes

• Gigabytes

• Terabytes

348


• Bits

• Kilobytes

• Megabits

• Gigabits

• Terabits

• Percent

• Count

• Bytes/Second

• Kilobytes/Second

• Megabytes/Second

• Gigabytes/Second

• Terabytes/Second

• Bits/Second

• Kilobits/Second

• Megabits/Second

• Gigabits/Second

• Terabits/Second

• Count/Second

• None

Example

O exemplo a seguir localiza o CPUUtilization máximo para um período de 2 horas, tirando umaamostra a cada 60 segundos.


aws cloudwatch get-metric-statistics \ --namespace AWS/DocDB \ --dimensions \ Name=DBInstanceIdentifier,Value=docdb-2019-01-09-23-55-38 \ --metric-name CPUUtilization \ --start-time 2019-02-11T05:00:00Z \ --end-time 2019-02-11T07:00:00Z \ --period 60 \ --statistics Maximum

Para Windows:

aws cloudwatch get-metric-statistics ^ --namespace AWS/DocDB ^ --dimensions ^ Name=DBInstanceIdentifier,Value=docdb-2019-01-09-23-55-38 ^ --metric-name CPUUtilization ^ --start-time 2019-02-11T05:00:00Z ^ --end-time 2019-02-11T07:00:00Z ^ --period 60 ^ --statistics Maximum


{ "Label": "CPUUtilization",

349

Amazon DocumentDB Guia do desenvolvedorAmazon DocumentDBDimensões de do

"Datapoints": [ { "Unit": "Percent", "Maximum": 4.49152542374361, "Timestamp": "2019-02-11T05:51:00Z" }, { "Unit": "Percent", "Maximum": 4.25000000000485, "Timestamp": "2019-02-11T06:44:00Z" }, ********* some output omitted for brevity ********* { "Unit": "Percent", "Maximum": 4.33333333331878, "Timestamp": "2019-02-11T06:07:00Z" } ] }

Amazon DocumentDBDimensões de doAs métricas para o Amazon DocumentDB são qualificadas de acordo com os valores de conta ouoperação. Pode utilizar o CloudWatch consola para recuperar Amazon DocumentDB dados filtrados porqualquer uma das dimensões na tabela seguinte.

Dimensão Description (Descrição)

DBClusterIdentifier Filtra os dados que solicita para um AmazonDocumentDB grupo.

DBClusterIdentifier, Role Filtra os dados solicitados por você para um clusterespecífico do Amazon DocumentDB, agregandoa métrica por função de instância (WRITER/READER). Por exemplo, você pode agregarmétricas para todas as instâncias de READER quepertençam a um cluster.

DBInstanceIdentifier Filtra os dados solicitados para uma instância debanco de dados específica.

Contador de monitorizaçãoAs métricas Opcounter têm um valor não zero (normalmente ~50) para grupos inativos. Isto porqueAmazon DocumentDB executa verificações periódicas de saúde, operações internas e tarefas de recolhade métricas.

Monitorar conexões de banco de dadosQuando visualizar o número de ligações, utilizando os comandos do motor da base de dados, taiscomo db.runCommand( { serverStatus: 1 }), pode ver até 10 ligações mais próximas do quever em DatabaseConnections através de CloudWatch. Isto ocorre porque Amazon DocumentDBexecuta verificações periódicas de saúde e tarefas de recolha de métricas que não são contabilizadas emDatabaseConnections. DatabaseConnections representa apenas ligações iniciadas pelo cliente.

350

Amazon DocumentDB Guia do desenvolvedorRegistro em log de chamadas da API doAmazon DocumentDB com o CloudTrail

Registro em log de chamadas da API do AmazonDocumentDB com o AWS CloudTrail

O Amazon DocumentDB (compatível com MongoDB) é integrado ao AWS CloudTrail, um serviço quefornece um registro de ações realizadas pelos usuários do IAM, funções do IAM ou um serviço daAWS no Amazon DocumentDB (compatível com MongoDB). O CloudTrail captura todas as chamadasda API da AWS CLI do Amazon DocumentDB como eventos, incluindo as chamadas do console doAmazon DocumentDB e as chamadas de código para o SDK do Amazon DocumentDB. Se você criaruma trilha, poderá habilitar a entrega contínua de eventos do CloudTrail para um bucket do AmazonS3, incluindo eventos para o Amazon DocumentDB. Se não configurar uma trilha, você ainda poderávisualizar os eventos mais recentes no console do CloudTrail em Event history (Histórico de eventos).Com as informações coletadas pelo CloudTrail, determine a solicitação feita para o Amazon DocumentDB(compatível com MongoDB), o endereço IP do qual a solicitação foi feita, quem fez a solicitação, quandoela foi feita e outros detalhes.

Important

Para determinados recursos de gerenciamento, o Amazon DocumentDB usa tecnologiaoperacional compartilhada com o Amazon Relational Database Service (Amazon RDS). O consoledo Amazon DocumentDB, a AWS CLI e as chamadas de API são registradas como chamadasfeitas à API do Amazon RDS.

Para saber mais sobre o AWS CloudTrail, consulte o Guia do usuário do AWS CloudTrail.

Informações do Amazon DocumentDB no CloudTrailO CloudTrail está habilitado na sua conta da AWS ao criá-la. Quando a atividade ocorre no AmazonDocumentDB (compatível com MongoDB), ela é registrada em um evento do CloudTrail junto com outroseventos de serviços da AWS em Event history (Histórico de eventos). Você pode visualizar, pesquisare fazer download de eventos recentes em sua conta da AWS. Para obter mais informações, consulteVisualizar eventos com o histórico de eventos do CloudTrail.

Para obter um registro contínuo de eventos em sua conta da AWS, incluindo eventos para o AmazonDocumentDB (compatível com MongoDB), crie uma trilha. Uma trilha permite CloudTrail para fornecerarquivos de log a um bucket do Amazon S3. Por padrão, quando você cria uma trilha no console, ela éaplicada a todas as regiões da AWS. A trilha registra eventos em log de todas as regiões na partição daAWS e entrega os arquivos de log ao bucket do Amazon S3 que você especificar. Além disso, você podeconfigurar outros serviços da AWS para analisar mais profundamente e agir sobre os dados de eventocoletados nos logs do CloudTrail. Para obter mais informações, consulte os seguintes tópicos no Guia dousuário do AWS CloudTrail:

• Visão geral da criação de uma trilha• CloudTrail Serviços compatíveis e integrações do• Configuração de notificações do Amazon SNS para o CloudTrail• Recebimento de arquivos de log do CloudTrail de várias regiões• Recebimento de arquivos de log do CloudTrail de várias contas

Cada entrada de log ou evento inclui informações sobre quem gerou a solicitação. As informações deidentidade ajudam a determinar:

• Se a solicitação foi feita com credenciais de usuário da raiz ou do IAM.• Se a solicitação foi feita com credenciais de segurança temporárias de uma função ou de um usuário

federado.

351

https://docs.aws.amazon.com/awscloudtrail/latest/userguide/

https://docs.aws.amazon.com/awscloudtrail/latest/userguide/view-cloudtrail-events.html

https://docs.aws.amazon.com/awscloudtrail/latest/userguide/cloudtrail-create-and-update-a-trail.html

https://docs.aws.amazon.com/awscloudtrail/latest/userguide/cloudtrail-aws-service-specific-topics.html#cloudtrail-aws-service-specific-topics-integrations

https://docs.aws.amazon.com/awscloudtrail/latest/userguide/configure-sns-notifications-for-cloudtrail.html

https://docs.aws.amazon.com/awscloudtrail/latest/userguide/receive-cloudtrail-log-files-from-multiple-regions.html

https://docs.aws.amazon.com/awscloudtrail/latest/userguide/cloudtrail-receive-logs-from-multiple-accounts.html

Amazon DocumentDB Guia do desenvolvedorProfiling Operations

• Se a solicitação foi feita por outro serviço da AWS.

Para obter mais informações, consulte Elemento userIdentity do CloudTrail.

Profiling Amazon DocumentDB OperationsÉ possível usar o profiler no Amazon DocumentDB (compatível com MongoDB) para registrar em logo tempo de execução e detalhes das operações executadas em seu cluster. O profiler é útil para omonitoramento das operações mais lentas em seu cluster, para ajudá-lo a melhorar o desempenhoindividual de consultas e o desempenho geral do cluster.

Por padrão, o recurso profiler está desabilitado. Quando habilitado, o profiler registra em log as operaçõesque estão levando mais tempo do que o valor limite definido pelo cliente (por exemplo, 100 ms) no AmazonCloudWatch Logs. Os detalhes registrados no log incluem o comando, a hora, o resumo do plano eos metadados do cliente do perfil. Depois que as operações forem registradas em log no CloudWatchLogs, será possível usar o CloudWatch Logs Insights para analisar, monitorar e arquivar seus dadosde criação de perfil do Amazon DocumentDB. Consultas comuns são fornecidas na seção CommonQueries (p. 358).

Quando habilitado, o profiler usa recursos adicionais em seu cluster. Recomendamos começar com umvalor limite alto (por exemplo, 500 ms) e diminuí-lo gradualmente para identificar as operações lentas.Começar com um valor limite de 50 ms pode causar problemas de desempenho no cluster para aplicativosde alta taxa de transferência. O profiler é habilitado no nível do cluster e funciona em todas as instânciase bancos de dados em um cluster. O Amazon DocumentDB registra em log operações no AmazonCloudWatch Logs com base no melhor esforço.

Embora o Amazon DocumentDB não imponha cobranças adicionais para habilitar o profiler, serãocobradas as taxas padrão pelo uso do CloudWatch Logs. Para obter mais informações sobre definição depreço do CloudWatch Logs, consulte Definição de preço do Amazon CloudWatch.

Tópicos• Supported Operations (p. 352)• Limitations (p. 353)• Enabling the Amazon DocumentDB Profiler (p. 353)• Disabling the Amazon DocumentDB Profiler (p. 356)• Disabling Profiler Logs Export (p. 356)• Accessing Your Amazon DocumentDB Profiler Logs (p. 358)• Common Queries (p. 358)

Supported OperationsO profiler do Amazon DocumentDB é compatível com as seguintes operações:

• aggregate

• count

• delete

• distinct

• find (OP_QUERY and command)• findAndModify

• insert

• update

352

https://docs.aws.amazon.com/awscloudtrail/latest/userguide/cloudtrail-event-reference-user-identity.html

https://aws.amazon.com/cloudwatch/pricing/

Amazon DocumentDB Guia do desenvolvedorLimitations

LimitationsO perfil de consulta lenta só pode emitir registos de perfil se todo o conjunto de resultados da consulta forcapaz de caber num lote e se o conjunto de resultados for inferior a 16 MB (tamanho máximo BSON). Osconjuntos de resultados superiores a 16 MB são automaticamente divididos em vários lotes.

A maioria dos condutores ou invólucros pode definir um tamanho de lote predefinido que é pequeno. Podeespecificar o tamanho do lote como parte da sua consulta. Para efeitos de captura de registos de consultalentos, recomendamos um tamanho de lote que exceda o tamanho do conjunto de resultados esperado.Se não tiver a certeza do tamanho do conjunto de resultados ou se variar, também pode definir o tamanhodo lote para um número grande (por exemplo, 100 k).

No entanto, utilizando um tamanho de lote maior significa que serão obtidos mais resultados da base dedados antes de uma resposta ser enviada para o cliente. Para algumas questões, que podem criar atrasosmais longos antes de obter resultados. Se não planear consumir todo o conjunto de resultados, é possívelque passe mais E/S para processar a consulta e eliminar o resultado.

Enabling the Amazon DocumentDB ProfilerA habilitação do profiler em um cluster é um processo de três etapas. Verifique se todas as etapas foramconcluídas, ou os logs de criação de perfil não serão enviados para o CloudWatch Logs. O profiler édefinido no nível do cluster e executado em todos os bancos de dados e instâncias do cluster.

Como habilitar o profiler em um cluster

1. Como você não pode modificar um grupo de parâmetros de cluster padrão, verifique se tem um grupode parâmetros de cluster personalizado disponível. Para obter mais informações, consulte CreatingAmazon DocumentDB Cluster Parameter Groups (p. 293).

2. Ao usar um grupo de parâmetros de cluster personalizado disponível, modifique os seguintesparâmetros. profiler, profiler_threshold_ms, e profiler_sampling_rate. Para maisinformações, consulte Modifying Amazon DocumentDB Cluster Parameter Groups (p. 295).

3. Crie ou modifique seu cluster para usar o grupo de parâmetros de cluster personalizado e habilitar aexportação de logs do profiler para o CloudWatch Logs.

As seções a seguir mostram como implementar essas etapas usando o Console de gerenciamento daAWS e a AWS Command Line Interface (AWS CLI).


1. Antes de começar, crie um cluster do Amazon DocumentDB e um grupo de parâmetros de clusterpersonalizado se você ainda não tiver um. Para obter mais informações, consulte CreatingAmazon DocumentDB Cluster Parameter Groups (p. 293) e Criação de um cluster do AmazonDocumentDB (p. 217).

2. Ao usar um grupo de parâmetros de cluster personalizado disponível, modifique os seguintesparâmetros. Para obter mais informações, consulte Modifying Amazon DocumentDB ClusterParameter Groups (p. 295).

• profiler — Enables or disables query profiling. Permitted values are enabled and disabled.The default value is disabled. To enable profiling, set the value to enabled.

• profiler_threshold_ms — When profiler is set to enabled, all commands that are takinglonger than profiler-threshold-ms are logged to CloudWatch. Permitted values are [50-INT_MAX]. The default value is 100.

• profiler_sampling_rate — The fraction of slow operations that should be profiled or logged.Permitted values are [0.0-1.0]. The default value is 1.0.

353

Amazon DocumentDB Guia do desenvolvedorEnabling the Profiler

3. Modifique seu cluster para usar o grupo de parâmetros de cluster personalizado e defina asexportações de log do profiler para publicar no Amazon CloudWatch.

a. No painel de navegação, escolha Clusters para adicionar o grupo de parâmetros personalizado aum cluster.

b. Selecione o botão à esquerda do nome do cluster que deseja associar ao grupo de parâmetros.Selecione Actions (Ações) e Modify (Modificar) para modificar seu cluster.

c. Em Cluster options (Opções de cluster), escolha o grupo de parâmetros personalizado na etapaacima para adicioná-lo ao cluster.

d. Em Log exports (Exportações de log), selecione Profiler logs (Logs do profiler) para publicar noAmazon CloudWatch.

e. Escolha Continue (Continuar) para exibir um resumo das modificações.f. Depois de verificar suas alterações, é possível aplicá-las imediatamente ou durante a próxima

janela de manutenção em Scheduling of modifications (Programação de modificações).g. Escolha Modify cluster (Modificar cluster) para atualizar seu cluster com o novo grupo de

parâmetros.

Using the AWS CLI

O procedimento a seguir habilita o profiler em todas as operações compatíveis para o cluster sample-cluster.

1. Antes de começar, verifique se você tem um grupo de parâmetros de cluster personalizado disponívelexecutando o seguinte comando e revisando a saída de um grupo de parâmetros de cluster que nãotem default no nome e tem docdb3.6 como família do grupo de parâmetros. Se você não tiverum grupo de parâmetros de cluster não padrão, consulte Creating Amazon DocumentDB ClusterParameter Groups (p. 293).

aws docdb describe-db-cluster-parameter-groups \ --query 'DBClusterParameterGroups[*].[DBClusterParameterGroupName,DBParameterGroupFamily]'

Na saída a seguir, somente sample-parameter-group atende ambos os critérios.

[ [ "default.docdb3.6", "docdb3.6" ], [ "sample-parameter-group", "docdb3.6" ]]

2. Usando seu grupo de parâmetros de cluster personalizado, modifique os seguintes parâmetros:

• profiler — Enables or disables query profiling. Permitted values are enabled and disabled.The default value is disabled. To enable profiling, set the value to enabled.

• profiler_threshold_ms — When profiler is set to enabled, all commands taking longerthan profiler -threshold-ms are logged to CloudWatch. Permitted values are [0-INT_MAX].Setting this value to 0 profiles all supported operations. The default value is 100.

• profiler_sampling_rate — The fraction of slow operations that should be profiled or logged.Permitted values are [0.0-1.0]. The default value is 1.0.

354

Amazon DocumentDB Guia do desenvolvedorEnabling the Profiler

aws docdb modify-db-cluster-parameter-group \ --db-cluster-parameter-group-name sample-parameter-group \ --parameters ParameterName=profiler,ParameterValue=enabled,ApplyMethod=immediate \ ParameterName=profiler_threshold_ms,ParameterValue=100,ApplyMethod=immediate \ ParameterName=profiler_sampling_rate,ParameterValue=0.5,ApplyMethod=immediate

3. Modifique o cluster do Amazon DocumentDB para que ele use o grupo de parâmetro de clusterpersonalizado sample-parameter-group da etapa anterior e defina o parâmetro --enable-cloudwatch-logs-exports como profiler.

O código a seguir modifica o cluster sample-cluster para usar o sample-parameter-group daetapa anterior e adiciona profiler às exportações do CloudWatch Logs habilitadas.

aws docdb modify-db-cluster \ --db-cluster-identifier sample-cluster \ --db-cluster-parameter-group-name sample-parameter-group \ --cloudwatch-logs-export-configuration '{"EnableLogTypes":["profiler"]}'


{ "DBCluster": { "AvailabilityZones": [ "us-east-1c", "us-east-1b", "us-east-1a" ], "BackupRetentionPeriod": 1, "DBClusterIdentifier": "sample-cluster", "DBClusterParameterGroup": "sample-parameter-group", "DBSubnetGroup": "default", "Status": "available", "EarliestRestorableTime": "2020-04-07T02:05:12.479Z", "Endpoint": "sample-cluster.node.us-east-1.docdb.amazonaws.com", "ReaderEndpoint": "sample-cluster.node.us-east-1.docdb.amazonaws.com", "MultiAZ": false, "Engine": "docdb", "EngineVersion": "3.6.0", "LatestRestorableTime": "2020-04-08T22:08:59.317Z", "Port": 27017, "MasterUsername": "test", "PreferredBackupWindow": "02:00-02:30", "PreferredMaintenanceWindow": "tue:09:50-tue:10:20", "DBClusterMembers": [ { "DBInstanceIdentifier": "sample-instance-1", "IsClusterWriter": true, "DBClusterParameterGroupStatus": "in-sync", "PromotionTier": 1 }, { "DBInstanceIdentifier": "sample-instance-2", "IsClusterWriter": true, "DBClusterParameterGroupStatus": "in-sync", "PromotionTier": 1 } ],

355

Amazon DocumentDB Guia do desenvolvedorDisabling the Profiler

"VpcSecurityGroups": [ { "VpcSecurityGroupId": "sg-abcd0123", "Status": "active" } ], "HostedZoneId": "ABCDEFGHIJKLM", "StorageEncrypted": true, "KmsKeyId": "arn:aws:kms:us-east-1:<accountID>:key/sample-key", "DbClusterResourceId": "cluster-ABCDEFGHIJKLMNOPQRSTUVWXYZ", "DBClusterArn": "arn:aws:rds:us-east-1:<accountID>:cluster:sample-cluster", "AssociatedRoles": [], "ClusterCreateTime": "2020-01-10T22:13:38.261Z", "EnabledCloudwatchLogsExports": [ "profiler" ], "DeletionProtection": true }}

Disabling the Amazon DocumentDB ProfilerPara desabilitar o profiler, desative o parâmetro profiler e a exportação de logs do profiler para oCloudWatch Logs.

Disabling the ProfilerVocê pode desabilitar o parâmetro profiler usando o Console de gerenciamento da AWS ou a AWSCLI, conforme segue.


O procedimento a seguir usa o Console de gerenciamento da AWS para desabilitar o profiler doAmazon DocumentDB.


2. No painel de navegação, selecione Parameter groups (Grupos de parâmetros). Selecione o nome dogrupo de parâmetros de cluster ao qual você deseja desabilitar o profiler.

3. Na página Cluster parameters (Parâmetros de cluster) resultante, selecione o botão à esquerda doparâmetro profiler e escolha Edit (Editar).

4. Na caixa de diálogo Modify profiler (Modificar profiler) escolha disabled na lista.5. Escolha Modify cluster parameter (Modificar parâmetro do cluster).

Using the AWS CLI

Para desabilitar o profiler em um cluster usando a AWS CLI, modifique o cluster da seguinte forma.

aws docdb modify-db-cluster-parameter-group \ --db-cluster-parameter-group-name sample-parameter-group \ --parameters ParameterName=profiler,ParameterValue=disabled,ApplyMethod=immediate

Disabling Profiler Logs ExportVocê pode desabilitar a exportação de logs do profiler para o CloudWatch Logs usando o Console degerenciamento da AWS ou a AWS CLI da seguinte forma.

356


Amazon DocumentDB Guia do desenvolvedorDisabling Profiler Logs Export

Using the Console de gerenciamento da AWSO procedimento a seguir usa o Console de gerenciamento da AWS para desativar a exportação de logs doAmazon DocumentDB para o CloudWatch.

1. Abra o console do Amazon DocumentDB em https://console.aws.amazon.com/docdb.2. No painel de navegação, escolha Clusters. Escolha o botão à esquerda do nome do cluster para o

qual você deseja desativar a exportação de logs.3. No menu Actions (Ações), escolha Modify (Modificar).4. Role para baixo até a seção Log exports (Exportações de log) e desmarque Profiler logs (Logs do

profiler).5. Escolha Continue (Continuar).6. Analise as alterações e escolha quando você deseja que essa mudança seja aplicada ao seu cluster:

• Apply during the next scheduled maintenance window (Aplicar durante a próxima janela demanutenção programada)

• Apply immediately (Aplicar imediatamente)7. Selecione Modify Cluster (Modificar cluster).

Using the AWS CLIO código a seguir modifica o cluster sample-cluster e desativa os logs do profiler do CloudWatch.

Example


aws docdb modify-db-cluster \ --db-cluster-identifier sample-cluster \ --cloudwatch-logs-export-configuration '{"DisableLogTypes":["profiler"]}'

Para Windows:

aws docdb modify-db-cluster ^ --db-cluster-identifier sample-cluster ^ --cloudwatch-logs-export-configuration '{"DisableLogTypes":["profiler"]}'


{ "DBCluster": { "AvailabilityZones": [ "us-east-1c", "us-east-1b", "us-east-1a" ], "BackupRetentionPeriod": 1, "DBClusterIdentifier": "sample-cluster", "DBClusterParameterGroup": "sample-parameter-group", "DBSubnetGroup": "default", "Status": "available", "EarliestRestorableTime": "2020-04-08T02:05:17.266Z", "Endpoint": "sample-cluster.node.us-east-1.docdb.amazonaws.com", "ReaderEndpoint": "sample-cluster.node.us-east-1.docdb.amazonaws.com", "MultiAZ": false, "Engine": "docdb", "EngineVersion": "3.6.0", "LatestRestorableTime": "2020-04-09T05:14:44.356Z",

357


Amazon DocumentDB Guia do desenvolvedorAccessing Your Profiler Logs

"Port": 27017, "MasterUsername": "test", "PreferredBackupWindow": "02:00-02:30", "PreferredMaintenanceWindow": "tue:09:50-tue:10:20", "DBClusterMembers": [ { "DBInstanceIdentifier": "sample-instance-1", "IsClusterWriter": true, "DBClusterParameterGroupStatus": "in-sync", "PromotionTier": 1 }, { "DBInstanceIdentifier": "sample-instance-2", "IsClusterWriter": true, "DBClusterParameterGroupStatus": "in-sync", "PromotionTier": 1 } ], "VpcSecurityGroups": [ { "VpcSecurityGroupId": "sg-abcd0123", "Status": "active" } ], "HostedZoneId": "ABCDEFGHIJKLM", "StorageEncrypted": true, "KmsKeyId": "arn:aws:kms:us-east-1:<accountID>:key/sample-key", "DbClusterResourceId": "cluster-ABCDEFGHIJKLMNOPQRSTUVWXYZ", "DBClusterArn": "arn:aws:rds:us-east-1:<accountID>:cluster:sample-cluster", "AssociatedRoles": [], "ClusterCreateTime": "2020-01-10T22:13:38.261Z", "DeletionProtection": true }}

Accessing Your Amazon DocumentDB Profiler LogsSiga estas etapas para acessar seus logs de perfil no Amazon CloudWatch.

1. Abra o console do CloudWatch em https://console.aws.amazon.com/cloudwatch/.2. Certifique-se de estar na mesma região que seu cluster do Amazon DocumentDB.3. No painel de navegação, selecione Logs.4. Para encontrar os logs do profiler do cluster, selecione /aws/docdb/yourClusterName/profile

na lista.

Os logs de perfil para cada uma das suas instâncias estão disponíveis em cada um dos respectivosnomes de instância.

Common QueriesVeja as seguintes consultas comuns que você pode usar para analisar seus comandos perfilados.Para obter mais informações sobre o CloudWatch Logs Insights, consulte Analisar dados de log com oCloudWatch Logs Insights e Exemplos de consultas.

Get the 10 Slowest Operations on a Specified Collectionfilter ns="test.foo" | sort millis desc | limit 10

358


https://docs.aws.amazon.com/AmazonCloudWatch/latest/logs/AnalyzingLogData.html

https://docs.aws.amazon.com/AmazonCloudWatch/latest/logs/AnalyzingLogData.html

https://docs.aws.amazon.com/AmazonCloudWatch/latest/logs/CWL_QuerySyntax-examples.html

Amazon DocumentDB Guia do desenvolvedorCommon Queries

Get All the Update Operations on a Collection That Took MoreThan 60 msfilter millis > 60 and op = "update"

Get the 10 Slowest Operations in the Last Monthsort millis desc | limit 10

Get All the Queries with a COLLSCAN Plan Summaryfilter planSummary="COLLSCAN"

359

Amazon DocumentDB Guia do desenvolvedorConexão de forma programática

Desenvolvimento com o AmazonDocumentDB

Essas seções abrangem o desenvolvimento com o uso do Amazon DocumentDB (compatível comMongoDB).

Tópicos• Conexão com o Amazon DocumentDB de forma programática (p. 360)• Usar fluxos de alterações com o Amazon DocumentDB (p. 377)• Conectar-se ao Amazon DocumentDB como um conjunto de réplicas (p. 384)• Conexão com um cluster do Amazon DocumentDB de fora de uma Amazon VPC (p. 388)• Ligar a um Amazon DocumentDB Cluster de Robo 3T (p. 389)• Ligar a um Amazon DocumentDB Cluster do Studio 3T (p. 392)• Conexão usando Amazon EC2 (p. 398)

Conexão com o Amazon DocumentDB de formaprogramática

Esta seção contém exemplos de código que demonstram como se conectar ao Amazon DocumentDB(compatível com MongoDB) usando várias linguagens diferentes. Os exemplos são separados emduas seções com base na conexão com um cluster que tenha o Transport Layer Security (TLS) ativadoou desativado. Por padrão, o TLS fica ativado em clusters do Amazon DocumentDB. No entanto, sequiser, você poderá desativar o TLS. Para obter mais informações, consulte Criptografia de dados emtrânsito (p. 122).

Se você estiver tentando se conectar ao seu Amazon DocumentDB de fora da VPC em que seucluster reside, consulte Conexão com um cluster do Amazon DocumentDB de fora de uma AmazonVPC (p. 388).

Antes de se conectar ao cluster, é necessário saber se o TLS está ativado no cluster. A próxima seçãomostra como determinar o valor do parâmetro tls do seu cluster usando o Console de gerenciamentoda AWS ou a AWS CLI. Depois disso, você pode continuar localizando e aplicando o exemplo de códigoapropriado.

Tópicos• Como determinar o valor do seu parâmetro tls (p. 360)• Conectar-se com o TLS habilitado (p. 362)• Conectar-se com o TLS desabilitado (p. 371)

Como determinar o valor do seu parâmetro tlsDeterminar se o seu cluster tem o TLS ativado é um processo de duas etapas que você pode executarusando o Console de gerenciamento da AWS ou a AWS CLI.

1. Descubra qual grupo de parâmetros está regendo de seu cluster.

360

Amazon DocumentDB Guia do desenvolvedorComo determinar o valor tls

Como usar o Console de gerenciamento da AWS


2. No painel de navegação à esquerda, escolha Clusters.3. Na lista de clusters, selecione o nome do cluster.4. A página resultante exibe os detalhes do cluster selecionado. Role para baixo até Cluster details

(Detalhes do cluster). Na parte inferior dessa seção, localize o nome do grupo de parâmetros sobCluster parameter group (Grupo de parâmetros de cluster).

Usar a AWS CLI

O código de AWS CLI a seguir determina qual parâmetro está regendo o cluster. Não se esqueça desubstituir sample-cluster pelo nome do cluster.

aws docdb describe-db-clusters \ --db-cluster-identifier sample-cluster \ --query 'DBClusters[*].[DBClusterIdentifier,DBClusterParameterGroup]'

A saída dessa operação é semelhante à seguinte:

[ [ "sample-cluster", "sample-parameter-group" ]]

2. Descubra o valor do parâmetro tls no grupo de parâmetros de seu cluster.


1. No painel de navegação, selecione Parameter groups.2. Na janela Cluster parameter groups (Grupos de parâmetros de cluster), selecione o grupo de

parâmetros do cluster.3. A página resultante mostra os parâmetros do grupo de parâmetros do cluster. Você pode ver

o valor do parâmetro tls aqui. Para obter informações sobre como modificar esse parâmetro,consulte Modifying Amazon DocumentDB Cluster Parameter Groups (p. 295).

Usar a AWS CLI

Você pode usar o comando da AWS CLI describe-db-cluster-parameters para exibir osdetalhes dos parâmetros no grupo de parâmetros do cluster.

• --describe-db-cluster-parameters — para listar todos os parâmetros em um grupo deparâmetros e seus valores.• --db-cluster-parameter-group name — obrigatório. O nome do grupo de parâmetros de

cluster.


361


Amazon DocumentDB Guia do desenvolvedorConectar-se com o TLS habilitado

A saída dessa operação é semelhante à seguinte:

{ "Parameters": [ { "ParameterName": "profiler_threshold_ms", "ParameterValue": "100", "Description": "Operations longer than profiler_threshold_ms will be logged", "Source": "system", "ApplyType": "dynamic", "DataType": "integer", "AllowedValues": "50-2147483646", "IsModifiable": true, "ApplyMethod": "pending-reboot" }, { "ParameterName": "tls", "ParameterValue": "disabled", "Description": "Config to enable/disable TLS", "Source": "user", "ApplyType": "static", "DataType": "string", "AllowedValues": "disabled,enabled", "IsModifiable": true, "ApplyMethod": "pending-reboot" } ]}

Depois de descobrir o valor do parâmetro tls, continue a conexão ao cluster usando um dos exemplos decódigo nas seções a seguir.

• Conectar-se com o TLS habilitado (p. 362)• Conectar-se com o TLS desabilitado (p. 371)

Conectar-se com o TLS habilitadoPara ver um exemplo de código para se conectar de forma programática a um cluster do AmazonDocumentDB com o TLS ativado, escolha a guia apropriada para a linguagem que você deseja usar.

Para criptografar dados em trânsito, baixe a chave pública para Amazon DocumentDB nomeada rds-combined-ca-bundle.pem usando a operação a seguir.


Python

O código a seguir demonstra como se conectar ao Amazon DocumentDB usando Python quando oTLS está ativado.

import pymongoimport sys

##Create a MongoDB client, open a connection to Amazon DocumentDB as a replica set and specify the read preference as secondary preferred

362


client = pymongo.MongoClient('mongodb://<sample-user>:<password>@sample-cluster.node.us-east-1.docdb.amazonaws.com:27017/?ssl=true&ssl_ca_certs=rds-combined-ca-bundle.pem&replicaSet=rs0&readPreference=secondaryPreferred')

##Specify the database to be useddb = client.sample_database

##Specify the collection to be usedcol = db.sample_collection

##Insert a single documentcol.insert_one({'hello':'Amazon DocumentDB'})

##Find the document that was previously writtenx = col.find_one({'hello':'Amazon DocumentDB'})

##Print the result to the screenprint(x)

##Close the connectionclient.close()

Node.js

O código a seguir demonstra como se conectar ao Amazon DocumentDB usando Node.js quando oTLS está ativado.

var MongoClient = require('mongodb').MongoClient, f = require('util').format, fs = require('fs');

//Specify the Amazon DocumentDB certvar ca = [fs.readFileSync("rds-combined-ca-bundle.pem")];

//Create a MongoDB client, open a connection to Amazon DocumentDB as a replica set, // and specify the read preference as secondary preferredvar client = MongoClient.connect('mongodb://<sample-user>:<password>@sample-cluster.node.us-east-1.docdb.amazonaws.com:27017/sample-database?ssl=true&replicaSet=rs0&readPreference=secondaryPreferred', { sslValidate: true, sslCA:ca, useNewUrlParser: true},function(err, client) { if(err) throw err; //Specify the database to be used db = client.db('sample-database'); //Specify the collection to be used col = db.collection('sample-collection');

//Insert a single document col.insertOne({'hello':'Amazon DocumentDB'}, function(err, result){ //Find the document that was previously written col.findOne({'hello':'Amazon DocumentDB'}, function(err, result){ //Print the result to the screen console.log(result); //Close the connection client.close()

363


}); });});

PHP

O código a seguir demonstra como se conectar ao Amazon DocumentDB usando PHP quando o TLSestá ativado.

<?php//Include Composer's autoloaderrequire 'vendor/autoload.php';

$SSL_DIR = "/home/ubuntu";$SSL_FILE = "rds-combined-ca-bundle.pem";

//Specify the Amazon DocumentDB cert$ctx = stream_context_create(array( "ssl" => array( "cafile" => $SSL_DIR . "/" . $SSL_FILE, )));

//Create a MongoDB client and open connection to Amazon DocumentDB$client = new MongoDB\Client("mongodb://<sample-user>:<password>@sample-cluster.node.us-east-1.docdb.amazonaws.com:27017", array("ssl" => true), array("context" => $ctx));

//Specify the database and collection to be used$col = $client->sample-database->sample-collection;

//Insert a single document$result = $col->insertOne( [ 'hello' => 'Amazon DocumentDB'] );

//Find the document that was previously written$result = $col->findOne(array('hello' => 'Amazon DocumentDB'));

//Print the result to the screenprint_r($result);?>

Go

O código a seguir demonstra como se conectar ao Amazon DocumentDB usando Go quando o TLSestá ativado.

Note

Desde a versão 1.2.1, o MongoDB Go Driver usará apenas o primeiro certificado de servidorCA encontrado em sslcertificateauthorityfile. O código de exemplo abaixo abordaessa limitação anexando manualmente todos os certificados de servidor encontrados emsslcertificateauthorityfile a uma configuração TLS personalizada usada durante acriação do cliente.

package main

import ( "context" "fmt" "log" "time"

364


"go.mongodb.org/mongo-driver/bson" "go.mongodb.org/mongo-driver/mongo" "go.mongodb.org/mongo-driver/mongo/options"

"io/ioutil" "crypto/tls" "crypto/x509" "errors")

const ( // Path to the AWS CA file caFilePath = "rds-combined-ca-bundle.pem"

// Timeout operations after N seconds connectTimeout = 5 queryTimeout = 30 username = "<sample-user>" password = "<password>" clusterEndpoint = "sample-cluster.node.us-east-1.docdb.amazonaws.com:27017"

// Which instances to read from readPreference = "secondaryPreferred"

connectionStringTemplate = "mongodb://%s:%s@%s/sample-database?ssl=true&replicaSet=rs0&readpreference=%s")

func main() {

connectionURI := fmt.Sprintf(connectionStringTemplate, username, password, clusterEndpoint, readPreference)

tlsConfig, err := getCustomTLSConfig(caFilePath) if err != nil { log.Fatalf("Failed getting TLS configuration: %v", err) }

client, err := mongo.NewClient(options.Client().ApplyURI(connectionURI).SetTLSConfig(tlsConfig)) if err != nil { log.Fatalf("Failed to create client: %v", err) }

ctx, cancel := context.WithTimeout(context.Background(), connectTimeout*time.Second) defer cancel()

err = client.Connect(ctx) if err != nil { log.Fatalf("Failed to connect to cluster: %v", err) }

// Force a connection to verify our connection string err = client.Ping(ctx, nil) if err != nil { log.Fatalf("Failed to ping cluster: %v", err) }

fmt.Println("Connected to DocumentDB!")

collection := client.Database("sample-database").Collection("sample-collection")

ctx, cancel = context.WithTimeout(context.Background(), queryTimeout*time.Second) defer cancel()

res, err := collection.InsertOne(ctx, bson.M{"name": "pi", "value": 3.14159})

365


if err != nil { log.Fatalf("Failed to insert document: %v", err) }

id := res.InsertedID log.Printf("Inserted document ID: %s", id)


cur, err := collection.Find(ctx, bson.D{})

if err != nil { log.Fatalf("Failed to run find query: %v", err) } defer cur.Close(ctx)

for cur.Next(ctx) { var result bson.M err := cur.Decode(&result) log.Printf("Returned: %v", result)

if err != nil { log.Fatal(err) } }

if err := cur.Err(); err != nil { log.Fatal(err) }

}

func getCustomTLSConfig(caFile string) (*tls.Config, error) { tlsConfig := new(tls.Config) certs, err := ioutil.ReadFile(caFile)

if err != nil { return tlsConfig, err }

tlsConfig.RootCAs = x509.NewCertPool() ok := tlsConfig.RootCAs.AppendCertsFromPEM(certs)

if !ok { return tlsConfig, errors.New("Failed parsing pem file") }

return tlsConfig, nil}

Java

Ao se conectar a um cluster do Amazon DocumentDB com o TLS habilitado em um aplicativo Java,o programa deve usar o arquivo da autoridade de certificação fornecido pela AWS para validar aconexão. Para usar o certificado CA do Amazon RDS, faça o seguinte:

1. Faça download do arquivo de CA do Amazon RDS em https://s3.amazonaws.com/rds-downloads/rds-combined-ca-bundle.pem.

2. Crie um armazenamento confiável com o certificado da CA contido no arquivo executando osseguintes comandos. Altere <truststorePassword> para algo diferente. Se estiver acessandoum armazenamento confiável que contenha o certificado da CA antigo (rds-ca-2015-

366




root.pem) e o novo (rds-ca-2019-root.pem), você poderá importar o pacote de certificadospara o armazenamento confiável.

Veja a seguir um exemplo de script shell que importa o pacote de certificados para umarmazenamento confiável em um sistema operacional Linux.

mydir=/tmp/certstruststore=${mydir}/rds-truststore.jksstorepassword=<truststorePassword>

curl -sS "https://s3.amazonaws.com/rds-downloads/rds-combined-ca-bundle.pem" > ${mydir}/rds-combined-ca-bundle.pemawk 'split_after == 1 {n++;split_after=0} /-----END CERTIFICATE-----/ {split_after=1}{print > "rds-ca-" n ".pem"}' < ${mydir}/rds-combined-ca-bundle.pem

for CERT in rds-ca-*; do alias=$(openssl x509 -noout -text -in $CERT | perl -ne 'next unless /Subject:/; s/.*(CN=|CN = )//; print') echo "Importing $alias" keytool -import -file ${CERT} -alias "${alias}" -storepass ${storepassword} -keystore ${truststore} -noprompt rm $CERTdone

rm ${mydir}/rds-combined-ca-bundle.pem

echo "Trust store content is: "

keytool -list -v -keystore "$truststore" -storepass ${storepassword} | grep Alias | cut -d " " -f3- | while read alias do expiry=`keytool -list -v -keystore "$truststore" -storepass ${storepassword} -alias "${alias}" | grep Valid | perl -ne 'if(/until: (.*?)\n/) { print "$1\n"; }'` echo " Certificate ${alias} expires in '$expiry'" done

Veja a seguir um exemplo de script do shell que importa o pacote de certificados em umarmazenamento de confiança no macOS.

mydir=/tmp/certstruststore=${mydir}/rds-truststore.jksstorepassword=<truststorePassword>

curl -sS "https://s3.amazonaws.com/rds-downloads/rds-combined-ca-bundle.pem" > ${mydir}/rds-combined-ca-bundle.pemsplit -p "-----BEGIN CERTIFICATE-----" ${mydir}/rds-combined-ca-bundle.pem rds-ca-

for CERT in rds-ca-*; do alias=$(openssl x509 -noout -text -in $CERT | perl -ne 'next unless /Subject:/; s/.*(CN=|CN = )//; print') echo "Importing $alias" keytool -import -file ${CERT} -alias "${alias}" -storepass ${storepassword} -keystore ${truststore} -noprompt rm $CERTdone

rm ${mydir}/rds-combined-ca-bundle.pem

echo "Trust store content is: "

keytool -list -v -keystore "$truststore" -storepass ${storepassword} | grep Alias | cut -d " " -f3- | while read alias

367


do expiry=`keytool -list -v -keystore "$truststore" -storepass ${storepassword} -alias "${alias}" | grep Valid | perl -ne 'if(/until: (.*?)\n/) { print "$1\n"; }'` echo " Certificate ${alias} expires in '$expiry'" done

3. Use o keystore no seu programa definindo as seguintes propriedades do sistema no aplicativoantes de estabelecer uma conexão com o cluster do Amazon DocumentDB.

javax.net.ssl.trustStore: <truststore>javax.net.ssl.trustStorePassword: <truststorePassword>

4. O código a seguir demonstra como se conectar ao Amazon DocumentDB usando Java quando oTLS está ativado.

package com.example.documentdb;

import com.mongodb.MongoClient;import com.mongodb.MongoClientURI;import com.mongodb.ServerAddress;import com.mongodb.MongoException;import com.mongodb.client.MongoCursor;import com.mongodb.client.MongoDatabase;import com.mongodb.client.MongoCollection;import org.bson.Document;

public final class Main { private Main() { } public static void main(String[] args) {

String template = "mongodb://%s:%s@%s/sample-database?ssl=true&replicaSet=rs0&readpreference=%s"; String username = "<sample-user>"; String password = "<password>"; String clusterEndpoint = "sample-cluster.node.us-east-1.docdb.amazonaws.com:27017"; String readPreference = "secondaryPreferred"; String connectionString = String.format(template, username, password, clusterEndpoint, readPreference);

String truststore = "<truststore>"; String truststorePassword = "<truststorePassword>";

System.setProperty("javax.net.ssl.trustStore", truststore); System.setProperty("javax.net.ssl.trustStorePassword", truststorePassword);

MongoClientURI clientURI = new MongoClientURI(connectionString); MongoClient mongoClient = new MongoClient(clientURI);

MongoDatabase testDB = mongoClient.getDatabase("sample-database"); MongoCollection<Document> numbersCollection = testDB.getCollection("sample-collection");

Document doc = new Document("name", "pi").append("value", 3.14159); numbersCollection.insertOne(doc);

MongoCursor<Document> cursor = numbersCollection.find().iterator(); try { while (cursor.hasNext()) { System.out.println(cursor.next().toJson());

368


} } finally { cursor.close(); }

}}

C# / .NET

O código a seguir demonstra como conectar-se ao Amazon DocumentDB usando C# / .NET quando oTLS está habilitado.

using System;using System.Text;using System.Linq;using System.Collections.Generic;using System.Security.Cryptography;using System.Security.Cryptography.X509Certificates;using System.Net.Security;using MongoDB.Driver;using MongoDB.Bson;

namespace DocDB{ class Program { static void Main(string[] args) { string template = "mongodb://{0}:{1}@{2}/sample-database?ssl=true&replicaSet=rs0&readpreference={3}"; string username = "<sample-user>"; string password = "<password>"; string readPreference = "secondaryPreferred"; string clusterEndpoint="sample-cluster.node.us-east-1.docdb.amazonaws.com:27017"; string connectionString = String.Format(template, username, password, clusterEndpoint, readPreference); string pathToCAFile = "<path_to_rds-combined-ca-bundle.p7b_file>";

// ADD CA certificate to local trust store // DO this once - Maybe when your service starts X509Store localTrustStore = new X509Store(StoreName.Root); X509Certificate2Collection certificateCollection = new X509Certificate2Collection(); certificateCollection.Import(pathToCAFile); try { localTrustStore.Open(OpenFlags.ReadWrite); localTrustStore.AddRange(certificateCollection); } catch (Exception ex) { Console.WriteLine("Root certificate import failed: " + ex.Message); throw; } finally { localTrustStore.Close(); }

369


var settings = MongoClientSettings.FromUrl(new MongoUrl(connectionString)); var client = new MongoClient(settings);

var database = client.GetDatabase("sample-database"); var collection = database.GetCollection<BsonDocument>("sample-collection"); var docToInsert = new BsonDocument { { "pi", 3.14159 } }; collection.InsertOne(docToInsert); } }}

mongo shell

O código a seguir demonstra como se conectar ao e consultar o Amazon DocumentDB usando o shellmongo quando TLS está habilitado.

1. Conecte-se ao Amazon DocumentDB com o shell mongo.

mongo --ssl --host sample-cluster.node.us-east-1.docdb.amazonaws.com:27017 --sslCAFile rds-combined-ca-bundle.pem --username <sample-user> --password <password>

2. Insira um único documento.

db.myTestCollection.insertOne({'hello':'Amazon DocumentDB'})

3. Encontre o documento inserido anteriormente.

db.myTestCollection.find({'hello':'Amazon DocumentDB'})

R

O código a seguir demonstra como se conectar ao Amazon DocumentDB com R usando o mongolite(https://jeroen.github.io/mongolite/) quando o TLS está habilitado.

#Include the mongolite library.library(mongolite)

mongourl <- paste("mongodb://<sample-user>:<password>@sample-cluster.node.us-east-1.docdb.amazonaws.com:27017/test2?ssl=true&", "readPreference=secondaryPreferred&replicaSet=rs0", sep="") #Create a MongoDB client, open a connection to Amazon DocumentDB as a replica# set and specify the read preference as secondary preferredclient <- mongo(url = mongo(url = mongourl, options = ssl_options(weak_cert_validation = F, ca = <path to 'rds-combined-ca-bundle.pem'>))

#Insert a single documentstr <- c('{"hello" : "Amazon DocumentDB"}')client$insert(str)

#Find the document that was previously writtenclient$find()

Ruby

O código a seguir demonstra como se conectar ao Amazon DocumentDB com o Ruby quando o TLSestá habilitado.

370

https://jeroen.github.io/mongolite/

Amazon DocumentDB Guia do desenvolvedorConectar-se com o TLS desabilitado

require 'mongo'require 'neatjson'require 'json'client_host = 'mongodb://sample-cluster.node.us-east-1.docdb.amazonaws.com:27017'client_options = { database: 'test', replica_set: 'rs0', read: {:secondary_preferred => 1}, user: '<sample-user>', password: '<password>', ssl: true, ssl_verify: true, ssl_ca_cert: <path to 'rds-combined-ca-bundle.pem'>}

begin ##Create a MongoDB client, open a connection to Amazon DocumentDB as a ## replica set and specify the read preference as secondary preferred client = Mongo::Client.new(client_host, client_options) ##Insert a single document x = client[:test].insert_one({"hello":"Amazon DocumentDB"}) ##Find the document that was previously written result = client[:test].find() #Print the document result.each do |document| puts JSON.neat_generate(document) endend

#Close the connectionclient.close

Conectar-se com o TLS desabilitadoPara ver um exemplo de código para se conectar de forma programática a um cluster do AmazonDocumentDB com o TLS desativado, escolha a guia para a linguagem que você deseja usar.

Python

O código a seguir demonstra como conectar-se ao Amazon DocumentDB usando Python quando oTLS está desabilitado.

## Create a MongoDB client, open a connection to Amazon DocumentDB as a replica set and specify the read preference as secondary preferred client = pymongo.MongoClient('mongodb://<sample-user>:<password>@sample-cluster.node.us-east-1.docdb.amazonaws.com:27017/?replicaSet=rs0&readPreference=secondaryPreferred')

##Specify the database to be useddb = client.sample_database

##Specify the collection to be usedcol = db.sample_collection

##Insert a single documentcol.insert_one({'hello':'Amazon DocumentDB'})

371


##Find the document that was previously writtenx = col.find_one({'hello':'Amazon DocumentDB'})

##Print the result to the screenprint(x)

##Close the connectionclient.close()

Node.js

O código a seguir demonstra como se conectar ao Amazon DocumentDB usando Node.js quando oTLS está desabilitado.

var MongoClient = require('mongodb').MongoClient; //Create a MongoDB client, open a connection to Amazon DocumentDB as a replica set,// and specify the read preference as secondary preferredvar client = MongoClient.connect('mongodb://<sample-user>:<password>@sample-cluster.node.us-east-1.docdb.amazonaws.com:27017/sample-database?replicaSet=rs0&readPreference=secondaryPreferred', { useNewUrlParser: true},

function(err, client) { if(err) throw err; //Specify the database to be used db = client.db('sample-database'); //Specify the collection to be used col = db.collection('sample-collection');

//Insert a single document col.insertOne({'hello':'Amazon DocumentDB'}, function(err, result){ //Find the document that was previously written col.findOne({'hello':'Amazon DocumentDB'}, function(err, result){ //Print the result to the screen console.log(result); //Close the connection client.close() }); });});

PHP

O código a seguir demonstra como se conectar ao Amazon DocumentDB usando PHP quando o TLSestá desabilitado.

<?php//Include Composer's autoloaderrequire 'vendor/autoload.php';

//Create a MongoDB client and open connection to Amazon DocumentDB$client = new MongoDB\Client("mongodb://<sample-user>:<password>@sample-cluster.node.us-east-1.docdb.amazonaws.com:27017");

372


//Specify the database and collection to be used$col = $client->sample-database->sample-collection;

//Insert a single document$result = $col->insertOne( [ 'hello' => 'Amazon DocumentDB'] );

//Find the document that was previously written$result = $col->findOne(array('hello' => 'Amazon DocumentDB'));

//Print the result to the screenprint_r($result);?>

Go

O código a seguir demonstra como se conectar ao Amazon DocumentDB usando Go quando o TLSestá desabilitado.

package main

import ( "context" "fmt" "log" "time"

"go.mongodb.org/mongo-driver/bson" "go.mongodb.org/mongo-driver/mongo" "go.mongodb.org/mongo-driver/mongo/options")

const ( // Timeout operations after N seconds connectTimeout = 5 queryTimeout = 30 username = "<sample-user>" password = "<password>" clusterEndpoint = "sample-cluster.node.us-east-1.docdb.amazonaws.com:27017" // Which instances to read from readPreference = "secondaryPreferred" connectionStringTemplate = "mongodb://%s:%s@%s/sample-database?replicaSet=rs0&readpreference=%s")

func main() {

connectionURI := fmt.Sprintf(connectionStringTemplate, username, password, clusterEndpoint, readPreference)

client, err := mongo.NewClient(options.Client().ApplyURI(connectionURI)) if err != nil { log.Fatalf("Failed to create client: %v", err) }

ctx, cancel := context.WithTimeout(context.Background(), connectTimeout*time.Second) defer cancel()

err = client.Connect(ctx) if err != nil { log.Fatalf("Failed to connect to cluster: %v", err) }

// Force a connection to verify our connection string

373


err = client.Ping(ctx, nil) if err != nil { log.Fatalf("Failed to ping cluster: %v", err) }

fmt.Println("Connected to DocumentDB!")

collection := client.Database("sample-database").Collection("sample-collection")


res, err := collection.InsertOne(ctx, bson.M{"name": "pi", "value": 3.14159}) if err != nil { log.Fatalf("Failed to insert document: %v", err) }

id := res.InsertedID log.Printf("Inserted document ID: %s", id)


cur, err := collection.Find(ctx, bson.D{})

if err != nil { log.Fatalf("Failed to run find query: %v", err) } defer cur.Close(ctx)

for cur.Next(ctx) { var result bson.M err := cur.Decode(&result) log.Printf("Returned: %v", result)

if err != nil { log.Fatal(err) } }

if err := cur.Err(); err != nil { log.Fatal(err) }

}

Java

O código a seguir demonstra como se conectar ao Amazon DocumentDB usando Java quando o TLSestá desabilitado.

package com.example.documentdb;

import com.mongodb.MongoClient;import com.mongodb.MongoClientURI;import com.mongodb.ServerAddress;import com.mongodb.MongoException;import com.mongodb.client.MongoCursor;import com.mongodb.client.MongoDatabase;import com.mongodb.client.MongoCollection;import org.bson.Document;

public final class Main {

374


private Main() { } public static void main(String[] args) {

String template = "mongodb://%s:%s@%s/sample-database?replicaSet=rs0&readpreference=%s"; String username = "<sample-user>"; String password = "<password>"; String clusterEndpoint = "sample-cluster.node.us-east-1.docdb.amazonaws.com:27017"; String readPreference = "secondaryPreferred"; String connectionString = String.format(template, username, password, clusterEndpoint, readPreference);

MongoClientURI clientURI = new MongoClientURI(connectionString); MongoClient mongoClient = new MongoClient(clientURI);

MongoDatabase testDB = mongoClient.getDatabase("sample-database"); MongoCollection<Document> numbersCollection = testDB.getCollection("sample-collection");

Document doc = new Document("name", "pi").append("value", 3.14159); numbersCollection.insertOne(doc);

MongoCursor<Document> cursor = numbersCollection.find().iterator(); try { while (cursor.hasNext()) { System.out.println(cursor.next().toJson()); } } finally { cursor.close(); }

}}

C# / .NET

O código a seguir demonstra como se conectar ao Amazon DocumentDB usando C#/.NET quando oTLS está desabilitado.

using System;using System.Text;using System.Linq;using System.Collections.Generic;using System.Security.Cryptography;using System.Security.Cryptography.X509Certificates;using System.Net.Security;using MongoDB.Driver;using MongoDB.Bson;

namespace CSharpSample{ class Program { static void Main(string[] args) { string template = "mongodb://{0}:{1}@{2}/sample-database?&replicaSet=rs0&readpreference={3}"; string username = "<sample-user>"; string password = "<password>"; string clusterEndpoint = "sample-cluster.node.us-east-1.docdb.amazonaws.com:27017"; string readPreference = "secondaryPreferred";

375


string connectionString = String.Format(template, username, password, clusterEndpoint, readPreference); var settings = MongoClientSettings.FromUrl(new MongoUrl(connectionString)); var client = new MongoClient(settings);

var database = client.GetDatabase("sample-database"); var collection = database.GetCollection<BsonDocument>("sample-collection"); var docToInsert = new BsonDocument { { "pi", 3.14159 } }; collection.InsertOne(docToInsert); } }}

mongo shell

O código a seguir demonstra como se conectar ao e consultar o Amazon DocumentDB usando o shellmongo quando TLS está desabilitado.

1. Conecte-se ao Amazon DocumentDB com o shell mongo.

mongo --host mycluster.node.us-east-1.docdb.amazonaws.com:27017 --username <sample-user> --password <password>

2. Insira um único documento.

db.myTestCollection.insertOne({'hello':'Amazon DocumentDB'})

3. Encontre o documento inserido anteriormente.

db.myTestCollection.find({'hello':'Amazon DocumentDB'})

R

O código a seguir demonstra como se conectar ao Amazon DocumentDB com R usando o mongolite(https://jeroen.github.io/mongolite/) quando o TLS está desabilitado.

#Include the mongolite library.library(mongolite) #Create a MongoDB client, open a connection to Amazon DocumentDB as a replica# set and specify the read preference as secondary preferredclient <- mongo(url = "mongodb://sample-user;:[email protected]:27017/sample-database?readPreference=secondaryPreferred&replicaSet=rs0")

##Insert a single documentstr <- c('{"hello" : "Amazon DocumentDB"}')client$insert(str)

##Find the document that was previously writtenclient$find()

Ruby

O código a seguir demonstra como se conectar ao Amazon DocumentDB com o Ruby quando o TLSestá desabilitado.

376

https://jeroen.github.io/mongolite/

Amazon DocumentDB Guia do desenvolvedorUsar fluxos de alterações

require 'mongo'require 'neatjson'require 'json'client_host = 'mongodb://sample-cluster.node.us-east-1.docdb.amazonaws.com:27017'client_options = { database: 'test', replica_set: 'rs0', read: {:secondary_preferred => 1}, user: '<sample-user>', password: '<password>', ssl: true, ssl_verify: true, ssl_ca_cert: <path to 'rds-combined-ca-bundle.pem'>} begin ##Create a MongoDB client, open a connection to Amazon DocumentDB as a ## replica set and specify the read preference as secondary preferred client = Mongo::Client.new(client_host, client_options) ##Insert a single document x = client[:test].insert_one({"hello":"Amazon DocumentDB"}) ##Find the document that was previously written result = client[:test].find() #Print the document result.each do |document| puts JSON.neat_generate(document) endend

#Close the connectionclient.close

Usar fluxos de alterações com o AmazonDocumentDB

O recurso de fluxos de alterações do Amazon DocumentDB (compatível com MongoDB) fornece umasequência ordenada por tempo das alterações que ocorrem nas coleções do cluster. É possível ler eventosde um fluxo de alterações para implementar muitos casos de uso diferentes, incluindo o seguinte:

• Notificação de alterações• Pesquisa de texto completo com o Amazon Elasticsearch Service (Amazon ES)• Análise com o Amazon Redshift

Os aplicativos podem usar os fluxos de alterações para assinar as alterações de dados em coleçõesindividuais. Os eventos dos fluxos de alterações são ordenados à medida que ocorrem no cluster e sãoarmazenados por 3 horas (por padrão) após a gravação do evento.

Tópicos• Operações compatíveis (p. 378)• Faturamento (p. 378)• Limitações (p. 378)

377

Amazon DocumentDB Guia do desenvolvedorOperações compatíveis

• Ativar fluxos de alterações (p. 378)• Exemplo: Usar fluxos de alterações com Python (p. 380)• Pesquisa completa de documentos (p. 381)• Retomar um fluxo de alterações (p. 381)• Modificação da duração da retenção do log do fluxo de alterações (p. 382)

Operações compatíveisO Amazon DocumentDB oferece suporte às seguintes operações para fluxos de alterações:

• Todos os eventos de alteração compatíveis na API db.collection.watch() do MongoDB 3.6.• Pesquisa completa de documentos para atualizações.• Estágios de agregação: $match, $project, $redact e $addFields (no momento, $replaceRoot

não é compatível).• Retomar um fluxo de alterações.

FaturamentoO recurso de fluxos de alterações do Amazon DocumentDB é desativado por padrão e não incorre emcobranças adicionais até ser ativado e usado. É possível usar a operação modifyChangeStreams de APIpara habilitar esse recurso para coleções no cluster. O uso dos fluxos de alterações em um cluster resultaem custos adicionais de IOPS e de armazenamento. Para obter mais informações, consulte Definição depreço do Amazon DocumentDB.

LimitaçõesOs fluxos de alterações têm as seguintes limitações no Amazon DocumentDB:

• Os fluxos de alterações só podem ser abertos de uma conexão com a instância primária de um clusterdo Amazon DocumentDB. No momento, a leitura dos fluxos de alterações em uma instância de réplicanão é compatível. Ao chamar a operação de API watch(), é necessário especificar uma preferência deleitura primary para garantir que todas as leituras sejam direcionadas à instância principal (consulte aseção Exemplo (p. 380)).

• Os eventos gravados em um fluxo de alterações para uma coleção estão disponíveis por até 24 horas(o padrão é 3 horas). Os dados de fluxos de alterações são excluídos após a janela de duração deretenção de log, mesmo que nenhuma nova alteração tenha ocorrido.

• Uma operação de gravação de longa duração em uma coleção como updateMany ou deleteManypode interromper temporariamente a gravação dos eventos dos fluxos de alterações até que ela sejaconcluída.

• O Amazon DocumentDB não oferece suporte ao log de operações do MongoDB (oplog).• Com o Amazon DocumentDB, é necessário ativar explicitamente os fluxos de alterações em

determinada coleção.• Se o tamanho total de um evento de fluxos de alterações (incluindo os dados das alterações e o

documento completo, se solicitado) for maior do que 16 MB, o cliente sofrerá uma falha de leitura nosfluxos de alterações.

Ativar fluxos de alteraçõesÉ possível habilitar os fluxos de alterações do Amazon DocumentDB em todas as coleções em umdeterminado banco de dados ou apenas em coleções específicas. Veja a seguir os exemplos de como

378



Amazon DocumentDB Guia do desenvolvedorAtivar fluxos de alterações

habilitar os fluxos de alterações em diferentes casos de uso com o shell do Mongo. As strings vazias sãotratadas como curingas na especificação de nomes de banco de dados e coleções.

//Enable change streams for the collection "foo" in database "bar"db.adminCommand({modifyChangeStreams: 1, database: "bar", collection: "foo", enable: true});

//Disable change streams on collection "foo" in database "bar"db.adminCommand({modifyChangeStreams: 1, database: "bar", collection: "foo", enable: false});

//Enable change streams for all collections in database "bar"db.adminCommand({modifyChangeStreams: 1, database: "bar", collection: "", enable: true});

//Enable change streams for all collections in all databases in a clusterdb.adminCommand({modifyChangeStreams: 1, database: "", collection: "", enable: true});

Os fluxos de alterações serão ativados em uma coleção se qualquer uma destas opções for verdadeira:

• O banco de dados e a coleção estão explicitamente ativados.• O banco de dados que contém a coleção está ativado.• Todos os bancos de dados estão ativados.

Eliminar uma coleção de um banco de dados não desativará os fluxos de alterações dessa coleção seo banco de dados pai também tiver fluxos de alterações ativados, ou se todos os bancos de dados docluster estiverem ativados. Se uma coleção for criada com o mesmo nome da coleção excluída, os fluxosde alterações serão ativados para essa coleção.

É possível listar todos os fluxos de alterações ativados para o cluster usando o estágio de agregaçãodo pipeline $listChangeStreams. Todas as etapas de agregação compatíveis com o AmazonDocumentDB podem ser usadas no pipeline para processamento adicional. Se uma coleção ativadaanteriormente tiver sido desativada, ela não aparecerá na saída $listChangeStreams.

//List all databases and collections with change streams enabledcursor = new DBCommandCursor(db, db.runCommand( {aggregate: 1, pipeline: [{$listChangeStreams: 1}], cursor:{}}));

//List of all databases and collections with change streams enabled

379

Amazon DocumentDB Guia do desenvolvedorExemplo

{ "database" : "test", "collection" : "foo" } { "database" : "bar", "collection" : "" }{ "database" : "", "collection" : "" }

//Determine if the database “bar” or collection “bar.foo” have change streams enabledcursor = new DBCommandCursor(db, db.runCommand( {aggregate: 1, pipeline: [{$listChangeStreams: 1}, {$match: {$or: [{database: "bar", collection: "foo"}, {database: "bar", collection: ""}, {database: "", collection: ""}]}} ], cursor:{}}));

Exemplo: Usar fluxos de alterações com PythonVeja a seguir um exemplo do uso de um fluxo de alterações do Amazon DocumentDB com Python.

from pymongo import MongoClient, ReadPreference

client = MongoClient("your-cluster-endpoint")db = client['bar'] #While ‘Primary’ is the default read preference, here we give an example of#how to specify the required read preference when reading the change streamscoll = db.get_collection('foo', read_preference=ReadPreference.PRIMARY) #Create a stream objectstream = coll.watch() #Write a new document to the collection to generate a change eventresult = coll.insert_one({'x': 1}) #Read the next change event from the stream (if any)stream.try_next() #Output:{'_id': {'_data': '015daf94f600000002010000000200009025'},'clusterTime': Timestamp(1571788022, 2),'documentKey': {'_id': ObjectId('5daf94f6ea258751778163d6')},'fullDocument': {'_id': ObjectId('5daf94f6ea258751778163d6'), 'x': 1},'ns': {'coll': 'foo', 'db': 'bar'},'operationType': 'insert'}

#A subsequent attempt to read the next change event returns nothing, as there are no new changesstream.try_next() #Generate a new change event by updating a documentresult = coll.update_one({'x': 1}, {'$set': {'x': 2}})

stream.try_next()

#Output:{'_id': {'_data': '015daf99d400000001010000000100009025'},'clusterTime': Timestamp(1571789268, 1),'documentKey': {'_id': ObjectId('5daf9502ea258751778163d7')},'ns': {'coll': 'foo', 'db': 'bar'},'operationType': 'update',

380

Amazon DocumentDB Guia do desenvolvedorPesquisa completa de documentos

'updateDescription': {'removedFields': [], 'updatedFields': {'x': 2}}}

Pesquisa completa de documentosO evento de alteração de atualização não inclui o documento completo, apenas a alteração que foi feita.Se o seu caso de uso exigir o documento completo afetado por uma atualização, você poderá ativar apesquisa completa do documento na abertura do fluxo.

O documento fullDocument de um evento de fluxos de alterações de atualização representa a versãomais atual do documento atualizado no momento em que ele é pesquisado. Se ocorrerem alterações entrea operação de atualização e a pesquisa do fullDocument, o documento fullDocument poderá nãorepresentar o estado dele no momento da atualização.

#Create a stream object with update lookup enabledstream = coll.watch(full_document='updateLookup') #Generate a new change event by updating a documentresult = coll.update_one({'x': 2}, {'$set': {'x': 3}})

stream.try_next()

#Output: {'_id': {'_data': '015daf9b7c00000001010000000100009025'},'clusterTime': Timestamp(1571789692, 1),'documentKey': {'_id': ObjectId('5daf9502ea258751778163d7')},'fullDocument': {'_id': ObjectId('5daf9502ea258751778163d7'), 'x': 3},'ns': {'coll': 'foo', 'db': 'bar'},'operationType': 'update','updateDescription': {'removedFields': [], 'updatedFields': {'x': 3}}}

Retomar um fluxo de alteraçõesÉ possível retomar um fluxo de alterações posteriormente usando um token de retomada, que é igual aocampo _id do último documento de evento de alteração recuperado.

#Generate a new change event by updating a documentresult = coll.update_one({'x': 3}, {'$set': {'x': 4}}) event = stream.try_next() token = event['_id']{'_data': '015daf9c5b00000001010000000100009025'} #Python provides a nice shortcut for getting a stream’s resume tokenstream.resume_token{'_data': '015daf9c5b00000001010000000100009025'} #Generate a new change event by updating a documentresult = coll.update_one({'x': 4}, {'$set': {'x': 5}}) #Generate another change event by inserting a documentresult = coll.insert_one({'y': 5}) #Open a stream starting after the selected resume tokenstream = coll.watch(full_document='updateLookup', resume_after=token)

#Our first change event is the update with the specified _idstream.try_next()

381

Amazon DocumentDB Guia do desenvolvedorModificação da duração da retenção

do log do fluxo de alterações

#Output: {'_id': {'_data': '015daf9d1900000001010000000100009025'},'clusterTime': Timestamp(1571790105, 1),'documentKey': {'_id': ObjectId('5daf94f6ea258751778163d6')},'fullDocument': {'_id': ObjectId('5daf94f6ea258751778163d6'), 'x': 5},'ns': {'coll': 'foo', 'db': 'bar'},'operationType': 'update','updateDescription': {'removedFields': [], 'updatedFields': {'x': 5}}} #Followed by the insertstream.try_next()

#Output:{'_id': {'_data': '015daf9d8800000001010000000100009025'},'clusterTime': Timestamp(1571790216, 1),'documentKey': {'_id': ObjectId('5daf9d88ea258751778163d9')},'fullDocument': {'_id': ObjectId('5daf9d88ea258751778163d9'), 'y': 5},'ns': {'coll': 'foo', 'db': 'bar'},'operationType': 'insert'}

Modificação da duração da retenção do log do fluxode alteraçõesÉ possível modificar a duração da retenção do log de fluxo de alterações para valores entre 1 hora e 24horas usando o Console de gerenciamento da AWS ou a AWS CLI.


Como modificar a duração da retenção do log do fluxo de alterações



Tip


3. No painel Parameter groups (Grupos de parâmetros), escolha o grupo de parâmetros de clusterassociado ao cluster. Para identificar o grupo de parâmetros de cluster associado ao cluster, consulteDetermining an Amazon DocumentDB Cluster's Parameter Group (p. 291).

4. A página resultante mostra os parâmetros e os detalhes correspondentes para seu grupo deparâmetros do cluster. Selecione o parâmetro change_stream_log_retention_duration.

5. No canto superior direito da página, selecione Edit (Editar) para alterar o valor do parâmetro. Oparâmetro change_stream_log_retention_duration pode ser modificado para ficar entre 1 e24 horas.

6. Faça a alteração e escolha Modify cluster parameter (Modificar parâmetro de cluster) para salvar asalterações. Para descartar as alterações, escolha Cancel (Cancelar).

Usar a AWS CLI

Para modificar o parâmetro change_stream_log_retention_duration de um grupo de parâmetrosde cluster, use a operação modify-db-cluster-parameter-group com os parâmetros a seguir:

382


Amazon DocumentDB Guia do desenvolvedorModificação da duração da retenção

do log do fluxo de alterações

• --db-cluster-parameter-group-name — obrigatório. O nome do parameter group de cluster quevocê está modificando. Para identificar o grupo de parâmetros de cluster associado ao cluster, consulteDetermining an Amazon DocumentDB Cluster's Parameter Group (p. 291).

• --parameters — obrigatório. O parâmetro que você está modificando. Cada entrada de parâmetrodeve incluir o seguinte:• ParameterName — o nome do parâmetro que você está modificando. Neste caso, échange_stream_log_retention_duration

• ParameterValue — o novo valor para esse parâmetro.• ApplyMethod — como você deseja aplicar as alterações nesse parâmetro. Os valores permitidos sãoimmediate e pending-reboot.

Note

Os parâmetros com ApplyType de static devem ter um ApplyMethod de pending-reboot.

1. Para alterar os valores do parâmetro change_stream_log_retention_duration, executeo seguinte comando e substitua parameter-value pelo valor para o qual deseja modificar oparâmetro.


aws docdb modify-db-cluster-parameter-group \ --db-cluster-parameter-group-name sample-parameter-group \ --parameters "ParameterName=change_stream_log_retention_duration,ParameterValue=<parameter-value>,ApplyMethod=immediate"

Para Windows:

aws docdb modify-db-cluster-parameter-group ^ --db-cluster-parameter-group-name sample-parameter-group ^ --parameters "ParameterName=change_stream_log_retention_duration,ParameterValue=<parameter-value>,ApplyMethod=immediate"


{ "DBClusterParameterGroupName": "sample-parameter-group"}

2. Aguarde pelo menos 5 minutos.3. Liste os valores de parâmetro de sample-parameter-group para garantir que suas alterações

foram feitas.



Para Windows:383

Amazon DocumentDB Guia do desenvolvedorConectar-se como um conjunto de réplicas



{ "Parameters": [ { "ParameterName": "audit_logs", "ParameterValue": "disabled", "Description": "Enables auditing on cluster.", "Source": "system", "ApplyType": "dynamic", "DataType": "string", "AllowedValues": "enabled,disabled", "IsModifiable": true, "ApplyMethod": "pending-reboot" }, { "ParameterName": "change_stream_log_retention_duration", "ParameterValue": "12345", "Description": "Duration of time in seconds that the change stream log is retained and can be consumed.", "Source": "user", "ApplyType": "dynamic", "DataType": "integer", "AllowedValues": "3600-86400", "IsModifiable": true, "ApplyMethod": "immediate" } ]}

Conectar-se ao Amazon DocumentDB como umconjunto de réplicas

Quando você estiver desenvolvendo no Amazon DocumentDB (compatível com MongoDB),recomendamos que você se conecte ao cluster como um conjunto de réplicas e distribua leituras parainstâncias de réplica usando os recursos internos de preferência de leitura de seu driver. Esta secçãoaprofunda o que significa e descreve como se pode ligar ao seu Amazon DocumentDB como um conjuntode réplica utilizando o SDK for Python como exemplo.

Amazon DocumentDBO tem três endpoints que podem ser usados para se conectar ao cluster:

• Endpoint do cluster• Endpoint de leitor• Endpoints da instância

Na maioria dos casos, quando você se conecta ao Amazon DocumentDB, recomendamos o uso doendpoint do cluster. Isso é um CNAME que aponta para a instância principal no cluster, conforme mostradono diagrama a seguir.

384

Amazon DocumentDB Guia do desenvolvedorConectar-se como um conjunto de réplicas

Ao usar um túnel SSH, recomendamos que você se conecte ao cluster usando o endpoint do cluster enão tente se conectar no modo de conjunto de réplicas (ou seja, especificando replicaSet=rs0 em suastring de conexão), pois isso resultará em um erro.

Note

Para obter mais informações sobre os endpoints do Amazon DocumentDB, consulte AmazonDocumentDBEndpoints do (p. 8).

Usando o endpoint do cluster, é possível se conectar ao cluster no modo de conjunto de réplicas. Depois,você poderá usar os recursos integrados do driver de preferência de leitura. No exemplo a seguir,especificar /?replicaSet=rs0 significa para o SDK que você deseja se conectar como um conjunto deréplicas. Se você omitir /?replicaSet=rs0', o cliente roteará todas as solicitações para o endpoint docluster, ou seja, sua instância principal.

## Create a MongoDB client, open a connection to Amazon DocumentDB as a ## replica set and specify the read preference as secondary preferred client = pymongo.MongoClient('mongodb://<user-name>:<password>@mycluster.node.us-east-1.docdb.amazonaws.com:27017/?replicaSet=rs0')

A vantagem de se conectar como um conjunto de réplicas é que isso permite que o SDK descubra atopografia do cluster automaticamente, incluindo quando as instâncias são adicionadas ou removidas docluster. Você poderá usar seu cluster de forma mais eficiente roteando solicitações de leitura para suasinstâncias de réplica.

Ao se conectar como um conjunto de réplicas, é possível especificar a readPreference para a conexão.Se você especificar uma preferência de leitura de secondaryPreferred, o cliente roteará as consultasde leitura para suas réplicas e as consultas de gravação para sua instância principal (como no diagrama aseguir). Esse é um uso melhor dos recursos do cluster. Para obter mais informações, consulte Opções depreferência de leitura (p. 12).

## Create a MongoDB client, open a connection to Amazon DocumentDB as a ## replica set and specify the read preference as secondary preferredclient = pymongo.MongoClient('mongodb://<user-name>:<password>@mycluster.node.us-east-1.docdb.amazonaws.com:27017/?replicaSet=rs0&readPreference=secondaryPreferred')

385

Amazon DocumentDB Guia do desenvolvedorUsar conexões de cluster

As leituras de réplicas do Amazon DocumentDB são eventualmente consistentes. Elas retornam osdados na mesma ordem em que foram gravados na instância principal, e geralmente há menos de 50ms de tempo de atraso de replicação. Pode monitorizar a réplica da réplica para o seu grupo utilizando oAmazon CloudWatch métricas DBInstanceReplicaLag e DBClusterReplicaLagMaximum. Para maisinformações, consulte Monitoramento do Amazon DocumentDB com o CloudWatch (p. 341).

Diferentemente da arquitetura de banco de dados monolítica tradicional, o Amazon DocumentDB separa oarmazenamento e a computação. Considerando essa arquitetura moderna, recomendamos que você façaa escalabilidade de leitura nas instâncias de réplica. As leituras nas instâncias de réplica não bloqueiamas gravações que são replicadas a partir da instância principal. É possível adicionar até 15 instâncias deréplica de leitura em um cluster e expandir para milhões de leituras por segundo.

O principal benefício de se conectar como um conjunto de réplicas e distribuir leituras para réplicas é queele aumenta os recursos gerais em seu cluster que estão disponíveis para trabalhar em seu aplicativo.Como uma melhor prática, recomendamos conectar-se como um conjunto de réplicas. Além disso,recomendamos que isso seja feito mais comumente nos seguintes cenários:

• Você está usando quase 100% de CPU na principal.• A proporção de acertos do cache em buffer é próxima de zero.• Você atinge os limites de conexão ou de cursor para uma instância individual.

Expandir o tamanho de uma instância de cluster é uma opção e, em alguns casos, essa pode ser a melhormaneira de escalar o cluster. Mas você também deve considerar como usar melhor as réplicas que játem em seu cluster. Isso permite aumentar a escala sem o aumento do custo de usar um tipo de instânciamaior. Recomendamos também que monitorize e alerte estes limites (ou seja, CPUUtilization,DatabaseConnections, e BufferCacheHitRatio) utilizando CloudWatch para que saiba quando umrecurso está a ser fortemente utilizado.

Para obter mais informações, consulte os seguintes tópicos:

• Melhores práticas do Amazon DocumentDB (p. 53)• Cotas e limites do Amazon DocumentDB (p. 406)

Usar conexões de clusterConsidere o cenário de uso de todas as conexões em seu cluster. Por exemplo, uma instânciar5.2xlarge tem um limite de 4.500 conexões (e 450 cursores abertos). Se você criar um cluster doAmazon DocumentDB de três instâncias e se conectar somente à instância principal usando o endpoint

386

Amazon DocumentDB Guia do desenvolvedorVários grupos de conexões

do cluster, os limites do cluster para conexões abertas e cursores serão 4.500 e 450, respectivamente.Talvez você atinja esses limites se estiver criando aplicativos que usem muitos operadores que sejamconfigurados em contêineres. Os contêineres abrem várias conexões de uma só vez e saturam o cluster.

Em vez disso, é possível se conectar ao cluster do Amazon DocumentDB como um conjunto de réplicase distribuir suas leituras para as instâncias de réplica. Depois, é possível efetivamente triplicar o númerode conexões e cursores disponíveis no cluster para 13.500 e 1.350, respectivamente. Adicionar maisinstâncias ao cluster só aumentará o número de conexões e cursores para cargas de trabalho de leitura.Se for necessário aumentar o número de conexões para gravações em seu cluster, recomendamosaumentar o tamanho da instância.

Note

O número de ligações para large, xlarge, e 2xlarge os casos aumentam com o tamanhoda instância até 4500. O número máximo de conexões por instância para instâncias 4xlargeou maiores é 4.500. Para obter mais informações sobre limites por tipos de instância, consulteLimites de instâncias (p. 410).

Normalmente, não recomendamos que ligue ao seu grupo utilizando a preferência de leitura desecondary. Isto porque se não existirem ocorrências de réplica no seu grupo, as leituras falharam. Porexemplo, suponha que você tenha um cluster do Amazon DocumentDB de duas instâncias com umaprincipal e uma de réplica. Se a réplica tiver um problema, leia pedidos de uma ligação de ligação definidacomo secondary falhou. A vantagem de secondaryPreferred é que, se o cliente não conseguirencontrar uma instância de réplica adequada à qual se conectar, ele voltará para a principal para leituras.

Vários grupos de conexõesEm alguns cenários, as leituras em um aplicativo devem ter consistência de leitura após gravação, quepode ser atendida somente a partir da instância principal no Amazon DocumentDB. Nesses cenários, vocêpode criar dois grupos de conexão de cliente: um para gravações e outro para leituras que precisam deconsistência de leitura após gravação. Para fazer isso, seu código deve ser semelhante ao seguinte:

## Create a MongoDB client, ## open a connection to Amazon DocumentDB as a replica set and specify the readPreference as primaryclientPrimary = pymongo.MongoClient('mongodb://<user-name>:<password>@mycluster.node.us-east-1.docdb.amazonaws.com:27017/?replicaSet=rs0&readPreference=primary') ## Create a MongoDB client, ## open a connection to Amazon DocumentDB as a replica set and specify the readPreference as secondaryPreferredsecondaryPreferred = pymongo.MongoClient('mongodb://<user-name>:<password>@mycluster.node.us-east-1.docdb.amazonaws.com:27017/?replicaSet=rs0&readPreference=secondaryPreferred')

Outra opção é criar um único grupo de conexões e substituir a preferência de leitura para uma determinadacoleção.

##Specify the collection and set the read preference level for that collectioncol = db.review.with_options(read_preference=ReadPreference.SECONDARY_PREFERRED)

SummaryPara usar melhor os recursos em seu cluster, recomendamos que você se conecte ao cluster usando omodo de conjunto de réplicas. Se for adequado para seu aplicativo, você poderá fazer a escalabilidade deleitura de seu aplicativo distribuindo suas leituras para as instâncias de réplica.

387

Amazon DocumentDB Guia do desenvolvedorConexão de fora de uma Amazon VPC

Conexão com um cluster do Amazon DocumentDBde fora de uma Amazon VPC

Os clusters do Amazon DocumentDB (compatível com MongoDB) são implantados em uma AmazonVirtual Private Cloud (Amazon VPC). Eles podem ser acessados diretamente por instâncias do AmazonEC2 ou outros serviços da AWS que são implantados na mesma Amazon VPC. Além disso, o AmazonDocumentDB pode ser acessado por instâncias do EC2 ou outros serviços da AWS em VPCs diferentes namesma ou em outras regiões da AWS por meio do emparelhamento de VPC.

No entanto, suponha que seu caso de uso exija que você (ou seu aplicativo) acesse seus recursosdo Amazon DocumentDB de fora da VPC do cluster. Nesse caso, você pode usar o tunelamentoSSH (também conhecido como encaminhamento de porta) para acessar seus recursos do AmazonDocumentDB.

Não faz parte da finalidade deste tópico abordar detalhadamente o tunelamento SSH. Para obter maisinformações sobre o tunelamento SSH, consulte o seguinte:

• Túnel de SSH• Exemplo de encaminhamento de porta SSH, especificamente a seção Encaminhamento local

Para criar um túnel SSH, é necessário uma instância do Amazon EC2 em execução na mesma AmazonVPC que o seu cluster do Amazon DocumentDB. É possível usar uma instância do EC2 existente namesma VPC que seu cluster ou criar uma instância. Para obter mais informações, consulte o tópicoapropriado para seu sistema operacional:

• Conceitos básicos das instâncias do Linux do Amazon EC2• Conceitos básicos das instâncias do Windows do Amazon EC2

Normalmente, você pode se conectar a uma instância do EC2 com o seguinte comando:

> ssh -i "ec2Access.pem" [email protected]

Se esse for o caso, será possível configurar um túnel SSH para o cluster sample-cluster.node.us-east-1.docdb.amazonaws.com do Amazon DocumentDB executando o comando a seguir no seucomputador local. O sinalizador -L é usado para encaminhar uma porta local. Ao usar um túnel SSH,recomendamos que você se conecte ao cluster usando o endpoint do cluster e não tente se conectar nomodo de conjunto de réplicas (ou seja, especificando replicaSet=rs0 em sua string de conexão), poisisso resultará em um erro.

> ssh -i "ec2Access.pem" -L 27017:sample-cluster.node.us-east-1.docdb.amazonaws.com:27017 [email protected] -N

Depois que o túnel SSH for criado, todos os comandos que você emitir para localhost:27017 serãoencaminhados para o cluster do Amazon DocumentDB sample-cluster em execução na AmazonVPC. Se o Transport Layer Security (TLS) estiver ativado no cluster do Amazon DocumentDB, seránecessário fazer download da chave pública para o Amazon DocumentDB em https://s3.amazonaws.com/rds-downloads/rds-combined-ca-bundle.pem. A operação a seguir faz download de um arquivo chamadords-combined-ca-bundle.pem:

> wget https://s3.amazonaws.com/rds-downloads/rds-combined-ca-bundle.pem

388

https://www.ssh.com/ssh/tunneling/

https://www.ssh.com/ssh/tunneling/example

https://www.ssh.com/ssh/tunneling/example#sec-Local-Forwarding

https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/EC2_GetStarted.html

https://docs.aws.amazon.com/AWSEC2/latest/WindowsGuide/EC2_GetStarted.html



Amazon DocumentDB Guia do desenvolvedorLigar utilizando Robo 3T

Note

O TLS está habilitado por padrão para todos os novos clusters do Amazon DocumentDB. Noentanto, é possível desabilitá-lo. Para obter mais informações, consulte Gerenciamento deconfigurações de TLS do cluster do Amazon DocumentDB (p. 122).

Para conectar-se ao seu cluster do Amazon DocumentDB de fora da Amazon VPC, use o comando aseguir.

> mongo --sslAllowInvalidHostnames --ssl --sslCAFile rds-combined-ca-bundle.pem --username <yourUsername> --password <yourPassword>

Ligar a um Amazon DocumentDB Cluster de Robo3T

Robo 3T é uma ferramenta gráfica de interface de utilizador, leve, aberta, de código aberto, centrada nashell, para gerir cargas de trabalho mongodb. Robo 3T dá-lhe a capacidade de criar bases de dados,recolhas, adicionar utilizadores, documentos, executar consultas únicas com a conclusão automática evisualizar os resultados de uma interface GUI.

Prerequisites• Se ainda não tiver um Amazon DocumentDB grupo em execução Amazon EC2, siga as instruções sobre

como Ligue-se a Amazon EC2.• Se não tem Robo 3T, transferir e instalar.

Ligar com Robo 3T1. Abra o Robo 3T e escolha Criar.

2. No Ligação , no Endereço , introduza as informações do ponto de avaliação do cluster.

389


https://robomongo.org/download

Amazon DocumentDB Guia do desenvolvedorLigar com Robo 3T

Note

Não consegue encontrar o seu ponto final de agrupamento? Basta seguir os passos aqui.3. No Autenticação , assinale a caixa para Realizar autenticação. Agora introduza as informações de

autenticação do seu grupo. Certifique-se de que utiliza um nome de base de dados personalizadocomo test. Utilizar admin (predefinição) não funciona para Amazon DocumentDB para clusters sembases de dados. Depois de criar a sua primeira base de dados, pode modificar a sua ligação a utilizaradmin.

4. No SSH , assinale a caixa para Utilizar túnel SSH, e adicione o endereço SSH, nome de utilizador echave/palavra-passe privada da sua instância EC2. O endereço SSH é o DNS público da sua instânciaEC2.

5. Em Método de privilégio SSH, escolha um dos métodos de autenticação.

• If you chose Chave privada, then select the “…” button to open up the file finder and select the .pemfile for your EC2 instance.

390

https://docs.aws.amazon.com/documentdb/latest/developerguide/db-instance-endpoint-find.html

Amazon DocumentDB Guia do desenvolvedorLigar com Robo 3T

• If you chose Senha, you must enter the SSH address, username and private key for your AWS EC2instance. You can find this on the AWS EC2 console.

Note

Dica Se estiver na máquina cliente Linux/macos, poderá ter de alterar as permissões da suachave privada utilizando o seguinte comando:> chmod 400 /fullpathtoyourpemfile/<yourkey>.pem

6. Agora escolha o SSL e adicione o certificado de documentdb da Amazon.

Note

Não tem o certificado? Pode descarregá-lo com o seguinte comando: wget https://s3.amazonaws.com/rds-downloads/rds-combined-ca-bundle.pem

7. Também no SSL , assinale a caixa para Opções avançadas. No menu pendente para Nomes denomes inválidos, selecione Permitido.

8. Teste a ligação escolhendo o Teste botão.

391

Amazon DocumentDB Guia do desenvolvedorLigar utilizando o Studio 3T

9. Um Diagnóstico deve aparecer com os resultados do teste. Se tudo estiver verde, feche a caixa.

10. Agora escolha Guardar.11. Agora selecione o seu grupo e escolha Ligar.

Ligar a um Amazon DocumentDB Cluster do Studio3T

Estúdio 3T é uma GUI e uma IDE populares para programadores e engenheiros de dados que trabalhamcom mongodb. Oferece várias capacidades poderosas de vistas de Árvore, Tabela e JSON dos seusdados, importação/exportação fácil em CSV, JSON, SQL e BSON/mongojar, opção de pesquisa flexível,uma interface de utilizador de arrastar e largar visual, uma concha mongo incorporada com preenchimentoautomático, um editor de pipeline de agregação e suporte de consulta SQL.

Prerequisites• Se ainda não tiver um Amazon DocumentDB grupo em execução Amazon EC2, siga as instruções sobre

como Ligue-se a Amazon EC2.• Se não tem Studio 3T, transferir e instalar.

Ligar ao Studio 3T1. Escolher Ligar no canto superior esquerdo da barra de ferramentas.

392

https://studio3t.com/


https://studio3t.org/download

Amazon DocumentDB Guia do desenvolvedorLigar ao Studio 3T

2. Escolher Nova ligação no canto superior esquerdo da barra de ferramentas.

3. No Servidor , no Servidor , introduza as informações do ponto de avaliação do cluster.

393


Note

Não consegue encontrar o seu ponto final de agrupamento? Basta seguir os passos aqui.4. Escolha o Autenticação e selecione Legado no menu pendente para Modo de autenticação.

5. Introduza o seu nome de utilizador e credenciais no Nome de utilizador e Palavra-passe.6. Escolha o SSL e assinale a caixa Utilizar protocolo SSL para ligar.

394

https://docs.aws.amazon.com/documentdb/latest/developerguide/db-instance-endpoint-find.html


7. Escolher Utilizar o próprio ficheiro da raiz CA. Depois adicione o Amazon DocumentDB (pode ignorareste passo se SSL estiver desativado no seu grupo de documentdb). Assinale a caixa para permitirnomes de nomes inválidos.

395


Note

Não tem o certificado? Pode descarregá-lo com o seguinte comando:wget https://s3.amazonaws.com/rds-downloads/rds-combined-ca-bundle.pem

8. Se estiver a ligar a uma máquina cliente fora do Amazon VPC, tem de criar um túnel SSH. Irá fazê-lono SSH separador.

a. Assinale a caixa para Utilizar túnel SSH e introduzir o endereço SSH no Endereço SSH campo.Este é o seu exemplo DNS Público (IPV4). Pode obter este URL do seu Amazon EC2 Consola degestão.

b. Introduza o seu nome de utilizador. Este é o nome de utilizador do seu Amazon EC2 instânciac. Para Modo de emissão SSH, selecione Chave privada. No Chave privada , escolha o ícone do

localizador de ficheiros para localizar e escolha a tecla Privada do seu Amazon EC2 instância.Este é o ficheiro.pem (par de teclas) que guardou ao criar a sua instância em Amazon EC2Consola.

d. Se estiver na máquina cliente Linux/macos, poderá ter de alterar as permissões da sua chaveprivada utilizando o seguinte comando:

chmod 400 /fullPathToYourPemFile/<yourKey>.pem

Note

Isto Amazon EC2 a instância deve estar no mesmo Amazon VPC e grupo de segurançacomo o seu grupo de documentários. Pode obter o endereço SSH, nome de utilizador echave privada do seu Amazon EC2 Consola de gestão.

9. Agora, teste a sua configuração escolhendo o Ligação de teste botão.

396





10. Uma janela de diagnóstico deve carregar uma barra verde para indicar que o teste foi bem sucedido.Agora escolha OK para fechar a janela de diagnóstico.

11. Escolher Guardar para guardar a sua ligação para utilização futura.

397

Amazon DocumentDB Guia do desenvolvedorConexão usando Amazon EC2

12. Agora selecione o seu grupo e escolha Ligar.

Parabéns! Está agora ligado com sucesso ao seu Amazon DocumentDB através do Studio 3T.

Conexão usando Amazon EC2Esta secção descreve como iniciar um Amazon DocumentDB (compatível com MongoDB) cluster usandoAmazon EC2 e interagir com o mesmo, usando o revestimento mongo. O vídeo abaixo demonstra ospassos neste guia.

PrerequisitesAntes de criar o primeiro cluster do Amazon DocumentDB, você deve fazer o seguinte:

398

Amazon DocumentDB Guia do desenvolvedorEtapa 1 Criar um Amazon EC2 Instância

Criar um Amazon Web Services (AWS) conta

Antes de começar a utilizar Amazon DocumentDB, tem de ter um Amazon Web Services (AWS) conta.A conta da AWS é gratuita. Você paga apenas pelos serviços e recursos usados.



1. Abra https://aws.amazon.com/ e escolha Create an AWS Account.2. Siga as instruções online.

Configurar o necessário AWS Identity and Access Management (IAM) permissões.

O acesso para gerenciar recursos do Amazon DocumentDB como clusters, instâncias e grupos deparâmetros de cluster exige credenciais que a AWS pode usar para autenticar suas solicitações. Paraobter mais informações, consulte Identity and Access Management no Amazon DocumentDB (p. 129).

1. Na barra de pesquisa da consola de gestão AWS, digite IAM e selecione LI no menu pendenteque aparece.

2. Quando estiver no IAM consola, seleccionar Utilizadores no painel de navegação.3. Selecione o seu nome de utilizador.4. Clique no botão Adicionar permissões.5. Selecione Attach existing policies directly (Anexar políticas existentes diretamente).6. Tipo AmazonDocDBFullAccess na barra de pesquisa e selecione-a assim que aparecer nos

resultados da pesquisa.7. Clique no botão azul na parte inferior que diz Seguinte: Review (Revisar)8. Clique no botão azul na parte inferior que diz Adicionar permissões.

Criar um Amazon Virtual Private Cloud (Amazon VPC)

Dependendo da região AWS em que se encontra, pode ou não ter um VPC predefinido já criado. Senão tiver um VPC predefinido, conclua o passo 1 do Como começar com Amazon VPC no Guia dousuário da Amazon VPC. Isto demorará menos de cinco minutos.

Etapa 1 Criar um Amazon EC2 InstânciaNeste passo, irá criar um Amazon EC2 na mesma região e Amazon VPC que irá utilizar posteriormentepara fornecer o seu Amazon DocumentDB grupo.

1. No Amazon EC2 consola, escolher Instância de lançamento.2. Localizar Amazon Linux 2 AMI e escolha Selecionar.3. Escolha o tipo de instância t3.micro.4. Escolher Revisão e lançamento, que lhe permitirá saltar para a consola Passo 7: Lançamento da

instância de revisão página.5. Em Grupos de segurança, escolha Editar grupos de segurança.6. Isto será predefinido para Criar um novo grupo de segurança. No Nome do grupo de segurança

campo, escrever demoEC2.7. Alterar tipo para SSH. Isto irá definir automaticamente o intervalo da porta para 22.8. Selecione o menu pendente para Fonte e escolha O meu IP.

399


https://docs.aws.amazon.com/vpc/latest/userguide/vpc-getting-started.html

Amazon DocumentDB Guia do desenvolvedorEtapa 2. Crie um grupo de segurança

Note

Só pode aceder ao grupo de segurança demoec2 a partir do seu endereço IP atual. Se o seuendereço IP mudar, tem de atualizar o grupo de segurança.

9. Agora escolha Revisão e lançamento. Deve agora ver o grupo de segurança demoec2 no Grupos desegurança secção.

10. Verifique a informação e escolha Iniciar.11. Surgirá uma janela com o título Seleccione um par de teclas existente ou crie um novo par de teclas.

Tem de fornecer um Amazon EC2 par de chaves.

Se tiver um Amazon EC2 par de chaves:

a. Selecione um par de teclas, escolha o seu par de chaves da lista.b. Já tem de ter o ficheiro de chave privada (ficheiro.pem) disponível para iniciar sessão no seu

Amazon EC2 instância.

Se não tiver um Amazon EC2 par de chaves:

a. Selecione Criar um novo par de chaves.b. Escreva um nome para a barra de teclas no campo Nome do par chave.c. Descarregue o ficheiro de chave privada (ficheiro.pem). Você precisará deste arquivo mais tarde

quando fizer login na instância do Amazon EC2.12. Selecione Launch Instances.

Etapa 2. Crie um grupo de segurançaIrá agora criar um novo grupo de segurança na sua predefinição Amazon VPC. O grupo de segurançademoDocDB permite-lhe ligar-se ao seu Amazon DocumentDB na porta 27017 (a porta predefinida paraAmazon DocumentDB) a partir do seu Amazon EC2 instância.

1. No Amazon EC2 consola, sob Rede e segurança, escolha Grupos de segurança.2. Escolha Create security group (Criar grupo de segurança).3. Em Security group name (Nome do grupo de segurança), insira demoDocDB.4. Para VPC, aceite a utilização do seu VPC predefinido.5. Em Description (Descrição), insira uma descrição.6. Na seção Regras de entrada, escolha Adicionar regra.7. Para Tipo, escolha Regra TCP personalizada.8. Para Intervalo de porta, enter 27017.9. Para Destino, escolha Personalizado. No campo ao lado, procure o grupo de segurança que acabou

de fazer demoEC2. Pode ter de atualizar o seu navegador para a consola da Amazon EC2 parapreencher automaticamente o demoEC2 nome da fonte.

10. Aceitar todas as outras predefinições e escolher Criar grupo de segurança.

Etapa 3 Criar um Amazon DocumentDB ClusterEnquanto o Amazon EC2 a instância está a ser provisionada, irá criar o seu Amazon DocumentDB grupo.

1. Navegue até o console Amazon DocumentDB.2. Escolher Clusters no painel de navegação.

400

Amazon DocumentDB Guia do desenvolvedorEtapa 4. Ligue-se ao seu Amazon EC2 instância

3. Selecione Create (Criar).4. Está agora na Criar Amazon DocumentDB cluster página. Para Número de ocorrências, escolha 1.

Isto irá minimizar o custo. Deixe outras definições na sua predefinição.5. No Autenticação , introduza um nome de utilizador e palavra-passe. Importante Irá precisar deste

nome de utilizador e palavra-passe para autenticar o seu grupo num passo posterior.6. Ligar Mostrar definições avançadas.7. No Definições de rede , para Amazon VPC grupos de segurança, escolha demodocdb.8. Selecione Create cluster (Criar cluster).

Etapa 4. Ligue-se ao seu Amazon EC2 instânciaPara instalar o revestimento de mongo, primeiro tem de se ligar ao seu Amazon EC2 instância. Instalaro revestimento mongo permite-lhe estabelecer ligação e consultar o seu Amazon DocumentDB grupo.Execute as etapas a seguir:

1. No Amazon EC2 consola, escolha a instância criada. Se o estado da instância estiver a ser executado,pode agora ligar-se à mesma e instalar o invólucro de mongo.

2. Escolher Ligar.3. Verá três opções para o seu método de ligação:

• Um cliente SSH autónomo• Session Manager• Amazon EC2 Instância Connect (ligação SSH baseada no navegador)

Note

Se o seu endereço IP mudar depois de iniciar esta demonstração, ou se regressar ao seuambiente mais tarde, tem de atualizar o seu demoEC2 regra de entrada do grupo de segurançapara permitir o tráfego de entrada do seu novo endereço API.

EC2 Instance Connect

Para ligar ao seu Amazon EC2 com uma ligação SSH baseada no browser, complete os seguintes passos:

1. No Ligue-se à sua instância , para Método de ligação, selecione Connect de instância CE2 (ligaçãoSSH baseada no navegador). O nome de utilizador será predefinido para ec2-user.

2. Escolher Ligar. Abre-se uma linha de comandos, a partir da qual pode executar comandos. Prossigapara a próxima etapa.

Cliente SSH individual

Para ligar ao método de ligação predefinido de um cliente SSH autónomo, realize os seguintes passos:

1. Abra um cliente SSH. Saiba como ligar utilizando a massa aqui.2. Localize o seu ficheiro de chave privada que descarregou anteriormente.3. Na consola de gestão AWS, navegue para EC2 e selecione a sua instância. Escolher Ligar.4. Uma janela pop-up chamada Ligue-se à sua instância irá aparecer. Selecionar Um cliente SSH

autónomo.5. No Exemplo , copie a cadeia de ligação e introduza-a no seu cliente SSH. Prima Enter.6. O comando deve devolver informações no seu último início de sessão (se aplicável), bem como

Amazon Linux 2 AMI.

401

Amazon DocumentDB Guia do desenvolvedorEtapa 5. Instale o shell do mongo

Etapa 5. Instale o shell do mongoAgora, pode instalar o revestimento mongo, que é um utilitário de linha de comandos que utiliza para ligare consultar o seu Amazon DocumentDB grupo. Siga as instruções abaixo para instalar o revestimentomongo para o seu sistema operativo.

No Amazon Linux

Para instalar o shell do Mongo no Amazon Linux

1. Crie o ficheiro do repositório. Na linha de comando da sua instância EC2, execute o comandoseguinte:

echo -e "[mongodb-org-3.6] \nname=MongoDB Repository\nbaseurl=https://repo.mongodb.org/yum/amazon/2013.03/mongodb-org/3.6/x86_64/\ngpgcheck=1 \nenabled=1 \ngpgkey=https://www.mongodb.org/static/pgp/server-3.6.asc" | sudo tee /etc/yum.repos.d/mongodb-org-3.6.repo

2. Quando terminar, instale o invólucro de mongo executando o seguinte comando:

sudo yum install -y mongodb-org-shell

No Ubuntu 18.04

Para instalar o shell do Mongo no Ubuntu 18.04

1. Importe a chave pública que será usada pelo sistema de gerenciamento de pacotes.

sudo apt-key adv --keyserver hkp://keyserver.ubuntu.com:80 --recv 2930ADAE8CAF5059EE73BB4B58712A2291FA4AD5

2. Crie o arquivo de lista /etc/apt/sources.list.d/mongodb-org-3.6.list para o MongoDBusando o comando apropriado para a versão do Ubuntu.

Ubuntu 18.04

echo "deb [ arch=amd64,arm64 ] https://repo.mongodb.org/apt/ubuntu xenial/mongodb-org/3.6 multiverse" | sudo tee /etc/apt/sources.list.d/mongodb-org-3.6.list

Note

O comando acima instalará o shell do Mongo 3.6 para Bionic e Xenial.3. Recarregue o banco de dados do pacote local usando o seguinte comando:

sudo apt-get update

4. Instalar o shell do MongoDB

sudo apt-get install -y mongodb-org-shell

Para obter informações sobre a instalação de versões anteriores de mongodb no seu sistema Ubuntu,consulte Instalar a Edição da Comunidade Mongodb em Ubuntu.

402

https://docs.mongodb.com/v3.6/tutorial/install-mongodb-on-ubuntu/

Amazon DocumentDB Guia do desenvolvedorEtapa 6. Gerir Amazon DocumentDB SLT

Em outros sistemas operacionais

Para instalar o invólucro mongo noutros sistemas operativos, consulte Instalar a edição da comunidadeMongodb na documentação da mongodb.

Etapa 6. Gerir Amazon DocumentDB SLTTransfira o certificado CA para a Amazon documentdb com o seguinte código: wget https://s3.amazonaws.com/rds-downloads/rds-combined-ca-bundle.pem

Note

A Segurança da Camada de Transporte (TLS) está activada por predefinição para qualquer novoAmazon DocumentDB grupos. Para mais informações, consulte Gerir definições de TLS do grupode documentdb da Amazon.

Etapa 7. Ligue-se ao seu Amazon DocumentDBcluster1. Na consola da Amazon Document DB, em Clusters, localize o seu grupo.2. Escolha o grupo que criou.3. 3. Copie a cadeia de ligação fornecida. Certifique-se de que tem o nome de utilizador correcto na

cadeia. Omitir <insertYourPassword> para que lhe seja pedida a palavra-passe pela concha domongo quando ligar. A sua cadeia de ligação deve ter um aspecto semelhante ao seguinte:

mongo --ssl host docdb-2020-02-08-14-15-11.cluster.region.docdb.amazonaws.com:27107 --sslCAFile rds-combined-ca-bundle.pem --username demoUser --password

4. Prima Enter. Ser-lhe-á pedido que introduza a sua palavra-passe. Insira a senha.5. Quando introduzir a sua palavra-passe e ver o rs0:PRIMARY> nota, está ligado com sucesso ao seu

grupo de documentários Amazon.

Tem problemas em estabelecer a ligação? Ver Resolução de problemas Amazon DocumentDB.

Etapa 8 Inserir e consultar dadosAgora que está ligado ao seu grupo, pode executar algumas questões para se familiarizar com a utilizaçãode uma base de dados de documentos.

1. Para inserir um único documento, introduza o seguinte:

db.collection.insert({"hello":"DocumentDB"})



3. Pode ler o documento que escreveu com o findOne() (porque apenas devolve um únicodocumento). Introduza o seguinte:

db.collection.findOne()


403

https://docs.mongodb.com/v3.6/administration/install-community/

https://docs.mongodb.com/v3.6/administration/install-community/




Amazon DocumentDB Guia do desenvolvedorEtapa 8 Inserir e consultar dados

{ "_id" : ObjectId("5e401fe56056fda7321fbd67"), "hello" : "DocumentDB" }

5. Para realizar mais algumas perguntas, considere um caso de utilização de perfis. Primeiro, insiraalgumas entradas numa coleção intitulada profiles. Introduza o seguinte:


6. Copie o seguinte comando e volte ao seu AWS Cloud9 e cole-o no AWS Cloud9 terminal.



{ "acknowledged" : true, "insertedIds" : [ 1, 2, 3, 4 ] }

8. Utilize o find() para devolver todos os documentos na coleção de perfis. Introduza o seguinte:

db.profiles.find()

9. Irá obter uma saída que corresponda aos dados que introduziu no Passo 5.10. Utilize uma consulta para um único documento utilizando um filtro. Introduza o seguinte:

db.profiles.find({name: "Katie"})

11. Deve recuperar esta saída:

{ "_id" : 4, "name" : "Katie", "status": "active", "level": 3, "score":27}

12. Agora tente encontrar um perfil e modificá-lo utilizando o findAndModify comando. Iremos dar aoutilizador a Matt mais dez pontos com o seguinte código:

db.profiles.findAndModify({ query: { name: "Matt", status: "active"}, update: { $inc: { score: 10 } } })

13. Obtém a seguinte saída (note que a sua pontuação ainda não aumentou):

{ "_id" : 1, "name" : "Matt", "status" : "active", "level" : 12, "score" : 202

404

Amazon DocumentDB Guia do desenvolvedorEtapa 9 Explorar

}

14. Pode verificar se a sua pontuação foi alterada com a seguinte consulta:

db.profiles.find({name: "Matt"})


{ "_id" : 1, "name" : "Matt", "status" : "active", "level" : 12, "score" :212 }

Etapa 9 ExplorarParabéns! Concluiu com sucesso o Guia de Iniciação Rápida para Amazon DocumentDB.

Próximas etapas Saiba como aproveitar totalmente esta poderosa base de dados com algumas das suascaracterísticas populares:

• Como gerenciar o . Amazon DocumentDB• Escalabilidade• Fazer cópias de segurança e restaurar

Note

Para poupar dinheiro, pode parar o seu Amazon DocumentDB para reduzir custos ou eliminar ogrupo. Por predefinição, após 30 minutos de inactividade, o seu AWS Cloud9 o ambiente irá pararo Amazon EC2 instância.

405

https://docs.aws.amazon.com/documentdb/latest/developerguide/managing-documentdb.html

https://docs.aws.amazon.com/documentdb/latest/developerguide/operational_tasks.html

https://docs.aws.amazon.com/documentdb/latest/developerguide/backup_restore.html

Amazon DocumentDB Guia do desenvolvedorTipos de instâncias do compatíveis

Cotas e limites do AmazonDocumentDB

Esse tópico descreve as cotas de recursos e as restrições de nomenclatura do Amazon DocumentDB(compatível com MongoDB).

Para determinados recursos de gerenciamento, o Amazon DocumentDB usa tecnologia operacionalcompartilhada com o Amazon Relational Database Service (Amazon RDS) e o Amazon Neptune.

Tópicos• Tipos de instâncias do compatíveis (p. 406)• Regiões do com suporte (p. 407)• Cotas regionais (p. 407)• Limites de agregação (p. 409)• Limites de cluster (p. 409)• Limites de instâncias (p. 410)• Restrições de nomenclatura (p. 411)• Restrições de TTL (p. 412)

Tipos de instâncias do compatíveisO Amazon DocumentDB oferece suporte a instâncias sob demanda e aos seguintes tipos de instância:

• Otimizadas para memória:• Tipos de instância R5: db.r5.large, db.r5.2xlarge, db.r5.4xlarge, db.r5.12xlarge,db.r5.24xlarge.

• Tipos de instância R4: db.r4.large, db.r4.2xlarge, db.r4.4xlarge, db.r4.8xlarge,db.r4.16xlarge.

• Desempenho Burstable:• Tipos de instância T3: db.t3.medium.

Para obter mais informações sobre os tipos de instância compatíveis e suas especificações, consulteInstance Class Specifications (p. 250).

406

Amazon DocumentDB Guia do desenvolvedorRegiões do com suporte

Regiões do com suporteO Amazon DocumentDB está disponível nas regiões da AWS a seguir:




us-east-1 6.


us-west-2 4.




ap-southeast-1 3.









Cotas regionaisPara determinados recursos de gerenciamento, o Amazon DocumentDB usa tecnologia operacionalcompartilhada com o Amazon Relational Database Service (Amazon RDS) e o Amazon Neptune. A tabelaa seguir contém os limites regionais que são compartilhados entre o Amazon DocumentDB, o AmazonRDS e o Neptune.

Os limites a seguir do AWS são por conta da AWS por região.

Recurso Limite padrão da AWS

Clusters 40

Grupos de parâmetros de clusters 50

Assinaturas de eventos 20

Instâncias 40

Snapshots de clusters manuais 100

407

Amazon DocumentDB Guia do desenvolvedorCotas regionais

Recurso Limite padrão da AWS

Réplicas de leitura por cluster 15

Grupos de sub-rede 50

Sub-redes por grupo de sub-rede 20

Tags por recurso 50

Grupos de segurança da VPC por instância 5

É possível usar cotas de serviço para solicitar um aumento para uma cota, se a cota for ajustável. Algumassolicitações são resolvidas automaticamente, enquanto outras são enviadas para o AWS Support. Épossível acompanhar o status de uma solicitação de aumento de cota enviada ao AWS Support. Assolicitações para aumentar as cotas de serviço não recebem suporte prioritário. Se você tiver umasolicitação urgente, entre em contato com o AWS Support. Para obter mais informações sobre cotas deserviço, consulte O que são cotas de serviço?

Para solicitar o aumento da cota, consulte Amazon DocumentDB:

1. Abra o console de Cotas de Serviço em https://console.aws.amazon.com/servicequotas e, senecessário, entre.

2. No painel de navegação, escolha AWS services (Serviços da AWS).3. Selecione o Amazon DocumentDB na lista ou digite o campo de pesquisa do Amazon DocumentDB.4. Se a cota for ajustável, será possível selecionar seu botão de opção ou seu nome e escolher Request

quota increase (Solicitar aumento de cota) no canto superior direito da página.5. Em Change quota value (Alterar valor da cota), insira o novo valor. O novo valor deve ser maior que o

valor atual.6. Escolha Request (Solicitar). Depois que a solicitação é resolvida, o Applied quota value (Valor da cota

aplicada) para a cota é definido como o novo valor.7. Para exibir quaisquer solicitações pendentes ou resolvidas recentemente, escolha Dashboard (Painel)

no painel de navegação. Para solicitações pendentes, escolha o status da solicitação para abrir orecibo da solicitação. O estado inicial de um pedido é Pending. Depois de o estado mudar paraQuota requested, verá o número do caso com o Suporte AWS. Escolha o número do caso paraabrir o tíquete de sua solicitação.

408


https://docs.aws.amazon.com//servicequotas/latest/userguide/intro.html

https://console.aws.amazon.com/servicequotas

Amazon DocumentDB Guia do desenvolvedorLimites de agregação

Limites de agregaçãoA tabela a seguir descreve os limites de agregação no Amazon DocumentDB.

Recurso Limit

Número máximo compatível de estágios 500

Limites de clusterA tabela a seguir descreve os limites de cluster do Amazon DocumentDB.

Recurso Limit

Tamanho do cluster (soma de todas as coleções e índices) 64 TB

Tamanho da coleção (a soma de todas as coleções não podeexceder o limite do cluster) – não inclui o tamanho do índice

32 TB

Coleções por cluster 100.000

Bancos de dados por cluster 100.000

Tamanho do banco de dados (a soma de todos os bancos de dadosnão pode exceder o limite do cluster)

64 TB

Profundidade do aninhamento de documentos 100 níveis

Tamanho do documento 16 MB

Tamanho da chave de índice 2.048 bytes

Índices por coleção 64

Chaves em um índice composto 32

O número máximo de gravações em um único comando em lote 100.000

Número de usuários por cluster 1.000

409

Amazon DocumentDB Guia do desenvolvedorLimites de instâncias

Limites de instânciasA tabela a seguir descreve os limites do Amazon DocumentDB por instância.

Tipo de instância (GiB) Memória deInstância

Limite de ligação Limite do cursor

T3.médio 4 500 30

R4.grande 15.25 1700 450

R4.xgrande 30.5 3400 450

R4.2xgrande 61 6800 450

R4.4xgrande 122 13600 725

R4,8xgrande 288 27200 1450

R4.16xgrande 488 30000 2900

R5.grande 16 1700 450

R5.xgrande 32 3500 450

R5.2xgrande 64 7100 450

R5.4xgrande 128 14200 760

R5,12xgrande 383 30000 2280

R5,24xgrande 768 30000 4560

410

Amazon DocumentDB Guia do desenvolvedorRestrições de nomenclatura

Restrições de nomenclaturaA tabela a seguir descreve restrições de nomenclatura no Amazon DocumentDB.

Recurso Limite padrão

Identificador de cluster • O comprimento é de [1–63] letras,números ou hifens.

• O primeiro caractere deve ser umaletra.

• Não podem terminar com um hífenou conter dois hífens consecutivos.

• Deve ser exclusivo para todos osclusters (no Amazon RDS, AmazonNeptune, e Amazon DocumentDB)por conta da AWS, por região.

Nome da coleção: <col> O tamanho é de [1 a 57] caracteres.

Nome do banco de dados: <db> O tamanho é de [1 a 63] caracteres.

Nome da coleção totalmente qualificado: <db>.<col> O tamanho é de [3 a 120] caracteres.

Nome do índice totalmente qualificado: <db>.<col>.$<index>

O tamanho é de [6 a 127] caracteres.

Nome do índice: <col>$<index> O tamanho é de [3 a 63] caracteres.

Identificador da instância • O comprimento é de [1–63] letras,números ou hifens

• O primeiro caractere deve ser umaletra

• Não podem terminar com um hífenou conter dois hífens consecutivos

• Deve ser exclusivo para todasas instâncias (no Amazon RDS,Amazon Neptune, e AmazonDocumentDB) por conta da AWS,por região.

Senha mestre • O comprimento é de [8 a 100]caracteres ASCII imprimíveis.

• Pode usar caracteres ASCIIimprimíveis, exceto o seguinte:• / (barra)• " (aspas duplas)• @ (arroba)

Nome do usuário mestre • O comprimento é de [1–63]caracteres alfanuméricos.


411

Amazon DocumentDB Guia do desenvolvedorRestrições de TTL

Recurso Limite padrão• Não pode ser uma palavra

reservada pelo mecanismo debanco de dados.

Nome do parameter group • O tamanho é de [1–255] caracteresalfanuméricos.


• Não podem terminar com um hífenou conter dois hífens consecutivos.

Restrições de TTLExclusões de um índice de TTL não são garantidas dentro de um período específico e têm como baseo melhor esforço. Fatores como utilização de recursos da instância, tamanho do documento e taxa detransferência geral podem afetar a sincronização de uma exclusão de TTL.

412

Amazon DocumentDB Guia do desenvolvedorProblemas de ligação

Solução de problemas do AmazonDocumentDB

As seções a seguir fornecem informações sobre como solucionar problemas que você pode ter ao usar oAmazon DocumentDB (compatível com MongoDB).

Tópicos• Problemas de ligação (p. 413)• Criação de índice (p. 416)• Performance and Resource Utilization (p. 417)

Problemas de ligaçãoTem dificuldade em ligar? Aqui estão alguns cenários comuns e como resolvê-los.

Não é possível ligar a um Amazon DocumentDBParâmetro de avaliaçãoQuando você tentar se conectar Amazon DocumentDB, a mensagem de erro a seguir é uma das maiscomuns que você pode receber.

connecting to: mongodb://docdb-2018-11-08-21-47-27.cluster-ccuszbx3pn5e.us-east-1.docdb.amazonaws.com:27017/2018-11-14T14:33:46.451-0800 W NETWORK [thread1] Failed to connect to172.31.91.193:27017 after 5000ms milliseconds, giving up.2018-11-14T14:33:46.452-0800 E QUERY [thread1] Error: couldn't connect to serverdocdb-2018-11-08-21-47-27.cluster-ccuszbx3pn5e.us-east-1.docdb.amazonaws.com:27017,connection attempt failed :connect@src/mongo/shell/mongo.js:237:13@(connect):1:6exception: connect failed

O que significa esta mensagem de erro normalmente é que o seu cliente (o invólucro de mongo nesteexemplo) não consegue aceder ao Amazon DocumentDB endpoint. Este pode ser o caso por váriosmotivos:

Tópicos• Conexão de endpoints públicos (p. 413)• Conexões entre regiões (p. 414)• Ligação de diferentes Amazon VPCs (p. 414)• O grupo de segurança bloqueia as conexões de entrada (p. 415)

Conexão de endpoints públicosVocê está tentando se conectar a um cluster do Amazon DocumentDB diretamente do seu laptop ou dasua máquina de desenvolvimento local.

413

Amazon DocumentDB Guia do desenvolvedorNão é possível ligar a um Amazon

DocumentDB Parâmetro de avaliação

A tentar ligar a um Amazon DocumentDB o grupo de um parâmetro de avaliação público, como o seucomputador portátil ou máquina de desenvolvimento local, irá falhar. Amazon DocumentDB é apenas umanuvem privada virtual (VPC) e não suporta atualmente parâmetros de avaliação públicos. Assim, vocênão poderá se conectar diretamente ao seu cluster do Amazon DocumentDB do seu notebook nem doambiente de desenvolvimento local fora da sua VPC.

Para ligar a um Amazon DocumentDB a partir do exterior de um Amazon VPC, pode utilizar um túnel SSH.Para obter mais informações, consulte Conexão com um cluster do Amazon DocumentDB de fora de umaAmazon VPC (p. 388). Além disso, se o seu ambiente de desenvolvimento for diferente Amazon VPC,também pode utilizar o VPC Peering e ligar ao seu Amazon DocumentDB cluster de outro Amazon VPC namesma região ou numa região diferente.

Conexões entre regiõesVocê está tentando se conectar a um cluster do Amazon DocumentDB em outra região.

Se tentar ligar-se a um Amazon DocumentDB cluster de um Amazon EC2 instância numa Região diferenteda Região do grupo—por exemplo, tentar ligar a um grupo em Leste dos EUA (Norte da Virgínia) Região(us-leste-1) de Região Oeste dos EUA (Oregon) (us-west-2)—a ligação irá falhar.

Para verificar a região do seu cluster do Amazon DocumentDB, execute o comando a seguir. A região estáno endpoint.

aws docdb describe-db-clusters \ --db-cluster-identifier sample-cluster \ --query 'DBClusters[*].Endpoint'


[ "sample-cluster.node.us-east-1.docdb.amazonaws.com"]

Para verificar a região da sua instância do EC2, execute o comando a seguir.

aws ec2 describe-instances \ --query 'Reservations[*].Instances[*].Placement.AvailabilityZone'


[ [ "us-east-1a" ]]

Ligação de diferentes Amazon VPCsEstá a tentar ligar-se a um Amazon DocumentDB de um VPC que é diferente do Amazon VPC o seucluster é implementado para.

Se ambos Amazon DocumentDB cluster e Amazon EC2 instância estão na mesma região AWS, mas nãono mesmo Amazon VPC, não pode ligar directamente ao seu Amazon DocumentDB do grupo a menos quea instalação VPC esteja activada entre os dois Amazon VPCs.

Para verificar o Amazon VPC do seu Amazon DocumentDB instância, execute o seguinte comando.

414

Amazon DocumentDB Guia do desenvolvedorTestar uma ligação a um Amazon DocumentDB Instância

aws docdb describe-db-instances \ --db-instance-identifier sample-instance \ --query 'DBInstances[*].DBSubnetGroup.VpcId'

Para verificar o Amazon VPC do seu Amazon EC2 instância, execute o seguinte comando.

aws ec2 describe-instances \ --query 'Reservations[*].Instances[*].VpcId'

O grupo de segurança bloqueia as conexões de entradaVocê está tentando se conectar a um cluster do Amazon DocumentDB, e o grupo de segurança do clusternão permite conexões de entrada na porta do cluster (porta padrão: 27017).

Suponha que o seu Amazon DocumentDB cluster e Amazon EC2 instância são ambas na mesma regiãoe Amazon VPC e utilizar o mesmo Amazon VPC grupo de segurança. Se não conseguir ligar-se ao seuAmazon DocumentDB cluster, a causa provável é que o seu grupo de segurança (ou seja, firewall) para oseu grupo não permita ligações de entrada na porta que escolheu para o seu Amazon DocumentDB painel(porta predefinida é 27017).

Para verificar a porta do seu cluster do Amazon DocumentDB, execute o comando a seguir.

aws docdb describe-db-clusters \ --db-cluster-identifier sample-cluster \ --query 'DBClusters[*].[DBClusterIdentifier,Port]'

Para obter os grupos de segurança do Amazon DocumentDB para o seu cluster, execute o seguintecomando.

aws docdb describe-db-clusters \ --db-cluster-identifier sample-cluster \ --query 'DBClusters[*].[VpcSecurityGroups[*],VpcSecurityGroupId]'

Para verificar as regras de entrada para o seu grupo de segurança, consulte os seguintes tópicos noAmazon EC2 documentação:

• Autorizar tráfego de entrada para as instâncias do Linux• Autorizar tráfego de entrada para as instâncias do Windows

Testar uma ligação a um Amazon DocumentDBInstânciaVocê pode testar sua conexão com um cluster usando ferramentas comuns do Linux ou Windows.

A partir de um terminal Linux ou Unix, teste a ligação introduzindo o seguinte (substitua cluster-endpoint com o endpoint e substituir port com o porto da sua instância):

nc -zv cluster-endpoint port

Veja a seguir um exemplo de operação e o valor de retorno:

nc -zv docdbTest.d4c7nm7stsfc0.us-west-2.docdb.amazonaws.com 27017

415

https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/authorizing-access-to-an-instance.html

https://docs.aws.amazon.com/AWSEC2/latest/WindowsGuide/authorizing-access-to-an-instance.html

Amazon DocumentDB Guia do desenvolvedorConexão a um endpoint inválido

Connection to docdbTest.d4c7nm7stsfc0.us-west-2.docdb.amazonaws.com 27017 port [tcp/*] succeeded!

Conexão a um endpoint inválidoAo conectar-se a um cluster do Amazon DocumentDB e usar um endpoint de cluster inválido, um errosemelhante ao seguinte será exibido.

mongo --ssl \ --host sample-cluster.node.us-east-1.docdb.amazonaws.com:27017 \ --sslCAFile rds-combined-ca-bundle.pem \ --username <user-name> \ --password <password>

O resultado se parece com:

MongoDB shell version v3.6connecting to: mongodb://sample-cluster.node.us-east-1.docdb.amazonaws.com:27017/2018-11-14T17:21:18.516-0800 I NETWORK [thread1] getaddrinfo("sample-cluster.node.us-east-1.docdb.amazonaws.com") failed: nodename nor servname provided, or not known 2018-11-14T17:21:18.537-0800 E QUERY [thread1] Error: couldn't initializeconnection to host sample-cluster.node.us-east-1.docdb.amazonaws.com, address is invalid :connect@src/mongo/shell/mongo.js:237:13@(connect):1:6exception: connect failed

Para obter o endpoint válido para um cluster, execute o seguinte comando:

aws docdb describe-db-clusters \ --db-cluster-identifier sample-cluster \ --query 'DBClusters[*].[Endpoint,Port]'

Para obter o endpoint válido para uma instância, execute o seguinte comando:

aws docdb describe-db-instances \ --db-instance-identifier sample-instance \ --query 'DBInstances[*].[Endpoint.Address,Endpoint.Port]'

Para obter mais informações, consulte Noções básicas sobre endpoints do Amazon DocumentDB (p. 312).

Criação de índiceOs tópicos a seguir abordam o que fazer se a criação do índice ou índice em segundo plano falhar.

Tópicos• Falha de compilação de índice (p. 416)• O índice de antecedentes gera problemas e falha (p. 417)

Falha de compilação de índiceAmazon DocumentDBO utiliza armazenamento local em uma instância como parte do processode criação do índice. Pode monitorizar esta utilização do disco utilizando o armazenamento livre

416

Amazon DocumentDB Guia do desenvolvedorO índice de antecedentes gera problemas e falha

CloudWatch métrico (CloudWatch -> Metrics -> DocDB -> Instance Metrics). Quando acriação do índice consumia todo o disco local e falhar, você receberá um erro. Ao migrar dados parao Amazon DocumentDB, recomendamos que você crie índices primeiro e, depois, insira os dados.Para mais informações sobre estratégias de migração e criação de índices, consulte Migrar para oAmazon DocumentDB (p. 103) no Amazon DocumentDB e o blogue: Migrar de mongodb para AmazonDocumentDB utilizar o método offline.

Ao criar índices num grupo existente, se a construção de índice estiver a demorar mais tempo do que oesperado ou falhar, recomendamos que aumente a instância para criar o índice depois, depois de o índiceser criado, a escala de volta. Amazon DocumentDB permite-lhe dimensionar rapidamente tamanhos deinstância em minutos utilizando o Console de gerenciamento da AWS ou o AWS CLI. Para obter maisinformações, consulte Managing Instance Classes (p. 247). Com a definição de preço de instâncias porsegundo, você paga apenas pelo recurso usado por segundo.

O índice de antecedentes gera problemas e falhaO índice de fundo constrói-se Amazon DocumentDB não comece até todas as questões sobre a instânciaprimária que começaram antes da construção do índice ter sido iniciada, executando o. Se houver umaconsulta de longo prazo, as construções de índice de fundo bloquearão até que a consulta terminee, assim, possa demorar mais tempo do que o esperado para concluir. Isto é verdade mesmo que asrecolhas estejam vazias.

As construções de índice inicial não apresentam o mesmo comportamento de bloqueio. Em vez disso,as acumulações de índice de primeiro plano têm um bloqueio exclusivo na coleção até que a construçãodo índice esteja concluída. Assim, para criar índices na recolha vazia e evitar o bloqueio em quaisquerconsultas de longo prazo, sugerimos que utilize o índice de primeiro plano.

Note

Amazon DocumentDBO permite que apenas uma compilação de índice de segundo plano ocorraem uma coleção a qualquer momento. Se DDL (Data Definition Language) operações, tais comocreateIndex() oudropIndex() ocorre na mesma coleção durante uma construção de índicede fundo, a construção do índice de fundo falha.

Performance and Resource UtilizationEsta seção fornece perguntas e soluções para problemas comuns de diagnóstico em implantações doAmazon DocumentDB. Os exemplos fornecidos utilizam o mongo shell e são clonadas para uma instânciaindividual. Para encontrar um endpoint de instância, consulte Noções básicas sobre endpoints do AmazonDocumentDB (p. 312).

Tópicos• How Do I Find and Terminate Long Running or Blocked Queries? (p. 418)• How Can I See a Query Plan and Optimize a Query? (p. 419)• How Do I List All Running Operations on an Instance? (p. 420)• How Do I Know When a Query Is Making Progress? (p. 422)• How Do I Determine Why a System Suddenly Runs Slowly? (p. 424)• How Do I Determine the Cause of High CPU Utilization on One or More Cluster Instances? (p. 425)• How Do I Determine the Open Cursors on an Instance? (p. 425)• How do I Determine the Current Amazon DocumentDB Engine Version? (p. 426)• How Do I Identify Unused Indexes? (p. 426)• How Do I Identify Missing Indexes? (p. 426)

417

https://aws.amazon.com/blogs/database/migrate-from-mongodb-to-amazon-documentdb-using-the-offline-method/

https://aws.amazon.com/blogs/database/migrate-from-mongodb-to-amazon-documentdb-using-the-offline-method/

Amazon DocumentDB Guia do desenvolvedorFind and Terminate Long Running or Blocked Queries

• Summary of Useful Queries (p. 427)

How Do I Find and Terminate Long Running orBlocked Queries?As consultas de usuário podem ser executadas lentamente devido a um plano de consulta pouco ideal oupodem ser bloqueadas devido à contenção de recursos.

Para encontrar consultas de longa execução que ficam lentas devido a um plano de consulta pouco idealou consultas bloqueadas devido à contenção de recursos, use o comando currentOp. Você pode filtraro comando para ajudar a refinar a lista de consultas relevantes para serem encerradas. É necessário teropid associado à consulta de longa duração para poder encerrar a consulta.

A consulta a seguir usa o comando currentOp para listar todas as consultas que estão bloqueadas ouem execução por mais de 10 segundos.

db.adminCommand({ aggregate: 1, pipeline: [ {$currentOp: {}}, {$match: {$or: [ {secs_running: {$gt: 10}}, {WaitState: {$exists: true}}]}}, {$project: {_id:0, opid: 1, secs_running: 1}}], cursor: {}});

Depois, você pode restringir a consulta para encontrar o opid de uma consulta em execução por mais de10 segundos e encerrá-lo.

Para localizar e encerrar uma consulta em execução por mais de 10 segundos

1. Encontre o opid da consulta.

db.adminCommand({ aggregate: 1, pipeline: [ {$currentOp: {}}, {$match: {$or: [{secs_running: {$gt: 10}}, {WaitState: {$exists: true}}]}}], cursor: {}});


{ "waitedMS" : NumberLong(0), "cursor" : { "firstBatch" : [ { "opid" : 24646, "secs_running" : 12 } ], "id" : NumberLong(0),

418

Amazon DocumentDB Guia do desenvolvedorSee a Query Plan and Optimize a Query

"ns" : "admin.$cmd" }, "ok" : 1}

2. Encerre a consulta usando a operação killOp.

db.adminCommand({killOp: 1, op: 24646});

How Can I See a Query Plan and Optimize a Query?Se uma consulta for executada lentamente, pode ser porque a execução da consulta requer umaverificação completa da coleção para escolher os documentos relevantes. Às vezes, criar índicesapropriados permitirá que a consulta seja executada mais rapidamente. Para detectar esse cenário edecidir os campos nos quais criar os índices, use o comando explain.

Note

O Amazon DocumentDB emula a API do MongoDB 3.6 em um mecanismo de banco de dadoscriado especificamente que utiliza um sistema de armazenamento distribuído, tolerante afalhas e de autorrecuperação. Como resultado, os planos de consulta e a saída de explain()podem diferir entre o Amazon DocumentDB e o MongoDB. Os clientes que desejam ter controlesobre seu plano de consulta podem usar o operador $hint para impor a seleção de um índicepreferencial.

Execute a consulta que você deseja melhorar com o comando explain da seguinte forma.

db.runCommand({explain: {<query document>}})

Veja a seguir um exemplo de operação.

db.runCommand({explain:{ aggregate: "sample-document", pipeline: [{$match: {x: {$eq: 1}}}], cursor: {batchSize: 1}}});


{ "queryPlanner" : { "plannerVersion" : 1, "namespace" : "db.test", "winningPlan" : { "stage" : "COLLSCAN" } }, "serverInfo" : { "host" : "...", "port" : ..., "version" : "..." }, "ok" : 1}

A saída acima indica que o estágio $match exige a verificação de toda a coleção e a verificação se ocampo "x" em cada documento é igual a 1. Se houver muitos documentos na coleção, a verificação

419

Amazon DocumentDB Guia do desenvolvedorList All Running Operations on an Instance

da coleção (e, portanto, o desempenho geral da consulta) serão muito lentos. Assim, a presença de"COLLSCAN" na saída do comando explain indica que o desempenho da consulta pode ser aprimoradocom a criação de índices apropriados.

Neste exemplo, a consulta verifica se o campo "x" é igual a 1 em todos os documentos. Portanto, criarum campo de índice no "x" permite que a consulta evite a verificação completa da coleção e use o índicepara retornar os documentos relevantes mais cedo.

Depois de criar um índice no campo "x", a saída explain será a seguinte.

{ "queryPlanner" : { "plannerVersion" : 1, "namespace" : "db.test", "winningPlan" : { "stage" : "IXSCAN", "indexName" : "x_1", "direction" : "forward" } }, "serverInfo" : { "host" : "...", "port" : ..., "version" : "..." }, "ok" : 1}

A criação de um índice no campo "x" permite que o estágio $match use uma varredura de índice parareduzir o número de documentos nos quais o predicado "x = 1" precisa ser avaliado.

Para pequenas coleções, o processador de consultas do Amazon DocumentDB pode optar por não usarum índice se os ganhos de desempenho forem negligenciáveis.

How Do I List All Running Operations on an Instance?Como usuário ou usuário mestre, muitas vezes você deseja listar todas as operações atuais em execuçãoem uma instância para fins de diagnóstico e solução de problemas. (Para obter informações sobre ogerenciamento de usuários, consulte Gerenciamento de usuários do Amazon DocumentDB (p. 142).)

Com o shell do mongo, você pode usar a seguinte consulta para listar todas as operações em execuçãoem uma instância do Amazon DocumentDB.

db.adminCommand({currentOp: 1, $all: 1});

A consulta retorna a lista completa de todas as consultas do usuário e tarefas internas do sistemaatualmente em operação na instância.


{ "inprog" : [ { "desc" : "INTERNAL" }, { "desc" : "TTLMonitor", "active" : false

420

Amazon DocumentDB Guia do desenvolvedorList All Running Operations on an Instance

}, { "desc" : "GARBAGE_COLLECTION" }, { "client" : ..., "desc" : "Conn", "active" : true, "killPending" : false, "opid" : 195, "ns" : "admin.$cmd", "command" : { "currentOp" : 1, "$all" : 1 }, "op" : "command", "$db" : "admin", "secs_running" : 0, "microsecs_running" : NumberLong(68), "clientMetaData" : { "application" : { "name" : "MongoDB Shell" }, "driver" : { ... }, "os" : { ... } } }], "ok" : 1}

Estes são valores válidos para o campo "desc":

• INTERNAL — Internal system tasks like the cursor cleanup or stale user cleanup tasks.• TTLMonitor — The Time to Live (TTL) monitor thread. Its running status is reflected in the "active"

field.• GARBAGE_COLLECTION — The internal garbage collector thread. There can be a maximum of three

garbage collector threads running concurrently in the system.• CONN — The user query.• CURSOR — The operation is an idle cursor waiting on the user to call the "getMore" command to get the

next batch of results. In this state, the cursor is consuming memory, but is not consuming any compute.

A saída anterior também lista todas as consultas do usuário em execução no sistema. Cada consulta deutilizador é executada no contexto de uma base de dados e recolha e a união destes dois é chamada denamespace. O nome homónimo de cada consulta do utilizador está disponível no "ns" campo.

Às vezes, você precisa listar todas as consultas de usuário em execução em um determinado namespace.Portanto, a saída anterior deve ser filtrada no campo "ns". Um exemplo de consulta para alcançar a saídapara filtrar é o seguinte. A consulta lista todas as consultas de usuário em execução no momento no bancode dados "db" e na coleção "test" (ou seja, o namespace "db.test").

db.adminCommand({aggregate: 1, pipeline: [{$currentOp: {allUsers: true, idleConnections: true}}, {$match: {ns: {$eq: "db.test"}}}], cursor: {}});

421

Amazon DocumentDB Guia do desenvolvedorKnow When a Query Is Making Progress

Como usuário mestre do sistema, você pode ver as consultas de todos os usuários e também todas astarefas internas do sistema. Todos os outros usuários só podem ver suas respectivas consultas.

Se o número total de consultas e tarefas internas do sistema exceder o tamanho do lote padrão do cursor,o shell do mongo gerará automaticamente um objeto iterador 'it' para visualizar o resto dos resultados.Continue executando o comando 'it' até que todos os resultados sejam esgotados.

How Do I Know When a Query Is Making Progress?As consultas do usuário podem ficar lentas devido a um plano de execução de consulta pouco satisfatórioou ficar bloqueadas devido à contenção de recursos. Depurar essas consultas é um processo de váriasetapas que pode exigir que a mesma etapa seja executada várias vezes.

A primeira etapa da depuração é listar todas as consultas que estão bloqueada ou de longa execução. Aconsulta a seguir lista todas as consultas de usuário que estão em execução por mais de 10 segundos ouque estão aguardando recursos.

db.adminCommand({aggregate: 1, pipeline: [{$currentOp: {}}, {$match: {$or: [{secs_running: {$gt: 10}}, {WaitState: {$exists: true}}]}}, {$project: {_id:0, opid: 1, secs_running: 1, WaitState: 1, blockedOn: 1, command: 1}}], cursor: {} });

Repita a consulta anterior periodicamente para determinar se a lista de consultas muda e identificar asconsultas bloqueadas ou de longa execução.

Se o documento de saída da consulta em questão tiver um campo WaitState, isso indica que acontenção de recursos é o motivo pelo qual a consulta está lenta ou bloqueada. A contenção de recursospode ocorrer devido a E/S, tarefas internas do sistema ou outras consultas do usuário.


{ "waitedMS" : NumberLong(0), "cursor" : { "firstBatch" : [ { "opid" : 201, "command" : { "aggregate" : ... }, "secs_running" : 208, "WaitState" : "IO" } ], "id" : NumberLong(0), "ns" : "admin.$cmd" }, "ok" : 1}

E/S poderá ser um gargalo se houver muitas consultas em diferentes coleções em execuçãosimultaneamente na mesma instância ou se o tamanho da instância for muito pequeno para o conjuntode dados no qual a consulta está sendo executada. Se as consultas forem somente leitura, você poderá

422

Amazon DocumentDB Guia do desenvolvedorKnow When a Query Is Making Progress

atenuar a situação anterior separando as consultas de cada coleção em réplicas separadas. Paraatualizações simultâneas em diferentes coleções ou quando o tamanho da instância for muito pequenopara o conjunto de dados, é possível mitigar aumentando a instância.

Se a contenção de recursos ocorrer devido a outra consulta do usuário, o campo "blockedOn" nodocumento de saída terá o "opid" da consulta que está afetando essa consulta. Com o "opid" sigaa cadeia de campos "WaitState" e "blockedOn" de todas as consultas para encontrar a consulta àfrente da cadeia.

Se a tarefa à frente da cadeia for uma tarefa interna, a única mitigação nesse caso seria encerrar aconsulta e executá-la novamente depois de algum tempo.

Veja a seguir um exemplo de saída em que a consulta de busca é bloqueada em um bloqueio de coleçãoque pertence a outra tarefa.

{ "inprog" : [ { "client" : "...", "desc" : "Conn", "active" : true, "killPending" : false, "opid" : 75, "ns" : "...", "command" : { "find" : "...", "filter" : {

} }, "op" : "query", "$db" : "test", "secs_running" : 9, "microsecs_running" : NumberLong(9449440), "threadId" : 24773, "clientMetaData" : { "application" : { "name" : "MongoDB Shell" }, "driver" : { ... }, "os" : { ... } }, "WaitState" : "CollectionLock", "blockedOn" : "INTERNAL" }, { "desc" : "INTERNAL" }, { "client" : "...", ... "command" : { "currentOp" : 1 }, ... } ], "ok" : 1}

423

Amazon DocumentDB Guia do desenvolvedorDetermine Why a System Suddenly Runs Slowly

Se "WaitState" tiver valores "Latch", "SystemLock", "BufferLock", "BackgroundActivity"ou "Other", a origem da contenção de recursos serão as tarefas internas do sistema. Se a situaçãocontinuar por um longo período, a única atenuação será encerrar a consulta e executá-la novamente maistarde.

How Do I Determine Why a System Suddenly RunsSlowly?Veja a seguir alguns motivos comuns para uma desaceleração do sistema:

• Excessive resource contention between concurrent queries• The number of active concurrent queries increasing over time• Internal system tasks such as "GARBAGE_COLLECTION"

Para monitorar o uso do sistema ao longo do tempo, execute a seguinte consulta "currentOp"periodicamente e gere a saída dos resultados em um armazenamento externo. A consulta conta o númerode consultas e operações em cada namespace no sistema. É possível analisar os resultados do uso dosistema para compreender a carga no sistema e tomar a medida apropriada.

db.adminCommand({aggregate: 1, pipeline: [{$currentOp: {allUsers: true, idleConnections: true}}, {$group: {_id: {desc: "$desc", ns: "$ns", WaitState: "$WaitState"}, count: {$sum: 1}}}], cursor: {} });

Essa consulta retorna um agregado de todas as consultas em execução em cada namespace e em todasas tarefas internas do sistema, e o número exclusivo de estados de espera, se houver, por namespace.


{ "waitedMS" : NumberLong(0), "cursor" : { "firstBatch" : [ { "_id" : { "desc" : "Conn", "ns" : "db.test", "WaitState" : "CollectionLock" }, "count" : 2 }, { "_id" : { "desc" : "Conn", "ns" : "admin.$cmd" }, "count" : 1 }, { "_id" : { "desc" : "TTLMonitor" }, "count" : 1 } ], "id" : NumberLong(0),

424

Amazon DocumentDB Guia do desenvolvedorDetermine the Cause of High CPU Utilization

"ns" : "admin.$cmd" }, "ok" : 1}

Na saída anterior, duas consultas de usuário no namespace "db.test" estão bloqueadas no bloqueio dacoleção: uma consulta no namespace "admin.$cmd" e uma tarefa interna "TTLMonitor".

Se a saída indicar muitas consultas com estados de espera de bloqueio, consulte How Do I Find andTerminate Long Running or Blocked Queries? (p. 418)

How Do I Determine the Cause of High CPU Utilizationon One or More Cluster Instances?As seções a seguir podem ajudá-lo a identificar a causa da alta utilização da CPU da instância. Osresultados podem variar dependendo da carga de trabalho.

• To determine why an instance is suddenly running slowly, see How Do I Determine Why a SystemSuddenly Runs Slowly? (p. 424)

• To identify and terminate long running queries on a particular instance, see How Do I Find and TerminateLong Running or Blocked Queries? (p. 418)

• To understand whether a query is progressing, see How Do I Know When a Query Is MakingProgress? (p. 422)

• To determine why a query takes a long time to run, see How Can I See a Query Plan and Optimize aQuery? (p. 419)

• To track long-running queries over time, see Profiling Amazon DocumentDB Operations (p. 352).

Dependendo do motivo da alta utilização da CPU da instância, executar uma ou mais das ações a seguirpode ajudar.

• If the primary instance exhibits high CPU utilization, but the replica instances don't, consider distributingread traffic across replicas via client read preference settings (for example, secondaryPreferred). Formore information, see Conectar-se ao Amazon DocumentDB como um conjunto de réplicas (p. 384).

Using replicas for reads can make better use of the cluster’s resources by allowing the primary instanceto process more write traffic. Reads from replicas are eventually consistent.

• If the high CPU utilization is a result of your write workload, changing the size of the cluster’s instancesto a larger instance type increases the number of CPU cores available to service the workload. For moreinformation, see Instances (p. 3) and Instance Class Specifications (p. 250).

• If all cluster instances exhibit high CPU utilization, and the workload is using replicas for reads, addingmore replicas to the cluster increases the resources available for read traffic. For more information, seeAdding an Amazon DocumentDB Instance to a Cluster (p. 252).

How Do I Determine the Open Cursors on anInstance?Quando estiver conectado a uma instância do Amazon DocumentDB, você poderá usar o comandodb.runCommand("listCursors") para listar os cursores abertos nessa instância. Observe que háum limite de 450 cursores abertos ativos ao mesmo tempo em uma instância do Amazon DocumentDB.Em geral, recomendamos fechar os cursores que não estão mais em uso, porque os cursores utilizam osrecursos em uma instância e têm um limite superior.

425

Amazon DocumentDB Guia do desenvolvedorHow do I Determine the Current

Amazon DocumentDB Engine Version?

db.runCommand("listCursors")

How do I Determine the Current Amazon DocumentDBEngine Version?Para determinar a versão atual do mecanismo do Amazon DocumentDB, execute o seguinte comando.

db.runCommand({getEngineVersion: 1})


{ "engineVersion" : "1.0.202313", "ok" : 1 }

How Do I Identify Unused Indexes?É uma prática recomendada identificar e remover regularmente índices não utilizados, a fim de melhoraro desempenho e reduzir custos, pois isso elimina computação, armazenamento e E/S desnecessáriosusados para manter os índices. Para identificar os índices de uma determinada coleção, execute oseguinte comando:


Para identificar se um índice foi ou não utilizado, execute o seguinte comando. A saída do comandodescreve o seguinte:

db.collection.aggregate([{$indexStats:{}}]).pretty()

• ops —The number of operations that used the index. If your workload has been running for a sufficientlylong time and you are confident that your workload is in a steady state, an ops value of zero wouldindicate that the index is not used at all.

• since —The time since Amazon DocumentDB started collecting stats on index usage, which is typicallythe value since the last database restart or maintenance action.

Para determinar o tamanho geral do índice para uma coleção, execute o seguinte comando:

db.collection.stats()

Para descartar um índice não utilizado, execute o seguinte comando:

db.collection.dropIndex("indexName")

How Do I Identify Missing Indexes?Você pode usar o profiler do Amazon DocumentDB para registrar consultas lentas em log. Uma consultaque aparece repetidamente no log de consulta lenta pode indicar que um índice adicional é necessáriopara melhorar o desempenho dessa consulta.

Você pode identificar oportunidades para índices úteis procurando consultas de longa execução quetenham um ou mais estágios que executem pelo menos um estágio COLLSCAN, o que significa que oestágio de consulta tem que ler todos os documentos na coleção para fornecer uma resposta à consulta.

426

https://docs.aws.amazon.com//documentdb/latest/developerguide/profiling.html

Amazon DocumentDB Guia do desenvolvedorSummary of Useful Queries

O exemplo a seguir mostra uma consulta em uma coleção de corridas de táxi que foi executada em umacoleção grande.

db.rides.count({"fare.totalAmount":{$gt:10.0}}))

Para executar este exemplo, a consulta tinha que realizar uma varredura na coleção (ou seja, ler todosos documentos da coleção), pois não há índice no campo fare.totalAmount. A saída do profiler doAmazon DocumentDB para essa consulta tem uma aparência semelhante à seguinte:

{ ... "cursorExhausted": true, "nreturned": 0, "responseLength": 0, "protocol": "op_query", "millis": 300679, "planSummary": "COLLSCAN", "execStats": { "stage": "COLLSCAN", "nReturned": "0", "executionTimeMillisEstimate": "300678.042" }, "client": "172.31.5.63:53878", "appName": "MongoDB Shell", "user": "example"}

Para acelerar a consulta neste exemplo, convém criar um índice no fare.totalAmount, como mostradoabaixo.

db.rides.createIndex( {"fare.totalAmount": 1}, {background: true} )

Note

Os índices criados em primeiro plano (ou seja, se a opção {background:true} não foifornecida ao criar o índice) usam um bloqueio de gravação exclusivo, o que impede que osaplicativos gravem dados na coleção até que a compilação do índice seja concluída. Esteja cientedesse possível impacto ao criar índices em clusters de produção. Ao criar índices, recomendamosa configuração {background:true}.

Em geral, convém criar índices em campos com cardinalidade alta (por exemplo, um grande número devalores exclusivos). Criar um índice em um campo com baixa cardinalidade pode resultar em um índicegrande que não é usado. O otimizador de consulta do Amazon DocumentDB considera o tamanho geral dacoleção e a seletividade dos índices ao criar um plano de consulta. Às vezes, você verá o processador deconsultas selecionar um COLLSCAN mesmo quando um índice estiver presente. Isso acontece quando oprocessador de consultas estima que a utilização do índice não produzirá uma vantagem de desempenhosobre a varredura de toda a coleção. Se você quiser forçar o processador de consultas a utilizar um índiceespecífico, use o operador hint() como mostrado abaixo.

db.collection.find().hint("indexName")

Summary of Useful QueriesAs consultas a seguir podem ser úteis para monitorar o desempenho e a utilização de recursos no AmazonDocumentDB.

• Use the following query to list all activity.

427

Amazon DocumentDB Guia do desenvolvedorSummary of Useful Queries

db.adminCommand({currentOp: 1, $all: 1});

• The following code lists all long running or blocked queries.

db.adminCommand({aggregate: 1, pipeline: [{$currentOp: {}}, {$match: {$or: [{secs_running: {$gt: 10}}, {WaitState: {$exists: true}}]}}, {$project: {_id:0, opid: 1, secs_running: 1, WaitState: 1, blockedOn: 1, command: 1}}], cursor: {} });

• The following code terminates a query.

db.adminCommand({killOp: 1, op: <opid of running or blocked query>});

• Use the following code to get an aggregated view of the system state.

db.adminCommand({aggregate: 1, pipeline: [{$currentOp: {allUsers: true, idleConnections: true}}, {$group: {_id: {desc: "$desc", ns: "$ns", WaitState: "$WaitState"}, count: {$sum: 1}}}], cursor: {} });

428

Amazon DocumentDB Guia do desenvolvedorActions

Amazon DocumentDBReferência deAPI de gerenciamento de cluster,instância e recurso

Esta secção descreve o grupo, instância e operações de gestão de recursos para Amazon DocumentDB(compatível com MongoDB) que estão acessíveis através do HTTP, AWS Command Line Interface (AWSCLI) ou o AWS SDK. Você pode usar essas APIs para criar, excluir e modificar clusters e instâncias.

Important

Essas APIs são usadas apenas para gerenciar clusters, instâncias e recursos relacionados. Paraobter informações sobre como se conectar a um cluster do Amazon DocumentDB em execução,consulte Guia de Introdução (p. 32).

Tópicos• Actions (p. 429)• Data Types (p. 534)• Common Errors (p. 581)• Common Parameters (p. 583)

ActionsThe following actions are supported:

• AddTagsToResource (p. 431)• ApplyPendingMaintenanceAction (p. 433)• CopyDBClusterParameterGroup (p. 435)• CopyDBClusterSnapshot (p. 437)• CreateDBCluster (p. 441)• CreateDBClusterParameterGroup (p. 447)• CreateDBClusterSnapshot (p. 449)• CreateDBInstance (p. 451)• CreateDBSubnetGroup (p. 455)• DeleteDBCluster (p. 457)• DeleteDBClusterParameterGroup (p. 459)• DeleteDBClusterSnapshot (p. 460)• DeleteDBInstance (p. 462)• DeleteDBSubnetGroup (p. 464)• DescribeCertificates (p. 466)• DescribeDBClusterParameterGroups (p. 468)• DescribeDBClusterParameters (p. 470)• DescribeDBClusters (p. 472)• DescribeDBClusterSnapshotAttributes (p. 474)

429

Amazon DocumentDB Guia do desenvolvedorActions

• DescribeDBClusterSnapshots (p. 476)• DescribeDBEngineVersions (p. 479)• DescribeDBInstances (p. 482)• DescribeDBSubnetGroups (p. 484)• DescribeEngineDefaultClusterParameters (p. 486)• DescribeEventCategories (p. 488)• DescribeEvents (p. 489)• DescribeOrderableDBInstanceOptions (p. 492)• DescribePendingMaintenanceActions (p. 494)• FailoverDBCluster (p. 496)• ListTagsForResource (p. 498)• ModifyDBCluster (p. 500)• ModifyDBClusterParameterGroup (p. 505)• ModifyDBClusterSnapshotAttribute (p. 507)• ModifyDBInstance (p. 509)• ModifyDBSubnetGroup (p. 513)• RebootDBInstance (p. 515)• RemoveTagsFromResource (p. 517)• ResetDBClusterParameterGroup (p. 519)• RestoreDBClusterFromSnapshot (p. 521)• RestoreDBClusterToPointInTime (p. 526)• StartDBCluster (p. 531)• StopDBCluster (p. 533)

430

Amazon DocumentDB Guia do desenvolvedorAddTagsToResource

AddTagsToResourceAdds metadata tags to an Amazon DocumentDB resource. You can use these tags with cost allocationreporting to track costs that are associated with Amazon DocumentDB resources. or in a Conditionstatement in an AWS Identity and Access Management (IAM) policy for Amazon DocumentDB.

Request ParametersFor information about the parameters that are common to all actions, see Common Parameters (p. 583).

ResourceName

The Amazon DocumentDB resource that the tags are added to. This value is an Amazon ResourceName .

Type: String

Required: YesTags.Tag.N

The tags to be assigned to the Amazon DocumentDB resource.

Type: Array of Tag (p. 579) objects

Required: Yes

ErrorsFor information about the errors that are common to all actions, see Common Errors (p. 581).

DBClusterNotFoundFault

DBClusterIdentifier doesn't refer to an existing cluster.

HTTP Status Code: 404DBInstanceNotFound

DBInstanceIdentifier doesn't refer to an existing instance.

HTTP Status Code: 404DBSnapshotNotFound

DBSnapshotIdentifier doesn't refer to an existing snapshot.

HTTP Status Code: 404

See AlsoFor more information about using this API in one of the language-specific AWS SDKs, see the following:

• AWS Command Line Interface• AWS SDK for .NET• AWS SDK for C++• AWS SDK for Go• AWS SDK for Java

431

https://docs.aws.amazon.com/goto/aws-cli/docdb-2014-10-31/AddTagsToResource

https://docs.aws.amazon.com/goto/DotNetSDKV3/docdb-2014-10-31/AddTagsToResource

https://docs.aws.amazon.com/goto/SdkForCpp/docdb-2014-10-31/AddTagsToResource

https://docs.aws.amazon.com/goto/SdkForGoV1/docdb-2014-10-31/AddTagsToResource

https://docs.aws.amazon.com/goto/SdkForJava/docdb-2014-10-31/AddTagsToResource

Amazon DocumentDB Guia do desenvolvedorAddTagsToResource

• AWS SDK for JavaScript• AWS SDK for PHP V3• AWS SDK for Python• AWS SDK for Ruby V3

432

https://docs.aws.amazon.com/goto/AWSJavaScriptSDK/docdb-2014-10-31/AddTagsToResource

https://docs.aws.amazon.com/goto/SdkForPHPV3/docdb-2014-10-31/AddTagsToResource

https://docs.aws.amazon.com/goto/boto3/docdb-2014-10-31/AddTagsToResource

https://docs.aws.amazon.com/goto/SdkForRubyV3/docdb-2014-10-31/AddTagsToResource

Amazon DocumentDB Guia do desenvolvedorApplyPendingMaintenanceAction

ApplyPendingMaintenanceActionApplies a pending maintenance action to a resource (for example, to an Amazon DocumentDB instance).


ApplyAction

The pending maintenance action to apply to this resource.

Valid values: system-update, db-upgrade

Type: String

Required: YesOptInType

A value that specifies the type of opt-in request or undoes an opt-in request. An opt-in request of typeimmediate can't be undone.

Valid values:• immediate - Apply the maintenance action immediately.• next-maintenance - Apply the maintenance action during the next maintenance window for the

resource.• undo-opt-in - Cancel any existing next-maintenance opt-in requests.

Type: String

Required: YesResourceIdentifier

The Amazon Resource Name (ARN) of the resource that the pending maintenance action applies to.

Type: String

Required: Yes

Response ElementsThe following element is returned by the service.

ResourcePendingMaintenanceActions

Represents the output of ApplyPendingMaintenanceAction (p. 433).

Type: ResourcePendingMaintenanceActions (p. 577) object


InvalidDBClusterStateFault

The cluster isn't in a valid state.

433

Amazon DocumentDB Guia do desenvolvedorApplyPendingMaintenanceAction

HTTP Status Code: 400InvalidDBInstanceState

The specified instance isn't in the available state.

HTTP Status Code: 400ResourceNotFoundFault

The specified resource ID was not found.



• AWS Command Line Interface• AWS SDK for .NET• AWS SDK for C++• AWS SDK for Go• AWS SDK for Java• AWS SDK for JavaScript• AWS SDK for PHP V3• AWS SDK for Python• AWS SDK for Ruby V3

434

https://docs.aws.amazon.com/goto/aws-cli/docdb-2014-10-31/ApplyPendingMaintenanceAction

https://docs.aws.amazon.com/goto/DotNetSDKV3/docdb-2014-10-31/ApplyPendingMaintenanceAction

https://docs.aws.amazon.com/goto/SdkForCpp/docdb-2014-10-31/ApplyPendingMaintenanceAction

https://docs.aws.amazon.com/goto/SdkForGoV1/docdb-2014-10-31/ApplyPendingMaintenanceAction

https://docs.aws.amazon.com/goto/SdkForJava/docdb-2014-10-31/ApplyPendingMaintenanceAction

https://docs.aws.amazon.com/goto/AWSJavaScriptSDK/docdb-2014-10-31/ApplyPendingMaintenanceAction

https://docs.aws.amazon.com/goto/SdkForPHPV3/docdb-2014-10-31/ApplyPendingMaintenanceAction

https://docs.aws.amazon.com/goto/boto3/docdb-2014-10-31/ApplyPendingMaintenanceAction

https://docs.aws.amazon.com/goto/SdkForRubyV3/docdb-2014-10-31/ApplyPendingMaintenanceAction

Amazon DocumentDB Guia do desenvolvedorCopyDBClusterParameterGroup

CopyDBClusterParameterGroupCopies the specified cluster parameter group.


SourceDBClusterParameterGroupIdentifier

The identifier or Amazon Resource Name (ARN) for the source cluster parameter group.

Constraints:• Must specify a valid cluster parameter group.• If the source cluster parameter group is in the same AWS Region as the copy, specify a valid

parameter group identifier; for example, my-db-cluster-param-group, or a valid ARN.• If the source parameter group is in a different AWS Region than the copy, specify a valid cluster

parameter group ARN; for example, arn:aws:rds:us-east-1:123456789012:sample-cluster:sample-parameter-group.

Type: String

Required: YesTargetDBClusterParameterGroupDescription

A description for the copied cluster parameter group.

Type: String

Required: YesTargetDBClusterParameterGroupIdentifier

The identifier for the copied cluster parameter group.

Constraints:• Cannot be null, empty, or blank.• Must contain from 1 to 255 letters, numbers, or hyphens.• The first character must be a letter.• Cannot end with a hyphen or contain two consecutive hyphens.

Example: my-cluster-param-group1

Type: String


The tags that are to be assigned to the parameter group.


Required: No


435

Amazon DocumentDB Guia do desenvolvedorCopyDBClusterParameterGroup

DBClusterParameterGroup

Detailed information about a cluster parameter group.

Type: DBClusterParameterGroup (p. 545) object


DBParameterGroupAlreadyExists

A parameter group with the same name already exists.

HTTP Status Code: 400DBParameterGroupNotFound

DBParameterGroupName doesn't refer to an existing parameter group.

HTTP Status Code: 404DBParameterGroupQuotaExceeded

This request would cause you to exceed the allowed number of parameter groups.




436

https://docs.aws.amazon.com/goto/aws-cli/docdb-2014-10-31/CopyDBClusterParameterGroup

https://docs.aws.amazon.com/goto/DotNetSDKV3/docdb-2014-10-31/CopyDBClusterParameterGroup

https://docs.aws.amazon.com/goto/SdkForCpp/docdb-2014-10-31/CopyDBClusterParameterGroup

https://docs.aws.amazon.com/goto/SdkForGoV1/docdb-2014-10-31/CopyDBClusterParameterGroup

https://docs.aws.amazon.com/goto/SdkForJava/docdb-2014-10-31/CopyDBClusterParameterGroup

https://docs.aws.amazon.com/goto/AWSJavaScriptSDK/docdb-2014-10-31/CopyDBClusterParameterGroup

https://docs.aws.amazon.com/goto/SdkForPHPV3/docdb-2014-10-31/CopyDBClusterParameterGroup

https://docs.aws.amazon.com/goto/boto3/docdb-2014-10-31/CopyDBClusterParameterGroup

https://docs.aws.amazon.com/goto/SdkForRubyV3/docdb-2014-10-31/CopyDBClusterParameterGroup

Amazon DocumentDB Guia do desenvolvedorCopyDBClusterSnapshot

CopyDBClusterSnapshotCopies a snapshot of a cluster.

To copy a cluster snapshot from a shared manual cluster snapshot,SourceDBClusterSnapshotIdentifier must be the Amazon Resource Name (ARN) of the sharedcluster snapshot. You can only copy a shared DB cluster snapshot, whether encrypted or not, in the sameAWS Region.

To cancel the copy operation after it is in progress, delete the target cluster snapshot identified byTargetDBClusterSnapshotIdentifier while that cluster snapshot is in the copying status.


SourceDBClusterSnapshotIdentifier

The identifier of the cluster snapshot to copy. This parameter is not case sensitive.

Constraints:• Must specify a valid system snapshot in the available state.• If the source snapshot is in the same AWS Region as the copy, specify a valid snapshot identifier.• If the source snapshot is in a different AWS Region than the copy, specify a valid cluster snapshot

ARN.

Example: my-cluster-snapshot1

Type: String

Required: YesTargetDBClusterSnapshotIdentifier

The identifier of the new cluster snapshot to create from the source cluster snapshot. This parameter isnot case sensitive.

Constraints:• Must contain from 1 to 63 letters, numbers, or hyphens.• The first character must be a letter.• Cannot end with a hyphen or contain two consecutive hyphens.


Type: String

Required: YesCopyTags

Set to true to copy all tags from the source cluster snapshot to the target cluster snapshot, andotherwise false. The default is false.

Type: Boolean

Required: NoKmsKeyId

The AWS KMS key ID for an encrypted cluster snapshot. The AWS KMS key ID is the AmazonResource Name (ARN), AWS KMS key identifier, or the AWS KMS key alias for the AWS KMSencryption key.

437


If you copy an encrypted cluster snapshot from your AWS account, you can specify a value forKmsKeyId to encrypt the copy with a new AWS KMS encryption key. If you don't specify a value forKmsKeyId, then the copy of the cluster snapshot is encrypted with the same AWS KMS key as thesource cluster snapshot.

If you copy an encrypted cluster snapshot that is shared from another AWS account, then you mustspecify a value for KmsKeyId.

To copy an encrypted cluster snapshot to another AWS Region, set KmsKeyId to the AWS KMSkey ID that you want to use to encrypt the copy of the cluster snapshot in the destination Region.AWS KMS encryption keys are specific to the AWS Region that they are created in, and you can't useencryption keys from one AWS Region in another AWS Region.

If you copy an unencrypted cluster snapshot and specify a value for the KmsKeyId parameter, an erroris returned.

Type: String

Required: NoPreSignedUrl

The URL that contains a Signature Version 4 signed request for the CopyDBClusterSnapshotAPI action in the AWS Region that contains the source cluster snapshot to copy. You must use thePreSignedUrl parameter when copying a cluster snapshot from another AWS Region.

If you are using an AWS SDK tool or the AWS CLI, you can specify SourceRegion (or --source-region for the AWS CLI) instead of specifying PreSignedUrl manually. Specifying SourceRegionautogenerates a pre-signed URL that is a valid request for the operation that can be executed in thesource AWS Region.

The presigned URL must be a valid request for the CopyDBClusterSnapshot API action that canbe executed in the source AWS Region that contains the cluster snapshot to be copied. The presignedURL request must contain the following parameter values:• SourceRegion - The ID of the region that contains the snapshot to be copied.• SourceDBClusterSnapshotIdentifier - The identifier for the the encrypted cluster snapshot to

be copied. This identifier must be in the Amazon Resource Name (ARN) format for the source AWSRegion. For example, if you are copying an encrypted cluster snapshot from the us-east-1 AWSRegion, then your SourceDBClusterSnapshotIdentifier looks something like the following:arn:aws:rds:us-east-1:12345678012:sample-cluster:sample-cluster-snapshot.

• TargetDBClusterSnapshotIdentifier - The identifier for the new cluster snapshot to becreated. This parameter isn't case sensitive.

Type: String

Required: NoTags.Tag.N

The tags to be assigned to the cluster snapshot.


Required: No


438


DBClusterSnapshot

Detailed information about a cluster snapshot.

Type: DBClusterSnapshot (p. 547) object


DBClusterSnapshotAlreadyExistsFault

You already have a cluster snapshot with the given identifier.

HTTP Status Code: 400DBClusterSnapshotNotFoundFault

DBClusterSnapshotIdentifier doesn't refer to an existing cluster snapshot.

HTTP Status Code: 404InvalidDBClusterSnapshotStateFault

The provided value isn't a valid cluster snapshot state.

HTTP Status Code: 400InvalidDBClusterStateFault


HTTP Status Code: 400KMSKeyNotAccessibleFault

An error occurred when accessing an AWS KMS key.

HTTP Status Code: 400SnapshotQuotaExceeded

The request would cause you to exceed the allowed number of snapshots.




439

https://docs.aws.amazon.com/goto/aws-cli/docdb-2014-10-31/CopyDBClusterSnapshot

https://docs.aws.amazon.com/goto/DotNetSDKV3/docdb-2014-10-31/CopyDBClusterSnapshot

https://docs.aws.amazon.com/goto/SdkForCpp/docdb-2014-10-31/CopyDBClusterSnapshot

https://docs.aws.amazon.com/goto/SdkForGoV1/docdb-2014-10-31/CopyDBClusterSnapshot

https://docs.aws.amazon.com/goto/SdkForJava/docdb-2014-10-31/CopyDBClusterSnapshot

https://docs.aws.amazon.com/goto/AWSJavaScriptSDK/docdb-2014-10-31/CopyDBClusterSnapshot

https://docs.aws.amazon.com/goto/SdkForPHPV3/docdb-2014-10-31/CopyDBClusterSnapshot

https://docs.aws.amazon.com/goto/boto3/docdb-2014-10-31/CopyDBClusterSnapshot

https://docs.aws.amazon.com/goto/SdkForRubyV3/docdb-2014-10-31/CopyDBClusterSnapshot


440

Amazon DocumentDB Guia do desenvolvedorCreateDBCluster

CreateDBClusterCreates a new Amazon DocumentDB cluster.


DBClusterIdentifier

The cluster identifier. This parameter is stored as a lowercase string.


Example: my-cluster

Type: String

Required: YesEngine

The name of the database engine to be used for this cluster.

Valid values: docdb

Type: String

Required: YesMasterUsername

The name of the master user for the cluster.

Constraints:• Must be from 1 to 63 letters or numbers.• The first character must be a letter.• Cannot be a reserved word for the chosen database engine.

Type: String

Required: YesMasterUserPassword

The password for the master database user. This password can contain any printable ASCII characterexcept forward slash (/), double quote ("), or the "at" symbol (@).

Constraints: Must contain from 8 to 100 characters.

Type: String

Required: YesAvailabilityZones.AvailabilityZone.N

A list of Amazon EC2 Availability Zones that instances in the cluster can be created in.

441


Type: Array of strings

Required: NoBackupRetentionPeriod

The number of days for which automated backups are retained. You must specify a minimum value of1.

Default: 1

Constraints:• Must be a value from 1 to 35.

Type: Integer

Required: NoDBClusterParameterGroupName

The name of the cluster parameter group to associate with this cluster.

Type: String

Required: NoDBSubnetGroupName

A subnet group to associate with this cluster.

Constraints: Must match the name of an existing DBSubnetGroup. Must not be default.

Example: mySubnetgroup

Type: String

Required: NoDeletionProtection

Specifies whether this cluster can be deleted. If DeletionProtection is enabled, the cluster cannotbe deleted unless it is modified and DeletionProtection is disabled. DeletionProtectionprotects clusters from being accidentally deleted.

Type: Boolean

Required: NoEnableCloudwatchLogsExports.member.N

A list of log types that need to be enabled for exporting to Amazon CloudWatch Logs. You can enableaudit logs or profiler logs. For more information, see Auditing Amazon DocumentDB Events and Profiling Amazon DocumentDB Operations.


Required: NoEngineVersion

The version number of the database engine to use. The --engine-version will default to the latest majorengine version. For production workloads, we recommend explicitly declaring this parameter with theintended major engine version.

Type: String

442

https://docs.aws.amazon.com/documentdb/latest/developerguide/event-auditing.html

https://docs.aws.amazon.com/documentdb/latest/developerguide/profiling.html




The AWS KMS key identifier for an encrypted cluster.

The AWS KMS key identifier is the Amazon Resource Name (ARN) for the AWS KMS encryption key.If you are creating a cluster using the same AWS account that owns the AWS KMS encryption keythat is used to encrypt the new cluster, you can use the AWS KMS key alias instead of the ARN for theAWS KMS encryption key.

If an encryption key is not specified in KmsKeyId:• If the StorageEncrypted parameter is true, Amazon DocumentDB uses your default encryption

key.

AWS KMS creates the default encryption key for your AWS account. Your AWS account has a differentdefault encryption key for each AWS Region.

Type: String

Required: NoPort

The port number on which the instances in the cluster accept connections.

Type: Integer

Required: NoPreferredBackupWindow

The daily time range during which automated backups are created if automated backups are enabledusing the BackupRetentionPeriod parameter.

The default is a 30-minute window selected at random from an 8-hour block of time for each AWSRegion.

Constraints:• Must be in the format hh24:mi-hh24:mi.• Must be in Universal Coordinated Time (UTC).• Must not conflict with the preferred maintenance window.• Must be at least 30 minutes.

Type: String

Required: NoPreferredMaintenanceWindow

The weekly time range during which system maintenance can occur, in Universal Coordinated Time(UTC).

Format: ddd:hh24:mi-ddd:hh24:mi

The default is a 30-minute window selected at random from an 8-hour block of time for each AWSRegion, occurring on a random day of the week.

Valid days: Mon, Tue, Wed, Thu, Fri, Sat, Sun

Constraints: Minimum 30-minute window.

Type: String

443


Required: NoPreSignedUrl

Not currently supported.

Type: String

Required: NoStorageEncrypted

Specifies whether the cluster is encrypted.

Type: Boolean


The tags to be assigned to the cluster.


Required: NoVpcSecurityGroupIds.VpcSecurityGroupId.N

A list of EC2 VPC security groups to associate with this cluster.


Required: No


DBCluster

Detailed information about a cluster.

Type: DBCluster (p. 539) object


DBClusterAlreadyExistsFault

You already have a cluster with the given identifier.

HTTP Status Code: 400DBClusterNotFoundFault


HTTP Status Code: 404DBClusterParameterGroupNotFound

DBClusterParameterGroupName doesn't refer to an existing cluster parameter group.

444


HTTP Status Code: 404DBClusterQuotaExceededFault

The cluster can't be created because you have reached the maximum allowed quota of clusters.



HTTP Status Code: 404DBSubnetGroupDoesNotCoverEnoughAZs

Subnets in the subnet group should cover at least two Availability Zones unless there is only oneAvailability Zone.

HTTP Status Code: 400DBSubnetGroupNotFoundFault

DBSubnetGroupName doesn't refer to an existing subnet group.

HTTP Status Code: 404InsufficientStorageClusterCapacity

There is not enough storage available for the current action. You might be able to resolve this error byupdating your subnet group to use different Availability Zones that have more storage available.





HTTP Status Code: 400InvalidDBSubnetGroupStateFault

The subnet group can't be deleted because it's in use.

HTTP Status Code: 400InvalidSubnet

The requested subnet is not valid, or multiple subnets were requested that are not all in a commonvirtual private cloud (VPC).

HTTP Status Code: 400InvalidVPCNetworkStateFault

The subnet group doesn't cover all Availability Zones after it is created because of changes that weremade.



445


HTTP Status Code: 400StorageQuotaExceeded

The request would cause you to exceed the allowed amount of storage available across all instances.




446

https://docs.aws.amazon.com/goto/aws-cli/docdb-2014-10-31/CreateDBCluster

https://docs.aws.amazon.com/goto/DotNetSDKV3/docdb-2014-10-31/CreateDBCluster

https://docs.aws.amazon.com/goto/SdkForCpp/docdb-2014-10-31/CreateDBCluster

https://docs.aws.amazon.com/goto/SdkForGoV1/docdb-2014-10-31/CreateDBCluster

https://docs.aws.amazon.com/goto/SdkForJava/docdb-2014-10-31/CreateDBCluster

https://docs.aws.amazon.com/goto/AWSJavaScriptSDK/docdb-2014-10-31/CreateDBCluster

https://docs.aws.amazon.com/goto/SdkForPHPV3/docdb-2014-10-31/CreateDBCluster

https://docs.aws.amazon.com/goto/boto3/docdb-2014-10-31/CreateDBCluster

https://docs.aws.amazon.com/goto/SdkForRubyV3/docdb-2014-10-31/CreateDBCluster

Amazon DocumentDB Guia do desenvolvedorCreateDBClusterParameterGroup

CreateDBClusterParameterGroupCreates a new cluster parameter group.

Parameters in a cluster parameter group apply to all of the instances in a cluster.

A cluster parameter group is initially created with the default parameters for the database engine usedby instances in the cluster. In Amazon DocumentDB, you cannot make modifications directly to thedefault.docdb3.6 cluster parameter group. If your Amazon DocumentDB cluster is using the defaultcluster parameter group and you want to modify a value in it, you must first create a new parameter groupor copy an existing parameter group, modify it, and then apply the modified parameter group to yourcluster. For the new cluster parameter group and associated settings to take effect, you must then rebootthe instances in the cluster without failover. For more information, see Modifying Amazon DocumentDBCluster Parameter Groups.


DBClusterParameterGroupName

The name of the cluster parameter group.

Constraints:• Must not match the name of an existing DBClusterParameterGroup.

Note

This value is stored as a lowercase string.

Type: String

Required: YesDBParameterGroupFamily

The cluster parameter group family name.

Type: String

Required: YesDescription

The description for the cluster parameter group.

Type: String


The tags to be assigned to the cluster parameter group.


Required: No


447

https://docs.aws.amazon.com/documentdb/latest/developerguide/cluster_parameter_group-create.html

https://docs.aws.amazon.com/documentdb/latest/developerguide/cluster_parameter_group-copy.html

https://docs.aws.amazon.com/documentdb/latest/developerguide/cluster_parameter_group-modify.html

https://docs.aws.amazon.com/documentdb/latest/developerguide/cluster_parameter_group-modify.html

Amazon DocumentDB Guia do desenvolvedorCreateDBClusterParameterGroup

DBClusterParameterGroup

Detailed information about a cluster parameter group.

Type: DBClusterParameterGroup (p. 545) object


DBParameterGroupAlreadyExists

A parameter group with the same name already exists.

HTTP Status Code: 400DBParameterGroupQuotaExceeded

This request would cause you to exceed the allowed number of parameter groups.




448

https://docs.aws.amazon.com/goto/aws-cli/docdb-2014-10-31/CreateDBClusterParameterGroup

https://docs.aws.amazon.com/goto/DotNetSDKV3/docdb-2014-10-31/CreateDBClusterParameterGroup

https://docs.aws.amazon.com/goto/SdkForCpp/docdb-2014-10-31/CreateDBClusterParameterGroup

https://docs.aws.amazon.com/goto/SdkForGoV1/docdb-2014-10-31/CreateDBClusterParameterGroup

https://docs.aws.amazon.com/goto/SdkForJava/docdb-2014-10-31/CreateDBClusterParameterGroup

https://docs.aws.amazon.com/goto/AWSJavaScriptSDK/docdb-2014-10-31/CreateDBClusterParameterGroup

https://docs.aws.amazon.com/goto/SdkForPHPV3/docdb-2014-10-31/CreateDBClusterParameterGroup

https://docs.aws.amazon.com/goto/boto3/docdb-2014-10-31/CreateDBClusterParameterGroup

https://docs.aws.amazon.com/goto/SdkForRubyV3/docdb-2014-10-31/CreateDBClusterParameterGroup

Amazon DocumentDB Guia do desenvolvedorCreateDBClusterSnapshot

CreateDBClusterSnapshotCreates a snapshot of a cluster.


DBClusterIdentifier

The identifier of the cluster to create a snapshot for. This parameter is not case sensitive.

Constraints:• Must match the identifier of an existing DBCluster.

Example: my-cluster

Type: String

Required: YesDBClusterSnapshotIdentifier

The identifier of the cluster snapshot. This parameter is stored as a lowercase string.



Type: String


The tags to be assigned to the cluster snapshot.


Required: No


DBClusterSnapshot




449

Amazon DocumentDB Guia do desenvolvedorCreateDBClusterSnapshot



HTTP Status Code: 404DBClusterSnapshotAlreadyExistsFault











450

https://docs.aws.amazon.com/goto/aws-cli/docdb-2014-10-31/CreateDBClusterSnapshot

https://docs.aws.amazon.com/goto/DotNetSDKV3/docdb-2014-10-31/CreateDBClusterSnapshot

https://docs.aws.amazon.com/goto/SdkForCpp/docdb-2014-10-31/CreateDBClusterSnapshot

https://docs.aws.amazon.com/goto/SdkForGoV1/docdb-2014-10-31/CreateDBClusterSnapshot

https://docs.aws.amazon.com/goto/SdkForJava/docdb-2014-10-31/CreateDBClusterSnapshot

https://docs.aws.amazon.com/goto/AWSJavaScriptSDK/docdb-2014-10-31/CreateDBClusterSnapshot

https://docs.aws.amazon.com/goto/SdkForPHPV3/docdb-2014-10-31/CreateDBClusterSnapshot

https://docs.aws.amazon.com/goto/boto3/docdb-2014-10-31/CreateDBClusterSnapshot

https://docs.aws.amazon.com/goto/SdkForRubyV3/docdb-2014-10-31/CreateDBClusterSnapshot

Amazon DocumentDB Guia do desenvolvedorCreateDBInstance

CreateDBInstanceCreates a new instance.


DBClusterIdentifier

The identifier of the cluster that the instance will belong to.

Type: String

Required: YesDBInstanceClass

The compute and memory capacity of the instance; for example, db.r5.large.

Type: String

Required: YesDBInstanceIdentifier

The instance identifier. This parameter is stored as a lowercase string.


Example: mydbinstance

Type: String

Required: YesEngine

The name of the database engine to be used for this instance.

Valid value: docdb

Type: String

Required: YesAutoMinorVersionUpgrade

Indicates that minor engine upgrades are applied automatically to the instance during the maintenancewindow.

Default: true

Type: Boolean

Required: NoAvailabilityZone

The Amazon EC2 Availability Zone that the instance is created in.

451


Default: A random, system-chosen Availability Zone in the endpoint's AWS Region.

Example: us-east-1d

Type: String


The time range each week during which system maintenance can occur, in Universal CoordinatedTime (UTC).





Type: String

Required: NoPromotionTier

A value that specifies the order in which an Amazon DocumentDB replica is promoted to the primaryinstance after a failure of the existing primary instance.

Default: 1

Valid values: 0-15

Type: Integer


The tags to be assigned to the instance. You can assign up to 10 tags to an instance.


Required: No


DBInstance

Detailed information about an instance.

Type: DBInstance (p. 554) object


452


AuthorizationNotFound

The specified CIDR IP or Amazon EC2 security group isn't authorized for the specified security group.

Amazon DocumentDB also might not be authorized to perform necessary actions on your behalf usingIAM.



HTTP Status Code: 404DBInstanceAlreadyExists

You already have a instance with the given identifier.



HTTP Status Code: 404DBSecurityGroupNotFound

DBSecurityGroupName doesn't refer to an existing security group.





HTTP Status Code: 404InstanceQuotaExceeded

The request would cause you to exceed the allowed number of instances.

HTTP Status Code: 400InsufficientDBInstanceCapacity

The specified instance class isn't available in the specified Availability Zone.





453








HTTP Status Code: 400StorageTypeNotSupported

Storage of the specified StorageType can't be associated with the DB instance.




454

https://docs.aws.amazon.com/goto/aws-cli/docdb-2014-10-31/CreateDBInstance

https://docs.aws.amazon.com/goto/DotNetSDKV3/docdb-2014-10-31/CreateDBInstance

https://docs.aws.amazon.com/goto/SdkForCpp/docdb-2014-10-31/CreateDBInstance

https://docs.aws.amazon.com/goto/SdkForGoV1/docdb-2014-10-31/CreateDBInstance

https://docs.aws.amazon.com/goto/SdkForJava/docdb-2014-10-31/CreateDBInstance

https://docs.aws.amazon.com/goto/AWSJavaScriptSDK/docdb-2014-10-31/CreateDBInstance

https://docs.aws.amazon.com/goto/SdkForPHPV3/docdb-2014-10-31/CreateDBInstance

https://docs.aws.amazon.com/goto/boto3/docdb-2014-10-31/CreateDBInstance

https://docs.aws.amazon.com/goto/SdkForRubyV3/docdb-2014-10-31/CreateDBInstance

Amazon DocumentDB Guia do desenvolvedorCreateDBSubnetGroup

CreateDBSubnetGroupCreates a new subnet group. subnet groups must contain at least one subnet in at least two AvailabilityZones in the AWS Region.


DBSubnetGroupDescription

The description for the subnet group.

Type: String

Required: YesDBSubnetGroupName

The name for the subnet group. This value is stored as a lowercase string.

Constraints: Must contain no more than 255 letters, numbers, periods, underscores, spaces, orhyphens. Must not be default.


Type: String

Required: YesSubnetIds.SubnetIdentifier.N

The Amazon EC2 subnet IDs for the subnet group.



The tags to be assigned to the subnet group.


Required: No


DBSubnetGroup

Detailed information about a subnet group.

Type: DBSubnetGroup (p. 559) object


455

Amazon DocumentDB Guia do desenvolvedorCreateDBSubnetGroup

DBSubnetGroupAlreadyExists

DBSubnetGroupName is already being used by an existing subnet group.



HTTP Status Code: 400DBSubnetGroupQuotaExceeded

The request would cause you to exceed the allowed number of subnet groups.

HTTP Status Code: 400DBSubnetQuotaExceededFault

The request would cause you to exceed the allowed number of subnets in a subnet group.






456

https://docs.aws.amazon.com/goto/aws-cli/docdb-2014-10-31/CreateDBSubnetGroup

https://docs.aws.amazon.com/goto/DotNetSDKV3/docdb-2014-10-31/CreateDBSubnetGroup

https://docs.aws.amazon.com/goto/SdkForCpp/docdb-2014-10-31/CreateDBSubnetGroup

https://docs.aws.amazon.com/goto/SdkForGoV1/docdb-2014-10-31/CreateDBSubnetGroup

https://docs.aws.amazon.com/goto/SdkForJava/docdb-2014-10-31/CreateDBSubnetGroup

https://docs.aws.amazon.com/goto/AWSJavaScriptSDK/docdb-2014-10-31/CreateDBSubnetGroup

https://docs.aws.amazon.com/goto/SdkForPHPV3/docdb-2014-10-31/CreateDBSubnetGroup

https://docs.aws.amazon.com/goto/boto3/docdb-2014-10-31/CreateDBSubnetGroup

https://docs.aws.amazon.com/goto/SdkForRubyV3/docdb-2014-10-31/CreateDBSubnetGroup

Amazon DocumentDB Guia do desenvolvedorDeleteDBCluster

DeleteDBClusterDeletes a previously provisioned cluster. When you delete a cluster, all automated backups for that clusterare deleted and can't be recovered. Manual DB cluster snapshots of the specified cluster are not deleted.


DBClusterIdentifier

The cluster identifier for the cluster to be deleted. This parameter isn't case sensitive.

Constraints:• Must match an existing DBClusterIdentifier.

Type: String

Required: YesFinalDBSnapshotIdentifier

The cluster snapshot identifier of the new cluster snapshot created when SkipFinalSnapshot is setto false.

Note

Specifying this parameter and also setting the SkipFinalShapshot parameter to trueresults in an error.

Constraints:• Must be from 1 to 255 letters, numbers, or hyphens.• The first character must be a letter.• Cannot end with a hyphen or contain two consecutive hyphens.

Type: String

Required: NoSkipFinalSnapshot

Determines whether a final cluster snapshot is created before the cluster is deleted. If true isspecified, no cluster snapshot is created. If false is specified, a cluster snapshot is created before theDB cluster is deleted.

Note

If SkipFinalSnapshot is false, you must specify a FinalDBSnapshotIdentifierparameter.

Default: false

Type: Boolean

Required: No


457

Amazon DocumentDB Guia do desenvolvedorDeleteDBCluster

DBCluster






HTTP Status Code: 404DBClusterSnapshotAlreadyExistsFault











458

https://docs.aws.amazon.com/goto/aws-cli/docdb-2014-10-31/DeleteDBCluster

https://docs.aws.amazon.com/goto/DotNetSDKV3/docdb-2014-10-31/DeleteDBCluster

https://docs.aws.amazon.com/goto/SdkForCpp/docdb-2014-10-31/DeleteDBCluster

https://docs.aws.amazon.com/goto/SdkForGoV1/docdb-2014-10-31/DeleteDBCluster

https://docs.aws.amazon.com/goto/SdkForJava/docdb-2014-10-31/DeleteDBCluster

https://docs.aws.amazon.com/goto/AWSJavaScriptSDK/docdb-2014-10-31/DeleteDBCluster

https://docs.aws.amazon.com/goto/SdkForPHPV3/docdb-2014-10-31/DeleteDBCluster

https://docs.aws.amazon.com/goto/boto3/docdb-2014-10-31/DeleteDBCluster

https://docs.aws.amazon.com/goto/SdkForRubyV3/docdb-2014-10-31/DeleteDBCluster

Amazon DocumentDB Guia do desenvolvedorDeleteDBClusterParameterGroup

DeleteDBClusterParameterGroupDeletes a specified cluster parameter group. The cluster parameter group to be deleted can't be associatedwith any clusters.



The name of the cluster parameter group.

Constraints:• Must be the name of an existing cluster parameter group.• You can't delete a default cluster parameter group.• Cannot be associated with any clusters.

Type: String

Required: Yes


DBParameterGroupNotFound


HTTP Status Code: 404InvalidDBParameterGroupState

The parameter group is in use, or it is in a state that is not valid. If you are trying to delete theparameter group, you can't delete it when the parameter group is in this state.




459

https://docs.aws.amazon.com/goto/aws-cli/docdb-2014-10-31/DeleteDBClusterParameterGroup

https://docs.aws.amazon.com/goto/DotNetSDKV3/docdb-2014-10-31/DeleteDBClusterParameterGroup

https://docs.aws.amazon.com/goto/SdkForCpp/docdb-2014-10-31/DeleteDBClusterParameterGroup

https://docs.aws.amazon.com/goto/SdkForGoV1/docdb-2014-10-31/DeleteDBClusterParameterGroup

https://docs.aws.amazon.com/goto/SdkForJava/docdb-2014-10-31/DeleteDBClusterParameterGroup

https://docs.aws.amazon.com/goto/AWSJavaScriptSDK/docdb-2014-10-31/DeleteDBClusterParameterGroup

https://docs.aws.amazon.com/goto/SdkForPHPV3/docdb-2014-10-31/DeleteDBClusterParameterGroup

https://docs.aws.amazon.com/goto/boto3/docdb-2014-10-31/DeleteDBClusterParameterGroup

https://docs.aws.amazon.com/goto/SdkForRubyV3/docdb-2014-10-31/DeleteDBClusterParameterGroup

Amazon DocumentDB Guia do desenvolvedorDeleteDBClusterSnapshot

DeleteDBClusterSnapshotDeletes a cluster snapshot. If the snapshot is being copied, the copy operation is terminated.

Note

The cluster snapshot must be in the available state to be deleted.


DBClusterSnapshotIdentifier

The identifier of the cluster snapshot to delete.

Constraints: Must be the name of an existing cluster snapshot in the available state.

Type: String

Required: Yes


DBClusterSnapshot




DBClusterSnapshotNotFoundFault






• AWS Command Line Interface• AWS SDK for .NET• AWS SDK for C++• AWS SDK for Go

460

https://docs.aws.amazon.com/goto/aws-cli/docdb-2014-10-31/DeleteDBClusterSnapshot

https://docs.aws.amazon.com/goto/DotNetSDKV3/docdb-2014-10-31/DeleteDBClusterSnapshot

https://docs.aws.amazon.com/goto/SdkForCpp/docdb-2014-10-31/DeleteDBClusterSnapshot

https://docs.aws.amazon.com/goto/SdkForGoV1/docdb-2014-10-31/DeleteDBClusterSnapshot

Amazon DocumentDB Guia do desenvolvedorDeleteDBClusterSnapshot

• AWS SDK for Java• AWS SDK for JavaScript• AWS SDK for PHP V3• AWS SDK for Python• AWS SDK for Ruby V3

461

https://docs.aws.amazon.com/goto/SdkForJava/docdb-2014-10-31/DeleteDBClusterSnapshot

https://docs.aws.amazon.com/goto/AWSJavaScriptSDK/docdb-2014-10-31/DeleteDBClusterSnapshot

https://docs.aws.amazon.com/goto/SdkForPHPV3/docdb-2014-10-31/DeleteDBClusterSnapshot

https://docs.aws.amazon.com/goto/boto3/docdb-2014-10-31/DeleteDBClusterSnapshot

https://docs.aws.amazon.com/goto/SdkForRubyV3/docdb-2014-10-31/DeleteDBClusterSnapshot

Amazon DocumentDB Guia do desenvolvedorDeleteDBInstance

DeleteDBInstanceDeletes a previously provisioned instance.


DBInstanceIdentifier

The instance identifier for the instance to be deleted. This parameter isn't case sensitive.

Constraints:• Must match the name of an existing instance.

Type: String

Required: Yes


DBInstance




DBInstanceNotFound


HTTP Status Code: 404DBSnapshotAlreadyExists

DBSnapshotIdentifier is already being used by an existing snapshot.







462

Amazon DocumentDB Guia do desenvolvedorDeleteDBInstance




463

https://docs.aws.amazon.com/goto/aws-cli/docdb-2014-10-31/DeleteDBInstance

https://docs.aws.amazon.com/goto/DotNetSDKV3/docdb-2014-10-31/DeleteDBInstance

https://docs.aws.amazon.com/goto/SdkForCpp/docdb-2014-10-31/DeleteDBInstance

https://docs.aws.amazon.com/goto/SdkForGoV1/docdb-2014-10-31/DeleteDBInstance

https://docs.aws.amazon.com/goto/SdkForJava/docdb-2014-10-31/DeleteDBInstance

https://docs.aws.amazon.com/goto/AWSJavaScriptSDK/docdb-2014-10-31/DeleteDBInstance

https://docs.aws.amazon.com/goto/SdkForPHPV3/docdb-2014-10-31/DeleteDBInstance

https://docs.aws.amazon.com/goto/boto3/docdb-2014-10-31/DeleteDBInstance

https://docs.aws.amazon.com/goto/SdkForRubyV3/docdb-2014-10-31/DeleteDBInstance

Amazon DocumentDB Guia do desenvolvedorDeleteDBSubnetGroup

DeleteDBSubnetGroupDeletes a subnet group.

Note

The specified database subnet group must not be associated with any DB instances.


DBSubnetGroupName

The name of the database subnet group to delete.

Note

You can't delete the default subnet group.

Constraints:

Must match the name of an existing DBSubnetGroup. Must not be default.


Type: String

Required: Yes


DBSubnetGroupNotFoundFault




HTTP Status Code: 400InvalidDBSubnetStateFault

The subnet isn't in the available state.



• AWS Command Line Interface• AWS SDK for .NET• AWS SDK for C++

464

https://docs.aws.amazon.com/goto/aws-cli/docdb-2014-10-31/DeleteDBSubnetGroup

https://docs.aws.amazon.com/goto/DotNetSDKV3/docdb-2014-10-31/DeleteDBSubnetGroup

https://docs.aws.amazon.com/goto/SdkForCpp/docdb-2014-10-31/DeleteDBSubnetGroup

Amazon DocumentDB Guia do desenvolvedorDeleteDBSubnetGroup

• AWS SDK for Go• AWS SDK for Java• AWS SDK for JavaScript• AWS SDK for PHP V3• AWS SDK for Python• AWS SDK for Ruby V3

465

https://docs.aws.amazon.com/goto/SdkForGoV1/docdb-2014-10-31/DeleteDBSubnetGroup

https://docs.aws.amazon.com/goto/SdkForJava/docdb-2014-10-31/DeleteDBSubnetGroup

https://docs.aws.amazon.com/goto/AWSJavaScriptSDK/docdb-2014-10-31/DeleteDBSubnetGroup

https://docs.aws.amazon.com/goto/SdkForPHPV3/docdb-2014-10-31/DeleteDBSubnetGroup

https://docs.aws.amazon.com/goto/boto3/docdb-2014-10-31/DeleteDBSubnetGroup

https://docs.aws.amazon.com/goto/SdkForRubyV3/docdb-2014-10-31/DeleteDBSubnetGroup

Amazon DocumentDB Guia do desenvolvedorDescribeCertificates

DescribeCertificatesReturns a list of certificate authority (CA) certificates provided by Amazon DocumentDB for this AWSaccount.


CertificateIdentifier

The user-supplied certificate identifier. If this parameter is specified, information for only the specifiedcertificate is returned. If this parameter is omitted, a list of up to MaxRecords certificates is returned.This parameter is not case sensitive.

Constraints• Must match an existing CertificateIdentifier.

Type: String

Required: NoFilters.Filter.N

This parameter is not currently supported.

Type: Array of Filter (p. 566) objects

Required: NoMarker

An optional pagination token provided by a previous DescribeCertificates request. If thisparameter is specified, the response includes only records beyond the marker, up to the valuespecified by MaxRecords.

Type: String

Required: NoMaxRecords

The maximum number of records to include in the response. If more records exist than the specifiedMaxRecords value, a pagination token called a marker is included in the response so that theremaining results can be retrieved.

Default: 100

Constraints:• Minimum: 20• Maximum: 100

Type: Integer

Required: No

Response ElementsThe following elements are returned by the service.

466

Amazon DocumentDB Guia do desenvolvedorDescribeCertificates

Certificates.Certificate.N

A list of certificates for this AWS account.

Type: Array of Certificate (p. 536) objectsMarker

An optional pagination token provided if the number of records retrieved is greater than MaxRecords.If this parameter is specified, the marker specifies the next record in the list. Including the value ofMarker in the next call to DescribeCertificates results in the next page of certificates.

Type: String


CertificateNotFound

CertificateIdentifier doesn't refer to an existing certificate.




467

https://docs.aws.amazon.com/goto/aws-cli/docdb-2014-10-31/DescribeCertificates

https://docs.aws.amazon.com/goto/DotNetSDKV3/docdb-2014-10-31/DescribeCertificates

https://docs.aws.amazon.com/goto/SdkForCpp/docdb-2014-10-31/DescribeCertificates

https://docs.aws.amazon.com/goto/SdkForGoV1/docdb-2014-10-31/DescribeCertificates

https://docs.aws.amazon.com/goto/SdkForJava/docdb-2014-10-31/DescribeCertificates

https://docs.aws.amazon.com/goto/AWSJavaScriptSDK/docdb-2014-10-31/DescribeCertificates

https://docs.aws.amazon.com/goto/SdkForPHPV3/docdb-2014-10-31/DescribeCertificates

https://docs.aws.amazon.com/goto/boto3/docdb-2014-10-31/DescribeCertificates

https://docs.aws.amazon.com/goto/SdkForRubyV3/docdb-2014-10-31/DescribeCertificates

Amazon DocumentDB Guia do desenvolvedorDescribeDBClusterParameterGroups

DescribeDBClusterParameterGroupsReturns a list of DBClusterParameterGroup descriptions. If a DBClusterParameterGroupNameparameter is specified, the list contains only the description of the specified cluster parameter group.



The name of a specific cluster parameter group to return details for.

Constraints:• If provided, must match the name of an existing DBClusterParameterGroup.

Type: String




Required: NoMarker

An optional pagination token provided by a previous request. If this parameter is specified, theresponse includes only records beyond the marker, up to the value specified by MaxRecords.

Type: String


The maximum number of records to include in the response. If more records exist than the specifiedMaxRecords value, a pagination token (marker) is included in the response so that the remainingresults can be retrieved.

Default: 100

Constraints: Minimum 20, maximum 100.

Type: Integer

Required: No


DBClusterParameterGroups.DBClusterParameterGroup.N

A list of cluster parameter groups.

Type: Array of DBClusterParameterGroup (p. 545) objects

468

Amazon DocumentDB Guia do desenvolvedorDescribeDBClusterParameterGroups

Marker


Type: String







469

https://docs.aws.amazon.com/goto/aws-cli/docdb-2014-10-31/DescribeDBClusterParameterGroups

https://docs.aws.amazon.com/goto/DotNetSDKV3/docdb-2014-10-31/DescribeDBClusterParameterGroups

https://docs.aws.amazon.com/goto/SdkForCpp/docdb-2014-10-31/DescribeDBClusterParameterGroups

https://docs.aws.amazon.com/goto/SdkForGoV1/docdb-2014-10-31/DescribeDBClusterParameterGroups

https://docs.aws.amazon.com/goto/SdkForJava/docdb-2014-10-31/DescribeDBClusterParameterGroups

https://docs.aws.amazon.com/goto/AWSJavaScriptSDK/docdb-2014-10-31/DescribeDBClusterParameterGroups

https://docs.aws.amazon.com/goto/SdkForPHPV3/docdb-2014-10-31/DescribeDBClusterParameterGroups

https://docs.aws.amazon.com/goto/boto3/docdb-2014-10-31/DescribeDBClusterParameterGroups

https://docs.aws.amazon.com/goto/SdkForRubyV3/docdb-2014-10-31/DescribeDBClusterParameterGroups

Amazon DocumentDB Guia do desenvolvedorDescribeDBClusterParameters

DescribeDBClusterParametersReturns the detailed parameter list for a particular cluster parameter group.



The name of a specific cluster parameter group to return parameter details for.

Constraints:• If provided, must match the name of an existing DBClusterParameterGroup.

Type: String

Required: YesFilters.Filter.N



Required: NoMarker


Type: String



Default: 100


Type: Integer

Required: NoSource

A value that indicates to return only parameters for a specific source. Parameter sources can beengine, service, or customer.

Type: String

Required: No


470

Amazon DocumentDB Guia do desenvolvedorDescribeDBClusterParameters

Marker


Type: StringParameters.Parameter.N

Provides a list of parameters for the cluster parameter group.

Type: Array of Parameter (p. 569) objects







471

https://docs.aws.amazon.com/goto/aws-cli/docdb-2014-10-31/DescribeDBClusterParameters

https://docs.aws.amazon.com/goto/DotNetSDKV3/docdb-2014-10-31/DescribeDBClusterParameters

https://docs.aws.amazon.com/goto/SdkForCpp/docdb-2014-10-31/DescribeDBClusterParameters

https://docs.aws.amazon.com/goto/SdkForGoV1/docdb-2014-10-31/DescribeDBClusterParameters

https://docs.aws.amazon.com/goto/SdkForJava/docdb-2014-10-31/DescribeDBClusterParameters

https://docs.aws.amazon.com/goto/AWSJavaScriptSDK/docdb-2014-10-31/DescribeDBClusterParameters

https://docs.aws.amazon.com/goto/SdkForPHPV3/docdb-2014-10-31/DescribeDBClusterParameters

https://docs.aws.amazon.com/goto/boto3/docdb-2014-10-31/DescribeDBClusterParameters

https://docs.aws.amazon.com/goto/SdkForRubyV3/docdb-2014-10-31/DescribeDBClusterParameters

Amazon DocumentDB Guia do desenvolvedorDescribeDBClusters

DescribeDBClustersReturns information about provisioned Amazon DocumentDB clusters. This API operation supportspagination. For certain management features such as cluster and instance lifecycle management, AmazonDocumentDB leverages operational technology that is shared with Amazon RDS and Amazon Neptune.Use the filterName=engine,Values=docdb filter parameter to return only Amazon DocumentDBclusters.


DBClusterIdentifier

The user-provided cluster identifier. If this parameter is specified, information from only the specificcluster is returned. This parameter isn't case sensitive.

Constraints:• If provided, must match an existing DBClusterIdentifier.

Type: String


A filter that specifies one or more clusters to describe.

Supported filters:• db-cluster-id - Accepts cluster identifiers and cluster Amazon Resource Names (ARNs). The

results list only includes information about the clusters identified by these ARNs.


Required: NoMarker


Type: String



Default: 100


Type: Integer

Required: No


472

Amazon DocumentDB Guia do desenvolvedorDescribeDBClusters

DBClusters.DBCluster.N

A list of clusters.

Type: Array of DBCluster (p. 539) objectsMarker


Type: String







473

https://docs.aws.amazon.com/goto/aws-cli/docdb-2014-10-31/DescribeDBClusters

https://docs.aws.amazon.com/goto/DotNetSDKV3/docdb-2014-10-31/DescribeDBClusters

https://docs.aws.amazon.com/goto/SdkForCpp/docdb-2014-10-31/DescribeDBClusters

https://docs.aws.amazon.com/goto/SdkForGoV1/docdb-2014-10-31/DescribeDBClusters

https://docs.aws.amazon.com/goto/SdkForJava/docdb-2014-10-31/DescribeDBClusters

https://docs.aws.amazon.com/goto/AWSJavaScriptSDK/docdb-2014-10-31/DescribeDBClusters

https://docs.aws.amazon.com/goto/SdkForPHPV3/docdb-2014-10-31/DescribeDBClusters

https://docs.aws.amazon.com/goto/boto3/docdb-2014-10-31/DescribeDBClusters

https://docs.aws.amazon.com/goto/SdkForRubyV3/docdb-2014-10-31/DescribeDBClusters

Amazon DocumentDB Guia do desenvolvedorDescribeDBClusterSnapshotAttributes

DescribeDBClusterSnapshotAttributesReturns a list of cluster snapshot attribute names and values for a manual DB cluster snapshot.

When you share snapshots with other AWS accounts, DescribeDBClusterSnapshotAttributesreturns the restore attribute and a list of IDs for the AWS accounts that are authorized to copy or restorethe manual cluster snapshot. If all is included in the list of values for the restore attribute, then themanual cluster snapshot is public and can be copied or restored by all AWS accounts.


DBClusterSnapshotIdentifier

The identifier for the cluster snapshot to describe the attributes for.

Type: String

Required: Yes


DBClusterSnapshotAttributesResult

Detailed information about the attributes that are associated with a cluster snapshot.

Type: DBClusterSnapshotAttributesResult (p. 551) object






• AWS Command Line Interface• AWS SDK for .NET• AWS SDK for C++• AWS SDK for Go• AWS SDK for Java• AWS SDK for JavaScript• AWS SDK for PHP V3• AWS SDK for Python

474

https://docs.aws.amazon.com/goto/aws-cli/docdb-2014-10-31/DescribeDBClusterSnapshotAttributes

https://docs.aws.amazon.com/goto/DotNetSDKV3/docdb-2014-10-31/DescribeDBClusterSnapshotAttributes

https://docs.aws.amazon.com/goto/SdkForCpp/docdb-2014-10-31/DescribeDBClusterSnapshotAttributes

https://docs.aws.amazon.com/goto/SdkForGoV1/docdb-2014-10-31/DescribeDBClusterSnapshotAttributes

https://docs.aws.amazon.com/goto/SdkForJava/docdb-2014-10-31/DescribeDBClusterSnapshotAttributes

https://docs.aws.amazon.com/goto/AWSJavaScriptSDK/docdb-2014-10-31/DescribeDBClusterSnapshotAttributes

https://docs.aws.amazon.com/goto/SdkForPHPV3/docdb-2014-10-31/DescribeDBClusterSnapshotAttributes

https://docs.aws.amazon.com/goto/boto3/docdb-2014-10-31/DescribeDBClusterSnapshotAttributes

Amazon DocumentDB Guia do desenvolvedorDescribeDBClusterSnapshotAttributes

• AWS SDK for Ruby V3

475

https://docs.aws.amazon.com/goto/SdkForRubyV3/docdb-2014-10-31/DescribeDBClusterSnapshotAttributes

Amazon DocumentDB Guia do desenvolvedorDescribeDBClusterSnapshots

DescribeDBClusterSnapshotsReturns information about cluster snapshots. This API operation supports pagination.


DBClusterIdentifier

The ID of the cluster to retrieve the list of cluster snapshots for. This parameter can't be used with theDBClusterSnapshotIdentifier parameter. This parameter is not case sensitive.

Constraints:• If provided, must match the identifier of an existing DBCluster.

Type: String

Required: NoDBClusterSnapshotIdentifier

A specific cluster snapshot identifier to describe. This parameter can't be used with theDBClusterIdentifier parameter. This value is stored as a lowercase string.

Constraints:• If provided, must match the identifier of an existing DBClusterSnapshot.• If this identifier is for an automated snapshot, the SnapshotType parameter must also be specified.

Type: String




Required: NoIncludePublic

Set to true to include manual cluster snapshots that are public and can be copied or restored by anyAWS account, and otherwise false. The default is false.

Type: Boolean

Required: NoIncludeShared

Set to true to include shared manual cluster snapshots from other AWS accounts that this AWSaccount has been given permission to copy or restore, and otherwise false. The default is false.

Type: Boolean

Required: NoMarker


476


Type: String



Default: 100


Type: Integer

Required: NoSnapshotType

The type of cluster snapshots to be returned. You can specify one of the following values:• automated - Return all cluster snapshots that Amazon DocumentDB has automatically created for

your AWS account.• manual - Return all cluster snapshots that you have manually created for your AWS account.• shared - Return all manual cluster snapshots that have been shared to your AWS account.• public - Return all cluster snapshots that have been marked as public.

If you don't specify a SnapshotType value, then both automated and manual cluster snapshots arereturned. You can include shared cluster snapshots with these results by setting the IncludeSharedparameter to true. You can include public cluster snapshots with these results by setting theIncludePublic parameter to true.

The IncludeShared and IncludePublic parameters don't apply for SnapshotType values ofmanual or automated. The IncludePublic parameter doesn't apply when SnapshotType is set toshared. The IncludeShared parameter doesn't apply when SnapshotType is set to public.

Type: String

Required: No


DBClusterSnapshots.DBClusterSnapshot.N

Provides a list of cluster snapshots.

Type: Array of DBClusterSnapshot (p. 547) objectsMarker


Type: String


477







478

https://docs.aws.amazon.com/goto/aws-cli/docdb-2014-10-31/DescribeDBClusterSnapshots

https://docs.aws.amazon.com/goto/DotNetSDKV3/docdb-2014-10-31/DescribeDBClusterSnapshots

https://docs.aws.amazon.com/goto/SdkForCpp/docdb-2014-10-31/DescribeDBClusterSnapshots

https://docs.aws.amazon.com/goto/SdkForGoV1/docdb-2014-10-31/DescribeDBClusterSnapshots

https://docs.aws.amazon.com/goto/SdkForJava/docdb-2014-10-31/DescribeDBClusterSnapshots

https://docs.aws.amazon.com/goto/AWSJavaScriptSDK/docdb-2014-10-31/DescribeDBClusterSnapshots

https://docs.aws.amazon.com/goto/SdkForPHPV3/docdb-2014-10-31/DescribeDBClusterSnapshots

https://docs.aws.amazon.com/goto/boto3/docdb-2014-10-31/DescribeDBClusterSnapshots

https://docs.aws.amazon.com/goto/SdkForRubyV3/docdb-2014-10-31/DescribeDBClusterSnapshots

Amazon DocumentDB Guia do desenvolvedorDescribeDBEngineVersions

DescribeDBEngineVersionsReturns a list of the available engines.


DBParameterGroupFamily

The name of a specific parameter group family to return details for.

Constraints:• If provided, must match an existing DBParameterGroupFamily.

Type: String

Required: NoDefaultOnly

Indicates that only the default version of the specified engine or engine and major version combinationis returned.

Type: Boolean

Required: NoEngine

The database engine to return.

Type: String


The database engine version to return.

Example: 3.6.0

Type: String




Required: NoListSupportedCharacterSets

If this parameter is specified and the requested engine supports the CharacterSetName parameterfor CreateDBInstance, the response includes a list of supported character sets for each engineversion.

Type: Boolean

Required: No

479


ListSupportedTimezones

If this parameter is specified and the requested engine supports the TimeZone parameter forCreateDBInstance, the response includes a list of supported time zones for each engine version.

Type: Boolean

Required: NoMarker


Type: String



Default: 100


Type: Integer

Required: No


DBEngineVersions.DBEngineVersion.N

Detailed information about one or more engine versions.

Type: Array of DBEngineVersion (p. 552) objectsMarker


Type: String



• AWS Command Line Interface• AWS SDK for .NET

480

https://docs.aws.amazon.com/goto/aws-cli/docdb-2014-10-31/DescribeDBEngineVersions

https://docs.aws.amazon.com/goto/DotNetSDKV3/docdb-2014-10-31/DescribeDBEngineVersions


• AWS SDK for C++• AWS SDK for Go• AWS SDK for Java• AWS SDK for JavaScript• AWS SDK for PHP V3• AWS SDK for Python• AWS SDK for Ruby V3

481

https://docs.aws.amazon.com/goto/SdkForCpp/docdb-2014-10-31/DescribeDBEngineVersions

https://docs.aws.amazon.com/goto/SdkForGoV1/docdb-2014-10-31/DescribeDBEngineVersions

https://docs.aws.amazon.com/goto/SdkForJava/docdb-2014-10-31/DescribeDBEngineVersions

https://docs.aws.amazon.com/goto/AWSJavaScriptSDK/docdb-2014-10-31/DescribeDBEngineVersions

https://docs.aws.amazon.com/goto/SdkForPHPV3/docdb-2014-10-31/DescribeDBEngineVersions

https://docs.aws.amazon.com/goto/boto3/docdb-2014-10-31/DescribeDBEngineVersions

https://docs.aws.amazon.com/goto/SdkForRubyV3/docdb-2014-10-31/DescribeDBEngineVersions

Amazon DocumentDB Guia do desenvolvedorDescribeDBInstances

DescribeDBInstancesReturns information about provisioned Amazon DocumentDB instances. This API supports pagination.



The user-provided instance identifier. If this parameter is specified, information from only the specificinstance is returned. This parameter isn't case sensitive.

Constraints:• If provided, must match the identifier of an existing DBInstance.

Type: String


A filter that specifies one or more instances to describe.


results list includes only the information about the instances that are associated with the clusters thatare identified by these ARNs.

• db-instance-id - Accepts instance identifiers and instance ARNs. The results list includes onlythe information about the instances that are identified by these ARNs.


Required: NoMarker


Type: String



Default: 100


Type: Integer

Required: No


482

Amazon DocumentDB Guia do desenvolvedorDescribeDBInstances

DBInstances.DBInstance.N

Detailed information about one or more instances.

Type: Array of DBInstance (p. 554) objectsMarker


Type: String


DBInstanceNotFound





483

https://docs.aws.amazon.com/goto/aws-cli/docdb-2014-10-31/DescribeDBInstances

https://docs.aws.amazon.com/goto/DotNetSDKV3/docdb-2014-10-31/DescribeDBInstances

https://docs.aws.amazon.com/goto/SdkForCpp/docdb-2014-10-31/DescribeDBInstances

https://docs.aws.amazon.com/goto/SdkForGoV1/docdb-2014-10-31/DescribeDBInstances

https://docs.aws.amazon.com/goto/SdkForJava/docdb-2014-10-31/DescribeDBInstances

https://docs.aws.amazon.com/goto/AWSJavaScriptSDK/docdb-2014-10-31/DescribeDBInstances

https://docs.aws.amazon.com/goto/SdkForPHPV3/docdb-2014-10-31/DescribeDBInstances

https://docs.aws.amazon.com/goto/boto3/docdb-2014-10-31/DescribeDBInstances

https://docs.aws.amazon.com/goto/SdkForRubyV3/docdb-2014-10-31/DescribeDBInstances

Amazon DocumentDB Guia do desenvolvedorDescribeDBSubnetGroups

DescribeDBSubnetGroupsReturns a list of DBSubnetGroup descriptions. If a DBSubnetGroupName is specified, the list will containonly the descriptions of the specified DBSubnetGroup.


DBSubnetGroupName

The name of the subnet group to return details for.

Type: String




Required: NoMarker


Type: String



Default: 100


Type: Integer

Required: No


DBSubnetGroups.DBSubnetGroup.N

Detailed information about one or more subnet groups.

Type: Array of DBSubnetGroup (p. 559) objectsMarker


484

Amazon DocumentDB Guia do desenvolvedorDescribeDBSubnetGroups

Type: String







485

https://docs.aws.amazon.com/goto/aws-cli/docdb-2014-10-31/DescribeDBSubnetGroups

https://docs.aws.amazon.com/goto/DotNetSDKV3/docdb-2014-10-31/DescribeDBSubnetGroups

https://docs.aws.amazon.com/goto/SdkForCpp/docdb-2014-10-31/DescribeDBSubnetGroups

https://docs.aws.amazon.com/goto/SdkForGoV1/docdb-2014-10-31/DescribeDBSubnetGroups

https://docs.aws.amazon.com/goto/SdkForJava/docdb-2014-10-31/DescribeDBSubnetGroups

https://docs.aws.amazon.com/goto/AWSJavaScriptSDK/docdb-2014-10-31/DescribeDBSubnetGroups

https://docs.aws.amazon.com/goto/SdkForPHPV3/docdb-2014-10-31/DescribeDBSubnetGroups

https://docs.aws.amazon.com/goto/boto3/docdb-2014-10-31/DescribeDBSubnetGroups

https://docs.aws.amazon.com/goto/SdkForRubyV3/docdb-2014-10-31/DescribeDBSubnetGroups

Amazon DocumentDB Guia do desenvolvedorDescribeEngineDefaultClusterParameters

DescribeEngineDefaultClusterParametersReturns the default engine and system parameter information for the cluster database engine.



The name of the cluster parameter group family to return the engine parameter information for.

Type: String




Required: NoMarker


Type: String



Default: 100


Type: Integer

Required: No


EngineDefaults

Contains the result of a successful invocation of theDescribeEngineDefaultClusterParameters operation.

Type: EngineDefaults (p. 562) object


486

Amazon DocumentDB Guia do desenvolvedorDescribeEngineDefaultClusterParameters



487

https://docs.aws.amazon.com/goto/aws-cli/docdb-2014-10-31/DescribeEngineDefaultClusterParameters

https://docs.aws.amazon.com/goto/DotNetSDKV3/docdb-2014-10-31/DescribeEngineDefaultClusterParameters

https://docs.aws.amazon.com/goto/SdkForCpp/docdb-2014-10-31/DescribeEngineDefaultClusterParameters

https://docs.aws.amazon.com/goto/SdkForGoV1/docdb-2014-10-31/DescribeEngineDefaultClusterParameters

https://docs.aws.amazon.com/goto/SdkForJava/docdb-2014-10-31/DescribeEngineDefaultClusterParameters

https://docs.aws.amazon.com/goto/AWSJavaScriptSDK/docdb-2014-10-31/DescribeEngineDefaultClusterParameters

https://docs.aws.amazon.com/goto/SdkForPHPV3/docdb-2014-10-31/DescribeEngineDefaultClusterParameters

https://docs.aws.amazon.com/goto/boto3/docdb-2014-10-31/DescribeEngineDefaultClusterParameters

https://docs.aws.amazon.com/goto/SdkForRubyV3/docdb-2014-10-31/DescribeEngineDefaultClusterParameters

Amazon DocumentDB Guia do desenvolvedorDescribeEventCategories

DescribeEventCategoriesDisplays a list of categories for all event source types, or, if specified, for a specified source type.


Filters.Filter.N



Required: NoSourceType

The type of source that is generating the events.

Valid values: db-instance, db-parameter-group, db-security-group, db-snapshot

Type: String

Required: No


EventCategoriesMapList.EventCategoriesMap.N

A list of event category maps.

Type: Array of EventCategoriesMap (p. 565) objects




488

https://docs.aws.amazon.com/goto/aws-cli/docdb-2014-10-31/DescribeEventCategories

https://docs.aws.amazon.com/goto/DotNetSDKV3/docdb-2014-10-31/DescribeEventCategories

https://docs.aws.amazon.com/goto/SdkForCpp/docdb-2014-10-31/DescribeEventCategories

https://docs.aws.amazon.com/goto/SdkForGoV1/docdb-2014-10-31/DescribeEventCategories

https://docs.aws.amazon.com/goto/SdkForJava/docdb-2014-10-31/DescribeEventCategories

https://docs.aws.amazon.com/goto/AWSJavaScriptSDK/docdb-2014-10-31/DescribeEventCategories

https://docs.aws.amazon.com/goto/SdkForPHPV3/docdb-2014-10-31/DescribeEventCategories

https://docs.aws.amazon.com/goto/boto3/docdb-2014-10-31/DescribeEventCategories

https://docs.aws.amazon.com/goto/SdkForRubyV3/docdb-2014-10-31/DescribeEventCategories

Amazon DocumentDB Guia do desenvolvedorDescribeEvents

DescribeEventsReturns events related to instances, security groups, snapshots, and DB parameter groups for the past 14days. You can obtain events specific to a particular DB instance, security group, snapshot, or parametergroup by providing the name as a parameter. By default, the events of the past hour are returned.


Duration

The number of minutes to retrieve events for.

Default: 60

Type: Integer

Required: NoEndTime

The end of the time interval for which to retrieve events, specified in ISO 8601 format.

Example: 2009-07-08T18:00Z

Type: Timestamp

Required: NoEventCategories.EventCategory.N

A list of event categories that trigger notifications for an event notification subscription.





Required: NoMarker


Type: String



Default: 100

489



Type: Integer

Required: NoSourceIdentifier

The identifier of the event source for which events are returned. If not specified, then all sources areincluded in the response.

Constraints:• If SourceIdentifier is provided, SourceType must also be provided.• If the source type is DBInstance, a DBInstanceIdentifier must be provided.• If the source type is DBSecurityGroup, a DBSecurityGroupName must be provided.• If the source type is DBParameterGroup, a DBParameterGroupName must be provided.• If the source type is DBSnapshot, a DBSnapshotIdentifier must be provided.• Cannot end with a hyphen or contain two consecutive hyphens.

Type: String


The event source to retrieve events for. If no value is specified, all events are returned.

Type: String

Valid Values: db-instance | db-parameter-group | db-security-group | db-snapshot | db-cluster | db-cluster-snapshot

Required: NoStartTime

The beginning of the time interval to retrieve events for, specified in ISO 8601 format.

Example: 2009-07-08T18:00Z

Type: Timestamp

Required: No


Events.Event.N

Detailed information about one or more events.

Type: Array of Event (p. 563) objectsMarker


Type: String

490





491

https://docs.aws.amazon.com/goto/aws-cli/docdb-2014-10-31/DescribeEvents

https://docs.aws.amazon.com/goto/DotNetSDKV3/docdb-2014-10-31/DescribeEvents

https://docs.aws.amazon.com/goto/SdkForCpp/docdb-2014-10-31/DescribeEvents

https://docs.aws.amazon.com/goto/SdkForGoV1/docdb-2014-10-31/DescribeEvents

https://docs.aws.amazon.com/goto/SdkForJava/docdb-2014-10-31/DescribeEvents

https://docs.aws.amazon.com/goto/AWSJavaScriptSDK/docdb-2014-10-31/DescribeEvents

https://docs.aws.amazon.com/goto/SdkForPHPV3/docdb-2014-10-31/DescribeEvents

https://docs.aws.amazon.com/goto/boto3/docdb-2014-10-31/DescribeEvents

https://docs.aws.amazon.com/goto/SdkForRubyV3/docdb-2014-10-31/DescribeEvents

Amazon DocumentDB Guia do desenvolvedorDescribeOrderableDBInstanceOptions

DescribeOrderableDBInstanceOptionsReturns a list of orderable instance options for the specified engine.


Engine

The name of the engine to retrieve instance options for.

Type: String

Required: YesDBInstanceClass

The instance class filter value. Specify this parameter to show only the available offerings that matchthe specified instance class.

Type: String


The engine version filter value. Specify this parameter to show only the available offerings that matchthe specified engine version.

Type: String




Required: NoLicenseModel

The license model filter value. Specify this parameter to show only the available offerings that matchthe specified license model.

Type: String

Required: NoMarker


Type: String



492

Amazon DocumentDB Guia do desenvolvedorDescribeOrderableDBInstanceOptions

Default: 100


Type: Integer

Required: NoVpc

The virtual private cloud (VPC) filter value. Specify this parameter to show only the available VPC ornon-VPC offerings.

Type: Boolean

Required: No


Marker


Type: StringOrderableDBInstanceOptions.OrderableDBInstanceOption.N

The options that are available for a particular orderable instance.

Type: Array of OrderableDBInstanceOption (p. 567) objects




493

https://docs.aws.amazon.com/goto/aws-cli/docdb-2014-10-31/DescribeOrderableDBInstanceOptions

https://docs.aws.amazon.com/goto/DotNetSDKV3/docdb-2014-10-31/DescribeOrderableDBInstanceOptions

https://docs.aws.amazon.com/goto/SdkForCpp/docdb-2014-10-31/DescribeOrderableDBInstanceOptions

https://docs.aws.amazon.com/goto/SdkForGoV1/docdb-2014-10-31/DescribeOrderableDBInstanceOptions

https://docs.aws.amazon.com/goto/SdkForJava/docdb-2014-10-31/DescribeOrderableDBInstanceOptions

https://docs.aws.amazon.com/goto/AWSJavaScriptSDK/docdb-2014-10-31/DescribeOrderableDBInstanceOptions

https://docs.aws.amazon.com/goto/SdkForPHPV3/docdb-2014-10-31/DescribeOrderableDBInstanceOptions

https://docs.aws.amazon.com/goto/boto3/docdb-2014-10-31/DescribeOrderableDBInstanceOptions

https://docs.aws.amazon.com/goto/SdkForRubyV3/docdb-2014-10-31/DescribeOrderableDBInstanceOptions

Amazon DocumentDB Guia do desenvolvedorDescribePendingMaintenanceActions

DescribePendingMaintenanceActionsReturns a list of resources (for example, instances) that have at least one pending maintenance action.


Filters.Filter.N

A filter that specifies one or more resources to return pending maintenance actions for.


results list includes only pending maintenance actions for the clusters identified by these ARNs.• db-instance-id - Accepts instance identifiers and instance ARNs. The results list includes only

pending maintenance actions for the DB instances identified by these ARNs.


Required: NoMarker


Type: String



Default: 100


Type: Integer

Required: NoResourceIdentifier

The ARN of a resource to return pending maintenance actions for.

Type: String

Required: No


Marker


494

Amazon DocumentDB Guia do desenvolvedorDescribePendingMaintenanceActions

Type: StringPendingMaintenanceActions.ResourcePendingMaintenanceActions.N

The maintenance actions to be applied.

Type: Array of ResourcePendingMaintenanceActions (p. 577) objects


ResourceNotFoundFault

The specified resource ID was not found.




495

https://docs.aws.amazon.com/goto/aws-cli/docdb-2014-10-31/DescribePendingMaintenanceActions

https://docs.aws.amazon.com/goto/DotNetSDKV3/docdb-2014-10-31/DescribePendingMaintenanceActions

https://docs.aws.amazon.com/goto/SdkForCpp/docdb-2014-10-31/DescribePendingMaintenanceActions

https://docs.aws.amazon.com/goto/SdkForGoV1/docdb-2014-10-31/DescribePendingMaintenanceActions

https://docs.aws.amazon.com/goto/SdkForJava/docdb-2014-10-31/DescribePendingMaintenanceActions

https://docs.aws.amazon.com/goto/AWSJavaScriptSDK/docdb-2014-10-31/DescribePendingMaintenanceActions

https://docs.aws.amazon.com/goto/SdkForPHPV3/docdb-2014-10-31/DescribePendingMaintenanceActions

https://docs.aws.amazon.com/goto/boto3/docdb-2014-10-31/DescribePendingMaintenanceActions

https://docs.aws.amazon.com/goto/SdkForRubyV3/docdb-2014-10-31/DescribePendingMaintenanceActions

Amazon DocumentDB Guia do desenvolvedorFailoverDBCluster

FailoverDBClusterForces a failover for a cluster.

A failover for a cluster promotes one of the Amazon DocumentDB replicas (read-only instances) in thecluster to be the primary instance (the cluster writer).

If the primary instance fails, Amazon DocumentDB automatically fails over to an Amazon DocumentDBreplica, if one exists. You can force a failover when you want to simulate a failure of a primary instance fortesting.


DBClusterIdentifier

A cluster identifier to force a failover for. This parameter is not case sensitive.


Type: String

Required: NoTargetDBInstanceIdentifier

The name of the instance to promote to the primary instance.

You must specify the instance identifier for an Amazon DocumentDB replica in the cluster. Forexample, mydbcluster-replica1.

Type: String

Required: No


DBCluster







496

Amazon DocumentDB Guia do desenvolvedorFailoverDBCluster

InvalidDBClusterStateFault







497

https://docs.aws.amazon.com/goto/aws-cli/docdb-2014-10-31/FailoverDBCluster

https://docs.aws.amazon.com/goto/DotNetSDKV3/docdb-2014-10-31/FailoverDBCluster

https://docs.aws.amazon.com/goto/SdkForCpp/docdb-2014-10-31/FailoverDBCluster

https://docs.aws.amazon.com/goto/SdkForGoV1/docdb-2014-10-31/FailoverDBCluster

https://docs.aws.amazon.com/goto/SdkForJava/docdb-2014-10-31/FailoverDBCluster

https://docs.aws.amazon.com/goto/AWSJavaScriptSDK/docdb-2014-10-31/FailoverDBCluster

https://docs.aws.amazon.com/goto/SdkForPHPV3/docdb-2014-10-31/FailoverDBCluster

https://docs.aws.amazon.com/goto/boto3/docdb-2014-10-31/FailoverDBCluster

https://docs.aws.amazon.com/goto/SdkForRubyV3/docdb-2014-10-31/FailoverDBCluster

Amazon DocumentDB Guia do desenvolvedorListTagsForResource

ListTagsForResourceLists all tags on an Amazon DocumentDB resource.


ResourceName

The Amazon DocumentDB resource with tags to be listed. This value is an Amazon Resource Name(ARN).

Type: String




Required: No


TagList.Tag.N

A list of one or more tags.











498

Amazon DocumentDB Guia do desenvolvedorListTagsForResource


499

https://docs.aws.amazon.com/goto/aws-cli/docdb-2014-10-31/ListTagsForResource

https://docs.aws.amazon.com/goto/DotNetSDKV3/docdb-2014-10-31/ListTagsForResource

https://docs.aws.amazon.com/goto/SdkForCpp/docdb-2014-10-31/ListTagsForResource

https://docs.aws.amazon.com/goto/SdkForGoV1/docdb-2014-10-31/ListTagsForResource

https://docs.aws.amazon.com/goto/SdkForJava/docdb-2014-10-31/ListTagsForResource

https://docs.aws.amazon.com/goto/AWSJavaScriptSDK/docdb-2014-10-31/ListTagsForResource

https://docs.aws.amazon.com/goto/SdkForPHPV3/docdb-2014-10-31/ListTagsForResource

https://docs.aws.amazon.com/goto/boto3/docdb-2014-10-31/ListTagsForResource

https://docs.aws.amazon.com/goto/SdkForRubyV3/docdb-2014-10-31/ListTagsForResource

Amazon DocumentDB Guia do desenvolvedorModifyDBCluster

ModifyDBClusterModifies a setting for an Amazon DocumentDB cluster. You can change one or more databaseconfiguration parameters by specifying these parameters and the new values in the request.


DBClusterIdentifier

The cluster identifier for the cluster that is being modified. This parameter is not case sensitive.


Type: String

Required: YesApplyImmediately

A value that specifies whether the changes in this request and any pending changes areasynchronously applied as soon as possible, regardless of the PreferredMaintenanceWindowsetting for the cluster. If this parameter is set to false, changes to the cluster are applied during thenext maintenance window.

The ApplyImmediately parameter affects only the NewDBClusterIdentifier andMasterUserPassword values. If you set this parameter value to false, the changes to theNewDBClusterIdentifier and MasterUserPassword values are applied during the nextmaintenance window. All other changes are applied immediately, regardless of the value of theApplyImmediately parameter.

Default: false

Type: Boolean


The number of days for which automated backups are retained. You must specify a minimum value of1.

Default: 1

Constraints:• Must be a value from 1 to 35.

Type: Integer

Required: NoCloudwatchLogsExportConfiguration

The configuration setting for the log types to be enabled for export to Amazon CloudWatch Logs for aspecific instance or cluster. The EnableLogTypes and DisableLogTypes arrays determine whichlogs are exported (or not exported) to CloudWatch Logs.

Type: CloudwatchLogsExportConfiguration (p. 538) object

Required: No

500



The name of the cluster parameter group to use for the cluster.

Type: String



Type: Boolean


The version number of the database engine to which you want to upgrade. Changing this parameterresults in an outage. The change is applied during the next maintenance window unless theApplyImmediately parameter is set to true.

Type: String

Required: NoMasterUserPassword

The password for the master database user. This password can contain any printable ASCII characterexcept forward slash (/), double quote ("), or the "at" symbol (@).

Constraints: Must contain from 8 to 100 characters.

Type: String

Required: NoNewDBClusterIdentifier

The new cluster identifier for the cluster when renaming a cluster. This value is stored as a lowercasestring.


Example: my-cluster2

Type: String

Required: NoPort

The port number on which the cluster accepts connections.

Constraints: Must be a value from 1150 to 65535.

Default: The same port as the original cluster.

Type: Integer

501



The daily time range during which automated backups are created if automated backups are enabled,using the BackupRetentionPeriod parameter.

The default is a 30-minute window selected at random from an 8-hour block of time for each AWSRegion.

Constraints:• Must be in the format hh24:mi-hh24:mi.• Must be in Universal Coordinated Time (UTC).• Must not conflict with the preferred maintenance window.• Must be at least 30 minutes.

Type: String


The weekly time range during which system maintenance can occur, in Universal Coordinated Time(UTC).





Type: String


A list of virtual private cloud (VPC) security groups that the cluster will belong to.


Required: No


DBCluster




502






HTTP Status Code: 404DBClusterParameterGroupNotFound

DBClusterParameterGroupName doesn't refer to an existing cluster parameter group.







HTTP Status Code: 400InvalidDBSecurityGroupState

The state of the security group doesn't allow deletion.










503




504

https://docs.aws.amazon.com/goto/aws-cli/docdb-2014-10-31/ModifyDBCluster

https://docs.aws.amazon.com/goto/DotNetSDKV3/docdb-2014-10-31/ModifyDBCluster

https://docs.aws.amazon.com/goto/SdkForCpp/docdb-2014-10-31/ModifyDBCluster

https://docs.aws.amazon.com/goto/SdkForGoV1/docdb-2014-10-31/ModifyDBCluster

https://docs.aws.amazon.com/goto/SdkForJava/docdb-2014-10-31/ModifyDBCluster

https://docs.aws.amazon.com/goto/AWSJavaScriptSDK/docdb-2014-10-31/ModifyDBCluster

https://docs.aws.amazon.com/goto/SdkForPHPV3/docdb-2014-10-31/ModifyDBCluster

https://docs.aws.amazon.com/goto/boto3/docdb-2014-10-31/ModifyDBCluster

https://docs.aws.amazon.com/goto/SdkForRubyV3/docdb-2014-10-31/ModifyDBCluster

Amazon DocumentDB Guia do desenvolvedorModifyDBClusterParameterGroup

ModifyDBClusterParameterGroupModifies the parameters of a cluster parameter group. To modify more than one parameter, submit a list ofthe following: ParameterName, ParameterValue, and ApplyMethod. A maximum of 20 parameters canbe modified in a single request.

Note

Changes to dynamic parameters are applied immediately. Changes to static parameters require areboot or maintenance window before the change can take effect.

Important

After you create a cluster parameter group, you should wait at least 5 minutes before creating yourfirst cluster that uses that cluster parameter group as the default parameter group. This allowsAmazon DocumentDB to fully complete the create action before the parameter group is usedas the default for a new cluster. This step is especially important for parameters that are criticalwhen creating the default database for a cluster, such as the character set for the default databasedefined by the character_set_database parameter.



The name of the cluster parameter group to modify.

Type: String

Required: YesParameters.Parameter.N

A list of parameters in the cluster parameter group to modify.


Required: Yes



The name of a cluster parameter group.

Constraints:• Must be from 1 to 255 letters or numbers.• The first character must be a letter.• Cannot end with a hyphen or contain two consecutive hyphens.

Note


Type: String

505

Amazon DocumentDB Guia do desenvolvedorModifyDBClusterParameterGroup









506

https://docs.aws.amazon.com/goto/aws-cli/docdb-2014-10-31/ModifyDBClusterParameterGroup

https://docs.aws.amazon.com/goto/DotNetSDKV3/docdb-2014-10-31/ModifyDBClusterParameterGroup

https://docs.aws.amazon.com/goto/SdkForCpp/docdb-2014-10-31/ModifyDBClusterParameterGroup

https://docs.aws.amazon.com/goto/SdkForGoV1/docdb-2014-10-31/ModifyDBClusterParameterGroup

https://docs.aws.amazon.com/goto/SdkForJava/docdb-2014-10-31/ModifyDBClusterParameterGroup

https://docs.aws.amazon.com/goto/AWSJavaScriptSDK/docdb-2014-10-31/ModifyDBClusterParameterGroup

https://docs.aws.amazon.com/goto/SdkForPHPV3/docdb-2014-10-31/ModifyDBClusterParameterGroup

https://docs.aws.amazon.com/goto/boto3/docdb-2014-10-31/ModifyDBClusterParameterGroup

https://docs.aws.amazon.com/goto/SdkForRubyV3/docdb-2014-10-31/ModifyDBClusterParameterGroup

Amazon DocumentDB Guia do desenvolvedorModifyDBClusterSnapshotAttribute

ModifyDBClusterSnapshotAttributeAdds an attribute and values to, or removes an attribute and values from, a manual DB cluster snapshot.

To share a manual cluster snapshot with other AWS accounts, specify restore as the AttributeName,and use the ValuesToAdd parameter to add a list of IDs of the AWS accounts that are authorized torestore the manual cluster snapshot. Use the value all to make the manual cluster snapshot public, whichmeans that it can be copied or restored by all AWS accounts. Do not add the all value for any manualDB cluster snapshots that contain private information that you don't want available to all AWS accounts. Ifa manual cluster snapshot is encrypted, it can be shared, but only by specifying a list of authorized AWSaccount IDs for the ValuesToAdd parameter. You can't use all as a value for that parameter in this case.


AttributeName

The name of the cluster snapshot attribute to modify.

To manage authorization for other AWS accounts to copy or restore a manual cluster snapshot, set thisvalue to restore.

Type: String

Required: YesDBClusterSnapshotIdentifier

The identifier for the cluster snapshot to modify the attributes for.

Type: String

Required: YesValuesToAdd.AttributeValue.N

A list of cluster snapshot attributes to add to the attribute specified by AttributeName.

To authorize other AWS accounts to copy or restore a manual cluster snapshot, set this list toinclude one or more AWS account IDs. To make the manual cluster snapshot restorable by any AWSaccount, set it to all. Do not add the all value for any manual cluster snapshots that contain privateinformation that you don't want to be available to all AWS accounts.


Required: NoValuesToRemove.AttributeValue.N

A list of cluster snapshot attributes to remove from the attribute specified by AttributeName.

To remove authorization for other AWS accounts to copy or restore a manual cluster snapshot, set thislist to include one or more AWS account identifiers. To remove authorization for any AWS account tocopy or restore the cluster snapshot, set it to all . If you specify all, an AWS account whose accountID is explicitly added to the restore attribute can still copy or restore a manual cluster snapshot.


Required: No

507

Amazon DocumentDB Guia do desenvolvedorModifyDBClusterSnapshotAttribute


DBClusterSnapshotAttributesResult

Detailed information about the attributes that are associated with a cluster snapshot.

Type: DBClusterSnapshotAttributesResult (p. 551) object






HTTP Status Code: 400SharedSnapshotQuotaExceeded

You have exceeded the maximum number of accounts that you can share a manual DB snapshot with.




508

https://docs.aws.amazon.com/goto/aws-cli/docdb-2014-10-31/ModifyDBClusterSnapshotAttribute

https://docs.aws.amazon.com/goto/DotNetSDKV3/docdb-2014-10-31/ModifyDBClusterSnapshotAttribute

https://docs.aws.amazon.com/goto/SdkForCpp/docdb-2014-10-31/ModifyDBClusterSnapshotAttribute

https://docs.aws.amazon.com/goto/SdkForGoV1/docdb-2014-10-31/ModifyDBClusterSnapshotAttribute

https://docs.aws.amazon.com/goto/SdkForJava/docdb-2014-10-31/ModifyDBClusterSnapshotAttribute

https://docs.aws.amazon.com/goto/AWSJavaScriptSDK/docdb-2014-10-31/ModifyDBClusterSnapshotAttribute

https://docs.aws.amazon.com/goto/SdkForPHPV3/docdb-2014-10-31/ModifyDBClusterSnapshotAttribute

https://docs.aws.amazon.com/goto/boto3/docdb-2014-10-31/ModifyDBClusterSnapshotAttribute

https://docs.aws.amazon.com/goto/SdkForRubyV3/docdb-2014-10-31/ModifyDBClusterSnapshotAttribute

Amazon DocumentDB Guia do desenvolvedorModifyDBInstance

ModifyDBInstanceModifies settings for an instance. You can change one or more database configuration parameters byspecifying these parameters and the new values in the request.



The instance identifier. This value is stored as a lowercase string.

Constraints:• Must match the identifier of an existing DBInstance.

Type: String

Required: YesApplyImmediately

Specifies whether the modifications in this request and any pending modifications are asynchronouslyapplied as soon as possible, regardless of the PreferredMaintenanceWindow setting for theinstance.

If this parameter is set to false, changes to the instance are applied during the next maintenancewindow. Some parameter changes can cause an outage and are applied on the next reboot.

Default: false

Type: Boolean

Required: NoAutoMinorVersionUpgrade

Indicates that minor version upgrades are applied automatically to the instance during the maintenancewindow. Changing this parameter doesn't result in an outage except in the following case, and thechange is asynchronously applied as soon as possible. An outage results if this parameter is setto true during the maintenance window, and a newer minor version is available, and AmazonDocumentDB has enabled automatic patching for that engine version.

Type: Boolean

Required: NoCACertificateIdentifier

Indicates the certificate that needs to be associated with the instance.

Type: String

Required: NoDBInstanceClass

The new compute and memory capacity of the instance; for example, db.r5.large. Not all instanceclasses are available in all AWS Regions.

If you modify the instance class, an outage occurs during the change. The change is applied during thenext maintenance window, unless ApplyImmediately is specified as true for this request.

509


Default: Uses existing setting.

Type: String

Required: NoNewDBInstanceIdentifier

The new instance identifier for the instance when renaming an instance. When you change theinstance identifier, an instance reboot occurs immediately if you set Apply Immediately to true. Itoccurs during the next maintenance window if you set Apply Immediately to false. This value isstored as a lowercase string.


Example: mydbinstance

Type: String


The weekly time range (in UTC) during which system maintenance can occur, which might result inan outage. Changing this parameter doesn't result in an outage except in the following situation, andthe change is asynchronously applied as soon as possible. If there are pending actions that cause areboot, and the maintenance window is changed to include the current time, changing this parametercauses a reboot of the instance. If you are moving this window to the current time, there must be atleast 30 minutes between the current time and end of the window to ensure that pending changes areapplied.

Default: Uses existing setting.



Constraints: Must be at least 30 minutes.

Type: String



Default: 1

Valid values: 0-15

Type: Integer

Required: No


510


DBInstance




AuthorizationNotFound

The specified CIDR IP or Amazon EC2 security group isn't authorized for the specified security group.

Amazon DocumentDB also might not be authorized to perform necessary actions on your behalf usingIAM.

HTTP Status Code: 404CertificateNotFound

CertificateIdentifier doesn't refer to an existing certificate.

HTTP Status Code: 404DBInstanceAlreadyExists

You already have a instance with the given identifier.





HTTP Status Code: 404DBSecurityGroupNotFound

DBSecurityGroupName doesn't refer to an existing security group.

HTTP Status Code: 404DBUpgradeDependencyFailure

The upgrade failed because a resource that the depends on can't be modified.

HTTP Status Code: 400InsufficientDBInstanceCapacity

The specified instance class isn't available in the specified Availability Zone.




511


InvalidDBSecurityGroupState

The state of the security group doesn't allow deletion.





HTTP Status Code: 400StorageTypeNotSupported

Storage of the specified StorageType can't be associated with the DB instance.




512

https://docs.aws.amazon.com/goto/aws-cli/docdb-2014-10-31/ModifyDBInstance

https://docs.aws.amazon.com/goto/DotNetSDKV3/docdb-2014-10-31/ModifyDBInstance

https://docs.aws.amazon.com/goto/SdkForCpp/docdb-2014-10-31/ModifyDBInstance

https://docs.aws.amazon.com/goto/SdkForGoV1/docdb-2014-10-31/ModifyDBInstance

https://docs.aws.amazon.com/goto/SdkForJava/docdb-2014-10-31/ModifyDBInstance

https://docs.aws.amazon.com/goto/AWSJavaScriptSDK/docdb-2014-10-31/ModifyDBInstance

https://docs.aws.amazon.com/goto/SdkForPHPV3/docdb-2014-10-31/ModifyDBInstance

https://docs.aws.amazon.com/goto/boto3/docdb-2014-10-31/ModifyDBInstance

https://docs.aws.amazon.com/goto/SdkForRubyV3/docdb-2014-10-31/ModifyDBInstance

Amazon DocumentDB Guia do desenvolvedorModifyDBSubnetGroup

ModifyDBSubnetGroupModifies an existing subnet group. subnet groups must contain at least one subnet in at least twoAvailability Zones in the AWS Region.


DBSubnetGroupName

The name for the subnet group. This value is stored as a lowercase string. You can't modify the defaultsubnet group.

Constraints: Must match the name of an existing DBSubnetGroup. Must not be default.


Type: String

Required: YesSubnetIds.SubnetIdentifier.N

The Amazon EC2 subnet IDs for the subnet group.


Required: YesDBSubnetGroupDescription

The description for the subnet group.

Type: String

Required: No


DBSubnetGroup

Detailed information about a subnet group.



DBSubnetGroupDoesNotCoverEnoughAZs



513

Amazon DocumentDB Guia do desenvolvedorModifyDBSubnetGroup



HTTP Status Code: 404DBSubnetQuotaExceededFault

The request would cause you to exceed the allowed number of subnets in a subnet group.



HTTP Status Code: 400SubnetAlreadyInUse

The subnet is already in use in the Availability Zone.




514

https://docs.aws.amazon.com/goto/aws-cli/docdb-2014-10-31/ModifyDBSubnetGroup

https://docs.aws.amazon.com/goto/DotNetSDKV3/docdb-2014-10-31/ModifyDBSubnetGroup

https://docs.aws.amazon.com/goto/SdkForCpp/docdb-2014-10-31/ModifyDBSubnetGroup

https://docs.aws.amazon.com/goto/SdkForGoV1/docdb-2014-10-31/ModifyDBSubnetGroup

https://docs.aws.amazon.com/goto/SdkForJava/docdb-2014-10-31/ModifyDBSubnetGroup

https://docs.aws.amazon.com/goto/AWSJavaScriptSDK/docdb-2014-10-31/ModifyDBSubnetGroup

https://docs.aws.amazon.com/goto/SdkForPHPV3/docdb-2014-10-31/ModifyDBSubnetGroup

https://docs.aws.amazon.com/goto/boto3/docdb-2014-10-31/ModifyDBSubnetGroup

https://docs.aws.amazon.com/goto/SdkForRubyV3/docdb-2014-10-31/ModifyDBSubnetGroup

Amazon DocumentDB Guia do desenvolvedorRebootDBInstance

RebootDBInstanceYou might need to reboot your instance, usually for maintenance reasons. For example, if you make certainchanges, or if you change the cluster parameter group that is associated with the instance, you must rebootthe instance for the changes to take effect.

Rebooting an instance restarts the database engine service. Rebooting an instance results in a momentaryoutage, during which the instance status is set to rebooting.



The instance identifier. This parameter is stored as a lowercase string.

Constraints:• Must match the identifier of an existing DBInstance.

Type: String

Required: YesForceFailover

When true, the reboot is conducted through a Multi-AZ failover.

Constraint: You can't specify true if the instance is not configured for Multi-AZ.

Type: Boolean

Required: No


DBInstance




DBInstanceNotFound





515

Amazon DocumentDB Guia do desenvolvedorRebootDBInstance



516

https://docs.aws.amazon.com/goto/aws-cli/docdb-2014-10-31/RebootDBInstance

https://docs.aws.amazon.com/goto/DotNetSDKV3/docdb-2014-10-31/RebootDBInstance

https://docs.aws.amazon.com/goto/SdkForCpp/docdb-2014-10-31/RebootDBInstance

https://docs.aws.amazon.com/goto/SdkForGoV1/docdb-2014-10-31/RebootDBInstance

https://docs.aws.amazon.com/goto/SdkForJava/docdb-2014-10-31/RebootDBInstance

https://docs.aws.amazon.com/goto/AWSJavaScriptSDK/docdb-2014-10-31/RebootDBInstance

https://docs.aws.amazon.com/goto/SdkForPHPV3/docdb-2014-10-31/RebootDBInstance

https://docs.aws.amazon.com/goto/boto3/docdb-2014-10-31/RebootDBInstance

https://docs.aws.amazon.com/goto/SdkForRubyV3/docdb-2014-10-31/RebootDBInstance

Amazon DocumentDB Guia do desenvolvedorRemoveTagsFromResource

RemoveTagsFromResourceRemoves metadata tags from an Amazon DocumentDB resource.


ResourceName

The Amazon DocumentDB resource that the tags are removed from. This value is an AmazonResource Name (ARN).

Type: String

Required: YesTagKeys.member.N

The tag key (name) of the tag to be removed.


Required: Yes










• AWS Command Line Interface• AWS SDK for .NET• AWS SDK for C++• AWS SDK for Go• AWS SDK for Java• AWS SDK for JavaScript

517

https://docs.aws.amazon.com/goto/aws-cli/docdb-2014-10-31/RemoveTagsFromResource

https://docs.aws.amazon.com/goto/DotNetSDKV3/docdb-2014-10-31/RemoveTagsFromResource

https://docs.aws.amazon.com/goto/SdkForCpp/docdb-2014-10-31/RemoveTagsFromResource

https://docs.aws.amazon.com/goto/SdkForGoV1/docdb-2014-10-31/RemoveTagsFromResource

https://docs.aws.amazon.com/goto/SdkForJava/docdb-2014-10-31/RemoveTagsFromResource

https://docs.aws.amazon.com/goto/AWSJavaScriptSDK/docdb-2014-10-31/RemoveTagsFromResource

Amazon DocumentDB Guia do desenvolvedorRemoveTagsFromResource

• AWS SDK for PHP V3• AWS SDK for Python• AWS SDK for Ruby V3

518

https://docs.aws.amazon.com/goto/SdkForPHPV3/docdb-2014-10-31/RemoveTagsFromResource

https://docs.aws.amazon.com/goto/boto3/docdb-2014-10-31/RemoveTagsFromResource

https://docs.aws.amazon.com/goto/SdkForRubyV3/docdb-2014-10-31/RemoveTagsFromResource

Amazon DocumentDB Guia do desenvolvedorResetDBClusterParameterGroup

ResetDBClusterParameterGroupModifies the parameters of a cluster parameter group to the default value. To reset specific parameters,submit a list of the following: ParameterName and ApplyMethod. To reset the entire cluster parametergroup, specify the DBClusterParameterGroupName and ResetAllParameters parameters.

When you reset the entire group, dynamic parameters are updated immediately and static parameters areset to pending-reboot to take effect on the next DB instance reboot.



The name of the cluster parameter group to reset.

Type: String

Required: YesParameters.Parameter.N

A list of parameter names in the cluster parameter group to reset to the default values. You can't usethis parameter if the ResetAllParameters parameter is set to true.


Required: NoResetAllParameters

A value that is set to true to reset all parameters in the cluster parameter group to their default values,and false otherwise. You can't use this parameter if there is a list of parameter names specified forthe Parameters parameter.

Type: Boolean

Required: No



The name of a cluster parameter group.

Constraints:• Must be from 1 to 255 letters or numbers.• The first character must be a letter.• Cannot end with a hyphen or contain two consecutive hyphens.

Note


Type: String

519

Amazon DocumentDB Guia do desenvolvedorResetDBClusterParameterGroup









520

https://docs.aws.amazon.com/goto/aws-cli/docdb-2014-10-31/ResetDBClusterParameterGroup

https://docs.aws.amazon.com/goto/DotNetSDKV3/docdb-2014-10-31/ResetDBClusterParameterGroup

https://docs.aws.amazon.com/goto/SdkForCpp/docdb-2014-10-31/ResetDBClusterParameterGroup

https://docs.aws.amazon.com/goto/SdkForGoV1/docdb-2014-10-31/ResetDBClusterParameterGroup

https://docs.aws.amazon.com/goto/SdkForJava/docdb-2014-10-31/ResetDBClusterParameterGroup

https://docs.aws.amazon.com/goto/AWSJavaScriptSDK/docdb-2014-10-31/ResetDBClusterParameterGroup

https://docs.aws.amazon.com/goto/SdkForPHPV3/docdb-2014-10-31/ResetDBClusterParameterGroup

https://docs.aws.amazon.com/goto/boto3/docdb-2014-10-31/ResetDBClusterParameterGroup

https://docs.aws.amazon.com/goto/SdkForRubyV3/docdb-2014-10-31/ResetDBClusterParameterGroup

Amazon DocumentDB Guia do desenvolvedorRestoreDBClusterFromSnapshot

RestoreDBClusterFromSnapshotCreates a new cluster from a snapshot or cluster snapshot.

If a snapshot is specified, the target cluster is created from the source DB snapshot with a defaultconfiguration and default security group.

If a cluster snapshot is specified, the target cluster is created from the source cluster restore point with thesame configuration as the original source DB cluster, except that the new cluster is created with the defaultsecurity group.


DBClusterIdentifier

The name of the cluster to create from the snapshot or cluster snapshot. This parameter isn't casesensitive.


Example: my-snapshot-id

Type: String

Required: YesEngine

The database engine to use for the new cluster.

Default: The same as source.

Constraint: Must be compatible with the engine of the source.

Type: String

Required: YesSnapshotIdentifier

The identifier for the snapshot or cluster snapshot to restore from.

You can use either the name or the Amazon Resource Name (ARN) to specify a cluster snapshot.However, you can use only the ARN to specify a snapshot.

Constraints:• Must match the identifier of an existing snapshot.

Type: String

Required: YesAvailabilityZones.AvailabilityZone.N

Provides the list of Amazon EC2 Availability Zones that instances in the restored DB cluster can becreated in.

521




The name of the subnet group to use for the new cluster.

Constraints: If provided, must match the name of an existing DBSubnetGroup.


Type: String



Type: Boolean


A list of log types that must be enabled for exporting to Amazon CloudWatch Logs.



The version of the database engine to use for the new cluster.

Type: String


The AWS KMS key identifier to use when restoring an encrypted cluster from a DB snapshot or clustersnapshot.

The AWS KMS key identifier is the Amazon Resource Name (ARN) for the AWS KMS encryption key.If you are restoring a cluster with the same AWS account that owns the AWS KMS encryption key usedto encrypt the new cluster, then you can use the AWS KMS key alias instead of the ARN for the AWSKMS encryption key.

If you do not specify a value for the KmsKeyId parameter, then the following occurs:• If the snapshot or cluster snapshot in SnapshotIdentifier is encrypted, then the restored cluster

is encrypted using the AWS KMS key that was used to encrypt the snapshot or the cluster snapshot.• If the snapshot or the cluster snapshot in SnapshotIdentifier is not encrypted, then the restored

DB cluster is not encrypted.

Type: String

Required: NoPort

The port number on which the new cluster accepts connections.

522



Default: The same port as the original cluster.

Type: Integer


The tags to be assigned to the restored cluster.



A list of virtual private cloud (VPC) security groups that the new cluster will belong to.


Required: No


DBCluster













523






HTTP Status Code: 404InsufficientDBClusterCapacityFault

The cluster doesn't have enough capacity for the current operation.





HTTP Status Code: 400InvalidDBSnapshotState

The state of the snapshot doesn't allow deletion.

HTTP Status Code: 400InvalidRestoreFault

You cannot restore from a virtual private cloud (VPC) backup to a non-VPC DB instance.










524


StorageQuotaExceeded





525

https://docs.aws.amazon.com/goto/aws-cli/docdb-2014-10-31/RestoreDBClusterFromSnapshot

https://docs.aws.amazon.com/goto/DotNetSDKV3/docdb-2014-10-31/RestoreDBClusterFromSnapshot

https://docs.aws.amazon.com/goto/SdkForCpp/docdb-2014-10-31/RestoreDBClusterFromSnapshot

https://docs.aws.amazon.com/goto/SdkForGoV1/docdb-2014-10-31/RestoreDBClusterFromSnapshot

https://docs.aws.amazon.com/goto/SdkForJava/docdb-2014-10-31/RestoreDBClusterFromSnapshot

https://docs.aws.amazon.com/goto/AWSJavaScriptSDK/docdb-2014-10-31/RestoreDBClusterFromSnapshot

https://docs.aws.amazon.com/goto/SdkForPHPV3/docdb-2014-10-31/RestoreDBClusterFromSnapshot

https://docs.aws.amazon.com/goto/boto3/docdb-2014-10-31/RestoreDBClusterFromSnapshot

https://docs.aws.amazon.com/goto/SdkForRubyV3/docdb-2014-10-31/RestoreDBClusterFromSnapshot

Amazon DocumentDB Guia do desenvolvedorRestoreDBClusterToPointInTime

RestoreDBClusterToPointInTimeRestores a cluster to an arbitrary point in time. Users can restore to any point in time beforeLatestRestorableTime for up to BackupRetentionPeriod days. The target cluster is created fromthe source cluster with the same configuration as the original cluster, except that the new cluster is createdwith the default security group.


DBClusterIdentifier

The name of the new cluster to be created.


Type: String

Required: YesSourceDBClusterIdentifier

The identifier of the source cluster from which to restore.


Type: String

Required: YesDBSubnetGroupName

The subnet group name to use for the new cluster.

Constraints: If provided, must match the name of an existing DBSubnetGroup.


Type: String



Type: Boolean


A list of log types that must be enabled for exporting to Amazon CloudWatch Logs.

526




The AWS KMS key identifier to use when restoring an encrypted cluster from an encrypted cluster.

The AWS KMS key identifier is the Amazon Resource Name (ARN) for the AWS KMS encryption key.If you are restoring a cluster with the same AWS account that owns the AWS KMS encryption key usedto encrypt the new cluster, then you can use the AWS KMS key alias instead of the ARN for the AWSKMS encryption key.

You can restore to a new cluster and encrypt the new cluster with an AWS KMS key that is differentfrom the AWS KMS key used to encrypt the source cluster. The new DB cluster is encrypted with theAWS KMS key identified by the KmsKeyId parameter.

If you do not specify a value for the KmsKeyId parameter, then the following occurs:• If the cluster is encrypted, then the restored cluster is encrypted using the AWS KMS key that was

used to encrypt the source cluster.• If the cluster is not encrypted, then the restored cluster is not encrypted.

If DBClusterIdentifier refers to a cluster that is not encrypted, then the restore request isrejected.

Type: String

Required: NoPort

The port number on which the new cluster accepts connections.


Default: The default port for the engine.

Type: Integer

Required: NoRestoreToTime

The date and time to restore the cluster to.

Valid values: A time in Universal Coordinated Time (UTC) format.

Constraints:• Must be before the latest restorable time for the instance.• Must be specified if the UseLatestRestorableTime parameter is not provided.• Cannot be specified if the UseLatestRestorableTime parameter is true.• Cannot be specified if the RestoreType parameter is copy-on-write.

Example: 2015-03-07T23:45:00Z

Type: Timestamp


The tags to be assigned to the restored cluster.

527



Required: NoUseLatestRestorableTime

A value that is set to true to restore the cluster to the latest restorable backup time, and falseotherwise.

Default: false

Constraints: Cannot be specified if the RestoreToTime parameter is provided.

Type: Boolean


A list of VPC security groups that the new cluster belongs to.


Required: No


DBCluster













528




HTTP Status Code: 404InsufficientDBClusterCapacityFault

The cluster doesn't have enough capacity for the current operation.







HTTP Status Code: 400InvalidDBSnapshotState

The state of the snapshot doesn't allow deletion.

HTTP Status Code: 400InvalidRestoreFault

You cannot restore from a virtual private cloud (VPC) backup to a non-VPC DB instance.










529




530

https://docs.aws.amazon.com/goto/aws-cli/docdb-2014-10-31/RestoreDBClusterToPointInTime

https://docs.aws.amazon.com/goto/DotNetSDKV3/docdb-2014-10-31/RestoreDBClusterToPointInTime

https://docs.aws.amazon.com/goto/SdkForCpp/docdb-2014-10-31/RestoreDBClusterToPointInTime

https://docs.aws.amazon.com/goto/SdkForGoV1/docdb-2014-10-31/RestoreDBClusterToPointInTime

https://docs.aws.amazon.com/goto/SdkForJava/docdb-2014-10-31/RestoreDBClusterToPointInTime

https://docs.aws.amazon.com/goto/AWSJavaScriptSDK/docdb-2014-10-31/RestoreDBClusterToPointInTime

https://docs.aws.amazon.com/goto/SdkForPHPV3/docdb-2014-10-31/RestoreDBClusterToPointInTime

https://docs.aws.amazon.com/goto/boto3/docdb-2014-10-31/RestoreDBClusterToPointInTime

https://docs.aws.amazon.com/goto/SdkForRubyV3/docdb-2014-10-31/RestoreDBClusterToPointInTime

Amazon DocumentDB Guia do desenvolvedorStartDBCluster

StartDBClusterRestarts the stopped cluster that is specified by DBClusterIdentifier. For more information, seeStopping and Starting an Amazon DocumentDB Cluster.


DBClusterIdentifier

The identifier of the cluster to restart. Example: docdb-2019-05-28-15-24-52

Type: String

Required: Yes


DBCluster













531

https://docs.aws.amazon.com/documentdb/latest/developerguide/db-cluster-stop-start.html

https://docs.aws.amazon.com/goto/aws-cli/docdb-2014-10-31/StartDBCluster

https://docs.aws.amazon.com/goto/DotNetSDKV3/docdb-2014-10-31/StartDBCluster

https://docs.aws.amazon.com/goto/SdkForCpp/docdb-2014-10-31/StartDBCluster

Amazon DocumentDB Guia do desenvolvedorStartDBCluster


532

https://docs.aws.amazon.com/goto/SdkForGoV1/docdb-2014-10-31/StartDBCluster

https://docs.aws.amazon.com/goto/SdkForJava/docdb-2014-10-31/StartDBCluster

https://docs.aws.amazon.com/goto/AWSJavaScriptSDK/docdb-2014-10-31/StartDBCluster

https://docs.aws.amazon.com/goto/SdkForPHPV3/docdb-2014-10-31/StartDBCluster

https://docs.aws.amazon.com/goto/boto3/docdb-2014-10-31/StartDBCluster

https://docs.aws.amazon.com/goto/SdkForRubyV3/docdb-2014-10-31/StartDBCluster

Amazon DocumentDB Guia do desenvolvedorStopDBCluster

StopDBClusterStops the running cluster that is specified by DBClusterIdentifier. The cluster must be in the availablestate. For more information, see Stopping and Starting an Amazon DocumentDB Cluster.


DBClusterIdentifier

The identifier of the cluster to stop. Example: docdb-2019-05-28-15-24-52

Type: String

Required: Yes


DBCluster













533


https://docs.aws.amazon.com/goto/aws-cli/docdb-2014-10-31/StopDBCluster

https://docs.aws.amazon.com/goto/DotNetSDKV3/docdb-2014-10-31/StopDBCluster

https://docs.aws.amazon.com/goto/SdkForCpp/docdb-2014-10-31/StopDBCluster

Amazon DocumentDB Guia do desenvolvedorData Types


Data TypesThe following data types are supported:

• AvailabilityZone (p. 535)• Certificate (p. 536)• CloudwatchLogsExportConfiguration (p. 538)• DBCluster (p. 539)• DBClusterMember (p. 544)• DBClusterParameterGroup (p. 545)• DBClusterRole (p. 546)• DBClusterSnapshot (p. 547)• DBClusterSnapshotAttribute (p. 550)• DBClusterSnapshotAttributesResult (p. 551)• DBEngineVersion (p. 552)• DBInstance (p. 554)• DBInstanceStatusInfo (p. 558)• DBSubnetGroup (p. 559)• Endpoint (p. 561)• EngineDefaults (p. 562)• Event (p. 563)• EventCategoriesMap (p. 565)• Filter (p. 566)• OrderableDBInstanceOption (p. 567)• Parameter (p. 569)• PendingCloudwatchLogsExports (p. 571)• PendingMaintenanceAction (p. 572)• PendingModifiedValues (p. 574)• ResourcePendingMaintenanceActions (p. 577)• Subnet (p. 578)• Tag (p. 579)• UpgradeTarget (p. 580)• VpcSecurityGroupMembership (p. 581)

534

https://docs.aws.amazon.com/goto/SdkForGoV1/docdb-2014-10-31/StopDBCluster

https://docs.aws.amazon.com/goto/SdkForJava/docdb-2014-10-31/StopDBCluster

https://docs.aws.amazon.com/goto/AWSJavaScriptSDK/docdb-2014-10-31/StopDBCluster

https://docs.aws.amazon.com/goto/SdkForPHPV3/docdb-2014-10-31/StopDBCluster

https://docs.aws.amazon.com/goto/boto3/docdb-2014-10-31/StopDBCluster

https://docs.aws.amazon.com/goto/SdkForRubyV3/docdb-2014-10-31/StopDBCluster

Amazon DocumentDB Guia do desenvolvedorAvailabilityZone

AvailabilityZoneInformation about an Availability Zone.

ContentsNote

In the following list, the required parameters are described first.

Name

The name of the Availability Zone.

Type: String

Required: No


• AWS SDK for C++• AWS SDK for Go• AWS SDK for Java• AWS SDK for Ruby V3

535

https://docs.aws.amazon.com/goto/SdkForCpp/docdb-2014-10-31/AvailabilityZone

https://docs.aws.amazon.com/goto/SdkForGoV1/docdb-2014-10-31/AvailabilityZone

https://docs.aws.amazon.com/goto/SdkForJava/docdb-2014-10-31/AvailabilityZone

https://docs.aws.amazon.com/goto/SdkForRubyV3/docdb-2014-10-31/AvailabilityZone

Amazon DocumentDB Guia do desenvolvedorCertificate

CertificateA certificate authority (CA) certificate for an AWS account.

ContentsNote


CertificateArn

The Amazon Resource Name (ARN) for the certificate.

Example: arn:aws:rds:us-east-1::cert:rds-ca-2019

Type: String

Required: NoCertificateIdentifier

The unique key that identifies a certificate.

Example: rds-ca-2019

Type: String

Required: NoCertificateType

The type of the certificate.

Example: CA

Type: String

Required: NoThumbprint

The thumbprint of the certificate.

Type: String

Required: NoValidFrom

The starting date-time from which the certificate is valid.

Example: 2019-07-31T17:57:09Z

Type: Timestamp

Required: NoValidTill

The date-time after which the certificate is no longer valid.

Example: 2024-07-31T17:57:09Z

Type: Timestamp

536

Amazon DocumentDB Guia do desenvolvedorCertificate

Required: No



537

https://docs.aws.amazon.com/goto/SdkForCpp/docdb-2014-10-31/Certificate

https://docs.aws.amazon.com/goto/SdkForGoV1/docdb-2014-10-31/Certificate

https://docs.aws.amazon.com/goto/SdkForJava/docdb-2014-10-31/Certificate

https://docs.aws.amazon.com/goto/SdkForRubyV3/docdb-2014-10-31/Certificate

Amazon DocumentDB Guia do desenvolvedorCloudwatchLogsExportConfiguration

CloudwatchLogsExportConfigurationThe configuration setting for the log types to be enabled for export to Amazon CloudWatch Logs for aspecific instance or cluster.

The EnableLogTypes and DisableLogTypes arrays determine which logs are exported (or notexported) to CloudWatch Logs. The values within these arrays depend on the engine that is being used.

ContentsNote


DisableLogTypes.member.N

The list of log types to disable.


Required: NoEnableLogTypes.member.N

The list of log types to enable.


Required: No



538

https://docs.aws.amazon.com/goto/SdkForCpp/docdb-2014-10-31/CloudwatchLogsExportConfiguration

https://docs.aws.amazon.com/goto/SdkForGoV1/docdb-2014-10-31/CloudwatchLogsExportConfiguration

https://docs.aws.amazon.com/goto/SdkForJava/docdb-2014-10-31/CloudwatchLogsExportConfiguration

https://docs.aws.amazon.com/goto/SdkForRubyV3/docdb-2014-10-31/CloudwatchLogsExportConfiguration

Amazon DocumentDB Guia do desenvolvedorDBCluster

DBClusterDetailed information about a cluster.

ContentsNote


AssociatedRoles.DBClusterRole.N

Provides a list of the AWS Identity and Access Management (IAM) roles that are associated with thecluster. IAM roles that are associated with a cluster grant permission for the cluster to access otherAWS services on your behalf.

Type: Array of DBClusterRole (p. 546) objects

Required: NoAvailabilityZones.AvailabilityZone.N

Provides the list of Amazon EC2 Availability Zones that instances in the cluster can be created in.



Specifies the number of days for which automatic snapshots are retained.

Type: Integer

Required: NoClusterCreateTime

Specifies the time when the cluster was created, in Universal Coordinated Time (UTC).

Type: Timestamp

Required: NoDBClusterArn

The Amazon Resource Name (ARN) for the cluster.

Type: String

Required: NoDBClusterIdentifier

Contains a user-supplied cluster identifier. This identifier is the unique key that identifies a cluster.

Type: String

Required: NoDBClusterMembers.DBClusterMember.N

Provides the list of instances that make up the cluster.

539


Type: Array of DBClusterMember (p. 544) objects

Required: NoDBClusterParameterGroup

Specifies the name of the cluster parameter group for the cluster.

Type: String

Required: NoDbClusterResourceId

The AWS Region-unique, immutable identifier for the cluster. This identifier is found in AWS CloudTraillog entries whenever the AWS KMS key for the cluster is accessed.

Type: String

Required: NoDBSubnetGroup

Specifies information on the subnet group that is associated with the cluster, including the name,description, and subnets in the subnet group.

Type: String



Type: Boolean

Required: NoEarliestRestorableTime

The earliest time to which a database can be restored with point-in-time restore.

Type: Timestamp

Required: NoEnabledCloudwatchLogsExports.member.N

A list of log types that this cluster is configured to export to Amazon CloudWatch Logs.


Required: NoEndpoint

Specifies the connection endpoint for the primary instance of the cluster.

Type: String

Required: NoEngine

Provides the name of the database engine to be used for this cluster.

540


Type: String


Indicates the database engine version.

Type: String

Required: NoHostedZoneId

Specifies the ID that Amazon Route 53 assigns when you create a hosted zone.

Type: String


If StorageEncrypted is true, the AWS KMS key identifier for the encrypted cluster.

Type: String

Required: NoLatestRestorableTime

Specifies the latest time to which a database can be restored with point-in-time restore.

Type: Timestamp

Required: NoMasterUsername

Contains the master user name for the cluster.

Type: String

Required: NoMultiAZ

Specifies whether the cluster has instances in multiple Availability Zones.

Type: Boolean

Required: NoPercentProgress

Specifies the progress of the operation as a percentage.

Type: String

Required: NoPort

Specifies the port that the database engine is listening on.

Type: Integer

Required: No

541


PreferredBackupWindow

Specifies the daily time range during which automated backups are created if automated backups areenabled, as determined by the BackupRetentionPeriod.

Type: String


Specifies the weekly time range during which system maintenance can occur, in Universal CoordinatedTime (UTC).

Type: String

Required: NoReaderEndpoint

The reader endpoint for the cluster. The reader endpoint for a cluster load balances connectionsacross the Amazon DocumentDB replicas that are available in a cluster. As clients request newconnections to the reader endpoint, Amazon DocumentDB distributes the connection requestsamong the Amazon DocumentDB replicas in the cluster. This functionality can help balance your readworkload across multiple Amazon DocumentDB replicas in your cluster.

If a failover occurs, and the Amazon DocumentDB replica that you are connected to is promoted to bethe primary instance, your connection is dropped. To continue sending your read workload to otherAmazon DocumentDB replicas in the cluster, you can then reconnect to the reader endpoint.

Type: String

Required: NoStatus

Specifies the current state of this cluster.

Type: String


Specifies whether the cluster is encrypted.

Type: Boolean

Required: NoVpcSecurityGroups.VpcSecurityGroupMembership.N

Provides a list of virtual private cloud (VPC) security groups that the cluster belongs to.

Type: Array of VpcSecurityGroupMembership (p. 581) objects

Required: No


• AWS SDK for C++

542

https://docs.aws.amazon.com/goto/SdkForCpp/docdb-2014-10-31/DBCluster


• AWS SDK for Go• AWS SDK for Java• AWS SDK for Ruby V3

543

https://docs.aws.amazon.com/goto/SdkForGoV1/docdb-2014-10-31/DBCluster

https://docs.aws.amazon.com/goto/SdkForJava/docdb-2014-10-31/DBCluster

https://docs.aws.amazon.com/goto/SdkForRubyV3/docdb-2014-10-31/DBCluster

Amazon DocumentDB Guia do desenvolvedorDBClusterMember

DBClusterMemberContains information about an instance that is part of a cluster.

ContentsNote


DBClusterParameterGroupStatus

Specifies the status of the cluster parameter group for this member of the DB cluster.

Type: String

Required: NoDBInstanceIdentifier

Specifies the instance identifier for this member of the cluster.

Type: String

Required: NoIsClusterWriter

A value that is true if the cluster member is the primary instance for the cluster and false otherwise.

Type: Boolean



Type: Integer

Required: No



544

https://docs.aws.amazon.com/goto/SdkForCpp/docdb-2014-10-31/DBClusterMember

https://docs.aws.amazon.com/goto/SdkForGoV1/docdb-2014-10-31/DBClusterMember

https://docs.aws.amazon.com/goto/SdkForJava/docdb-2014-10-31/DBClusterMember

https://docs.aws.amazon.com/goto/SdkForRubyV3/docdb-2014-10-31/DBClusterMember

Amazon DocumentDB Guia do desenvolvedorDBClusterParameterGroup

DBClusterParameterGroupDetailed information about a cluster parameter group.

ContentsNote


DBClusterParameterGroupArn

The Amazon Resource Name (ARN) for the cluster parameter group.

Type: String

Required: NoDBClusterParameterGroupName

Provides the name of the cluster parameter group.

Type: String

Required: NoDBParameterGroupFamily

Provides the name of the parameter group family that this cluster parameter group is compatible with.

Type: String

Required: NoDescription

Provides the customer-specified description for this cluster parameter group.

Type: String

Required: No



545

https://docs.aws.amazon.com/goto/SdkForCpp/docdb-2014-10-31/DBClusterParameterGroup

https://docs.aws.amazon.com/goto/SdkForGoV1/docdb-2014-10-31/DBClusterParameterGroup

https://docs.aws.amazon.com/goto/SdkForJava/docdb-2014-10-31/DBClusterParameterGroup

https://docs.aws.amazon.com/goto/SdkForRubyV3/docdb-2014-10-31/DBClusterParameterGroup

Amazon DocumentDB Guia do desenvolvedorDBClusterRole

DBClusterRoleDescribes an AWS Identity and Access Management (IAM) role that is associated with a cluster.

ContentsNote


RoleArn

The Amazon Resource Name (ARN) of the IAM role that is associated with the DB cluster.

Type: String

Required: NoStatus

Describes the state of association between the IAM role and the cluster. The Status property returnsone of the following values:• ACTIVE - The IAM role ARN is associated with the cluster and can be used to access other AWS

services on your behalf.• PENDING - The IAM role ARN is being associated with the DB cluster.• INVALID - The IAM role ARN is associated with the cluster, but the cluster cannot assume the IAM

role to access other AWS services on your behalf.

Type: String

Required: No



546

https://docs.aws.amazon.com/goto/SdkForCpp/docdb-2014-10-31/DBClusterRole

https://docs.aws.amazon.com/goto/SdkForGoV1/docdb-2014-10-31/DBClusterRole

https://docs.aws.amazon.com/goto/SdkForJava/docdb-2014-10-31/DBClusterRole

https://docs.aws.amazon.com/goto/SdkForRubyV3/docdb-2014-10-31/DBClusterRole

Amazon DocumentDB Guia do desenvolvedorDBClusterSnapshot

DBClusterSnapshotDetailed information about a cluster snapshot.

ContentsNote


AvailabilityZones.AvailabilityZone.N

Provides the list of Amazon EC2 Availability Zones that instances in the cluster snapshot can berestored in.


Required: NoClusterCreateTime

Specifies the time when the cluster was created, in Universal Coordinated Time (UTC).

Type: Timestamp


Specifies the cluster identifier of the cluster that this cluster snapshot was created from.

Type: String

Required: NoDBClusterSnapshotArn

The Amazon Resource Name (ARN) for the cluster snapshot.

Type: String


Specifies the identifier for the cluster snapshot.

Type: String

Required: NoEngine

Specifies the name of the database engine.

Type: String


Provides the version of the database engine for this cluster snapshot.

Type: String

Required: No

547


KmsKeyId

If StorageEncrypted is true, the AWS KMS key identifier for the encrypted cluster snapshot.

Type: String

Required: NoMasterUsername

Provides the master user name for the cluster snapshot.

Type: String

Required: NoPercentProgress

Specifies the percentage of the estimated data that has been transferred.

Type: Integer

Required: NoPort

Specifies the port that the cluster was listening on at the time of the snapshot.

Type: Integer

Required: NoSnapshotCreateTime

Provides the time when the snapshot was taken, in UTC.

Type: Timestamp

Required: NoSnapshotType

Provides the type of the cluster snapshot.

Type: String

Required: NoSourceDBClusterSnapshotArn

If the cluster snapshot was copied from a source cluster snapshot, the ARN for the source clustersnapshot; otherwise, a null value.

Type: String

Required: NoStatus

Specifies the status of this cluster snapshot.

Type: String


Specifies whether the cluster snapshot is encrypted.

548


Type: Boolean

Required: NoVpcId

Provides the virtual private cloud (VPC) ID that is associated with the cluster snapshot.

Type: String

Required: No



549

https://docs.aws.amazon.com/goto/SdkForCpp/docdb-2014-10-31/DBClusterSnapshot

https://docs.aws.amazon.com/goto/SdkForGoV1/docdb-2014-10-31/DBClusterSnapshot

https://docs.aws.amazon.com/goto/SdkForJava/docdb-2014-10-31/DBClusterSnapshot

https://docs.aws.amazon.com/goto/SdkForRubyV3/docdb-2014-10-31/DBClusterSnapshot

Amazon DocumentDB Guia do desenvolvedorDBClusterSnapshotAttribute

DBClusterSnapshotAttributeContains the name and values of a manual cluster snapshot attribute.

Manual cluster snapshot attributes are used to authorize other AWS accounts to restore a manual clustersnapshot.

ContentsNote


AttributeName

The name of the manual cluster snapshot attribute.

The attribute named restore refers to the list of AWS accounts that have permission to copy orrestore the manual cluster snapshot.

Type: String

Required: NoAttributeValues.AttributeValue.N

The values for the manual cluster snapshot attribute.

If the AttributeName field is set to restore, then this element returns a list of IDs of the AWSaccounts that are authorized to copy or restore the manual cluster snapshot. If a value of all is in thelist, then the manual cluster snapshot is public and available for any AWS account to copy or restore.


Required: No



550

https://docs.aws.amazon.com/goto/SdkForCpp/docdb-2014-10-31/DBClusterSnapshotAttribute

https://docs.aws.amazon.com/goto/SdkForGoV1/docdb-2014-10-31/DBClusterSnapshotAttribute

https://docs.aws.amazon.com/goto/SdkForJava/docdb-2014-10-31/DBClusterSnapshotAttribute

https://docs.aws.amazon.com/goto/SdkForRubyV3/docdb-2014-10-31/DBClusterSnapshotAttribute

Amazon DocumentDB Guia do desenvolvedorDBClusterSnapshotAttributesResult

DBClusterSnapshotAttributesResultDetailed information about the attributes that are associated with a cluster snapshot.

ContentsNote


DBClusterSnapshotAttributes.DBClusterSnapshotAttribute.N

The list of attributes and values for the cluster snapshot.

Type: Array of DBClusterSnapshotAttribute (p. 550) objects


The identifier of the cluster snapshot that the attributes apply to.

Type: String

Required: No



551

https://docs.aws.amazon.com/goto/SdkForCpp/docdb-2014-10-31/DBClusterSnapshotAttributesResult

https://docs.aws.amazon.com/goto/SdkForGoV1/docdb-2014-10-31/DBClusterSnapshotAttributesResult

https://docs.aws.amazon.com/goto/SdkForJava/docdb-2014-10-31/DBClusterSnapshotAttributesResult

https://docs.aws.amazon.com/goto/SdkForRubyV3/docdb-2014-10-31/DBClusterSnapshotAttributesResult

Amazon DocumentDB Guia do desenvolvedorDBEngineVersion

DBEngineVersionDetailed information about an engine version.

ContentsNote


DBEngineDescription

The description of the database engine.

Type: String

Required: NoDBEngineVersionDescription

The description of the database engine version.

Type: String

Required: NoDBParameterGroupFamily

The name of the parameter group family for the database engine.

Type: String

Required: NoEngine

The name of the database engine.

Type: String


The version number of the database engine.

Type: String

Required: NoExportableLogTypes.member.N

The types of logs that the database engine has available for export to Amazon CloudWatch Logs.


Required: NoSupportsLogExportsToCloudwatchLogs

A value that indicates whether the engine version supports exporting the log types specified byExportableLogTypes to CloudWatch Logs.

Type: Boolean

552

Amazon DocumentDB Guia do desenvolvedorDBEngineVersion

Required: NoValidUpgradeTarget.UpgradeTarget.N

A list of engine versions that this database engine version can be upgraded to.

Type: Array of UpgradeTarget (p. 580) objects

Required: No



553

https://docs.aws.amazon.com/goto/SdkForCpp/docdb-2014-10-31/DBEngineVersion

https://docs.aws.amazon.com/goto/SdkForGoV1/docdb-2014-10-31/DBEngineVersion

https://docs.aws.amazon.com/goto/SdkForJava/docdb-2014-10-31/DBEngineVersion

https://docs.aws.amazon.com/goto/SdkForRubyV3/docdb-2014-10-31/DBEngineVersion

Amazon DocumentDB Guia do desenvolvedorDBInstance

DBInstanceDetailed information about an instance.

ContentsNote


AutoMinorVersionUpgrade

Indicates that minor version patches are applied automatically.

Type: Boolean

Required: NoAvailabilityZone

Specifies the name of the Availability Zone that the instance is located in.

Type: String


Specifies the number of days for which automatic snapshots are retained.

Type: Integer


The identifier of the CA certificate for this DB instance.

Type: String


Contains the name of the cluster that the instance is a member of if the instance is a member of acluster.

Type: String

Required: NoDBInstanceArn

The Amazon Resource Name (ARN) for the instance.

Type: String


Contains the name of the compute and memory capacity class of the instance.

Type: String

554



Contains a user-provided database identifier. This identifier is the unique key that identifies aninstance.

Type: String

Required: NoDBInstanceStatus

Specifies the current state of this database.

Type: String

Required: NoDbiResourceId

The AWS Region-unique, immutable identifier for the instance. This identifier is found in AWSCloudTrail log entries whenever the AWS KMS key for the instance is accessed.

Type: String

Required: NoDBSubnetGroup

Specifies information on the subnet group that is associated with the instance, including the name,description, and subnets in the subnet group.


Required: NoEnabledCloudwatchLogsExports.member.N

A list of log types that this instance is configured to export to Amazon CloudWatch Logs.


Required: NoEndpoint

Specifies the connection endpoint.

Type: Endpoint (p. 561) object

Required: NoEngine

Provides the name of the database engine to be used for this instance.

Type: String



Type: String

Required: No

555


InstanceCreateTime

Provides the date and time that the instance was created.

Type: Timestamp


If StorageEncrypted is true, the AWS KMS key identifier for the encrypted instance.

Type: String

Required: NoLatestRestorableTime

Specifies the latest time to which a database can be restored with point-in-time restore.

Type: Timestamp

Required: NoPendingModifiedValues

Specifies that changes to the instance are pending. This element is included only when changes arepending. Specific changes are identified by subelements.

Type: PendingModifiedValues (p. 574) object


Specifies the daily time range during which automated backups are created if automated backups areenabled, as determined by the BackupRetentionPeriod.

Type: String


Specifies the weekly time range during which system maintenance can occur, in Universal CoordinatedTime (UTC).

Type: String



Type: Integer

Required: NoPubliclyAccessible

Not supported. Amazon DocumentDB does not currently support public endpoints. The value ofPubliclyAccessible is always false.

Type: Boolean

556


Required: NoStatusInfos.DBInstanceStatusInfo.N

The status of a read replica. If the instance is not a read replica, this is blank.

Type: Array of DBInstanceStatusInfo (p. 558) objects


Specifies whether or not the instance is encrypted.

Type: Boolean

Required: NoVpcSecurityGroups.VpcSecurityGroupMembership.N

Provides a list of VPC security group elements that the instance belongs to.

Type: Array of VpcSecurityGroupMembership (p. 581) objects

Required: No



557

https://docs.aws.amazon.com/goto/SdkForCpp/docdb-2014-10-31/DBInstance

https://docs.aws.amazon.com/goto/SdkForGoV1/docdb-2014-10-31/DBInstance

https://docs.aws.amazon.com/goto/SdkForJava/docdb-2014-10-31/DBInstance

https://docs.aws.amazon.com/goto/SdkForRubyV3/docdb-2014-10-31/DBInstance

Amazon DocumentDB Guia do desenvolvedorDBInstanceStatusInfo

DBInstanceStatusInfoProvides a list of status information for an instance.

ContentsNote


Message

Details of the error if there is an error for the instance. If the instance is not in an error state, this valueis blank.

Type: String

Required: NoNormal

A Boolean value that is true if the instance is operating normally, or false if the instance is in anerror state.

Type: Boolean

Required: NoStatus

Status of the instance. For a StatusType of read replica, the values can be replicating, error,stopped, or terminated.

Type: String

Required: NoStatusType

This value is currently "read replication."

Type: String

Required: No



558

https://docs.aws.amazon.com/goto/SdkForCpp/docdb-2014-10-31/DBInstanceStatusInfo

https://docs.aws.amazon.com/goto/SdkForGoV1/docdb-2014-10-31/DBInstanceStatusInfo

https://docs.aws.amazon.com/goto/SdkForJava/docdb-2014-10-31/DBInstanceStatusInfo

https://docs.aws.amazon.com/goto/SdkForRubyV3/docdb-2014-10-31/DBInstanceStatusInfo

Amazon DocumentDB Guia do desenvolvedorDBSubnetGroup

DBSubnetGroupDetailed information about a subnet group.

ContentsNote


DBSubnetGroupArn

The Amazon Resource Name (ARN) for the DB subnet group.

Type: String

Required: NoDBSubnetGroupDescription

Provides the description of the subnet group.

Type: String


The name of the subnet group.

Type: String

Required: NoSubnetGroupStatus

Provides the status of the subnet group.

Type: String

Required: NoSubnets.Subnet.N

Detailed information about one or more subnets within a subnet group.

Type: Array of Subnet (p. 578) objects

Required: NoVpcId

Provides the virtual private cloud (VPC) ID of the subnet group.

Type: String

Required: No


• AWS SDK for C++

559

https://docs.aws.amazon.com/goto/SdkForCpp/docdb-2014-10-31/DBSubnetGroup

Amazon DocumentDB Guia do desenvolvedorDBSubnetGroup


560

https://docs.aws.amazon.com/goto/SdkForGoV1/docdb-2014-10-31/DBSubnetGroup

https://docs.aws.amazon.com/goto/SdkForJava/docdb-2014-10-31/DBSubnetGroup

https://docs.aws.amazon.com/goto/SdkForRubyV3/docdb-2014-10-31/DBSubnetGroup

Amazon DocumentDB Guia do desenvolvedorEndpoint

EndpointNetwork information for accessing a cluster or instance. Client programs must specify a valid endpoint toaccess these Amazon DocumentDB resources.

ContentsNote


Address

Specifies the DNS address of the instance.

Type: String

Required: NoHostedZoneId

Specifies the ID that Amazon Route 53 assigns when you create a hosted zone.

Type: String

Required: NoPort

Specifies the port that the database engine is listening on.

Type: Integer

Required: No



561

https://docs.aws.amazon.com/goto/SdkForCpp/docdb-2014-10-31/Endpoint

https://docs.aws.amazon.com/goto/SdkForGoV1/docdb-2014-10-31/Endpoint

https://docs.aws.amazon.com/goto/SdkForJava/docdb-2014-10-31/Endpoint

https://docs.aws.amazon.com/goto/SdkForRubyV3/docdb-2014-10-31/Endpoint

Amazon DocumentDB Guia do desenvolvedorEngineDefaults

EngineDefaultsContains the result of a successful invocation of the DescribeEngineDefaultClusterParametersoperation.

ContentsNote



The name of the cluster parameter group family to return the engine parameter information for.

Type: String

Required: NoMarker


Type: String

Required: NoParameters.Parameter.N

The parameters of a particular cluster parameter group family.


Required: No



562

https://docs.aws.amazon.com/goto/SdkForCpp/docdb-2014-10-31/EngineDefaults

https://docs.aws.amazon.com/goto/SdkForGoV1/docdb-2014-10-31/EngineDefaults

https://docs.aws.amazon.com/goto/SdkForJava/docdb-2014-10-31/EngineDefaults

https://docs.aws.amazon.com/goto/SdkForRubyV3/docdb-2014-10-31/EngineDefaults

Amazon DocumentDB Guia do desenvolvedorEvent

EventDetailed information about an event.

ContentsNote


Date

Specifies the date and time of the event.

Type: Timestamp

Required: NoEventCategories.EventCategory.N

Specifies the category for the event.


Required: NoMessage

Provides the text of this event.

Type: String

Required: NoSourceArn

The Amazon Resource Name (ARN) for the event.

Type: String

Required: NoSourceIdentifier

Provides the identifier for the source of the event.

Type: String


Specifies the source type for this event.

Type: String

Valid Values: db-instance | db-parameter-group | db-security-group | db-snapshot | db-cluster | db-cluster-snapshot

Required: No


563

Amazon DocumentDB Guia do desenvolvedorEvent


564

https://docs.aws.amazon.com/goto/SdkForCpp/docdb-2014-10-31/Event

https://docs.aws.amazon.com/goto/SdkForGoV1/docdb-2014-10-31/Event

https://docs.aws.amazon.com/goto/SdkForJava/docdb-2014-10-31/Event

https://docs.aws.amazon.com/goto/SdkForRubyV3/docdb-2014-10-31/Event

Amazon DocumentDB Guia do desenvolvedorEventCategoriesMap

EventCategoriesMapAn event source type, accompanied by one or more event category names.

ContentsNote


EventCategories.EventCategory.N

The event categories for the specified source type.



The source type that the returned categories belong to.

Type: String

Required: No



565

https://docs.aws.amazon.com/goto/SdkForCpp/docdb-2014-10-31/EventCategoriesMap

https://docs.aws.amazon.com/goto/SdkForGoV1/docdb-2014-10-31/EventCategoriesMap

https://docs.aws.amazon.com/goto/SdkForJava/docdb-2014-10-31/EventCategoriesMap

https://docs.aws.amazon.com/goto/SdkForRubyV3/docdb-2014-10-31/EventCategoriesMap

Amazon DocumentDB Guia do desenvolvedorFilter

FilterA named set of filter values, used to return a more specific list of results. You can use a filter to match a setof resources by specific criteria, such as IDs.

Wildcards are not supported in filters.

ContentsNote


Name

The name of the filter. Filter names are case sensitive.

Type: String

Required: YesValues.Value.N

One or more filter values. Filter values are case sensitive.


Required: Yes



566

https://docs.aws.amazon.com/goto/SdkForCpp/docdb-2014-10-31/Filter

https://docs.aws.amazon.com/goto/SdkForGoV1/docdb-2014-10-31/Filter

https://docs.aws.amazon.com/goto/SdkForJava/docdb-2014-10-31/Filter

https://docs.aws.amazon.com/goto/SdkForRubyV3/docdb-2014-10-31/Filter

Amazon DocumentDB Guia do desenvolvedorOrderableDBInstanceOption

OrderableDBInstanceOptionThe options that are available for an instance.

ContentsNote


AvailabilityZones.AvailabilityZone.N

A list of Availability Zones for an instance.

Type: Array of AvailabilityZone (p. 535) objects


The instance class for an instance.

Type: String

Required: NoEngine

The engine type of an instance.

Type: String


The engine version of an instance.

Type: String


The license model for an instance.

Type: String

Required: NoVpc

Indicates whether an instance is in a virtual private cloud (VPC).

Type: Boolean

Required: No


• AWS SDK for C++

567

https://docs.aws.amazon.com/goto/SdkForCpp/docdb-2014-10-31/OrderableDBInstanceOption

Amazon DocumentDB Guia do desenvolvedorOrderableDBInstanceOption


568

https://docs.aws.amazon.com/goto/SdkForGoV1/docdb-2014-10-31/OrderableDBInstanceOption

https://docs.aws.amazon.com/goto/SdkForJava/docdb-2014-10-31/OrderableDBInstanceOption

https://docs.aws.amazon.com/goto/SdkForRubyV3/docdb-2014-10-31/OrderableDBInstanceOption

Amazon DocumentDB Guia do desenvolvedorParameter

ParameterDetailed information about an individual parameter.

ContentsNote


AllowedValues

Specifies the valid range of values for the parameter.

Type: String

Required: NoApplyMethod

Indicates when to apply parameter updates.

Type: String

Valid Values: immediate | pending-reboot

Required: NoApplyType

Specifies the engine-specific parameters type.

Type: String

Required: NoDataType

Specifies the valid data type for the parameter.

Type: String


Provides a description of the parameter.

Type: String

Required: NoIsModifiable

Indicates whether (true) or not (false) the parameter can be modified. Some parameters havesecurity or operational implications that prevent them from being changed.

Type: Boolean

Required: NoMinimumEngineVersion

The earliest engine version to which the parameter can apply.

569

Amazon DocumentDB Guia do desenvolvedorParameter

Type: String

Required: NoParameterName

Specifies the name of the parameter.

Type: String

Required: NoParameterValue

Specifies the value of the parameter.

Type: String

Required: NoSource

Indicates the source of the parameter value.

Type: String

Required: No



570

https://docs.aws.amazon.com/goto/SdkForCpp/docdb-2014-10-31/Parameter

https://docs.aws.amazon.com/goto/SdkForGoV1/docdb-2014-10-31/Parameter

https://docs.aws.amazon.com/goto/SdkForJava/docdb-2014-10-31/Parameter

https://docs.aws.amazon.com/goto/SdkForRubyV3/docdb-2014-10-31/Parameter

Amazon DocumentDB Guia do desenvolvedorPendingCloudwatchLogsExports

PendingCloudwatchLogsExportsA list of the log types whose configuration is still pending. These log types are in the process of beingactivated or deactivated.

ContentsNote


LogTypesToDisable.member.N

Log types that are in the process of being enabled. After they are enabled, these log types areexported to Amazon CloudWatch Logs.


Required: NoLogTypesToEnable.member.N

Log types that are in the process of being deactivated. After they are deactivated, these log typesaren't exported to CloudWatch Logs.


Required: No



571

https://docs.aws.amazon.com/goto/SdkForCpp/docdb-2014-10-31/PendingCloudwatchLogsExports

https://docs.aws.amazon.com/goto/SdkForGoV1/docdb-2014-10-31/PendingCloudwatchLogsExports

https://docs.aws.amazon.com/goto/SdkForJava/docdb-2014-10-31/PendingCloudwatchLogsExports

https://docs.aws.amazon.com/goto/SdkForRubyV3/docdb-2014-10-31/PendingCloudwatchLogsExports

Amazon DocumentDB Guia do desenvolvedorPendingMaintenanceAction

PendingMaintenanceActionProvides information about a pending maintenance action for a resource.

ContentsNote


Action

The type of pending maintenance action that is available for the resource.

Type: String

Required: NoAutoAppliedAfterDate

The date of the maintenance window when the action is applied. The maintenance action is appliedto the resource during its first maintenance window after this date. If this date is specified, any next-maintenance opt-in requests are ignored.

Type: Timestamp

Required: NoCurrentApplyDate

The effective date when the pending maintenance action is applied to the resource.

Type: Timestamp


A description providing more detail about the maintenance action.

Type: String

Required: NoForcedApplyDate

The date when the maintenance action is automatically applied. The maintenance action is appliedto the resource on this date regardless of the maintenance window for the resource. If this date isspecified, any immediate opt-in requests are ignored.

Type: Timestamp

Required: NoOptInStatus

Indicates the type of opt-in request that has been received for the resource.

Type: String

Required: No

572

Amazon DocumentDB Guia do desenvolvedorPendingMaintenanceAction



573

https://docs.aws.amazon.com/goto/SdkForCpp/docdb-2014-10-31/PendingMaintenanceAction

https://docs.aws.amazon.com/goto/SdkForGoV1/docdb-2014-10-31/PendingMaintenanceAction

https://docs.aws.amazon.com/goto/SdkForJava/docdb-2014-10-31/PendingMaintenanceAction

https://docs.aws.amazon.com/goto/SdkForRubyV3/docdb-2014-10-31/PendingMaintenanceAction

Amazon DocumentDB Guia do desenvolvedorPendingModifiedValues

PendingModifiedValuesOne or more modified settings for an instance. These modified settings have been requested, but haven'tbeen applied yet.

ContentsNote


AllocatedStorage

Contains the new AllocatedStorage size for then instance that will be applied or is currently beingapplied.

Type: Integer


Specifies the pending number of days for which automated backups are retained.

Type: Integer


Specifies the identifier of the certificate authority (CA) certificate for the DB instance.

Type: String


Contains the new DBInstanceClass for the instance that will be applied or is currently being applied.

Type: String


Contains the new DBInstanceIdentifier for the instance that will be applied or is currently beingapplied.

Type: String


The new subnet group for the instance.

Type: String



Type: String

574


Required: NoIops

Specifies the new Provisioned IOPS value for the instance that will be applied or is currently beingapplied.

Type: Integer


The license model for the instance.

Valid values: license-included, bring-your-own-license, general-public-license

Type: String

Required: NoMasterUserPassword

Contains the pending or currently in-progress change of the master credentials for the instance.

Type: String

Required: NoMultiAZ

Indicates that the Single-AZ instance is to change to a Multi-AZ deployment.

Type: Boolean

Required: NoPendingCloudwatchLogsExports

A list of the log types whose configuration is still pending. These log types are in the process of beingactivated or deactivated.

Type: PendingCloudwatchLogsExports (p. 571) object

Required: NoPort

Specifies the pending port for the instance.

Type: Integer

Required: NoStorageType

Specifies the storage type to be associated with the instance.

Type: String

Required: No


575



576

https://docs.aws.amazon.com/goto/SdkForCpp/docdb-2014-10-31/PendingModifiedValues

https://docs.aws.amazon.com/goto/SdkForGoV1/docdb-2014-10-31/PendingModifiedValues

https://docs.aws.amazon.com/goto/SdkForJava/docdb-2014-10-31/PendingModifiedValues

https://docs.aws.amazon.com/goto/SdkForRubyV3/docdb-2014-10-31/PendingModifiedValues

Amazon DocumentDB Guia do desenvolvedorResourcePendingMaintenanceActions

ResourcePendingMaintenanceActionsRepresents the output of ApplyPendingMaintenanceAction (p. 433).

ContentsNote


PendingMaintenanceActionDetails.PendingMaintenanceAction.N

A list that provides details about the pending maintenance actions for the resource.

Type: Array of PendingMaintenanceAction (p. 572) objects

Required: NoResourceIdentifier

The Amazon Resource Name (ARN) of the resource that has pending maintenance actions.

Type: String

Required: No



577

https://docs.aws.amazon.com/goto/SdkForCpp/docdb-2014-10-31/ResourcePendingMaintenanceActions

https://docs.aws.amazon.com/goto/SdkForGoV1/docdb-2014-10-31/ResourcePendingMaintenanceActions

https://docs.aws.amazon.com/goto/SdkForJava/docdb-2014-10-31/ResourcePendingMaintenanceActions

https://docs.aws.amazon.com/goto/SdkForRubyV3/docdb-2014-10-31/ResourcePendingMaintenanceActions

Amazon DocumentDB Guia do desenvolvedorSubnet

SubnetDetailed information about a subnet.

ContentsNote


SubnetAvailabilityZone

Specifies the Availability Zone for the subnet.

Type: AvailabilityZone (p. 535) object

Required: NoSubnetIdentifier

Specifies the identifier of the subnet.

Type: String

Required: NoSubnetStatus

Specifies the status of the subnet.

Type: String

Required: No



578

https://docs.aws.amazon.com/goto/SdkForCpp/docdb-2014-10-31/Subnet

https://docs.aws.amazon.com/goto/SdkForGoV1/docdb-2014-10-31/Subnet

https://docs.aws.amazon.com/goto/SdkForJava/docdb-2014-10-31/Subnet

https://docs.aws.amazon.com/goto/SdkForRubyV3/docdb-2014-10-31/Subnet

Amazon DocumentDB Guia do desenvolvedorTag

TagMetadata assigned to an Amazon DocumentDB resource consisting of a key-value pair.

ContentsNote


Key

The required name of the tag. The string value can be from 1 to 128 Unicode characters in length andcan't be prefixed with "aws:" or "rds:". The string can contain only the set of Unicode letters, digits,white space, '_', '.', '/', '=', '+', '-' (Java regex: "^([\\p{L}\\p{Z}\\p{N}_.:/=+\\-]*)$").

Type: String

Required: NoValue

The optional value of the tag. The string value can be from 1 to 256 Unicode characters in length andcan't be prefixed with "aws:" or "rds:". The string can contain only the set of Unicode letters, digits,white space, '_', '.', '/', '=', '+', '-' (Java regex: "^([\\p{L}\\p{Z}\\p{N}_.:/=+\\-]*)$").

Type: String

Required: No



579

https://docs.aws.amazon.com/goto/SdkForCpp/docdb-2014-10-31/Tag

https://docs.aws.amazon.com/goto/SdkForGoV1/docdb-2014-10-31/Tag

https://docs.aws.amazon.com/goto/SdkForJava/docdb-2014-10-31/Tag

https://docs.aws.amazon.com/goto/SdkForRubyV3/docdb-2014-10-31/Tag

Amazon DocumentDB Guia do desenvolvedorUpgradeTarget

UpgradeTargetThe version of the database engine that an instance can be upgraded to.

ContentsNote


AutoUpgrade

A value that indicates whether the target version is applied to any source DB instances that haveAutoMinorVersionUpgrade set to true.

Type: Boolean


The version of the database engine that an instance can be upgraded to.

Type: String

Required: NoEngine

The name of the upgrade target database engine.

Type: String


The version number of the upgrade target database engine.

Type: String

Required: NoIsMajorVersionUpgrade

A value that indicates whether a database engine is upgraded to a major version.

Type: Boolean

Required: No



580

https://docs.aws.amazon.com/goto/SdkForCpp/docdb-2014-10-31/UpgradeTarget

https://docs.aws.amazon.com/goto/SdkForGoV1/docdb-2014-10-31/UpgradeTarget

https://docs.aws.amazon.com/goto/SdkForJava/docdb-2014-10-31/UpgradeTarget

https://docs.aws.amazon.com/goto/SdkForRubyV3/docdb-2014-10-31/UpgradeTarget

Amazon DocumentDB Guia do desenvolvedorVpcSecurityGroupMembership

VpcSecurityGroupMembershipUsed as a response element for queries on virtual private cloud (VPC) security group membership.

ContentsNote


Status

The status of the VPC security group.

Type: String

Required: NoVpcSecurityGroupId

The name of the VPC security group.

Type: String

Required: No



Common ErrorsThis section lists the errors common to the API actions of all AWS services. For errors specific to an APIaction for this service, see the topic for that API action.

AccessDeniedException

You do not have sufficient access to perform this action.

HTTP Status Code: 400IncompleteSignature

The request signature does not conform to AWS standards.

HTTP Status Code: 400InternalFailure

The request processing has failed because of an unknown error, exception or failure.


581

https://docs.aws.amazon.com/goto/SdkForCpp/docdb-2014-10-31/VpcSecurityGroupMembership

https://docs.aws.amazon.com/goto/SdkForGoV1/docdb-2014-10-31/VpcSecurityGroupMembership

https://docs.aws.amazon.com/goto/SdkForJava/docdb-2014-10-31/VpcSecurityGroupMembership

https://docs.aws.amazon.com/goto/SdkForRubyV3/docdb-2014-10-31/VpcSecurityGroupMembership

Amazon DocumentDB Guia do desenvolvedorCommon Errors

InvalidAction

The action or operation requested is invalid. Verify that the action is typed correctly.

HTTP Status Code: 400InvalidClientTokenId

The X.509 certificate or AWS access key ID provided does not exist in our records.

HTTP Status Code: 403InvalidParameterCombination

Parameters that must not be used together were used together.

HTTP Status Code: 400InvalidParameterValue

An invalid or out-of-range value was supplied for the input parameter.

HTTP Status Code: 400InvalidQueryParameter

The AWS query string is malformed or does not adhere to AWS standards.

HTTP Status Code: 400MalformedQueryString

The query string contains a syntax error.

HTTP Status Code: 404MissingAction

The request is missing an action or a required parameter.

HTTP Status Code: 400MissingAuthenticationToken

The request must contain either a valid (registered) AWS access key ID or X.509 certificate.

HTTP Status Code: 403MissingParameter

A required parameter for the specified action is not supplied.

HTTP Status Code: 400NotAuthorized

You do not have permission to perform this action.

HTTP Status Code: 400OptInRequired

The AWS access key ID needs a subscription for the service.

HTTP Status Code: 403RequestExpired

The request reached the service more than 15 minutes after the date stamp on the request or morethan 15 minutes after the request expiration date (such as for pre-signed URLs), or the date stamp onthe request is more than 15 minutes in the future.

582

Amazon DocumentDB Guia do desenvolvedorCommon Parameters

HTTP Status Code: 400ServiceUnavailable

The request has failed due to a temporary failure of the server.

HTTP Status Code: 503ThrottlingException

The request was denied due to request throttling.

HTTP Status Code: 400ValidationError

The input fails to satisfy the constraints specified by an AWS service.


Common ParametersThe following list contains the parameters that all actions use for signing Signature Version 4 requests witha query string. Any action-specific parameters are listed in the topic for that action. For more informationabout Signature Version 4, see Signature Version 4 Signing Process in the Amazon Web Services GeneralReference.

Action

The action to be performed.

Type: string

Required: YesVersion

The API version that the request is written for, expressed in the format YYYY-MM-DD.

Type: string

Required: YesX-Amz-Algorithm

The hash algorithm that you used to create the request signature.

Condition: Specify this parameter when you include authentication information in a query string insteadof in the HTTP authorization header.

Type: string

Valid Values: AWS4-HMAC-SHA256

Required: ConditionalX-Amz-Credential

The credential scope value, which is a string that includes your access key, the date, the region youare targeting, the service you are requesting, and a termination string ("aws4_request"). The value isexpressed in the following format: access_key/YYYYMMDD/region/service/aws4_request.

For more information, see Task 2: Create a String to Sign for Signature Version 4 in the Amazon WebServices General Reference.

583

http://docs.aws.amazon.com/general/latest/gr/signature-version-4.html

http://docs.aws.amazon.com/general/latest/gr/sigv4-create-string-to-sign.html

Amazon DocumentDB Guia do desenvolvedorCommon Parameters


Type: string

Required: ConditionalX-Amz-Date

The date that is used to create the signature. The format must be ISO 8601 basic format(YYYYMMDD'T'HHMMSS'Z'). For example, the following date time is a valid X-Amz-Date value:20120325T120000Z.

Condition: X-Amz-Date is optional for all requests; it can be used to override the date used for signingrequests. If the Date header is specified in the ISO 8601 basic format, X-Amz-Date is not required.When X-Amz-Date is used, it always overrides the value of the Date header. For more information, seeHandling Dates in Signature Version 4 in the Amazon Web Services General Reference.

Type: string

Required: ConditionalX-Amz-Security-Token

The temporary security token that was obtained through a call to AWS Security Token Service (AWSSTS). For a list of services that support temporary security credentials from AWS Security TokenService, go to AWS Services That Work with IAM in the IAM User Guide.

Condition: If you're using temporary security credentials from the AWS Security Token Service, youmust include the security token.

Type: string

Required: ConditionalX-Amz-Signature

Specifies the hex-encoded signature that was calculated from the string to sign and the derived signingkey.


Type: string

Required: ConditionalX-Amz-SignedHeaders

Specifies all the HTTP headers that were included as part of the canonical request. For moreinformation about specifying signed headers, see Task 1: Create a Canonical Request For SignatureVersion 4 in the Amazon Web Services General Reference.


Type: string

Required: Conditional

584

http://docs.aws.amazon.com/general/latest/gr/sigv4-date-handling.html

http://docs.aws.amazon.com/IAM/latest/UserGuide/reference_aws-services-that-work-with-iam.html

http://docs.aws.amazon.com/general/latest/gr/sigv4-create-canonical-request.html

http://docs.aws.amazon.com/general/latest/gr/sigv4-create-canonical-request.html


Document History for the AmazonDocumentDB Developer Guide

• API version: 2014-10-31• Latest documentation update: July 17, 2020

A tabela a seguir descreve a documentação desta versão do Amazon DocumentDB Developer Guide.

update-history-change update-history-description update-history-date

Zonas adicionais dedisponibilidade suportadas

Amazon DocumentDBadicionado suporte para umaZona de Disponibilidade adicionalem Ásia-Pacífico (Seul) (ap-nordeste-2).

July 14, 2020

Adicionado suporte para copiarinstantâneos entre Regiões.

Amazon DocumentDBadicionado suporte para copiarinstantâneos de agrupamentoentre regiões AWS. Para maisinformações, consulte Copiarinstantâneos entre regiões.

July 10, 2020

Adicionado suporte para classede instância T3.

Suporte adicionado para tiposde instância de T3 em todasas regiões que suportamAmazon DocumentDB. Paramais informações, consulte Classes de instância suportadaspor região e Especificações daclasse de instância.

June 30, 2020

Adicionado o suporte para AWSGovCloud (US).

Amazon DocumentDB está agoradisponível no AWS GovCloud(US) Região (us-gov-west-1).

June 29, 2020

Adição de 16 novas métricasturdwatch.

Amazon DocumentDBadicionado suporte para 16novas métricas de relógioPrince cloudwatch. Paramais informações, consulte Monitorização AmazonDocumentDB com relógiocloudwatch.

June 23, 2020

Adicionado suporte paracaracteres nulos e operador$regex.

O Amazon DocumentDBadicionou suporte paracaracteres nulos em stringse a capacidade de usar umíndice para $regex. Paravisualizar as APIs do MongoDBe os recursos de pipeline de

June 22, 2020

585

https://docs.aws.amazon.com/documentdb/latest/developerguide/what-is.html#what-is-regions-and-azs


https://docs.aws.amazon.com/documentdb/latest/developerguide/backup_restore-copy_cluster_snapshot.html




https://docs.aws.amazon.com/documentdb/latest/developerguide/db-instance-classes.html#db-instance-class-specs


https://docs.aws.amazon.com/documentdb/latest/developerguide/db-instance-classes.html#db-instance-classes-by-region







https://docs.aws.amazon.com/documentdb/latest/developerguide/cloud_watch.html






https://docs.aws.amazon.com/documentdb/latest/developerguide/functional-differences.updated-functional-differences.html




agregação compatíveis com oAmazon DocumentDB, consulteDiferenças funcionais com oMongoDB.

Adicionamos suporte pararecursos melhorados deindexação de várias chaves.

O Amazon DocumentDBadicionou suporte para recursosmelhorados de indexação devárias chaves, que incluemindexação de matrizes maioresque 2.048 bytes e a capacidadede criar um índice compostode várias chaves com váriaschaves na mesma matriz. Paraobter mais informações, consulte Diferenças funcionais comrelação ao MongoDB.

April 23, 2020

Adicionamos suporte paraproteção contra exclusão de umapilha do AWS CloudFormation doAmazon DocumentDB.

O Amazon DocumentDBadicionou suporte para habilitara proteção contra exclusãoao criar uma pilha do AWSCloudFormation do AmazonDocumentDB.

April 20, 2020

Adicionado suporte para umazona de disponibilidade adicionalna Canadá (Central) (ca-central-1).

Agora, o Amazon DocumentDBestá disponível na região Canadá(Central) (ca-central-1) cominstâncias de classe R5 e 3zonas de disponibilidade.

March 26, 2020

Adicionado suporte para ocontrole de acesso baseado emfunção.

O Amazon DocumentDBadicionou suporte para controlede acesso baseado em funçãousando funções internas.

March 26, 2020

Adicionado suporte para trêsAPIs adicionais do MongoDB

O Amazon DocumentDBadicionou suporte para asAPIs $dateFromString eexecutionStats do MongoDB.

March 23, 2020

Adição de suporte para cincoAPIs do MongoDB adicionais.

Amazon DocumentDBadicionado suporte para$objectToArray,$arrayToObject, $slice,$mod, e $range API mongodb.

February 6, 2020

Adicionado o suporte paraCanadá (Central).

O Amazon DocumentDB agoraestá disponível na região Canadá(Central) (ca-central-1) cominstâncias de classe R5.

December 11, 2019

Adicionamos suporte paraChangeStreamLogSize.

O Amazon DocumentDBadicionou suporte paraChangeStreamLogSize paramétricas do Cloudwatch.

November 22, 2019

586

https://docs.aws.amazon.com/documentdb/latest/developerguide/functional-differences.html


https://docs.aws.amazon.com/documentdb/latest/developerguide/functional-differences.array-indexing.html






https://docs.aws.amazon.com/documentdb/latest/developerguide/quick_start_cfn.html








https://docs.aws.amazon.com/documentdb/latest/developerguide/role_based_access_control.html



https://docs.aws.amazon.com/documentdb/latest/developerguide/mongo-apis.html






https://docs.aws.amazon.com/documentdb/latest/developerguide/cloud_watch.html#cloud_watch-docdb_metrics_list

https://docs.aws.amazon.com/documentdb/latest/developerguide/cloud_watch.html#cloud_watch-docdb_metrics_list


Adicionamos suporte para aregião Europa (Paris)

O Amazon DocumentDB jáestá disponível na regiãoEuropa (Paris) (eu-west-3) cominstâncias de classe R5.

October 30, 2019

Adicionamos suporte para aregião Ásia Pacífico (Mumbai)

Agora o Amazon DocumentDBestá disponível na região ÁsiaPacífico (Mumbai) (ap-south-1)com instâncias de classe R5.

October 17, 2019

Adicionado o suporte para trêsAPIs do MongoDB adicionais

O Amazon DocumentDBadicionou suporte para as APIs$addFields, $concatArrayse $lookup do MongoDB.

October 16, 2019

Adicionamos suporte para aregião Ásia-Pacífico (Cingapura)

Agora o Amazon DocumentDBestá disponível na região Ásia-Pacífico (Cingapura) (ap-southeast-1) com instâncias declasse R5.

October 14, 2019

Adicionado novo documento paraatualizar os certificados TLS

Adicionadas instruções paraatualizar certificados deautoridade de certificação (CA)para usar o novo certificado daautoridade de certificação nacriação de conexões TLS.

October 2, 2019

Adicionado suporte à API paracertificados

Amazon DocumentDB um novotipo de dados de certificadopara instâncias. Para obtermais informações, consulteDBInstance.

October 1, 2019

Suporte à criação de perfis deconsulta

O Amazon DocumentDBadicionou a possibilidade de criaro perfil de operações compatíveisnas instâncias e bancos dedados do cluster.

August 19, 2019

Adicionada a terceira AZ emÁsia-Pacífico (Tóquio)

O Amazon DocumentDBadicionou uma terceira zona dedisponibilidade (AZ) para suasinstâncias de computação noÁsia-Pacífico (Tóquio).

August 9, 2019

587









https://docs.aws.amazon.com/documentdb/latest/developerguide/ca_cert_rotation.html

https://docs.aws.amazon.com/documentdb/latest/developerguide/ca_cert_rotation.html

https://docs.aws.amazon.com/documentdb/latest/developerguide/API_Certificate.html

https://docs.aws.amazon.com/documentdb/latest/developerguide/API_Certificate.html

https://docs.aws.amazon.com/documentdb/latest/developerguide/API_DBInstance.html






Suporte a APIs do Mongoadicionais

Adicionado suporte a recursosde pipeline de agregaçãoadicionais que incluem osoperadores de agregação $in,$isoWeek, $isoWeekYear,$isoDayOfWeek,$dateToString e o estágiode agregação $addToSet. OAmazon DocumentDB tambémadicionou suporte ao comandotop() para o diagnóstico nonível da coleção e a capacidadede modificar o parâmetroexpireAfterSeconds paraíndices de TTL usando ocomando collMod().

July 31, 2019

Adicionado o suporte paraEuropa (Londres)

O Amazon DocumentDB agoraestá disponível na Europa(Londres) (eu-west-2) cominstâncias de classe R5.

July 18, 2019

Adicionados exemplos de código Adicionados exemplos de códigoem R e Ruby para a conexão deforma programática ao AmazonDocumentDB.

July 17, 2019

Adicionadas melhores práticas Adicionada uma melhor práticapara ajudar você a gerenciarseus custos do AmazonDocumentDB.

July 17, 2019

Suporte à proteção contraexclusão do cluster

Para proteger seus clusterscontra a exclusão acidental, oAmazon DocumentDB adicionouproteção contra exclusão.Para obter mais informações,consulte os seguintestópicos: Criar uma AmazonDocumentDB Cluster, Modificarum Amazon DocumentDBCluster, Eliminar um AmazonDocumentDB Cluster, eDeletionProtection notópico API dbcluster.

July 1, 2019

Suporte à interrupção e ao iníciode um cluster

O Amazon DocumentDBadicionou suporte à interrupçãoe ao início de clusterspara gerenciar os custosdos ambientes de teste edesenvolvimento.

July 1, 2019

Atualização das diferençasfuncionais

Adição de transações implícitas adiferenças funcionais.

June 26, 2019

588





https://docs.aws.amazon.com/documentdb/latest/developerguide/connect.html

https://docs.aws.amazon.com/documentdb/latest/developerguide/best_practices.html#best_practices-cost_optimization



https://docs.aws.amazon.com/documentdb/latest/developerguide/db-cluster-create.html

https://docs.aws.amazon.com/documentdb/latest/developerguide/db-cluster-create.html

https://docs.aws.amazon.com/documentdb/latest/developerguide/db-cluster-modify.html





https://docs.aws.amazon.com/documentdb/latest/developerguide/API_DBCluster.html



https://docs.aws.amazon.com/documentdb/latest/developerguide/functional-differences.html#functional-differences.implicit-transactions

https://docs.aws.amazon.com/documentdb/latest/developerguide/functional-differences.html#functional-differences.implicit-transactions


Adição de diferenças funcionais Adição de uma observaçãosobre armazenamento ecompressão de índice noAmazon DocumentDB.

June 13, 2019

Suporte a mais uma região Agora o Amazon DocumentDBestá disponível em Ásia-Pacífico(Sydney) (ap-southeast-2) cominstâncias de classe R5.

June 5, 2019

Classe de instância R5compatível em regiões adicionais

Adicionado suporte de classede instância R5 para 4 regiõesadicionais: EUA East (Ohio),EUA East (N. Virginia), US West(Oregon) e UE (Irlanda). Comessa mudança, as instânciasR5 passam a ser compatíveisem todas as regiões queoferecem suporte ao AmazonDocumentDB.

May 17, 2019

Outras regiões com suporte Adicionado suporte para 2regiões adicionais, Ásia-Pacífico(Tóquio) (ap-northeast-1 e Ásia-Pacífico (Seul) ap-northeast-2)com classes de instâncias R5.Para obter mais informações,consulte Classes de instânciacompatíveis por região eEspecificações de classe deinstância.

May 8, 2019

Adição de mais exemplos decódigo de conexão

Adição de exemplos de códigoem Java e C # para conexão como Amazon DocumentDB.

April 24, 2019

Suporte adicional à API doMongo

Adicionado suporte para seteoperadores de cadeia deagregação ($indexOfBytes,$indexOfCP, $strLenBytes,$strLenCP, $toLower,$toUpper, e $split), noveoperadores de data-hora($dayOfYear, $dayOfMonth,$dayOfWeek, $year, $month,$hour, $minute, $second, e$millisecond) e o $samplefase de pipeline de agregação.

April 4, 2019

Adicionados exemplos de códigode conexão

Adição de exemplos de códigoem Python, Node.js, PHP e Gopara conexão com o AmazonDocumentDB.

March 21, 2019

589

https://docs.aws.amazon.com/documentdb/latest/developerguide/functional-differences.html#functional-differences.storage-compression




https://docs.aws.amazon.com/documentdb/latest/developerguide/how-it-works.html#how-it-works.availability












Suporte para a região deFrankfurt e instâncias R5

Adicionado suporte para aregião Europa (Frankfurt) (eu-central-1) com classes deinstância R5. Para obter maisinformações, consulte Classes deinstância compatíveis por regiãoe Especificações de classe deinstância.

March 13, 2019

Suporte a operadores de pipelinede agregação

Adicionado suporte paranovos operadores de string deagregação ($concat, $substr,$substrBytes, $substrCP,$strcasecmp), um operador deagregação de matriz ($size),um operador de acumulador dogrupo de agregação ($push) eestágios de agregação ($redacte $indexStats). Tambémadicionamos suporte paraoperadores de matriz posicional($[] e $[<identifier>]) ehint().

February 28, 2019

Atualizações do mecanismo Adicionada documentação paradeterminar as modificações decluster pendentes e atualizar aversão do mecanismo do cluster.

February 15, 2019

Auditoria de eventos Adicionado suporte para aauditoria de eventos de bancode dados com o AmazonCloudWatch Logs.

February 12, 2019

Início rápido Adicionado um tópico de Iníciorápido para ajudar você acomeçar com facilidade a usar oAmazon DocumentDB com AWSCloudFormation.

January 11, 2019

Lançamento público (p. 585) Este é o lançamento públicoinicial do Amazon DocumentDB(compatível com MongoDB).Esse lançamento inclui o Guiado desenvolvedor e a Referênciade API de gerenciamento derecursos integrada.

January 9, 2019

590







https://docs.aws.amazon.com/documentdb/latest/developerguide/mongo-apis-aggregation-pipeline.html

https://docs.aws.amazon.com/documentdb/latest/developerguide/mongo-apis-aggregation-pipeline.html

https://docs.aws.amazon.com/documentdb/latest/developerguide/db-cluster-version-upgrade.html

https://docs.aws.amazon.com/documentdb/latest/developerguide/event-auditing.html


https://docs.aws.amazon.com/documentdb/latest/developerguide/what-is.html

https://docs.aws.amazon.com/documentdb/latest/developerguide/what-is.html

https://docs.aws.amazon.com/documentdb/latest/developerguide/api-reference.html




Se fornecermos uma tradução da versão em inglês do guia, a versão em inglês prevalecerá caso hajaqualquer conflito entre as versões. A tradução é fornecida com o uso de tradução por máquina.

dxci