Condividi tramite

Panoramica del Azure SDK per le librerie Go

Il Azure SDK per Go include librerie di gestione e librerie client del piano dati. Questo articolo offre una panoramica per comprendere quali sono le librerie, come si adattano ai flussi di lavoro Azure e dove andare avanti per i modelli specifici di Go.

Librerie di gestione

Usare le librerie di gestione per effettuare il provisioning, configurare e gestire le risorse Azure. Si concentrano sulla gestione delle risorse stesse anziché sui dati archiviati all'interno di essi. Le librerie di gestione eseguono operazioni piano di controllo, che gestiscono le risorse Azure e la configurazione del servizio. Le attività tipiche includono:

  • Creazione o aggiornamento di gruppi di risorse, reti virtuali o macchine virtuali.
  • Configurazione di impostazioni di sicurezza, identità, criteri di accesso e diagnostica.
  • Elencare, contrassegnare ed eliminare risorse Azure all'interno di una sottoscrizione.
  • Automazione delle operazioni di distribuzione, pulizia, conformità e piattaforma.

I pacchetti della libreria di gestione hanno nomi come armcompute, armnetworke armkeyvault. Usare le librerie di gestione durante le fasi di configurazione, configurazione e governance di un ciclo di vita di un'applicazione. Per la documentazione dettagliata del pacchetto, cercare il pacchetto in pkg.go.dev.

Librerie dei client

Usare le librerie client quando l'applicazione Go deve interagire con i dati o le proprietà di runtime all'interno di un servizio Azure già configurato. Le librerie client eseguono operazioni del piano dati , che funzionano con i dati archiviati in o che passano attraverso un servizio. Le attività tipiche includono:

  • Caricamento e download di BLOB da un account di archiviazione.
  • Invio e ricezione di messaggi con bus di servizio o Event Hubs.
  • Lettura, scrittura o eliminazione di record in un database.
  • Recuperare segreti dal Key Vault.
  • Esecuzione di query o operazioni su risorse fornite.

I pacchetti di libreria client hanno nomi come azblob, azstorageazsecrets, azservicebus, e azeventhubs. Usare le librerie client dopo aver già effettuato il provisioning del servizio Azure sottostante usando le librerie di gestione. Per la documentazione dettagliata del pacchetto, cercare il pacchetto in pkg.go.dev.

Uso di librerie di gestione e librerie client

Una singola soluzione Go può usare sia le librerie di gestione che le librerie client tra piani di controllo e dati. Ad esempio, è possibile usare una libreria di gestione durante l'installazione per creare un account di archiviazione (piano di controllo) e quindi usare una libreria client nell'applicazione per caricare e scaricare BLOB (piano dati). La comprensione della distinzione consente di scegliere la libreria corretta per ogni attività nel flusso di lavoro.

Per modelli ed esempi specifici di Go per ogni piano, vedere questi articoli:

Installazione dei pacchetti Go

Nella maggior parte dei progetti si installano i pacchetti Go per la gestione delle versioni e delle dipendenze.

Per installare un pacchetto Go, eseguire il go get comando .

Ad esempio, per installare il armcompute pacchetto, eseguire il comando seguente:

go get github.com/Azure/azure-sdk-for-go/sdk/resourcemanager/compute/armcompute

Nella maggior parte delle app Go installare i pacchetti seguenti per l'autenticazione:

  • github.com/Azure/azure-sdk-for-go/sdk/azcore/to
  • github.com/Azure/azure-sdk-for-go/sdk/azidentity

Importazione di pacchetti nel codice Go

Dopo aver scaricato i pacchetti, importarli nell'app usando l'istruzione import :

import (
    "github.com/Azure/azure-sdk-for-go/sdk/azcore/to"
    "github.com/Azure/azure-sdk-for-go/sdk/azidentity"
    "github.com/Azure/azure-sdk-for-go/sdk/resourcemanager/compute/armcompute"
)

Autenticazione per Azure

Le app Go che usano le librerie SDK di Azure devono autenticarsi usando Microsoft Entra ID con la libreria Azure Identity. L'autenticazione basata su token è più sicura e gestibile rispetto alle stringhe di connessione o alle chiavi. La credenziale consigliata dipende dalla posizione in cui viene eseguita l'app: usare le identità gestite per le app ospitate Azure, le credenziali dello sviluppatore o un'entità servizio per lo sviluppo locale e un'entità servizio per la maggior parte degli scenari locali.

L'opzione di autenticazione predefinita è DefaultAzureCredential, che usa le variabili di ambiente impostate in precedenza in questo articolo. Nel codice Go creare un azidentity oggetto come indicato di seguito:

cred, err := azidentity.NewDefaultAzureCredential(nil)
if err != nil {
  // handle error
}

Per altre informazioni sull'autenticazione, vedere Azure SDK per l'autenticazione Go.

Creazione di un client di Gestione risorse

Dopo aver ottenuto le credenziali da Azure Identity, creare un client per connettersi al servizio di Azure di destinazione.

Si supponga, ad esempio, di volersi connettere al servizio Azure Compute. Il pacchetto Compute è costituito da uno o più client. Un client raggruppa un set di API correlate, fornendo l'accesso alla relativa funzionalità all'interno della sottoscrizione specificata. Creare uno o più client per accedere alle API necessarie.

Il codice seguente usa il armcompute. Nuovo tipoVirtualMachinesClient per creare un client per gestire le macchine virtuali:

