Condividi tramite

HDInsight SDK per Go (anteprima)

Panoramica

HDInsight SDK per Go offre classi e funzioni che consentono di gestire i cluster HDInsight. Include operazioni per creare, eliminare, aggiornare, elencare, ridimensionare, eseguire azioni di script, monitorare, ottenere le proprietà dei cluster di HDInsight e altro ancora.

Nota

Il materiale di riferimenti GoDoc per questo SDK è disponibile anche qui.

Se non si ha una sottoscrizione di Azure, creare un account gratuito prima di iniziare.

Prerequisiti

Installazione dell'SDK

Dal percorso dell'ambiente GOPATH eseguire go get github.com/Azure/azure-sdk-for-go/tree/master/services/preview/hdinsight/mgmt/2018-06-01-preview/hdinsight

Autenticazione

L'SDK deve essere prima autenticato con la sottoscrizione di Azure. Seguire questo esempio per creare un'entità servizio e usarla per l'autenticazione. Al termine si avrà un'istanza di un ClustersClient che contiene molte funzioni, descritte nelle sezioni seguenti, che possono essere usate per operazioni di gestione.

Nota

Oltre all'esempio seguente esistono altre modalità di autenticazione che possono essere più adatte alle proprie esigenze. Tutte le funzioni sono descritte nell'articolo Funzioni di autenticazione in Azure SDK per Go

Esempio di autenticazione con un'entità servizio

Per prima cosa, accedere ad Azure Cloud Shell. Verificare che si stia attualmente usando la sottoscrizione in cui si vuole creare l'entità servizio.

az account show

Le informazioni sulla sottoscrizione vengono visualizzate in formato JSON.

{
  "environmentName": "AzureCloud",
  "id": "XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX",
  "isDefault": true,
  "name": "XXXXXXX",
  "state": "Enabled",
  "tenantId": "XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX",
  "user": {
    "cloudShellID": true,
    "name": "XXX@XXX.XXX",
    "type": "user"
  }
}

Se non si è eseguito l'accesso alla sottoscrizione corretta, selezionare quella corretta eseguendo:

az account set -s <name or ID of subscription>

Importante

Se il provider di risorse HDInsight non è già stato registrato con un'altra funzione, ad esempio creando un cluster HDInsight tramite il portale di Azure, è necessario eseguire questa operazione una volta prima di poter eseguire l'autenticazione. La registrazione può essere eseguita da Azure Cloud Shell eseguendo questo comando:

az provider register --namespace Microsoft.HDInsight

Scegliere quindi un nome per l'entità servizio e crearla con il comando seguente:

az ad sp create-for-rbac --name <Service Principal Name> --sdk-auth --role Contributor --scopes /subscriptions/<subscription id>

Verranno visualizzate le informazioni relative all'entità servizio in formato JSON.

{
  "clientId": "XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX",
  "clientSecret": "XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX",
  "subscriptionId": "XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX",
  "tenantId": "XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX",
  "activeDirectoryEndpointUrl": "https://login.microsoftonline.com",
  "resourceManagerEndpointUrl": "https://management.azure.com/",
  "sqlManagementEndpointUrl": "https://management.core.windows.net:8443/",
  "galleryEndpointUrl": "https://gallery.azure.com/",
  "managementEndpointUrl": "https://management.core.windows.net/"
}

Copiare il frammento di codice seguente e compilare TENANT_ID, CLIENT_ID, CLIENT_SECRET e SUBSCRIPTION_ID con le stringhe JSON restituite dopo aver eseguito il comando per creare l'entità servizio.

package main

import (
    "context"
    "github.com/Azure/go-autorest/autorest/azure/auth"
    hdi "github.com/Azure/azure-sdk-for-go/services/preview/hdinsight/mgmt/2018-06-01-preview/hdinsight"
    "github.com/Azure/go-autorest/autorest/to"
)

