Condividi tramite

Guida introduttiva: Modulo client di Archiviazione BLOB di Azure per Go

  • Articolo

Introduzione al modulo client di Archiviazione BLOB di Azure per Go per gestire BLOB e contenitori. Seguire questi passaggi per installare il pacchetto e provare il codice di esempio per le attività di base.

Documentazione di riferimento sull'API | Codice sorgente della libreria | Pacchetto (pkg.go.dev)

Prerequisiti

Configurazione

Questa sezione illustra come preparare un progetto da usare con il modulo client di Archiviazione BLOB di Azure per Go.

Scaricare l'applicazione di esempio

L'applicazione di esempio usata in questa guida rapida è un'applicazione Go di base.

Usare git per scaricare una copia dell'applicazione nell'ambiente di sviluppo.

git clone https://github.com/Azure-Samples/storage-blobs-go-quickstart

Questo comando consente di duplicare il repository nella cartella locale git. Per aprire l'esempio Go per l'archiviazione BLOB, cercare il file denominato storage-quickstart.go.

Installare i pacchetti

Per usare le risorse BLOB e contenitori in un account di archiviazione, installare il pacchetto azblob usando il comando seguente:

go get github.com/Azure/azure-sdk-for-go/sdk/storage/azblob

Per eseguire l'autenticazione con Microsoft Entra ID (scelta consigliata), installare il modulo azidentity usando il comando seguente:

go get github.com/Azure/azure-sdk-for-go/sdk/azidentity

Eseguire l'autenticazione ad Azure e autorizzare l'accesso ai dati BLOB

Le richieste dell'applicazione ad Archiviazione BLOB di Azure devono essere autorizzate. L'uso di DefaultAzureCredential e della libreria client di identità di Azure è l'approccio consigliato per l'implementazione di connessioni senza password ai servizi di Azure nel codice, inclusa l'archiviazione BLOB.

È anche possibile autorizzare le richieste ad Archiviazione BLOB di Azure usando la chiave di accesso dell'account. Tuttavia, questo approccio deve essere usato con cautela. Gli sviluppatori devono essere diligenti per non esporre mai la chiave di accesso in una posizione non sicura. Chiunque abbia la chiave di accesso può autorizzare richieste all'account di archiviazione e di fatto ha accesso a tutti i dati. DefaultAzureCredential offre maggiore sicurezza e semplicità di gestione rispetto alla chiave dell'account per consentire l'autenticazione senza password. Entrambe le opzioni sono illustrate nell'esempio seguente.

DefaultAzureCredential è un'implementazione della catena di credenziali fornita dalla libreria client di identità di Azure per Go. DefaultAzureCredential supporta più metodi di autenticazione e determina il metodo da usare in fase di esecuzione. Questo approccio consente all'app di usare metodi di autenticazione diversi in ambienti diversi (locale e di produzione) senza implementare codice specifico dell'ambiente.

Per altre informazioni sull'ordine e le posizioni in cui DefaultAzureCredential cerca le credenziali, vedere Panoramica della libreria di identità di Azure.

Ad esempio, l'app può eseguire l'autenticazione usando le credenziali di accesso dell'interfaccia della riga di comando di Azure durante lo sviluppo in locale. Dopo la distribuzione in Azure, l'app può quindi usare un'identità gestita. Questa transizione tra ambienti non richiede modifiche al codice.

Assegnare ruoli all'account utente di Microsoft Entra

Quando si sviluppa in locale, assicurarsi che l'account utente che accede ai dati BLOB disponga delle autorizzazioni corrette. Per leggere e scrivere dati BLOB, è necessario disporre del ruolo Collaboratore ai dati dei BLOB di archiviazione. Per assegnare a se stessi questo ruolo, è necessario assegnare il ruolo Amministratore accesso utenti o un altro ruolo che include l'azione Microsoft.Authorization/roleAssignments/write. È possibile assegnare ruoli controllo degli accessi in base al ruolo di Azure a un utente usando il portale di Azure, l'interfaccia della riga di comando di Azure o Azure PowerShell. Per altre informazioni sugli ambiti disponibili per le assegnazioni di ruolo, vedere la pagina panoramica dell'ambito.

In questo scenario si assegneranno le autorizzazioni all'account utente con ambito all'account utente, per seguire il principio dei privilegi minimi. Questa procedura offre agli utenti solo le autorizzazioni minime necessarie e crea ambienti di produzione più sicuri.

L'esempio seguente assegnerà il ruolo Collaboratore ai dati dei BLOB di archiviazione all'account utente, che fornisce l'accesso in lettura e scrittura ai dati BLOB nell'account di archiviazione.

Importante

