Azure HDInsight SDK für .NETAzure HDInsight SDK for .NET

Azure HDInsight bietet Verwaltungs- und Auftrags-SDKs für .NET mit Klassen zum Verwalten Ihres HDInsight-Clusters sowie zum Übermitteln und Überwachen von Hadoop-Aufträgen.Azure HDInsight offers management and job SDKs for .NET that provide classes for managing your HDInsight cluster and submitting and monitoring Hadoop jobs.

VerwaltungManagement

Das HDInsight-Verwaltungs-SDK für .NET bietet Klassen und Methoden, mit denen Sie Ihre HDInsight-Cluster verwalten können.The HDInsight management SDK for .NET provides classes and methods that allow you to manage your HDInsight clusters. Es enthält Vorgänge zum Erstellen, Löschen, Aktualisieren, Auflisten, Ändern der Größe, Ausführen von Skriptaktionen, Überwachen, Abrufen der Eigenschaften von HDInsight-Clustern und mehr.It includes operations to create, delete, update, list, resize, execute script actions, monitor, get properties of HDInsight clusters, and more.

VoraussetzungenPrerequisites

SDK-InstallationSDK Installation

Öffnen Sie über Ihr Visual Studio-Projekt die Paket-Manager-Konsole, indem Sie auf Extras > NuGet-Paket-Manager und dann auf Paket-Manager-Konsole klicken.From your Visual Studio project, open the Package Manager Console by clicking Tools, NuGet Package Manager, and then click Package Manager Console.

Führen Sie in der Paket-Manager-Konsole die folgenden Befehle aus:In the Package Manager Console, execute the following commands:

  Install-Package Microsoft.Azure.Management.HDInsight
  Install-Package Microsoft.Azure.Management.Fluent
  Install-Package Microsoft.Azure.Management.ResourceManager.Fluent

AuthenticationAuthentication

Das SDK muss zunächst für Ihr Azure-Abonnement authentifiziert werden.The SDK first needs to be authenticated with your Azure subscription. Erstellen Sie anhand des Beispiels unten einen Dienstprinzipal, und verwenden Sie ihn für die Authentifizierung.Follow the example below to create a service principal and use it to authenticate. Nachdem dies erfolgt ist, verfügen Sie über eine Instanz von HDInsightManagementClient mit vielen Methoden (in den Abschnitten unten beschrieben), die zum Durchführen von Verwaltungsvorgängen verwendet werden können.After this is done, you will have an instance of an HDInsightManagementClient, which contains many methods (outlined in below sections) that can be used to perform management operations.

Hinweis

Neben dem Beispiel unten gibt es noch andere Möglichkeiten der Authentifizierung, die für Ihre Anforderungen unter Umständen besser geeignet sind.There are other ways to authenticate besides the below example that could potentially be better suited for your needs. Hier werden alle Methoden beschrieben: Authentifizieren bei den Azure-Bibliotheken für .NETAll methods are outlined here: Authenticate with the Azure Libraries for .NET

Beispiel für die Authentifizierung mit einem DienstprinzipalAuthentication Example Using a Service Principal

Melden Sie sich zuerst bei Azure Cloud Shell an.First, login to Azure Cloud Shell. Vergewissern Sie sich, dass Sie derzeit das Abonnement verwenden, in dem der Dienstprinzipal erstellt werden soll.Verify you are currently using the subscription in which you want the service principal created.

az account show

Die Informationen zu Ihrem Abonnement werden im JSON-Format angezeigt.Your subscription information is displayed as 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"
  }
}

Wenn Sie nicht am richtigen Abonnement angemeldet sind, können Sie das richtige auswählen, indem Sie Folgendes ausführen:If you're not logged into the correct subscription, select the correct one by running:

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

Wichtig

Falls Sie den HDInsight-Ressourcenanbieter nicht bereits mit einer anderen Methode registriert haben (z.B. durch das Erstellen eines HDInsight-Clusters über das Azure-Portal), müssen Sie dies vor dem Authentifizieren durchführen.If you have not already registered the HDInsight Resource Provider by another method (such as by creating an HDInsight Cluster through the Azure Portal), you need to do this once before you can authenticate. Dies ist über Azure Cloud Shell möglich, indem Sie den folgenden Befehl ausführen:This can be done from the Azure Cloud Shell by running the following command:

az provider register --namespace Microsoft.HDInsight

Wählen Sie als Nächstes einen Namen für Ihren Dienstprinzipal aus, und erstellen Sie ihn mit dem folgenden Befehl:Next, choose a name for your service principal and create it with the following command:

