Inizia a usare i cluster elastici Amazon DocumentDB

Questa sezione introduttiva illustra come creare e interrogare il primo cluster elastico.

Esistono molti modi per connettersi e iniziare a usare Amazon DocumentDB. La seguente procedura è il modo più rapido, semplice e facile per gli utenti di iniziare a utilizzare il nostro potente database di documenti. Questa guida consente AWS CloudShell di connettere e interrogare il cluster Amazon DocumentDB direttamente da. Console di gestione AWS I nuovi clienti idonei per il piano AWS gratuito possono utilizzare Amazon DocumentDB e CloudShell gratuitamente. Se il tuo AWS CloudShell ambiente o il cluster elastico di Amazon DocumentDB utilizza risorse oltre il livello gratuito, ti verranno addebitate le AWS tariffe normali per tali risorse. Questa guida ti aiuterà a iniziare a usare Amazon DocumentDB in meno di 5 minuti.

Prerequisiti

Prima di creare il tuo primo cluster Amazon DocumentDB, devi fare quanto segue:

Crea un account Amazon Web Services (AWS)

Prima di poter iniziare a utilizzare Amazon DocumentDB, devi disporre di un account Amazon Web Services (AWS). L' AWS account è gratuito. Paghi solo per i servizi e le risorse che utilizzi.

Se non ne hai uno Account AWS, completa i seguenti passaggi per crearne uno.

Per iscriverti a Account AWS

1. Aprire https://portal.aws.amazon.com/billing/signup.

2. Segui le istruzioni online.

   Nel corso della procedura di registrazione riceverai una telefonata o un messaggio di testo e ti verrà chiesto di inserire un codice di verifica attraverso la tastiera del telefono.

   Quando ti iscrivi a un Account AWS, Utente root dell'account AWS viene creato un. L’utente root dispone dell’accesso a tutte le risorse e tutti i Servizi AWS nell’account. Come best practice di sicurezza, assegna l’accesso amministrativo a un utente e utilizza solo l’utente root per eseguire attività che richiedono l’accesso di un utente root.

Configura le autorizzazioni AWS Identity and Access Management (IAM) necessarie.

L'accesso per gestire le risorse di Amazon DocumentDB come cluster, istanze e gruppi di parametri del cluster richiede credenziali che AWS possono essere utilizzate per autenticare le tue richieste. Per ulteriori informazioni, consulta Gestione delle identità e degli accessi per Amazon DocumentDB.

1. Nella barra di ricerca di Console di gestione AWS, inserisci IAM e seleziona IAM nel menu a discesa.

2. Una volta entrati nella console IAM, seleziona Utenti dal pannello di navigazione.

3. Seleziona il tuo nome utente.

4. Scegli Add Permissions (Aggiungi autorizzazioni).

5. Seleziona Allega direttamente le politiche.

6. AmazonDocDBElasticFullAccessDigita la barra di ricerca e selezionala una volta visualizzata nei risultati della ricerca.

7. Scegli Next (Successivo).

8. Scegli Add Permissions (Aggiungi autorizzazioni).

Nota

Il tuo AWS account include un VPC predefinito in ogni regione. Se scegli di utilizzare un Amazon VPC, completa i passaggi nell'argomento Creazione di un Amazon VPC nella Amazon VPC User Guide.

Fase 1: Creare un cluster elastico

In questa sezione spieghiamo come creare un nuovo cluster elastico, utilizzando Console di gestione AWS o AWS CLI con le seguenti istruzioni.

Using the Console di gestione AWS

Per creare una configurazione di cluster elastico utilizzando Console di gestione AWS:

1. Accedi a e apri Console di gestione AWS la console Amazon DocumentDB all'indirizzo https://console.aws.amazon.com/docdb.

2. Nella console di gestione Amazon DocumentDB, in Clusters, scegli Crea.

   

3. Nella pagina Crea cluster Amazon DocumentDB, nella sezione Tipo di cluster, scegli Elastic cluster.

   

