SDK do HDInsight para Python

Visão geral

O SDK do HDInsight para Python oferece classes e métodos que permitem gerenciar os clusters do HDInsight. Inclui operações para criar, excluir, atualizar, listar, redimensionar, executar ações de script, monitorar, obter propriedades dos clusters HDInsight e muito mais.

Pré-requisitos

• Uma conta do Azure. Se você não tiver uma, obtenha uma avaliação gratuita.
• Python
• pip

Instalação do SDK

O SDK do HDInsight para Python pode ser encontrado no Índice do Pacote do Python e instalado executando:

pip install azure-mgmt-hdinsight

Autenticação

O SDK precisa primeiro ser autenticado com a assinatura do Azure. Siga o exemplo abaixo para criar uma entidade de serviço e use-a para a autenticação. 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.

Exemplo de autenticação usando uma entidade de serviço

Primeiro, faça logon no Azure Cloud Shell. Verifique se você está usando atualmente a assinatura na qual deseja a entidade de serviço criada.

az account show

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

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

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:

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

As informações da entidade de serviço são exibidas como 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 snippet 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.

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 clusters

Criar um cluster

Um novo cluster pode ser criado chamando client.clusters.create().

Exemplos

Exemplos de código para criar vários tipos comuns de clusters HDInsight estão disponíveis: Exemplos de Python do HDInsight.

Exemplo

Este exemplo demonstra como criar um cluster Spark com 2 nós principais e 1 nó de trabalho.

Criar um grupo de recursos

É possível criar um grupo de recursos usando o Azure Cloud Shell executando:

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

Criar uma conta de armazenamento

É possível criar uma conta de armazenamento usando o Azure Cloud Shell executando:

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):

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

O snippet do Python abaixo cria um cluster Spark com dois nós principais e um nó de trabalho. Preencha as variáveis em branco conforme explicado nos comentários e fique à vontade para alterar outros parâmetros conforme as suas necessidades.

# 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 cluster

Para obter propriedades para um determinado cluster:

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

Exemplo

Você pode usar get para confirmar que criou com êxito o seu cluster.

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

A saída deve ser assim:

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

Listar os clusters em uma assinatura

client.clusters.list()

Listar os clusters por grupo de recursos

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

Exemplo

O exemplo a seguir imprime as propriedades de todos os clusters da assinatura atual:

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

Excluir um cluster

Para excluir um cluster:

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

Atualizar marcas de cluster

É possível atualizar as marcas de um determinado cluster da seguinte forma:

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

Exemplo

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

Redimensionar Cluster

É possível redimensionar o número de nós de trabalho de determinado cluster especificando um novo tamanho, assim:

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

Monitoramento do cluster

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).

Habilitar Monitoramento de OMS

Para habilitar o Monitoramento de OMS no seu cluster:

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

Exibir o status do Monitoramento de OMS

Para obter o status do OMS no seu cluster:

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

Desabilitar Monitoramento de OMS

Para desabilitar o OMS no seu cluster:

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

Ações de script

O HDInsight fornece um método de configuração chamado ações de script que chama os scripts personalizados para personalizar o cluster.

Executar ações de script

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

Para excluir uma ação de script persistente específica em um determinado cluster:

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

Listar ações de script persistentes

Para listar todas as ações de script persistentes para o cluster especificado:

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

Exemplo

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 scripts

Para listar o histórico de execução de todos os scripts para o cluster especificado:

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

Exemplo

Este exemplo imprime todos os detalhes para todas as execuções de script anteriores.

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