az ad sp create-for-rbac --name <Service Principal Name> --sdk-auth

Die Dienstprinzipalinformationen werden im JSON-Format angezeigt.The service principal information is displayed as 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/",
  "activeDirectoryGraphResourceId": "https://graph.windows.net/",
  "sqlManagementEndpointUrl": "https://management.core.windows.net:8443/",
  "galleryEndpointUrl": "https://gallery.azure.com/",
  "managementEndpointUrl": "https://management.core.windows.net/"
}

Kopieren Sie den unten angegebenen Codeausschnitt, und geben Sie für TENANT_ID, CLIENT_ID, CLIENT_SECRET und SUBSCRIPTION_ID die Zeichenfolgen aus dem JSON-Code ein, der nach dem Ausführen des Befehls zurückgegeben wurde, um den Dienstprinzipal zu erstellen.Copy the below snippet and fill in TENANT_ID, CLIENT_ID, CLIENT_SECRET, and SUBSCRIPTION_ID with the strings from the JSON that was returned after running the command to create the service principal.

using Microsoft.Azure.Management.HDInsight;
using Microsoft.Azure.Management.HDInsight.Models;
using Microsoft.Azure.Management.ResourceManager.Fluent;

namespace HDI_SDK_Test
{
    class Program
    {
        static void Main(string[] args)
        {
            // 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 = SdkContext.AzureCredentialsFactory
                .FromServicePrincipal(
                CLIENT_ID,
                CLIENT_SECRET,
                TENANT_ID,
                AzureEnvironment.AzureGlobalCloud);

            var client = new HDInsightManagementClient(credentials);
            client.SubscriptionId = SUBSCRIPTION_ID;
        }
    }
}

ClusterverwaltungCluster Management

Hinweis

In diesem Abschnitt wird davon ausgegangen, dass Sie bereits eine HDInsightManagementClient-Instanz authentifiziert und in einer Variablen mit dem Namen client gespeichert haben.This section assumes you have already authenticated and constructed an HDInsightManagementClient instance and store it in a variable called client. Eine Anleitung zum Authentifizieren und Abrufen eines HDInsightManagementClient-Elements finden Sie oben im Abschnitt „Authentifizierung“.Instructions for authenticating and obtaining an HDInsightManagementClient can be found in the Authentication section above.

Erstellen eines ClustersCreate a Cluster

Sie können einen neuen Cluster erstellen, indem Sie client.Clusters.Create() aufrufen.A new cluster can be created by calling client.Clusters.Create().

BeispieleSamples

Codebeispiele zum Erstellen verschiedener allgemeiner HDInsight-Clustertypen stehen zur Verfügung: HDInsight-.NET-Beispiele.Code samples for creating several common types of HDInsight clusters are available: HDInsight .NET Samples.

BeispielExample

In diesem Beispiel wird gezeigt, wie Sie einen Spark-Cluster mit zwei Hauptknoten und einem Workerknoten erstellen.This example demonstrates how to create a Spark cluster with 2 head nodes and 1 worker node.

Hinweis

Sie müssen zuerst wie unten beschrieben eine Ressourcengruppe und ein Speicherkonto erstellen.You first need to create a Resource Group and Storage Account, as explained below. Wenn Sie diese Komponenten bereits erstellt haben, können Sie diese Schritte überspringen.If you have already created these, you can skip these steps.

Erstellen einer RessourcengruppeCreating a Resource Group

Sie können eine Ressourcengruppe erstellen, indem Sie mit Azure Cloud Shell Folgendes ausführen:You can create a resource group using the Azure Cloud Shell by running

az group create -l <Region Name (i.e. eastus)> --n <Resource Group Name>
Erstellen eines SpeicherkontosCreating a Storage Account

Sie können ein Speicherkonto erstellen, indem Sie mit Azure Cloud Shell Folgendes ausführen:You can create a storage account using the Azure Cloud Shell by running:

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>

Führen Sie jetzt den folgenden Befehl aus, um den Schlüssel für Ihr Speicherkonto abzurufen (Sie benötigen ihn, um einen Cluster zu erstellen):Now run the following command to get the key for your storage account (you will need this to create a cluster):

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

Mit dem unten angegebenen .NET-Codeausschnitt wird ein Spark-Cluster mit zwei Hauptknoten und einem Workerknoten erstellt.The below .NET snippet creates a Spark cluster with 2 head nodes and 1 worker node. Geben Sie gemäß den Anweisungen in den Kommentaren Werte in die leeren Variablen ein, und ändern Sie ggf. auch andere Parameter, um diese an Ihre Anforderungen anzupassen.Fill in the blank variables as explained in the comments and feel free to change other parameters to suit your specific needs.

