Partilhar via

HDInsight SDK for Python (SDK do HDInsight para Python)

  • Artigo

Descrição Geral

O HDInsight SDK para Python fornece aulas e métodos que lhe permitem gerir os seus clusters HDInsight. Inclui operações para criar, eliminar, atualizar, listar, redimensionar, executar ações de script, monitorizar, obter propriedades de clusters do HDInsight, entre outras.

Pré-requisitos

Instalação SDK

O HDInsight SDK para Python pode ser encontrado no Python Package Index e pode ser instalado em execução:

pip install azure-mgmt-hdinsight

Autenticação

O SDK precisa primeiro de ser autenticado com a sua subscrição Azure. Siga o exemplo abaixo para criar um principal de serviço e usá-lo para autenticar. Depois disso, terá um exemplo de um HDInsightManagementClient, que contém muitos métodos (descritos em secções abaixo) que podem ser usados para realizar operações de gestão.

Nota

Existem outras formas de autenticar além do exemplo abaixo que poderia potencialmente ser mais adequado para as suas necessidades. Todos os métodos são delineados aqui: Autenticar com as Bibliotecas de Gestão Azure para Python

Exemplo de autenticação Usando um diretor de serviço

Primeiro, faça login no Azure Cloud Shell. Verifique se está a utilizar a subscrição na qual pretende que o titular do serviço seja criado.

az account show

As suas informações de subscrição são apresentadas 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 não estiver registado na subscrição correta, selecione a correta executando:

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

Importante

Se ainda não registou o Fornecedor de Recursos HDInsight por outro método (como por exemplo, criar um Cluster HDInsight através do Portal Azure), tem de o fazer uma vez antes de poder autenticar. Isto pode ser feito a partir do Azure Cloud Shell executando o seguinte comando:

az provider register --namespace Microsoft.HDInsight

Em seguida, escolha um nome para o seu principal de serviço e crie-o com o seguinte comando:

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

A informação principal do serviço é apresentada 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 de Python abaixo e preenchaTENANT_ID, CLIENT_IDe CLIENT_SECRETSUBSCRIPTION_ID com as cordas do JSON que foi devolvido após executar o comando para criar o principal 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)

Gestão de Clusters

Nota

Esta secção pressupõe que já autenticou e construiu um HDInsightManagementClient caso e guardou-o numa variável chamada client. As instruções para autenticar e obter uma HDInsightManagementClient pode ser encontrada na secção de Autenticação acima.

Criar um Cluster

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

Amostras

Estão disponíveis amostras de código para a criação de vários tipos comuns de clusters HDInsight: Amostras de Python HDInsight.

Exemplo

Este exemplo demonstra como criar um cluster Spark com 2 nós de cabeça e 1 nó de trabalhador.

Nota

Primeiro precisa de criar um Grupo de Recursos e Conta de Armazenamento, como explicado abaixo. Se já os criou, pode saltar estes passos.

Criação de um Grupo de Recursos

Pode criar um grupo de recursos utilizando o Azure Cloud Shell executando

az group create -l <Region Name (i.e. eastus)> --n <Resource Group Name>
Criação de uma conta de armazenamento

Pode criar uma conta de armazenamento utilizando 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 executar o seguinte comando para obter a chave para a sua conta de armazenamento (você precisará deste para criar um cluster):

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

O snippet abaixo do Python cria um aglomerado de faíscas com 2 nós de cabeça e 1 nó de trabalhador. Preencha as variáveis em branco como explicado nos comentários e sinta-se livre para alterar outros parâmetros de acordo com as suas necessidades específicas.

# 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

Pode usar get para confirmar que criou com sucesso o seu cluster.

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

A saída deve parecer:

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

Agrupamentos de listas

Agrupamentos de listas sob a subscrição

client.clusters.list()

Agrupamentos de listas por grupo de recursos

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

Nota

Ambos list() e list_by_resource_group() devolvam um ClusterPaged objeto. A chamada advance_page() devolve uma lista de clusters nessa página e avança o ClusterPaged objeto para a página seguinte. Isto pode ser repetido até que uma StopIteration exceção seja levantada, indicando que não há mais páginas.

Exemplo

O exemplo a seguir imprime as propriedades de todos os clusters para a subscrição atual:

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

Delete a Cluster (Eliminar um Cluster)

Para eliminar um cluster:

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

Atualizar tags de cluster

Pode atualizar as etiquetas de um determinado cluster assim:

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

Pode redimensionar o número de nós de trabalhadores de um determinado cluster especificando um novo tamanho como:

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

Monitorização de Cluster

O HDInsight Management SDK também pode ser usado para gerir a monitorização dos seus clusters através do Suite de Gestão de Operações (OMS).

Permitir a monitorização de OMS

Nota

Para ativar o controlo do OMS, tem de ter um espaço de trabalho log analytics existente. Se ainda não criou um, pode aprender a fazê-lo aqui: Criar um espaço de trabalho Log Analytics no portal do Azure.

Para ativar a monitorização do OMS no seu cluster:

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

Ver estado da monitorização de OMS

Para obter o estado da OMS no seu cluster:

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

Desativar a monitorização dos OMS

Para desativar 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 invoca scripts personalizados para personalizar o cluster.

Nota

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

Executar ações de script

Para executar ações de script num 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

Eliminar ação do script

Para eliminar uma ação de scripts persistiu especificada num determinado cluster:

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

Lista de ações de script persistidas

Nota

list() e list_persisted_scripts() devolver um RuntimeScriptActionDetailPaged objeto. A chamada advance_page() devolve uma lista dessa RuntimeScriptActionDetail página e avança o RuntimeScriptActionDetailPaged objeto para a página seguinte. Isto pode ser repetido até que uma StopIteration exceção seja levantada, indicando que não há mais páginas. Veja o exemplo abaixo.

Para listar todas as ações de scripts persistidos 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 a história da 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 scripts 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