Nella maggior parte dei casi, la propagazione dell'assegnazione di ruolo in Azure richiederà almeno due minuti, ma in rari casi può richiedere fino a otto minuti. Se si ricevono errori di autenticazione quando si esegue il codice per la prima volta, attendere alcuni istanti e riprovare.

  1. Nel portale di Azure, individuare l'account di archiviazione usando la barra di ricerca principale o lo spostamento a sinistra.

  2. Nella pagina di panoramica dell'account di archiviazione selezionare Controllo di accesso (IAM) dal menu a sinistra.

  3. Nella pagina Controllo di accesso (IAM), selezionare la scheda Assegnazioni di ruolo.

  4. Selezionare + Aggiungi dal menu in alto e quindi Aggiungi assegnazione di ruolo dal menu a discesa risultante.

    Screenshot che mostra come assegnare un ruolo.

  5. Usare la casella di ricerca per filtrare i risultati in base al ruolo desiderato. Per questo esempio, cercare Collaboratore ai dati dei BLOB di archiviazione e selezionare il risultato corrispondente, quindi scegliere Avanti.

  6. In Assegna accesso a selezionare Utente, gruppo o entità servizio e quindi scegliere + Seleziona membri.

  7. Nella finestra di dialogo cercare il nome utente di Microsoft Entra (in genere l'indirizzo di posta elettronica user@domain) e quindi scegliere Selezionare nella parte inferiore della finestra di dialogo.

  8. Selezionare Rivedi e assegna per passare alla pagina finale e quindi Rivedi e assegna di nuovo per completare il processo.

Eseguire l'accesso e connettere il codice dell'app ad Azure usando DefaultAzureCredential

È possibile autorizzare l'accesso ai dati nell'account di archiviazione seguendo questa procedura:

  1. Assicurarsi di essere autenticati con lo stesso account Microsoft Entra a cui è stato assegnato il ruolo nell'account di archiviazione. L'esempio seguente illustra come eseguire l'autenticazione tramite l'interfaccia della riga di comando di Azure:

    az login

  2. Per usare DefaultAzureCredential in un'applicazione Go, installare il modulo azidentity usando il comando seguente:

    go get github.com/Azure/azure-sdk-for-go/sdk/azidentity

L'autenticazione tramite l'interfaccia della riga di comando di Azure non è consigliata per le applicazioni in esecuzione in Azure. Quando viene distribuito in Azure, è possibile usare lo stesso codice per autorizzare le richieste ad Archiviazione di Azure da un'applicazione in esecuzione in Azure. È tuttavia necessario abilitare l'identità gestita nell'app in Azure e configurare l'account di archiviazione per consentire la connessione a tale identità gestita. Per istruzioni dettagliate sulla configurazione di questa connessione tra i servizi di Azure, vedere l'esercitazione Autenticare le app ospitate in Azure.

Per altre informazioni sui diversi metodi di autenticazione, vedere Autenticazione di Azure con Azure SDK per Go.

Eseguire l'esempio

L'esempio di codice esegue le azioni seguenti:

  • Crea un oggetto client autorizzato per l'accesso ai dati tramite DefaultAzureCredential
  • Crea un contenitore in un account di archiviazione
  • Carica un BLOB nel contenitore
  • Elenca i BLOB nel contenitore
  • Scarica i dati BLOB in un buffer
  • Elimina le risorse BLOB e contenitore create dall'app

Prima di eseguire l'esempio, aprire il file storage-quickstart.go. Sostituire <storage-account-name> con il nome del proprio account di archiviazione di Azure.

Eseguire quindi l'applicazione usando il comando seguente:

go run storage-quickstart.go

L'output dell'app è simile all'esempio seguente:

Azure Blob storage quick start sample
Creating a container named quickstart-sample-container
Uploading a blob named sample-blob
Listing the blobs in the container:
sample-blob
Blob contents:

Hello, world! This is a blob.

Press enter key to delete resources and exit the application.

Cleaning up.
Deleting the blob sample-blob
Deleting the container quickstart-sample-container

Quando si preme il tasto INVIO al prompt, il programma di esempio elimina le risorse BLOB e contenitore create dall'app.

Suggerimento

È anche possibile usare uno strumento come Azure Storage Explorer per visualizzare i file nell'archiviazione BLOB. Azure Storage Explorer è uno strumento multipiattaforma gratuito che consente di accedere alle informazioni dell'account di archiviazione.

Informazioni sul codice di esempio

A questo punto, viene descritto in dettaglio il codice di esempio per consentire di comprenderne il funzionamento.

Autorizzare l'accesso e creare un oggetto client

L'uso di qualsiasi risorsa di Azure con l'SDK inizia con la creazione di un oggetto client. Per creare l'oggetto client, l'esempio di codice chiama azblob.NewClient con i valori seguenti:

  • serviceURL: URL dell'account di archiviazione
  • cred: credenziali di Microsoft Entra ottenute tramite il modulo azidentity
  • options: opzioni client. Passare un valore nullo per accettare i valori predefiniti

Nell'esempio di codice seguente viene creato un oggetto client per interagire con le risorse contenitore e BLOB in un account di archiviazione:

// TODO: replace <storage-account-name> with your actual storage account name
url := "https://<storage-account-name>.blob.core.windows.net/"
ctx := context.Background()

credential, err := azidentity.NewDefaultAzureCredential(nil)
handleError(err)

client, err := azblob.NewClient(url, credential, nil)
handleError(err)

Creazione di un contenitore

L'esempio di codice crea una nuova risorsa contenitore nell'account di archiviazione. Se esiste già un contenitore con lo stesso nome, viene generato un errore ResourceExistsError.

Importante

I nomi dei contenitori devono essere in minuscolo. Per altre informazioni sui requisiti di denominazione per contenitori e BLOB, vedere Denominazione e riferimento a contenitori, BLOB e metadati.

L'esempio di codice seguente crea un nuovo contenitore denominato quickstart-sample-container nell'account di archiviazione:

// Create the container
containerName := "quickstart-sample-container"
fmt.Printf("Creating a container named %s\n", containerName)
_, err = client.CreateContainer(ctx, containerName, nil)
handleError(err)

Per altre informazioni sulla creazione di un contenitore e per esplorare altri esempi di codice, vedere Creare un contenitore BLOB con Go.

Caricare i BLOB nel contenitore

L'esempio di codice crea una matrice di byte con alcuni dati e carica i dati come buffer in una nuova risorsa BLOB nel contenitore specificato.

L'esempio di codice seguente carica i dati BLOB nel contenitore specificato usando il metodo UploadBuffer:

data := []byte("\nHello, world! This is a blob.\n")
blobName := "sample-blob"

// Upload to data to blob storage
fmt.Printf("Uploading a blob named %s\n", blobName)
_, err = client.UploadBuffer(ctx, containerName, blobName, data, &azblob.UploadBufferOptions{})
handleError(err)

Per altre informazioni sul caricamento di BLOB e per esplorare altri esempi di codice, vedere Caricare un BLOB con Go.

Elencare i BLOB in un contenitore

L'esempio di codice elenca i BLOB nel contenitore specificato. Questo esempio usa NewListBlobsFlatPager, che restituisce un PAGER per i BLOB a partire dall'indicatore specificato. In questo caso viene usato un indicatore vuoto per avviare l'enumerazione dall'inizio e continuare il paging fino a quando non sono presenti altri risultati. Questo metodo restituisce i nomi dei BLOB in ordine lessicografico.

L'esempio di codice seguente elenca i BLOB nel contenitore specificato:

// List the blobs in the container
fmt.Println("Listing the blobs in the container:")

pager := client.NewListBlobsFlatPager(containerName, &azblob.ListBlobsFlatOptions{
	Include: azblob.ListBlobsInclude{Snapshots: true, Versions: true},
})

for pager.More() {
	resp, err := pager.NextPage(context.TODO())
	handleError(err)

	for _, blob := range resp.Segment.BlobItems {
		fmt.Println(*blob.Name)
	}
}

Per altre informazioni sull'elenco dei BLOB e per esplorare altri esempi di codice, vedere Elencare i BLOB con Go.

Scaricare il BLOB

L'esempio di codice scarica un BLOB usando il metodo DownloadStream e crea un lettore di ripetizione dei tentativi per la lettura dei dati. Se si verifica un errore di connessione durante la lettura, il lettore di ripetizione dei tentativi effettuerà ulteriori richieste per ristabilire una connessione e continuare la lettura. È possibile specificare le opzioni del lettore di ripetizione dei tentativi usando lo struct RetryReaderOptions.

L'esempio di codice seguente scarica un BLOB e scrive il contenuto nella console:

// Download the blob
get, err := client.DownloadStream(ctx, containerName, blobName, nil)
handleError(err)

downloadedData := bytes.Buffer{}
retryReader := get.NewRetryReader(ctx, &azblob.RetryReaderOptions{})
_, err = downloadedData.ReadFrom(retryReader)
handleError(err)

err = retryReader.Close()
handleError(err)

// Print the contents of the blob we created
fmt.Println("Blob contents:")
fmt.Println(downloadedData.String())

Per altre informazioni sul download dei BLOB e per esplorare altri esempi di codice, vedere Scaricare un BLOB con Go.

Pulire le risorse

Se i BLOB caricati in questa guida introduttiva non sono più necessari, è possibile eliminare il singolo BLOB usando il metodo DeleteBlob oppure l'intero contenitore e il relativo contenuto usando il metodo DeleteContainer.

// Delete the blob
fmt.Printf("Deleting the blob " + blobName + "\n")

_, err = client.DeleteBlob(ctx, containerName, blobName, nil)
handleError(err)

// Delete the container
fmt.Printf("Deleting the container " + containerName + "\n")
_, err = client.DeleteContainer(ctx, containerName, nil)
handleError(err)

Per altre informazioni sull'eliminazione di BLOB e contenitori e per esplorare altri esempi di codice, vedere Eliminare un BLOB con Go e Eliminare un contenitore con Go.

Passaggio successivo

Guide per sviluppatori di Archiviazione BLOB di Azure per Go