你当前正在访问 Microsoft Azure Global Edition 技术文档网站。如果需要访问由世纪互联运营的 Microsoft Azure 中国技术文档网站，请访问 https://docs.azure.cn。

HDInsight SDK for Python

项目
11/01/2024

概述

HDInsight SDK for Python 提供用于管理 HDInsight 群集的类和方法。该 SDK 包含用于创建、删除、更新、列出、调整大小、执行脚本操作，以及监视、获取 HDInsight 群集属性等操作。

先决条件

一个 Azure 帐户。如果没有帐户，可获取一个免费试用帐户。
Python
pip

SDK 安装

HDInsight SDK for Python 在 Python Package Index 中提供，可以通过运行以下命令来安装：

pip install azure-mgmt-hdinsight

身份验证

首先需要使用 Azure 订阅对该 SDK 进行身份验证。请遵循以下示例创建服务主体，然后使用该服务主体进行身份验证。完成此操作后，将会获得 HDInsightManagementClient 的实例，其中包含可用于执行管理操作的多个方法（以下部分将概述这些方法）。

注意

除了以下示例中所示的方法以外，还有其他一些身份验证方法可能更符合你的需要。使用用于 Python 的 Azure 管理库进行身份验证中概述了所有方法

使用服务主体的身份验证示例

首先登录到 Azure Cloud Shell。验证当前使用的是要在其中创建服务主体的订阅。

az account show

订阅信息将显示为 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"
  }
}

如果尚未登录到正确的订阅，请运行以下命令选择正确的订阅：

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

重要

如果尚未通过其他方法（例如，通过 Azure 门户创建 HDInsight 群集）注册 HDInsight 资源提供程序，则需要先执行此操作一次，然后才能进行身份验证。可以在 Azure Cloud Shell 中运行以下命令来完成此操作：

az provider register --namespace Microsoft.HDInsight

接下来，选择服务主体的名称，然后使用以下命令创建服务主体：

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

服务主体信息将以 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/"
}

复制以下 Python 代码片段，并在 TENANT_ID、CLIENT_ID、CLIENT_SECRET 和 SUBSCRIPTION_ID 中填写运行创建服务主体的命令后返回的 JSON 中的字符串。

from azure.mgmt.hdinsight import HDInsightManagementClient
from azure.common.credentials import ServicePrincipalCredentials
from azure.mgmt.hdinsight.models import *

# Tenant ID for your Azure Subscription
TENANT_ID = ''
# Your Service Principal App Client ID
CLIENT_ID = ''
# Your Service Principal Client Secret
CLIENT_SECRET = ''
# Your Azure Subscription ID
SUBSCRIPTION_ID = ''

credentials = ServicePrincipalCredentials(
    client_id = CLIENT_ID,
    secret = CLIENT_SECRET,
    tenant = TENANT_ID
)

client = HDInsightManagementClient(credentials, SUBSCRIPTION_ID)

群集管理

注意

本部分假设你已完成身份验证，已构造 HDInsightManagementClient 实例并已将其存储在名为 client 的变量中。在前面的“身份验证”部分可以找到有关身份验证和获取 HDInsightManagementClient 的说明。

创建群集

可以通过调用 client.clusters.create() 来创建新群集。

示例

提供了用于创建几种常见 HDInsight 群集的代码示例： HDInsight Python 示例。

示例

本示例演示如何创建包含 2 个头节点和 1 个工作节点的 Spark 群集。

备注

首先需要创建一个资源组和存储帐户，下面将予以介绍。如果已创建资源组和存储帐户，则可以跳过这些步骤。

创建资源组

可以在 Azure Cloud Shell 中运行以下命令来创建资源组

az group create -l <Region Name (i.e. eastus)> --n <Resource Group Name>

创建存储帐户

可以在 Azure Cloud Shell 中运行以下命令来创建存储帐户

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>

现在，运行以下命令获取存储帐户的密钥（创建群集时需要用到）：

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

以下 Python 代码片段创建包含 2 个头节点和 1 个工作节点的 Spark 群集。按照注释中所述填写空白变量，并根据具体的需要任意更改其他参数。

# The name for the cluster you are creating
cluster_name = ""
# The name of your existing Resource Group
resource_group_name = ""
# Choose a username
username = ""
# Choose a password
password = ""
# Replace <> with the name of your storage account
storage_account = "<>.blob.core.windows.net"
# Storage account key you obtained above
storage_account_key = ""
# Choose a region
location = ""
container = "default"

params = ClusterCreateProperties(
    cluster_version="3.6",
    os_type=OSType.linux,
    tier=Tier.standard,
    cluster_definition=ClusterDefinition(
        kind="spark",
        configurations={
            "gateway": {
                "restAuthCredential.enabled_credential": "True",
                "restAuthCredential.username": username,
                "restAuthCredential.password": password
            }
        }
    ),
    compute_profile=ComputeProfile(
        roles=[
            Role(
                name="headnode",
                target_instance_count=2,
                hardware_profile=HardwareProfile(vm_size="Large"),
                os_profile=OsProfile(
                    linux_operating_system_profile=LinuxOperatingSystemProfile(
                        username=username,
                        password=password
                    )
                )
            ),
            Role(
                name="workernode",
                target_instance_count=1,
                hardware_profile=HardwareProfile(vm_size="Large"),
                os_profile=OsProfile(
                    linux_operating_system_profile=LinuxOperatingSystemProfile(
                        username=username,
                        password=password
                    )
                )
            )
        ]
    ),
    storage_profile=StorageProfile(
        storageaccounts=[StorageAccount(
            name=storage_account,
            key=storage_account_key,
            container=container,
            is_default=True
        )]
    )
)

