SDK do HDInsight para Python

  • Artigo

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

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.

Observação

Existem outras formas de autenticar além do exemplo abaixo que talvez sejam mais adequadas às suas necessidades. Todos os métodos são descritos aqui: Autenticar com as Bibliotecas de Gerenciamento do Azure para Python

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>

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. Isso também pode ser feito no Azure Cloud Shell executando o seguinte comando:

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

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. As instruções para autenticar e obter um HDInsightManagementClient podem ser encontradas na seção Autenticação acima.

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.

Observação

Primeiro você precisa criar um grupo de recursos e uma conta de armazenamento, conforme explicado abaixo. Se você já os tiver criado, ignore as próximas etapas.

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

Observação

Tanto list() quanto list_by_resource_group() retornam um objeto ClusterPaged. Chamar advance_page() retorna uma lista de clusters nessa página e avança o objeto ClusterPaged para a página seguinte. Isso pode ser repetido até uma exceção StopIteration ser gerada, indicando que não existem mais páginas.

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

Observação

Para habilitar o Monitoramento de OMS, você deve ter um espaço de trabalho do Log Analytics existente. Se você já não tiver criado um, você pode aprender como fazer isso aqui: Criar um espaço de trabalho do Log Analytics no portal do Azure.

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.

Observação

Mais informações sobre como usar as ações de script podem ser encontradas aqui: Personalizar clusters HDInsight com base em Linux usando ações de script

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

Observação

list() e list_persisted_scripts() retornam um objeto RuntimeScriptActionDetailPaged. Chamar advance_page() retorna uma lista de RuntimeScriptActionDetail nessa página e avança o objeto RuntimeScriptActionDetailPaged para a página seguinte. Isso pode ser repetido até uma exceção StopIteration ser gerada, indicando que não existem mais páginas. Veja o exemplo abaixo.

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