Editar

Compartilhar via

SDK do HDInsight para PythonHDInsight SDK for Python

  • Artigo

Visão geralOverview

O SDK do HDInsight para Python oferece classes e métodos que permitem gerenciar os clusters do HDInsight.The HDInsight SDK for Python provides classes and methods that allow you to manage your HDInsight clusters. Inclui operações para criar, excluir, atualizar, listar, redimensionar, executar ações de script, monitorar, obter propriedades dos clusters HDInsight e muito mais.It includes operations to create, delete, update, list, resize, execute script actions, monitor, get properties of HDInsight clusters, and more.

Pré-requisitosPrerequisites

Instalação do SDKSDK Installation

O SDK do HDInsight para Python pode ser encontrado no Índice do Pacote do Python e instalado executando: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

O SDK precisa primeiro ser autenticado com a assinatura do Azure.The SDK first needs to be authenticated with your Azure subscription. Siga o exemplo abaixo para criar uma entidade de serviço e use-a para a autenticação.Follow the example below to create a service principal and use it to authenticate. Após isso ser feito, você terá uma instância de um HDInsightManagementClient, que contém muitos métodos (destacados nas seções abaixo) que podem ser usados para realizar operações de gerenciamento.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.

Observação

Existem outras formas de autenticar além do exemplo abaixo que talvez sejam mais adequadas às suas necessidades.There are other ways to authenticate besides the below example that could potentially be better suited for your needs. Todos os métodos são descritos aqui: Autenticar com as Bibliotecas de Gerenciamento do Azure para PythonAll methods are outlined here: Authenticate with the Azure Management Libraries for Python

Exemplo de autenticação usando uma entidade de serviçoAuthentication Example Using a Service Principal

Primeiro, faça logon no Azure Cloud Shell.First, login to Azure Cloud Shell. Verifique se você está usando atualmente a assinatura na qual deseja a entidade de serviço criada.Verify you are currently using the subscription in which you want the service principal created.

az account show

As informações da assinatura são exibidas como 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"
  }
}

Se você não estiver conectado à assinatura correta, selecione a correta executando: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

Se você já não tiver registrado o Provedor de Recursos do HDInsight através de outro método (tais como criar um cluster do HDInsight através do portal do Azure), você precisa fazer isso uma vez antes de poder autenticar.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. Isso também pode ser feito no Azure Cloud Shell executando o seguinte comando:This can be done from the Azure Cloud Shell by running the following command:

az provider register --namespace Microsoft.HDInsight

Em seguida, escolha um nome para a sua entidade de serviço e crie-a com o seguinte 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

As informações da entidade de serviço são exibidas como 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 o trecho do Python abaixo e preencha TENANT_ID, CLIENT_ID, CLIENT_SECRET e SUBSCRIPTION_ID com as cadeias de caracteres do JSON retornadas após a execução do comando para criar a entidade de serviço.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)

Gerenciamento de clustersCluster Management

Observação

Essa seção pressupõe que você já autenticou e criou uma HDInsightManagementClient instância e a armazenou em uma variável chamada client.This section assumes you have already authenticated and constructed an HDInsightManagementClient instance and store it in a variable called client. As instruções para autenticar e obter um HDInsightManagementClient podem ser encontradas na seção Autenticação acima.Instructions for authenticating and obtaining an HDInsightManagementClient can be found in the Authentication section above.

Criar um clusterCreate a Cluster

Um novo cluster pode ser criado chamando client.clusters.create().A new cluster can be created by calling client.clusters.create().

ExemplosSamples

Os exemplos de código para criar vários tipos comuns de clusters HDInsight estão disponíveis: Exemplos de HDInsight para Python.Code samples for creating several common types of HDInsight clusters are available: HDInsight Python Samples.

ExemploExample

Este exemplo demonstra como criar um cluster Spark com 2 nós principais e 1 nó de trabalho.This example demonstrates how to create a Spark cluster with 2 head nodes and 1 worker node.

Observação

Primeiro você precisa criar um grupo de recursos e uma conta de armazenamento, conforme explicado abaixo.You first need to create a Resource Group and Storage Account, as explained below. Se você já os tiver criado, ignore as próximas etapas.If you have already created these, you can skip these steps.

Criar um grupo de recursosCreating a Resource Group

É possível criar um grupo de recursos usando o Azure Cloud Shell executando: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>
Criar uma conta de armazenamentoCreating a Storage Account

É possível criar uma conta de armazenamento usando o Azure Cloud Shell executando: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>

Agora execute o comando a seguir para obter a chave para a sua conta de armazenamento (você precisará dela para criar um cluster):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>