4. Nella sezione Configurazione, configura quanto segue:

   1. Nel campo Nome del cluster, inserisci un identificatore univoco del cluster (seguendo i requisiti di denominazione sotto il campo).

   2. Nel campo Numero di frammenti, inserisci il numero di frammenti che desideri inserire nel cluster. Il numero massimo di frammenti per cluster è 32.

      Nota

      Verranno distribuiti due nodi per ogni shard. Entrambi i nodi avranno la stessa capacità di shard.

   3. Nel campo Numero di istanze di Shard, scegli il numero di istanze di replica da associare a ogni shard. Il numero massimo di istanze dello shard è 16, con incrementi di 1. Tutte le istanze di replica hanno la stessa capacità di shard definita nel campo seguente. A scopo di test, il valore predefinito di 2 dovrebbe essere sufficiente.

      Nota

      Il numero di istanze di replica si applica a tutti i frammenti del cluster elastico. Un valore di conteggio delle istanze dello shard pari a 1 indica che esiste un'istanza di writer e tutte le istanze aggiuntive sono repliche che possono essere utilizzate per le letture e per migliorare la disponibilità. A scopo di test, il valore predefinito di 2 dovrebbe essere sufficiente.

   4. Nel campo Capacità dello shard, scegli il numero di CPU virtuali (vCPU) da associare a ciascuna istanza dello shard. Il numero massimo di vCPU per istanza di shard è 64. I valori consentiti sono 2, 4, 8, 16, 32, 64. A scopo di test, il valore predefinito di 2 dovrebbe essere sufficiente.

   5. Nel campo Virtual Private Cloud (VPC), scegli un VPC dall'elenco a discesa.

   6. Per le sottoreti e i gruppi di sicurezza VPC, puoi utilizzare le impostazioni predefinite o selezionare tre sottoreti a tua scelta e fino a tre gruppi di sicurezza VPC (minimo uno).

   

5. Nella sezione Autenticazione, inserisci una stringa che identifichi il nome di accesso dell'utente principale nel campo Nome utente.

   Nel campo Password, inserisci una password univoca conforme alle istruzioni, quindi confermala.

   

6. Nella sezione Crittografia, mantieni l'impostazione predefinita (Chiave predefinita).

   Facoltativamente, puoi inserire un AWS KMS key ARN che hai creato. Per ulteriori informazioni, consulta Crittografia dei dati inattivi per i cluster elastici Amazon DocumentDB.

   Importante

   La crittografia deve essere abilitata per i cluster elastici.

7. Nella sezione Backup, modifica i campi in base ai requisiti di backup. A scopo di test, è possibile mantenere le impostazioni predefinite.

   

   1. Periodo di conservazione dei backup: nell'elenco, scegli il numero di giorni per conservare i backup automatici di questo cluster prima di eliminarli.

   2. Finestra di backup: imposta l'ora e la durata giornaliere durante le quali Amazon DocumentDB deve effettuare i backup di questo cluster.

      1. Scegli Seleziona finestra se desideri configurare l'ora e la durata di creazione dei backup.

         Ora di inizio: nel primo elenco, scegli l'ora di inizio (UTC) per l'avvio dei backup automatici. Dal secondo elenco scegli il minuto dell'ora in cui desideri inizino i backup automatici.

         Durata: nell'elenco, scegli il numero di ore da assegnare alla creazione di backup automatici.

      2. Scegli Nessuna preferenza se desideri che Amazon DocumentDB scelga l'ora e la durata di creazione dei backup.

8. Nella sezione Manutenzione, scegli il giorno, l'ora e la durata in cui le modifiche o le patch vengono applicate al cluster. A scopo di test, puoi mantenere le impostazioni predefinite.

   

9. Scegli Crea cluster.

Il cluster elastico è ora in fase di provisioning. Il completamento dell'operazione può richiedere alcuni minuti. Puoi connetterti al tuo cluster quando lo stato del cluster elastico appare come Disponibile nell'elenco dei cluster.

Using the AWS CLI

Per creare un cluster elastico utilizzando il AWS CLI, utilizza l'create-clusteroperazione con i seguenti parametri:

• --cluster-name: obbligatorio. Il nome corrente del cluster di scala elastica immesso durante la creazione o l'ultima modifica.

• --shard-capacity: obbligatorio. Il numero di vCPU assegnate a ogni shard. Il massimo è 64. I valori consentiti sono 2, 4, 8, 16, 32, 64.

• --shard-count: obbligatorio. Il numero di frammenti assegnati al cluster. Il massimo è 32.

• --shard-instance-count—Facoltativo. Il numero di istanze di replica che si applicano a tutti i frammenti di questo cluster. Il massimo è 16.

• --admin-user-name: obbligatorio. Il nome utente associato all'utente amministratore.

• --admin-user-password: obbligatorio. La password associata all'utente amministratore.

• --auth-type: obbligatorio. Il tipo di autenticazione utilizzato per determinare dove recuperare la password utilizzata per accedere al cluster elastico. I tipi validi sono PLAIN_TEXT o. SECRET_ARN

