SDK de HDInsight para PythonHDInsight SDK for Python

Información generalOverview

El SDK de HDInsight para Python proporciona clases y métodos que permiten administrar los clústeres de HDInsight.The HDInsight SDK for Python provides classes and methods that allow you to manage your HDInsight clusters. Incluye operaciones para crear, eliminar, actualizar, enumerar, cambiar tamaño, ejecutar acciones de script, supervisar y obtener propiedades de clústeres de HDInsight, entre otras.It includes operations to create, delete, update, list, resize, execute script actions, monitor, get properties of HDInsight clusters, and more.

Requisitos previosPrerequisites

• Una cuenta de Azure.An Azure account. Si no tiene una, obtenga la versión de evaluación gratuita.If you don't have one, get a free trial.
• PythonPython
• pippip

Instalación del SDKSDK Installation

El SDK de HDInsight para Python se puede encontrar en el Índice de paquetes de Python y se puede instalar mediante la ejecución de:The HDInsight SDK for Python can be found in the Python Package Index and can be installed by running:

pip install azure-mgmt-hdinsight

AuthenticationAuthentication

En primer lugar, el SDK necesita autenticarse en su suscripción de Azure.The SDK first needs to be authenticated with your Azure subscription. Siga el ejemplo siguiente para crear una entidad de servicio y usarla para la autenticación.Follow the example below to create a service principal and use it to authenticate. Una vez hecho esto, tendrá una instancia de HDInsightManagementClient, que contiene muchos métodos que pueden usarse para realizar operaciones de administración (se describen en las secciones siguientes).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.

Nota

Además del siguiente ejemplo, hay otras maneras de autenticar que podrían ser más adecuadas para sus necesidades.There are other ways to authenticate besides the below example that could potentially be better suited for your needs. Todos los métdosos se describen aquí: Autenticación con las bibliotecas de administración de Azure para PythonAll methods are outlined here: Authenticate with the Azure Management Libraries for Python

Ejemplo de autenticación con una entidad de servicioAuthentication Example Using a Service Principal

En primer lugar, inicie sesión en Azure Cloud Shell.First, login to Azure Cloud Shell. Compruebe que está usando la suscripción en la que desea crear la entidad de servicio.Verify you are currently using the subscription in which you want the service principal created.

az account show

La información de la suscripción se muestra en formato JSON.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"
  }
}

Si no ha iniciado sesión en la suscripción correcta, ejecute lo siguiente para seleccionar la correcta:If you're not logged into the correct subscription, select the correct one by running:

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

Importante

Si aún no ha registrado el proveedor de recursos de HDInsight con otro método (por ejemplo, creando un clúster de HDInsight mediante Azure Portal), deberá hacerlo una vez antes de poder realizar la autenticación.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. Se puede hacer desde Azure Cloud Shell, con el siguiente comando:This can be done from the Azure Cloud Shell by running the following command:

az provider register --namespace Microsoft.HDInsight

A continuación, elija un nombre para la entidad de servicio y créela con el siguiente comando: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

La información de la entidad de servicio se muestra con formato JSON.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/"
}

Copie el siguiente fragmento de código de Python y rellene TENANT_ID, CLIENT_ID, CLIENT_SECRET y SUBSCRIPTION_ID con las cadenas del código JSON que se devolvió después de ejecutar el comando para crear la entidad de servicio.Copy the below Python 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.

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)

Administración de clústeresCluster Management

Nota

En esta sección se da por supuesto que ya ha autenticado y construido una instancia de HDInsightManagementClient, y que la ha almacenado en una variable llamada client.This section assumes you have already authenticated and constructed an HDInsightManagementClient instance and store it in a variable called client. En la sección Autenticación anterior encontrará las instrucciones para autenticarse y obtener un HDInsightManagementClient.Instructions for authenticating and obtaining an HDInsightManagementClient can be found in the Authentication section above.

Creación de un clústerCreate a Cluster

Para crear un nuevo clúster, se puede llamar a client.clusters.create().A new cluster can be created by calling client.clusters.create().

EjemplosSamples

Hay disponibles ejemplos de código para crear varios tipos comunes de clústeres de HDInsight: Ejemplos de HDInsight para PythonCode samples for creating several common types of HDInsight clusters are available: HDInsight Python Samples.

EjemploExample

En este ejemplo se muestra cómo crear un clúster de Spark con dos nodos principales y un nodo de trabajo.This example demonstrates how to create a Spark cluster with 2 head nodes and 1 worker node.

Nota

En primer lugar debe crear un grupo de recursos y la cuenta de almacenamiento, tal y como se explica más adelante.You first need to create a Resource Group and Storage Account, as explained below. Si ya los ha creado, puede omitir estos pasos.If you have already created these, you can skip these steps.

Creación de un grupo de recursosCreating a Resource Group

Puede crear un grupo de recursos con Azure Cloud Shell, con el siguiente comando: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>

Creación de una cuenta de almacenamientoCreating a Storage Account

Puede crear una cuenta de almacenamiento con Azure Cloud Shell, con el siguiente comando: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>

Ahora, ejecute el siguiente comando para obtener la clave de la cuenta de almacenamiento (que necesitará para crear un clúster):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>

---