O trecho do Python abaixo cria um cluster Spark com dois nós principais e um nó de trabalho.The below Python snippet creates a Spark cluster with 2 head nodes and 1 worker node. Preencha as variáveis em branco conforme explicado nos comentários e fique à vontade para alterar outros parâmetros conforme as suas necessidades.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
    ))

Obter detalhes do clusterGet Cluster Details

Para obter propriedades para um determinado cluster:To get properties for a given cluster:

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

ExemploExample

Você pode usar get para confirmar que criou com êxito o seu cluster.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)

A saída deve ser assim: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>}

Listar clustersList Clusters

Listar os clusters em uma assinaturaList Clusters Under The Subscription

client.clusters.list()

Listar os clusters por grupo de recursosList Clusters By Resource Group

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

Observação

Tanto list() quanto list_by_resource_group() retornam um objeto ClusterPaged.Both list() and list_by_resource_group() return a ClusterPaged object. Chamar advance_page() retorna uma lista de clusters nessa página e avança o objeto ClusterPaged para a página seguinte.Calling advance_page() returns a list of clusters on that page and advances the ClusterPaged object to the next page. Isso pode ser repetido até uma exceção StopIteration ser gerada, indicando que não existem mais páginas.This can be repeated until a StopIteration exception is raised, indicating that there are no more pages.

ExemploExample

O exemplo a seguir imprime as propriedades de todos os clusters da assinatura atual: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

Excluir um clusterDelete a Cluster

Para excluir um cluster:To delete a cluster:

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

Atualizar marcas de clusterUpdate Cluster Tags

É possível atualizar as marcas de um determinado cluster da seguinte forma:You can update the tags of a given cluster like so:

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

ExemploExample

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

Redimensionar ClusterResize Cluster

É possível redimensionar o número de nós de trabalho de determinado cluster especificando um novo tamanho, assim: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>)

Monitoramento do clusterCluster Monitoring

O SDK de gerenciamento do HDInsight também pode ser usado para gerenciar o monitoramento dos seus clusters através do Operations Management Suite (OMS).The HDInsight Management SDK can also be used to manage monitoring on your clusters via the Operations Management Suite (OMS).

Habilitar Monitoramento de OMSEnable OMS Monitoring

Observação

Para habilitar o Monitoramento de OMS, você deve ter um espaço de trabalho do Log Analytics existente.To enable OMS Monitoring, you must have an existing Log Analytics workspace. Se você ainda não criou, aprenda como fazer isso aqui: Criar um espaço de trabalho do Log Analytics no Portal do Azure.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 o Monitoramento de OMS no seu cluster:To enable OMS Monitoring on your cluster:

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

Exibir o status do Monitoramento de OMSView Status Of OMS Monitoring

Para obter o status do OMS no seu cluster:To get the status of OMS on your cluster:

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

Desabilitar Monitoramento de OMSDisable OMS Monitoring

Para desabilitar o OMS no seu cluster:To disable OMS on your cluster:

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

Ações de scriptScript Actions

O HDInsight fornece um método de configuração chamado ações de script que chama os scripts personalizados para personalizar o cluster.HDInsight provides a configuration method called script actions that invokes custom scripts to customize the cluster.

Observação

Mais informações sobre como usar as ações de script podem ser encontradas aqui: Customizar clusters HDInsight baseados em Linux usando as ações de scriptMore information on how to use script actions can be found here: Customize Linux-based HDInsight clusters using script actions

Executar ações de scriptExecute Script Actions

Para executar as ações de script em um determinado cluster: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

Excluir ação de scriptDelete Script Action

Para excluir uma ação de script persistente específica em um determinado cluster:To delete a specified persisted script action on a given cluster:

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

Listar ações de script persistentesList Persisted Script Actions

Observação

list() e list_persisted_scripts() retornam um objeto RuntimeScriptActionDetailPaged.list() and list_persisted_scripts() return a RuntimeScriptActionDetailPaged object. Chamar advance_page() retorna uma lista de RuntimeScriptActionDetail nessa página e avança o objeto RuntimeScriptActionDetailPaged para a página seguinte.Calling advance_page() returns a list of RuntimeScriptActionDetail on that page and advances the RuntimeScriptActionDetailPaged object to the next page. Isso pode ser repetido até uma exceção StopIteration ser gerada, indicando que não existem mais páginas.This can be repeated until a StopIteration exception is raised, indicating that there are no more pages. Veja o exemplo abaixo.See the example below.

Para listar todas as ações de script persistentes para o cluster especificado:To list all persisted script actions for the specified cluster:

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

ExemploExample

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

Listar o histórico de execução de todos os scriptsList All Scripts' Execution History

Para listar o histórico de execução de todos os scripts para o cluster especificado:To list all scripts' execution history for the specified cluster:

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

ExemploExample

Este exemplo imprime todos os detalhes para todas as execuções de script anteriores.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