• --vpc-security-group-ids—Facoltativo. Configura un elenco di gruppi di sicurezza EC2 VPC da associare a questo cluster.

• --preferred-maintenance-window—Facoltativo. Configura l'intervallo di tempo settimanale durante il quale può avvenire la manutenzione del sistema, in Universal Coordinated Time (UTC).

  Il formato è:ddd:hh24:mi-ddd:hh24:mi. Giorni validi (ddd): lun, mar, mer, gio, ven, sab, dom

  L'impostazione predefinita è una finestra di 30 minuti selezionata a caso da un intervallo di 8 ore per ciascuna regione Amazon Web Services, che si verifica in un giorno della settimana casuale.

  Finestra minima di 30 minuti.

• --kms-key-id—Opzionale. Configurare l'identificatore della chiave KMS per un cluster crittografato.

  L'identificatore della chiave KMS è Amazon Resource Name (ARN) per la chiave di crittografia. AWS KMS Se stai creando un cluster utilizzando lo stesso account Amazon Web Services che possiede la chiave di crittografia KMS utilizzata per crittografare il nuovo cluster, puoi utilizzare l'alias della chiave KMS anziché l'ARN per la chiave di crittografia KMS.

  Se non è specificata una chiave di crittografia KmsKeyId e se il StorageEncrypted parametro è vero, Amazon DocumentDB utilizza la chiave di crittografia predefinita.

• --preferred-backup-window—Facoltativo. L'intervallo di tempo giornaliero preferito durante il quale vengono creati i backup automatici. L'impostazione predefinita è una finestra di 30 minuti selezionata a caso da un intervallo di tempo di 8 ore per ciascuno. Regione AWS

• --backup-retention-period—Facoltativo. Il numero di giorni durante i quali vengono conservati i backup automatici. Il valore predefinito è 1.

• --storage-encrypted—Facoltativo. Configura se il cluster è crittografato o meno.

  --no-storage-encryptedspecifica che il cluster non è crittografato.

• --subnet-ids—Facoltativo. Configurare gli ID delle sottoreti di rete.

Nel seguente esempio, sostituisci ciascuno user input placeholder con le tue informazioni.

Nota

Gli esempi seguenti includono la creazione di una chiave KMS specifica. Per utilizzare la chiave KMS predefinita, non includete il --kms-key-id parametro.

Per Linux, macOS o Unix:

aws docdb-elastic create-cluster \
     --cluster-name sample-cluster-123 \
     --shard-capacity 8 \
     --shard-count 4 \
     --shard-instance-count 3 \
     --auth-type PLAIN_TEXT \
     --admin-user-name testadmin \
     --admin-user-password testPassword \
     --vpc-security-group-ids ec-65f40350 \
     --kms-key-id arn:aws:docdb-elastic:us-east-1:477568257630:cluster/b9f1d489-6c3e-4764-bb42-da62ceb7bda2 \
     --subnet-ids subnet-9253c6a3, subnet-9f1b5af9 \
     --preferred-backup-window 18:00-18:30 \ 
     --backup-retention-period 7

Per Windows:

aws docdb-elastic create-cluster ^
     --cluster-name sample-cluster-123 ^
     --shard-capacity 8 ^
     --shard-count 4 ^
     --shard-instance-count 3 ^
     --auth-type PLAIN_TEXT ^
     --admin-user-name testadmin ^
     --admin-user-password testPassword ^
     --vpc-security-group-ids ec-65f40350 ^
     --kms-key-id arn:aws:docdb-elastic:us-east-1:477568257630:cluster/b9f1d489-6c3e-4764-bb42-da62ceb7bda2 ^
     --subnet-ids subnet-9253c6a3, subnet-9f1b5af9 \
     --preferred-backup-window 18:00-18:30 \ 
     --backup-retention-period 7

Passaggio 2: connettiti al tuo cluster elastico

Connettiti al tuo cluster elastico Amazon DocumentDB utilizzando AWS CloudShell.

1. Nella console di gestione Amazon DocumentDB, in Clusters, individua il cluster elastico che hai creato. Scegli il tuo cluster facendo clic sulla casella di controllo accanto ad esso.

   

2. Scegli Connetti al cluster (che si trova accanto al menu a discesa Azioni). Questo pulsante è abilitato solo dopo aver fatto clic sulla casella di controllo accanto al cluster e lo stato del cluster viene visualizzato come Disponibile. Viene visualizzata la schermata del comando CloudShell Esegui.

