Información general sobre las bibliotecas de SDK de Azure para Go

El SDK de Azure para Go incluye las bibliotecas de administración y las bibliotecas cliente del plano de datos. En este artículo se proporciona información general para que pueda comprender cuáles son las bibliotecas, cómo encajan en los flujos de trabajo de Azure y dónde ir a continuación para los patrones específicos de Go.

Bibliotecas de administración

Use las bibliotecas de administración para aprovisionar, configurar y controlar Azure recursos. Se centran en administrar los recursos en lugar de los datos almacenados dentro de ellos. Las bibliotecas de administración realizan operaciones de plano de control, que administran los recursos de Azure y la configuración de los servicios. Entre las tareas típicas se incluyen:

  • Crear o actualizar grupos de recursos, redes virtuales o máquinas virtuales.
  • Configuración de opciones de seguridad, identidades, directivas de acceso y diagnósticos.
  • Enumerar, etiquetar y eliminar recursos de Azure en una suscripción.
  • Automatización de las operaciones de implementación, limpieza, cumplimiento y plataforma.

Los paquetes de biblioteca de administración tienen nombres como armcompute, armnetworky armkeyvault. Use bibliotecas de administración durante las fases de configuración, configuración y gobernanza de un ciclo de vida de una aplicación. Para obtener documentación detallada del paquete, busque el paquete en pkg.go.dev.

Bibliotecas de cliente

Utiliza las bibliotecas cliente cuando tu aplicación Go necesite trabajar con superficies de datos o superficies de tiempo de ejecución dentro de un servicio de Azure ya aprovisionado. Las bibliotecas cliente realizan operaciones de plano de datos, que funcionan con los datos almacenados en un servicio o que fluyen a través de él. Entre las tareas típicas se incluyen:

  • Carga y descarga de blobs desde una cuenta de almacenamiento.
  • Envío y recepción de mensajes con Service Bus o Event Hubs.
  • Lectura, escritura o eliminación de registros en una base de datos.
  • Recuperando secretos de Key Vault.
  • Ejecución de consultas o operaciones contra recursos aprovisionados.

Los paquetes de biblioteca cliente tienen nombres como azblob, azstorage, azsecrets, , azservicebusy azeventhubs. Use bibliotecas de cliente después de aprovisionar el servicio Azure subyacente mediante bibliotecas de administración. Para obtener documentación detallada del paquete, busque el paquete en pkg.go.dev.

Uso simultáneo de bibliotecas de gestión y de cliente

Una única solución en Go puede usar tanto bibliotecas de gestión como de cliente en los planos de control y datos. Por ejemplo, puede usar una biblioteca de administración durante la instalación para crear una cuenta de almacenamiento (plano de control) y, a continuación, usar una biblioteca cliente en la aplicación para cargar y descargar blobs (plano de datos). Comprender la distinción le ayuda a elegir la biblioteca adecuada para cada tarea del flujo de trabajo.

Para obtener ejemplos y patrones específicos de Go para cada plano, consulte estos artículos:

Instalación de paquetes de Go

En la mayoría de los proyectos, se instalan los paquetes de Go para el control de versiones y la administración de dependencias.

Para instalar un paquete de Go, ejecute el go get comando .

Por ejemplo, para instalar el armcompute paquete, ejecute el siguiente comando:

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

En la mayoría de las aplicaciones de Go, instale los siguientes paquetes para la autenticación:

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

Importación de paquetes en el código de Go

Después de descargar los paquetes, impórtelos en la aplicación mediante la import instrucción :

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"
)

Autenticación en Azure

Las aplicaciones de Go que usan bibliotecas de SDK de Azure deben autenticarse mediante Microsoft Entra ID con la biblioteca Azure Identity. La autenticación basada en tokens es más segura y fácil de administrar que las cadenas de conexión o las claves. La credencial recomendada depende de dónde se ejecute la aplicación: use identidades administradas para aplicaciones hospedadas en Azure, credenciales de desarrollador o un principal de servicio para el desarrollo local, y un principal de servicio para la mayoría de los escenarios locales.

La opción de autenticación predeterminada es DefaultAzureCredential, que usa las variables de entorno establecidas anteriormente en este artículo. En el código de Go, cree un azidentity objeto de la siguiente manera:

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

Para obtener más información sobre la autenticación, consulte SDK de Azure for Go authentication.

Creación de un cliente de Administración de recursos

Después de obtener una credencial de Azure Identity, cree un cliente para conectarse al servicio de Azure de destino.