// 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 = new ClusterCreateParametersExtended
{
    Location = location,
    Tags = new Dictionary<string, string>(),
    Properties = new ClusterCreateProperties
    {
        ClusterVersion = "3.6",
        OsType = OSType.Linux,
        ClusterDefinition = new ClusterDefinition
        {
            Kind = "Hadoop",            
            Configurations = new Dictionary<string, Dictionary<string, string>>()
            {                
                { "gateway", new Dictionary<string, string>
                    {
                        { "restAuthCredential.isEnabled", "true" },
                        { "restAuthCredential.username", username},
                        { "restAuthCredential.password", password}
                    }
                }
            }
        },
        Tier = Tier.Standard,
        ComputeProfile = new ComputeProfile
        {
            Roles = new List<Role>{
                new Role
                {
                    Name = "headnode",
                    TargetInstanceCount = 2,
                    HardwareProfile = new HardwareProfile
                    {
                        VmSize = "Large"
                    },
                    OsProfile = new OsProfile
                    {
                        LinuxOperatingSystemProfile = new LinuxOperatingSystemProfile
                        {
                            Username = username,
                            Password = password
                        }
                    }
                },
                new Role
                {
                    Name = "workernode",
                    TargetInstanceCount = 1,
                    HardwareProfile = new HardwareProfile
                    {
                        VmSize = "Large"
                    },
                    OsProfile = new OsProfile
                    {
                        LinuxOperatingSystemProfile = new LinuxOperatingSystemProfile
                        {
                            Username = username,
                            Password = password
                        }
                    }
                },
            }
        },
        StorageProfile = new StorageProfile
        {
            Storageaccounts = new[]
            {
                new StorageAccount
                {
                    Name = storageAccount,
                    Key = storageAccountKey,
                    Container = container,
                    IsDefault = true
                }
            }
        }
    }
};
client.Clusters.Create(
    resourceGroupName,
    clusterName,
    parameters
);

Abrufen von ClusterdetailsGet Cluster Details

Rufen Sie die Eigenschaften für einen Cluster wie folgt ab:To get properties for a given cluster:

client.Clusters.Get("<Resource Group Name>", "<Cluster Name>");

BeispielExample

Sie können get verwenden, um zu bestätigen, dass die Erstellung des Clusters erfolgreich war.You can use get to confirm that you have successfully created your cluster.

var myCluster = client.Clusters.Get("<Resource Group Name>", "<Cluster Name>");
Debug.WriteLine(myCluster.Name); //Prints the name of the cluster
Debug.WriteLine(myCluster.Id) //Prints the resource Id of the cluster

Die Ausgabe sollte wie folgt aussehen:The output should look like:

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

Hinweis

Der Rückgabewert von get, der in der Variablen myCluster gespeichert ist, hat den Typ Microsoft.Azure.Management.HDInsight.ModelsCluster.The return value of get, stored in variable myCluster, is of type Microsoft.Azure.Management.HDInsight.ModelsCluster. Eine vollständige Liste mit den Eigenschaften dieses Objekts finden Sie hier.A full list of this object's properties can be found here.

Auflisten von ClusternList Clusters

Auflisten von Clustern unter dem AbonnementList Clusters Under The Subscription

client.Clusters.List();

Auflisten von Clustern nach RessourcengruppeList Clusters By Resource Group

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

Hinweis

Sowohl für List() als auch für ListByResourceGroup() wird ein IPage<Cluster>-Objekt zurückgegeben.Both List() and ListByResourceGroup() return an IPage<Cluster> object. Sie können client.Clusters.ListNext("Next Page Link") aufrufen, um die nächste Seite zu erhalten.To get the next page, you can call client.Clusters.ListNext("Next Page Link"). Dies kann wiederholt werden, bis NextPageLink den Wert null hat (wie im Beispiel unten zu sehen).This can be repeated until NextPageLink is null, as shown in the example below.

BeispielExample

Im folgenden Beispiel werden die Eigenschaften aller Cluster für das aktuelle Abonnement ausgegeben:The following example prints the properties of all clusters for the current subscription:

var clustersPaged = client.Clusters.List();
while (true)
{
  foreach (var cluster in clustersPaged)
  {
    Debug.WriteLine(cluster.Name);
  
}  if (clustersPaged.NextPageLink == null)
  {
    break;
  }
  clustersPaged = client.Clusters.ListNext(clustersPaged.NextPageLink);
}