El siguiente fragmento de código de Python crea un clúster de Spark con dos nodos principales y un nodo de trabajo.The below Python snippet creates a Spark cluster with 2 head nodes and 1 worker node. Rellene las variables en blanco tal y como se explica en los comentarios y no dude en cambiar otros parámetros para que se adapten a sus necesidades específicas.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
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
    ))

Obtención de los detalles del clústerGet Cluster Details

Para obtener las propiedades de un clúster determinado:To get properties for a given cluster:

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

EjemploExample

Puede usar get para confirmar que ha creado correctamente el clúster.You can use get to confirm that you have successfully created your cluster.

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

La salida debe ser similar a la siguiente:The output should look like:

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

Lista de clústeresList Clusters

Lista de clústeres de la suscripciónList Clusters Under The Subscription

client.clusters.list()

Lista de clústeres por grupo de recursosList Clusters By Resource Group

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

Nota

Tanto list() como list_by_resource_group() devuelven un objeto ClusterPaged.Both list() and list_by_resource_group() return a ClusterPaged object. Una llamada a advance_page() devuelve una lista de clústeres en esa página y hace avanzar el objeto ClusterPaged a la página siguiente.Calling advance_page() returns a list of clusters on that page and advances the ClusterPaged object to the next page. Esto se puede repetir hasta que se produzca una excepción StopIteration, que indica que no existen más páginas.This can be repeated until a StopIteration exception is raised, indicating that there are no more pages.

EjemploExample

El ejemplo siguiente imprime las propiedades de todos los clústeres de la suscripción actual:The following example prints the properties of all clusters for the current subscription:

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

Eliminación de un clústerDelete a Cluster

Para eliminar un clúster:To delete a cluster:

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

Actualización de las etiquetas del clústerUpdate Cluster Tags

Puede actualizar las etiquetas de un clúster determinado de este modo:You can update the tags of a given cluster like so:

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

EjemploExample

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

Cambio del tamaño de clústerResize Cluster

Para cambiar el tamaño de un número de nodos de trabajo de un clúster determinado, puede especificar un nuevo tamaño como sigue: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>", target_instance_count=<Num of Worker Nodes>)

Supervisión de clústeresCluster Monitoring

El SDK de administración de HDInsight también puede utilizarse para administrar la supervisión en los clústeres mediante Operations Management Suite (OMS).The HDInsight Management SDK can also be used to manage monitoring on your clusters via the Operations Management Suite (OMS).

Habilitación de OMS MonitoringEnable OMS Monitoring

Nota

Para habilitar OMS Monitoring, debe tener un área de trabajo de Log Analytics.To enable OMS Monitoring, you must have an existing Log Analytics workspace. Si aún no ha creado una, puede aprender a hacerlo aquí: Creación de un área de trabajo de Log Analytics en Azure Portal.If you have not already created one, you can learn how to do that here: Create a Log Analytics workspace in the Azure portal.

Para habilitar OMS Monitoring en el clúster:To enable OMS Monitoring on your cluster:

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

Ver el estado de OMS MonitoringView Status Of OMS Monitoring

Para obtener el estado de OMS en el clúster:To get the status of OMS on your cluster:

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

Deshabilitación de OMS MonitoringDisable OMS Monitoring

Para deshabilitar OMS en el clúster:To disable OMS on your cluster:

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

Acciones de scriptScript Actions

HDInsight proporciona un método de configuración llamado acciones de script, que invoca scripts personalizados para personalizar el clúster.HDInsight provides a configuration method called script actions that invokes custom scripts to customize the cluster.

Nota

Encontrará más información sobre cómo usar acciones de script aquí: Personalización de clústeres de HDInsight basados en Linux mediante acciones de scriptMore information on how to use script actions can be found here: Customize Linux-based HDInsight clusters using script actions

Ejecución de acciones de scriptExecute Script Actions

Para ejecutar acciones de script en un clúster determinado:To execute script actions on a given cluster:

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

Eliminación de una acción de scriptDelete Script Action

Para eliminar una acción de script persistente específica en un clúster determinado:To delete a specified persisted script action on a given cluster:

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

Lista de acciones de script persistentesList Persisted Script Actions

Nota

list() y list_persisted_scripts() devuelven un objeto RuntimeScriptActionDetailPaged.list() and list_persisted_scripts() return a RuntimeScriptActionDetailPaged object. Una llamada a advance_page() devuelve la lista de RuntimeScriptActionDetail de esa página y hace avanzar el objeto RuntimeScriptActionDetailPaged a la página siguiente.Calling advance_page() returns a list of RuntimeScriptActionDetail on that page and advances the RuntimeScriptActionDetailPaged object to the next page. Esto se puede repetir hasta que se produzca una excepción StopIteration, que indica que no existen más páginas.This can be repeated until a StopIteration exception is raised, indicating that there are no more pages. Observe el ejemplo siguiente.See the example below.

Para mostrar una lista de todas las acciones de script persistentes para el clúster especificado:To list all persisted script actions for the specified cluster:

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

EjemploExample

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

Lista del historial de ejecución de todos los scriptsList All Scripts' Execution History

Para mostrar una lista del historial de ejecución de todos los scripts para el clúster especificado:To list all scripts' execution history for the specified cluster:

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

EjemploExample

Este ejemplo imprime todos los detalles de todas las ejecuciones de script pasadas.This example prints all the details for all past script executions.

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