Por ejemplo, supongamos que desea conectarse al servicio Azure Compute. El paquete Compute consta de uno o varios clientes. Un cliente agrupa un conjunto de API relacionadas, lo que proporciona acceso a su funcionalidad dentro de la suscripción especificada. Cree uno o varios clientes para acceder a las API que necesita.

El código siguiente usa el armcompute. Tipo NewVirtualMachinesClient para crear un cliente para administrar máquinas virtuales:

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

Para obtener más información sobre cómo administrar recursos de Azure con Go, consulte Use el SDK de Azure para Go para las operaciones del plano de control.

Use el mismo patrón para conectarse con otros servicios de Azure. Por ejemplo, instale el armnetwork paquete y cree un cliente de red virtual para administrar los recursos de red virtual.

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

Ejemplo de código:

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

Para obtener más información sobre el uso del SDK de Azure para Go para servicios de Azure, consulte Use el SDK de Azure para Go para operaciones del plano de datos.

Uso del repositorio de SDK de Azure para Go

Después de crear una instancia de un cliente, úsela para realizar llamadas API a los recursos de Azure. En escenarios de administración de recursos, la mayoría de los casos de uso son operaciones CRUD (crear, leer, actualizar, eliminar).

Para buscar operaciones para un tipo específico, examine el código fuente en el repositorio de GitHub del SDK de Azure para Go. El origen del SDK se organiza en el directorio sdk/, con bibliotecas de administración en sdk/resourcemanager/ y bibliotecas cliente en carpetas específicas del servicio, como sdk/storage/ y sdk/security/keyvault/.

Para buscar el origen de un tipo específico, siga estos pasos:

  1. Vaya al repositorio SDK de Azure para Go en GitHub.
  2. Vaya a sdk/resourcemanager/ para ver las bibliotecas de administración o sdk/ para las bibliotecas cliente.
  3. Abra la carpeta de servicio y, a continuación, la carpeta del paquete. Por ejemplo: sdk/resourcemanager/compute/armcompute/.
  4. Busque el archivo de origen que contiene el tipo que necesita. Los tipos de cliente y sus métodos suelen estar en archivos denominados después del cliente, como virtualmachines_client.go.
  5. Lea los comentarios del tipo y las signaturas de métodos para obtener información sobre el uso.

También puede compilar la dirección URL directamente. Por ejemplo, para buscar el origen de operaciones del grupo de recursos, vaya a https://github.com/Azure/azure-sdk-for-go/tree/main/sdk/resourcemanager/resources/armresources.

En este ejemplo, se muestra cómo encontrar el origen de las operaciones de grupo de recursos de Azure.

  1. Vaya al repositorio SDK de Azure para go en GitHub.
  2. Vaya a sdk/resourcemanager/resources/armresources/.
  3. Abra resource_groups_client.go para encontrar el tipo ResourceGroupsClient y su método CreateOrUpdate.
  4. Lea los comentarios y parámetros del método para comprender cómo realizar la llamada API.

Para obtener documentación de referencia generada, busque el paquete en pkg.go.dev.

Operaciones de larga duración

Algunas operaciones tardan mucho tiempo en finalizarse. Para controlar estas operaciones, las bibliotecas de administración proporcionan funciones que admiten operaciones de ejecución prolongada (LRO) a través de llamadas asincrónicas. Estos nombres de función comienzan por Begin, como BeginCreate y BeginDelete.

Dado que estas funciones son asincrónicas, el código no se bloquea mientras la función finaliza su tarea. En su lugar, la función devuelve inmediatamente un objeto poller. A continuación, el código llama a una función de sondeo sincrónica que se devuelve cuando se completa la función asincrónica original.

El siguiente fragmento de código muestra un ejemplo de este patrón.

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.

Puntos clave:

  • La PollUntilDone función requiere un intervalo de sondeo que especifica la frecuencia con la que debe intentar obtener el estado. El valor predeterminado interval es de 30 segundos si pasa nil para el parámetro options, pero puede ajustarlo en función de sus necesidades.
  • El intervalo suele ser corto. Consulte la documentación del recurso de Azure específico para conocer los intervalos recomendados.
  • La sección LRO de la página Directrices de diseño de Go SDK de Azure tiene un ejemplo más avanzado y directrices generales para LRO.

Para obtener más información sobre los patrones, consulte los patrones de uso de Common en SDK de Azure para Go.

Pasos siguientes

Para obtener más información sobre la autenticación, la construcción del cliente, las operaciones de larga duración y los patrones de recorrido de servicio, consulte los artículos específicos del plano.

Para obtener ejemplos, consulte SDK de Azure para ver ejemplos de Go en GitHub.

  • Last updated on