Löschen eines ClustersDelete a Cluster

Löschen Sie einen Cluster wie folgt:To delete a cluster:

client.Clusters.Delete("<Resource Group Name>", "<Cluster Name>");

Aktualisieren von ClustermarkierungenUpdate Cluster Tags

Sie können die Markierungen eines Clusters wie folgt aktualisieren:You can update the tags of a given cluster like so:

client.Clusters.Update("<Resource Group Name>", "<Cluster Name>", new ClusterPatchParameters(<Dictionary of Tags>));

BeispielExample

client.Clusters.Update("<Resource Group Name>", "<Cluster Name>", new ClusterPatchParameters(new Dictionary<string, string> { { "tag1Name", "tag1Value" }, { "tag2Name", "tag2Value" } }));

Ändern der ClustergrößeResize Cluster

Sie können die Anzahl von Workerknoten für einen Cluster ändern, indem Sie wie folgt eine neue Größe angeben:You can resize a given cluster's number of worker nodes by specifying a new size like so:

client.Clusters.Resize("<Resource Group Name>", "<Cluster Name>", <Num of Worker Nodes (int)>)

ClusterüberwachungCluster Monitoring

Das HDInsight Management SDK kann auch verwendet werden, um die Überwachung Ihrer Cluster per Operations Management Suite (OMS) zu verwalten.The HDInsight Management SDK can also be used to manage monitoring on your clusters via the Operations Management Suite (OMS).

Aktivieren der OMS-ÜberwachungEnable OMS Monitoring

Hinweis

Sie müssen über einen vorhandenen Log Analytics-Arbeitsbereich verfügen, um die OMS-Überwachung zu ermöglichen.To enable OMS Monitoring, you must have an existing Log Analytics workspace. Wenn Sie noch keinen erstellt haben, erfahren Sie an dieser Stelle, wie Sie dazu vorgehen: Erstellen eines Log Analytics-Arbeitsbereichs im Azure-PortalIf you have not already created one, you can learn how to do that here: Create a Log Analytics workspace in the Azure portal.

Aktivieren Sie die OMS-Überwachung in Ihrem Cluster wie folgt:To enable OMS Monitoring on your cluster:

client.Extension.EnableMonitoring("<Resource Group Name", "Cluster Name", new ClusterMonitoringRequest(workspaceId: "<Workspace Id>"));

Anzeigen des Status der OMS-ÜberwachungView Status Of OMS Monitoring

Rufen Sie den Status von OMS in Ihrem Cluster wie folgt ab:To get the status of OMS on your cluster:

client.Extension.GetMonitoringStatus("<Resource Group Name", "Cluster Name");

Deaktivieren der OMS-ÜberwachungDisable OMS Monitoring

Deaktivieren Sie OMS in Ihrem Cluster wie folgt:To disable OMS on your cluster:

client.Extension.DisableMonitoring("<Resource Group Name>", "<Cluster Name>");

SkriptaktionenScript Actions

HDInsight verfügt über eine Konfigurationsmethode mit der Bezeichnung „Skriptaktionen“, mit der benutzerdefinierte Skripts zum Anpassen des Clusters aufgerufen werden.HDInsight provides a configuration method called script actions that invokes custom scripts to customize the cluster.

Hinweis

Weitere Informationen zum Verwenden von Skriptaktionen finden Sie hier: Anpassen Linux-basierter HDInsight-Cluster mithilfe von SkriptaktionenMore information on how to use script actions can be found here: Customize Linux-based HDInsight clusters using script actions

Ausführen von SkriptaktionenExecute Script Actions

Sie können Skriptaktionen für einen Cluster wie folgt ausführen:You can execute script actions on a given cluster like so:

var scriptAction1 = new RuntimeScriptAction("<Script Name>", "<URL To Script>", <List<string> of roles>); //valid roles are "headnode", "workernode", "zookeepernode", and "edgenode"

client.Clusters.ExecuteScriptActions("<Resource Group Name>", "<Cluster Name>", new List<RuntimeScriptAction> { scriptAction1 }, <persistOnSuccess (bool)>); //add more RuntimeScriptActions to the list to execute multiple scripts

Löschen der SkriptaktionDelete Script Action

Löschen Sie eine angegebene permanente Skriptaktion für einen Cluster wie folgt:To delete a specified persisted script action on a given cluster:

client.ScriptActions.Delete("<Resource Group Name>", "<Cluster Name>", "<Script Name>");