3. Nel campo Nome nuovo ambiente, inserisci un nome univoco, ad esempio «test» e scegli Crea ed esegui. I dettagli dell'ambiente VPC vengono configurati automaticamente per il database Amazon DocumentDB.

   

4. Quando richiesto, inserisci la password che hai creato nella fase 1: creazione di un cluster elastico Amazon DocumentDB (sottofase 5).

   

   Dopo aver inserito la password e ricevuto la richiestadirect: mongos] <env-name>>, la connessione al cluster Amazon DocumentDB è stata completata

Nota

Per informazioni sulla risoluzione dei problemi, consulta Troubleshooting Amazon DocumentDB.

Passaggio 3: condividi la tua raccolta, inserisci ed interroga i dati

I cluster elastici aggiungono il supporto per lo sharding in Amazon DocumentDB. Ora che sei connesso al tuo cluster, puoi condividere il cluster, inserire dati ed eseguire alcune query.

1. Per condividere una raccolta, inserisci quanto segue:

   sh.shardCollection("db.Employee1" , { "Employeeid" : "hashed" })

2. Per inserire un singolo documento, inserisci quanto segue:

   db.Employee1.insertOne({"Employeeid":1, "Name":"Joe", "LastName": "Bruin", "level": 1 })

   Viene visualizzato il seguente output:

   WriteResult({ "nInserted" : 1 })

3. Per leggere il documento che hai scritto, inserisci il findOne() comando (restituisce un singolo documento):

   db.Employee1.findOne()

   Viene visualizzato il seguente output:

   {
   "_id" : ObjectId("61f344e0594fe1a1685a8151"),
   "EmployeeID" : 1,
   "Name" : "Joe",
   "LastName" : "Bruin",
   "level" : 1
   }

4. Per eseguire qualche altra domanda, considera un caso d'uso del profilo di gioco. Innanzitutto, inserisci alcune voci in una raccolta intitolata «Employee». Immetti i seguenti dati:

   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 }
   ])

   Viene visualizzato il seguente risultato:

   { acknowledged: true, 
        insertedIds: { 
           '0': ObjectId('679d02cd6b5a0581be78bcbd'),
           '1': ObjectId('679d02cd6b5a0581be78bcbe'),
           '2': ObjectId('679d02cd6b5a0581be78bcbf'),
           '3': ObjectId('679d02cd6b5a0581be78bcc0')
       }
   }

5. Per restituire tutti i documenti della raccolta dei profili, immettete il comando find ():

   db.Employee.find()

   Vengono visualizzati i dati inseriti nel passaggio 4.

6. Per interrogare un singolo documento, includi un filtro (ad esempio: «Katie»). Immetti i seguenti dati:

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

   Viene visualizzato il seguente output:

   [

      {

        _id: ObjectId('679d02cd6b5a0581be78bcc0'),

        Employeeid: 4,

        name: 'Katie',

        lastname: 'Schaper',

        level: 3

      }

   ]

7. Per trovare un profilo e modificarlo, immettete il findAndModify comando. In questo esempio, al dipendente «Matt» viene assegnato un livello più alto di «14":

   db.Employee.findAndModify({     
       query: { "Employeeid" : 1, "name" : "Matt"},     
       update: { "Employeeid" : 1, "name" : "Matt", "lastname" : "Winkle", "level" : 14 } 
   })

   Viene visualizzato il seguente risultato (si noti che il livello non è ancora cambiato):

   {

      _id: ObjectId('679d02cd6b5a0581be78bcbd'),

      Employeeid: 1,

      name: 'Matt',

      lastname: 'Winkle',

      level: 12

   }

8. Per verificare l'aumento del livello, inserisci la seguente query:

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

   Viene visualizzato il seguente output:

   [
      {

      _id: ObjectId('679d02cd6b5a0581be78bcbd'),

      Employeeid: 1,

      name: 'Matt',

      lastname: 'Winkle',

      level: 14

      }
   ]

Fase 4: Esplora

Complimenti! Hai completato con successo la procedura introduttiva per i cluster elastici Amazon DocumentDB.

Qual è il prossimo passo? Scopri come sfruttare appieno questo database con alcune delle sue funzionalità più popolari:

• Best practice per i cluster elastici Amazon DocumentDB

• Gestione dei cluster elastici Amazon DocumentDB

Nota

Il cluster elastico che hai creato con questa procedura introduttiva continuerà a generare costi a meno che tu non lo elimini. Per indicazioni, consulta Eliminazione di un cluster elastico.