client, err := armcompute.NewVirtualMachinesClient("<subscription ID>", cred, nil)
if err != nil {
  // handle error
}

Per altre informazioni sulla gestione delle risorse di Azure con Go, vedere Use the Azure SDK for Go for control plane operations.

Usare lo stesso modello per connettersi ad altri servizi Azure. Ad esempio, installare il pacchetto armnetwork e creare un client di rete virtuale per gestire le risorse di rete virtuale.

client, err := armnetwork.NewVirtualNetworksClient("<subscription ID>", cred, nil)
if err != nil {
  // handle error
}

Esempio di codice:

package main

import (
    "github.com/Azure/azure-sdk-for-go/sdk/azidentity"
    "github.com/Azure/azure-sdk-for-go/sdk/resourcemanager/compute/armcompute"
)

func main() {
    cred, err := azidentity.NewDefaultAzureCredential(nil)
    if err != nil {
        // handle error
    }
    client, err := armcompute.NewVirtualMachinesClient("<subscription ID>", cred, nil)
    if err != nil {
        // handle error
    }
}

Per altre informazioni sull'uso del Azure SDK per i servizi di Azure Go, vedere Use the Azure SDK for Go for data plane operations.

Uso del repository Azure SDK per Go

Dopo aver creato un'istanza di un client, utilizzarlo per effettuare chiamate API alle risorse di Azure. Per gli scenari di gestione delle risorse, la maggior parte dei casi d'uso sono operazioni CRUD (creazione, lettura, aggiornamento, eliminazione).

Per trovare le operazioni per un tipo specifico, sfogliare il codice sorgente nel repository GitHub di Azure SDK per Go. L'origine SDK è organizzata nella directory sdk/, con librerie di gestione in sdk/resourcemanager/ e librerie client in cartelle specifiche del servizio, ad esempio sdk/storage/ e sdk/security/keyvault/.

Per individuare l'origine per un tipo specifico, seguire questa procedura:

  1. Vai al repository GitHub di Azure SDK per Go.
  2. Passare a sdk/resourcemanager/ per le librerie di gestione o sdk/ per le librerie client.
  3. Aprire la cartella del servizio e quindi la cartella del pacchetto. Ad esempio: sdk/resourcemanager/compute/armcompute/.
  4. Trova il file di origine che contiene il tipo necessario. I tipi client e i relativi metodi sono in genere nei file denominati dopo il client, ad esempio virtualmachines_client.go.
  5. Per informazioni sull'utilizzo, leggere i commenti e le firme dei metodi del tipo.

È anche possibile compilare direttamente l'URL. Ad esempio, per trovare l'origine delle operazioni del gruppo di risorse, passare a https://github.com/Azure/azure-sdk-for-go/tree/main/sdk/resourcemanager/resources/armresources.

Questo esempio illustra come trovare la fonte per le operazioni del gruppo di risorse di Azure.

  1. Passare al repository Azure SDK per Go su GitHub.
  2. Vai a sdk/resourcemanager/resources/armresources/.
  3. Aprire resource_groups_client.go per trovare il tipo /ResourceGroupsClient e il relativo metodo CreateOrUpdate.
  4. Leggere i commenti e i parametri del metodo per comprendere come effettuare la chiamata API.

Per la documentazione di riferimento generata, cercare il pacchetto in pkg.go.dev.

Operazioni a esecuzione prolungata

Il completamento di alcune operazioni richiede molto tempo. Per gestire queste operazioni, le librerie di gestione forniscono funzioni che supportano operazioni a esecuzione prolungata tramite chiamate asincrone. Questi nomi di funzione iniziano con Begin, ad esempio BeginCreate e BeginDelete.

Poiché queste funzioni sono asincrone, il codice non si blocca mentre la funzione termina l'attività. La funzione restituisce invece immediatamente un oggetto poller . Il codice chiama quindi una funzione poller sincrona che restituisce quando viene completata la funzione asincrona originale.

Il frammento di codice seguente illustra un esempio di questo modello.

ctx := context.Background()
// Call an asynchronous function to create a client. The return value is a poller object.
poller, err := client.BeginCreate(ctx, "resource_identifier", "additional_parameter")

if err != nil {
    // handle error...
}

// Call the poller object's PollUntilDone function that will block until the poller object
// has been updated to indicate the task has completed.
resp, err = poller.PollUntilDone(ctx, nil)
if err != nil {
    // handle error...
}

// Print the fact that the LRO completed.
fmt.Printf("LRO done")

// Work with the response ("resp") object.

Punti principali:

  • La PollUntilDone funzione richiede un intervallo di polling che specifica la frequenza con cui deve tentare di ottenere lo stato. Il valore predefinito interval è 30 secondi se si passa nil per il parametro options, ma è possibile modificarlo in base alle esigenze.
  • L'intervallo è in genere breve. Vedere la documentazione relativa alla risorsa Azure specifica per gli intervalli consigliati.
  • La sezione LRO della pagina Go Azure SDK Design Guidelines include un esempio più avanzato e linee guida generali per LRO.

Per ulteriori dettagli sui modelli di utilizzo comuni, vedere Common usage patterns in Azure SDK for Go.

Passaggi successivi

Per ulteriori informazioni sull'autenticazione, la costruzione client, l'operazione a esecuzione prolungata e i modelli di procedura dettagliata per il servizio, vedere gli articoli specifici per il piano:

Per esempi, vedere Azure SDK per gli esempi go su GitHub.

  • Last updated on