Auflisten von permanenten SkriptaktionenList Persisted Script Actions

Hinweis

Für ListPersistedScripts() und List() wird ein IPage<RuntimeScriptActionDetail>-Objekt zurückgegeben.ListPersistedScripts() and List() return an IPage<RuntimeScriptActionDetail> object. Sie können client.ScriptActions.ListPersistedScriptsNext("Next Page Link") oder client.ScriptExecutionHistory.ListNext("Next Page Link") aufrufen, um die nächste Seite zu erhalten.To get the next page, you can call client.ScriptActions.ListPersistedScriptsNext("Next Page Link") or client.ScriptExecutionHistory.ListNext("Next Page Link"). Dies kann wiederholt werden, bis NextPageLink den Wert null hat (wie in den Beispielen unten zu sehen).This can be repeated until NextPageLink is null, as shown in the examples below.

Listen Sie alle permanenten Skriptaktionen für den angegebenen Cluster wie folgt auf:To list all persisted script actions for the specified cluster:

client.ScriptActions.ListPersistedScripts("<Resource Group Name>", "<Cluster Name>");

BeispielExample

var scriptsPaged = client.ScriptActions.ListPersistedScripts("<Resource Group Name>", "<Cluster Name>");
while (true)
{
    foreach (var script in scriptsPaged)
    {
        Debug.WriteLine(script.Name); //There are other properties of RuntimeScriptActionDetail besides Name, such as Status, Operation, StartTime, EndTime, etc. See reference documentation.
    }
    if (scriptsPaged.NextPageLink == null)
    {
        break;
    }
    scriptsPaged = client.ScriptActions.ListPersistedScriptsNext(scriptsPaged.NextPageLink);
}

Auflisten des Ausführungsverlaufs aller SkriptsList All Scripts' Execution History

Listen Sie den Ausführungsverlauf aller Skripts für den angegebenen Cluster wie folgt auf:To list all scripts' execution history for the specified cluster:

client.script_execution_history.list("<Resource Group Name>", "<Cluster Name>");

BeispielExample

In diesem Beispiel werden alle Details zu allen erfolgten Skriptausführungen ausgegeben.This example prints all the details for all past script executions.

var scriptExecutionsPaged = client.ScriptExecutionHistory.List("<Resource Group Name>", "<Cluster Name>");
while (true)
{
    foreach (var script in scriptExecutionsPaged)
    {
        Debug.WriteLine(script.Name); //There are other properties of RuntimeScriptActionDetail besides Name, such as Status, Operation, StartTime, EndTime, etc. See reference documentation.

    }
    if (scriptExecutionsPaged.NextPageLink == null)
    {
        break;
    }
    scriptExecutionsPaged = client.ScriptExecutionHistory.ListNext(scriptExecutionsPaged.NextPageLink);
}

AufträgeJobs

Verwenden Sie das Azure HDInsight-Auftrags-SDK zum Erstellen, Verwalten und Überwachen von Aufträgen in einem Hadoop-Cluster.Use the Azure HDInsight job SDK for .NET to create, manage, and monitor jobs on a Hadoop cluster.

SDK-InstallationSDK Installation

Installieren Sie das NuGet-Paket direkt über die [Paket-Manager-Konsole][PackageManager] in Visual Studio oder mit der [.NET Core CLI][DotNetCLI].Install the NuGet package directly from the Visual Studio [Package Manager console][PackageManager] or with the [.NET Core CLI][DotNetCLI].

Visual Studio-Paket-ManagerVisual Studio Package Manager

Install-Package Microsoft.Azure.Management.HDInsight.Job
dotnet add package Microsoft.Azure.Management.HDInsight.Job

CodebeispielCode Example

In diesem Beispiel wird ein Hive-Auftrag in einem Hadoop-Cluster ausgeführt.This example runs a Hive job in a Hadoop cluster.

HDInsightJobManagementClient managementClient = new HDInsightJobManagementClient(clusterUri, credentials);

Dictionary<string, string> defines = new Dictionary<string, string> {
    { "hive.execution.engine", "tez" },
    { "hive.exec.reducers.max", "1" }
};
List<string> arguments = new List<string> { { "argA" }, { "argB" } };
HiveJobSubmissionParameters parameters = new HiveJobSubmissionParameters
{
    Query = "SHOW TABLES",
    Defines = defines,
    Arguments = arguments
};

JobSubmissionResponse jobResponse = managementClient.JobManagement.SubmitHiveJob(parameters);

BeispieleSamples