func main() {
    var err error

    // Tenant ID for your Azure Subscription
    var TENANT_ID = ""
    // Your Service Principal App Client ID
    var CLIENT_ID = ""
    // Your Service Principal Client Secret
    var CLIENT_SECRET = ""
    // Azure Subscription ID
    var SUBSCRIPTION_ID = ""

    var credentials = auth.NewClientCredentialsConfig(CLIENT_ID, CLIENT_SECRET, TENANT_ID)
    var client = hdi.NewClustersClient(SUBSCRIPTION_ID)

    client.Authorizer, err = credentials.Authorizer()
    if (err != nil) {
        fmt.Println("Error: ", err)
    }

Gestione dei cluster

Nota

Questa sezione presuppone che l'utente abbia già eseguito l'autenticazione e abbia creato un'istanza ClusterClient che ha poi archiviato in una variabile chiamata client. Le istruzioni per l'autenticazione e l'ottenimento di un ClusterClient sono disponibili nella sezione Autenticazione precedente.

Creare un cluster

Un nuovo cluster può essere creato chiamando client.Create().

Esempio

Questo esempio illustra come creare un cluster Apache Spark con due nodi head e un nodo di lavoro.

Nota

È prima necessario creare un gruppo di risorse e un account di archiviazione, come spiegato di seguito. Se sono già stati creati, è possibile ignorare questi passaggi.

Creazione di un gruppo di risorse

È possibile creare un gruppo di risorse con Azure Cloud Shell eseguendo

az group create -l <Region Name (i.e. eastus)> --n <Resource Group Name>
Creazione di un account di archiviazione

È possibile creare un account di archiviazione con Azure Cloud Shell eseguendo:

az storage account create -n <Storage Account Name> -g <Existing Resource Group Name> -l <Region Name (i.e. eastus)> --sku <SKU i.e. Standard_LRS>

Eseguire ora questo comando per ottenere la chiave per l'account di archiviazione. Questa chiave sarà necessaria per creare un cluster:

az storage account keys list -n <Storage Account Name>

Il frammento di codice Go seguente crea un cluster Spark con due nodi head e un nodo di lavoro. Inserire le variabili vuote come spiegato nei commenti. È possibile modificare altri parametri in base alle proprie esigenze.

// The name for the cluster you are creating
var clusterName = "";
// The name of your existing Resource Group
var resourceGroupName = "";
// Choose a username
var username = "";
// Choose a password
var password = "";
// Replace <> with the name of your storage account
var storageAccount = "<>.blob.core.windows.net";
// Storage account key you obtained above
var storageAccountKey = "";
// Choose a region
var location = "";
var container = "default";

var parameters = hdi.ClusterCreateParametersExtended {
    Location: to.StringPtr(location),
    Tags: make(map[string]*string),
    Properties: &hdi.ClusterCreateProperties {
        ClusterVersion: to.StringPtr("3.6"),
        OsType: hdi.Linux,
        ClusterDefinition: &hdi.ClusterDefinition {
            Kind: to.StringPtr("spark"),
            Configurations: map[string]map[string]interface{}{
                "gateway": {
                    "restAuthCredential.isEnabled": "True",
                    "restAuthCredential.username":  username,
                    "restAuthCredential.password":  password,
                },
            },
        },
        Tier: hdi.Standard,
        ComputeProfile: &hdi.ComputeProfile {
            Roles: &[]hdi.Role {
                hdi.Role {
                    Name: to.StringPtr("headnode"),
                    TargetInstanceCount: to.Int32Ptr(2),
                    HardwareProfile: &hdi.HardwareProfile {
                        VMSize: to.StringPtr("Large"),
                    },
                    OsProfile: &hdi.OsProfile {
                        LinuxOperatingSystemProfile: &hdi.LinuxOperatingSystemProfile {
                            Username: to.StringPtr(username),
                            Password: to.StringPtr(password),
                        },
                    },
                },
                hdi.Role {
                    Name: to.StringPtr("workernode"),
                    TargetInstanceCount: to.Int32Ptr(1),
                    HardwareProfile: &hdi.HardwareProfile {
                        VMSize: to.StringPtr("Large"),
                    },
                    OsProfile: &hdi.OsProfile {
                        LinuxOperatingSystemProfile: &hdi.LinuxOperatingSystemProfile {
                            Username: to.StringPtr(username),
                            Password: to.StringPtr(password),
                        },
                    },
                },
            },
        },
        StorageProfile: &hdi.StorageProfile {
            Storageaccounts: &[]hdi.StorageAccount {
                hdi.StorageAccount {
                    Name: to.StringPtr(storageAccount),
                    Key: to.StringPtr(storageAccountKey),
                    Container: to.StringPtr(container),
                    IsDefault: to.BoolPtr(true),
                },
            },
        },
    },
}
client.Create(context.Background(), resourceGroupName, clusterName, parameters)

Ottenere i dettagli del cluster

Per ottenere le proprietà di un dato cluster:

client.Get(context.Background(), "<Resource Group Name>", "<Cluster Name>")

Esempio

È possibile usare get per verificare che il cluster sia stato creato correttamente.

cluster, err := client.Get(context.Background(), resourceGroupName, clusterName)
if (err != nil) {
    fmt.Println("Error: ", err)
}
fmt.Println(*cluster.Name)
fmt.Println(*cluster.ID

L'output sarà simile al seguente:

<Cluster Name>
/subscriptions/XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX/resourceGroups/<Resource Group Name>/providers/Microsoft.HDInsight/clusters/<Cluster Name>

Elencare i cluster

Elencare i cluster nella sottoscrizione

client.List()

Elencare i cluster per gruppo di risorse

client.ListByResourceGroup("<Resource Group Name>")

Nota

Sia List() che ListByResourceGroup() restituiscono una struct ClusterListResultPage. Per ottenere la pagina successiva è possibile chiamare Next(). Questa operazione può essere ripetuta fino a quando ClusterListResultPage.NotDone() non restituisce false, come illustrato nell'esempio seguente.

Esempio

L'esempio seguente mostra le proprietà di tutti i cluster per la sottoscrizione corrente:

page, err := client.List(context.Background())
if (err != nil) {
    fmt.Println("Error: ", err)
}
for (page.NotDone()) {
    for _, cluster := range page.Values() {
        fmt.Println(*cluster.Name)
    }
    err = page.Next();
    if (err != nil) {
        fmt.Println("Error: ", err)
    }
}

Eliminare un cluster

Per eliminare un cluster:

client.Delete(context.Background(), "<Resource Group Name>", "<Cluster Name>")

Aggiornare i tag del cluster

È possibile aggiornare i tag di un dato cluster nel modo seguente:

client.Update(context.Background(), "<Resource Group Name>", "<Cluster Name>", hdi.ClusterPatchParameters{<map[string]*string} of Tags>)

Esempio

client.Update(context.Background(), "SDKTestRG", "SDKTest", hdi.ClusterPatchParameters{map[string]*string{"tag1Name" : to.StringPtr("tag1Value"), "tag2Name" : to.StringPtr("tag2Value")}})

Ridimensionare un cluster

È possibile ridimensionare il numero di nodi di ruolo di lavoro di un dato cluster specificando una nuova dimensione nel modo seguente:

client.Resize(context.Background(), "<Resource Group Name>", "<Cluster Name>", hdi.ClusterResizeParameters{<Num of Worker Nodes (int)>})

Monitoraggio del cluster

HDInsight Management SDK può essere usato anche per gestire il monitoraggio dei cluster tramite Operations Management Suite (OMS).

Così come è stato creato un ClusterClient per le operazioni di gestione, è necessario ora creare un ExtensionClient da usare per le operazioni di monitoraggio. Dopo aver completato la sezione Autenticazione precedente, è possibile creare un oggetto ExtensionClient come descritto di seguito:

extClient := hdi.NewExtensionsClient(SUBSCRIPTION_ID)
extClient.Authorizer, _ = credentials.Authorizer()

Nota

Gli esempi di monitoraggio seguenti presuppongono che sia già stato inizializzato un ExtensionClient denominato extClient e impostato il relativo Authorizer, come illustrato in precedenza.

Abilitare il monitoraggio di OMS

Nota

Per abilitare il monitoraggio di OMS è necessaria un'area di lavoro Log Analytics esistente. Se l'area non è stata ancora creata, vedere Creare un'area di lavoro Log Analytics nel portale di Azure per informazioni su come crearla.

Per abilitare il monitoraggio di OMS nel cluster:

extClient.EnableMonitoring(context.Background(), "<Resource Group Name", "Cluster Name", hdi.ClusterMonitoringRequest {WorkspaceID: to.StringPtr("<Workspace Id>")})

Visualizzare lo stato del monitoraggio di OMS

Per ottenere lo stato di OMS nel cluster:

extClient.GetMonitoringStatus(context.Background(), "<Resource Group Name", "Cluster Name")

Disabilitare il monitoraggio di OMS

Per disabilitare OMS nel cluster:

extClient.DisableMonitoring(context.Background(), "<Resource Group Name", "Cluster Name")

Azioni script

HDInsight offre una funzione di configurazione denominata "azioni script" che richiama script personalizzati per il cluster.

Nota

Per altre informazioni sulle azioni script, vedere Personalizzare i cluster HDInsight basati su Linux tramite azioni script

Eseguire azioni script

È possibile eseguire azioni script in un dato cluster nel modo seguente:

var scriptAction1 = hdi.RuntimeScriptAction{Name: to.StringPtr("<Script Name>"), URI: to.StringPtr("<URL To Script>"), Roles: <&[]string of roles>} //valid roles are "headnode", "workernode", "zookeepernode", and "edgenode"
client.ExecuteScriptActions(context.Background(), "<Resource Group Name>", "<Cluster Name>", hdi.ExecuteScriptActionParameters{PersistOnSuccess: to.BoolPtr(true), ScriptActions: &[]hdi.RuntimeScriptAction{scriptAction1}}) //add more RuntimeScriptActions to the list to execute multiple scripts

Per le operazioni "Eliminare un'azione script" ed "Elencare le azioni script persistenti" è necessario creare un ScriptActionsClient, analogamente al modo in cui è stato creato un ClusterClient per le operazioni di gestione. Dopo aver completato la sezione Autenticazione precedente, è possibile creare un oggetto ScriptActionsClient come descritto di seguito:

scriptActionsClient := hdi.NewScriptActionsClient(SUBSCRIPTION_ID)
scriptActionsClient.Authorizer, _ = credentials.Authorizer()

Nota

Gli esempi di azioni script seguenti presuppongono che sia già stato inizializzato un ScriptActionsClient denominato scriptActionsClient e impostato il relativo Authorizer, come illustrato in precedenza.

Eliminare un'azione script

Per eliminare una determinata azione script persistente in un dato cluster:

scriptActionsClient.Delete(context.Background(), "<Resource Group Name>", "<Cluster Name>", "<Script Name>")

Elencare le azioni script persistenti

Nota

ListByCluster() restituisce una struct ScriptActionsListPage. Per ottenere la pagina successiva è possibile chiamare Next(). Questa operazione può essere ripetuta fino a quando ClusterListResultPage.NotDone() non restituisce false, come illustrato nell'esempio seguente.

Per elencare tutte le azioni script persistenti per il cluster specificato:

scriptActionsClient.ListByCluster(context.Background(), "<Resource Group Name>", "<Cluster Name>")

Esempio

page, err := scriptActionsClient.ListByCluster(context.Background(), resourceGroupName, clusterName)
if (err != nil) {
    fmt.Println("Error: ", err)
}
for (page.NotDone()) {
    for _, script := range page.Values() {
        fmt.Println(*script.Name) //There are functions to get other properties of RuntimeScriptActionDetail besides Name, such as Status, Operation, StartTime, EndTime, etc. See reference documentation.
    }
    err = page.Next();
    if (err != nil) {
        fmt.Println("Error: ", err)
    }
}

Elencare la cronologia di esecuzione di tutti gli script

Per eseguire questa operazione è necessario creare un ScriptExecutionHistoryClient, analogamente al modo in cui è stato creato un ClusterClient per le operazioni di monitoraggio. Dopo aver completato la sezione Autenticazione precedente, è possibile creare un oggetto ScriptActionsClient come descritto di seguito:

scriptExecutionHistoryClient := hdi.NewScriptExecutionHistoryClient(SUBSCRIPTION_ID)
scriptExecutionHistoryClient.Authorizer, _ = credentials.Authorizer()

Nota

Gli esempi seguenti presuppongono che sia già stato inizializzato un ScriptExecutionHistoryClient denominato scriptExecutionHistoryClient e impostato il relativo Authorizer, come illustrato in precedenza.

Per elencare la cronologia di esecuzione di tutti gli script per il cluster specificato:

scriptExecutionHistoryClient.ListByCluster(context.Background(), "<Resource Group Name>", "<Cluster Name>")

Esempio

Questo esempio visualizza tutti i dettagli di tutte le precedenti esecuzioni di script.

page, err := scriptExecutionHistoryClient.ListByCluster(context.Background(), resourceGroupName, clusterName)
if (err != nil) {
    fmt.Println("Error: ", err)
}
for (page.NotDone()) {
    for _, script := range page.Values() {
        fmt.Println(*script.Name) //There are functions to get other properties of RuntimeScriptActionDetail besides Name, such as Status, Operation, StartTime, EndTime, etc. See reference documentation.
    }
    err = page.Next();
    if (err != nil) {
        fmt.Println("Error: ", err)
    }
}

Passaggi successivi

Esplorare il materiale di riferimento GoDoc. I GoDoc forniscono documentazione di riferimento per tutte le funzioni dell'SDK.