client.clusters.create(
    cluster_name=cluster_name,
    resource_group_name=resource_group_name,
    parameters=ClusterCreateParametersExtended(
        location=location,
        tags={},
        properties=params
    ))

获取群集详细信息

获取给定群集的属性：

client.clusters.get("<Resource Group Name>", "<Cluster Name>")

示例

可以使用 get 来确认已成功创建群集。

my_cluster = client.clusters.get("<Resource Group Name>", "<Cluster Name>")
print(my_cluster)

输出应如下所示：

{'additional_properties': {}, 'id': '/subscriptions/XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX/resourceGroups/<Resource Group Name>/providers/Microsoft.HDInsight/clusters/<Cluster Name>', 'name': '<Cluster Name>', 'type': 'Microsoft.HDInsight/clusters', 'location': '<Location>', 'tags': {}, 'etag': 'XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX', 'properties': <azure.mgmt.hdinsight.models.cluster_get_properties_py3.ClusterGetProperties object at 0x0000013766D68048>}

列出群集

列出订阅下的群集

client.clusters.list()

按资源组列出群集

client.clusters.list_by_resource_group("<Resource Group Name>")

注意

list() 和 list_by_resource_group() 都返回 ClusterPaged 对象。调用 advance_page() 会在该页上返回群集列表，并会将 ClusterPaged 对象推到下一页。此操作可以一直重复，直至引发 StopIteration 异常（表明没有其他页）。

示例

以下示例列显当前订阅的所有群集的属性：

clusters_paged = client.clusters.list()
while True:
  try:
    for cluster in clusters_paged.advance_page():
      print(cluster)
  except StopIteration: 
    break

删除群集

删除群集：

client.clusters.delete("<Resource Group Name>", "<Cluster Name>")

更新群集标记

可按如下所示更新给定群集的标记：

client.clusters.update("<Resource Group Name>", "<Cluster Name>", tags={<Dictionary of Tags>})

示例

client.clusters.update("<Resource Group Name>", "<Cluster Name>", tags={"tag1Name" : "tag1Value", "tag2Name" : "tag2Value"})

调整群集大小

可以通过指定新大小来调整给定群集的工作节点数，如下所示：

client.clusters.resize("<Resource Group Name>", "<Cluster Name>", target_instance_count=<Num of Worker Nodes>)

群集监视

使用 HDInsight 管理 SDK 还可以通过 Operations Management Suite (OMS) 来管理群集的监视。

启用 OMS 监视

注意

若要启用 OMS 监视，必须已有一个 Log Analytics 工作区。如果尚未创建工作区，可在此了解创建方法：在 Azure 门户中创建 Log Analytics 工作区。

在群集上启用 OMS 监视：

client.extension.enable_monitoring("<Resource Group Name>", "<Cluster Name>", workspace_id="<Workspace Id>")

查看 OMS 监视状态

获取群集上的 OMS 状态：

client.extension.get_monitoring_status("<Resource Group Name", "Cluster Name")

禁用 OMS 监视

在群集上禁用 OMS：

client.extension.disable_monitoring("<Resource Group Name>", "<Cluster Name>")

脚本操作

HDInsight 提供一个称为“脚本操作”的配置方法，该方法可调用用于自定义群集的自定义脚本。

备注

有关如何使用脚本操作的详细信息见此处：使用脚本操作自定义基于 Linux 的 HDInsight 群集

执行脚本操作

若要在给定群集上执行脚本操作，请使用以下命令：

script_action1 = RuntimeScriptAction(name="<Script Name>", uri="<URL To Script>", roles=[<List of Roles>]) #valid roles are "headnode", "workernode", "zookeepernode", and "edgenode"

client.clusters.execute_script_actions("<Resource Group Name>", "<Cluster Name>", <persist_on_success (bool)>, script_actions=[script_action1]) #add more RuntimeScriptActions to the list to execute multiple scripts

删除脚本操作

删除给定群集上指定的持久化脚本操作：

client.script_actions.delete("<Resource Group Name>", "<Cluster Name", "<Script Name>")

列出持久化脚本操作

注意

list() 和 list_persisted_scripts() 返回 RuntimeScriptActionDetailPaged 对象。调用 advance_page() 会在该页上返回 RuntimeScriptActionDetail 列表，并会将 RuntimeScriptActionDetailPaged 对象推到下一页。此操作可以一直重复，直至引发 StopIteration 异常（表明没有其他页）。请参阅以下示例。

列出指定群集的所有持久化脚本操作：

client.script_actions.list_persisted_scripts("<Resource Group Name>", "<Cluster Name>")

示例

scripts_paged = client.script_actions.list_persisted_scripts(resource_group_name, cluster_name)
while True:
  try:
    for script in scripts_paged.advance_page():
      print(script)
  except StopIteration:
    break

列出所有脚本的执行历史记录

列出指定群集的所有脚本的执行历史记录：

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

示例

此示例列显以往所有脚本执行活动的所有详细信息。

script_executions_paged = client.script_execution_history.list("<Resource Group Name>", "<Cluster Name>")
while True:
  try:
    for script in script_executions_paged.advance_page():            
      print(script)
    except StopIteration:       
      break

通过