편집

다음을 통해 공유

Python용 HDInsight SDKHDInsight SDK for Python

  • 아티클

개요Overview

Python용 HDInsight SDK는 HDInsight 클러스터를 관리할 수 있는 클래스와 메서드를 제공합니다.The HDInsight SDK for Python provides classes and methods that allow you to manage your HDInsight clusters. 여기에는 HDInsight 클러스터의 속성 만들기, 삭제, 업데이트, 나열, 크기 조정, 스크립트 작업 실행, 모니터링, 가져오기 작업을 포함합니다.It includes operations to create, delete, update, list, resize, execute script actions, monitor, get properties of HDInsight clusters, and more.

필수 조건Prerequisites

SDK 설치SDK Installation

Python용 HDInsight SDK는 Python 패키지 인덱스에 있으며 다음을 실행하여 설치할 수 있습니다.The HDInsight SDK for Python can be found in the Python Package Index and can be installed by running:

pip install azure-mgmt-hdinsight

인증Authentication

Azure 구독을 사용해서 SDK를 먼저 인증해야 합니다.The SDK first needs to be authenticated with your Azure subscription. 아래 예제에 따라 서비스 주체를 만들고 이를 인증에 사용합니다.Follow the example below to create a service principal and use it to authenticate. 완료되었으면 관리 작업 수행을 위해 사용할 수 있는 여러 메서드(아래 섹션 참조)가 포함된 HDInsightManagementClient 인스턴스가 준비됩니다.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.

참고

아래 설명된 예제 외에도 사용자 요구에 더 적합할 수 있는 다른 인증 방법이 있습니다.There are other ways to authenticate besides the below example that could potentially be better suited for your needs. 모든 메서드는 여기에 설명되어 있습니다. Python용 Azure 관리 라이브러리를 사용하여 인증All methods are outlined here: Authenticate with the Azure Management Libraries for Python

서비스 주체를 사용한 인증 예제Authentication Example Using a Service Principal

먼저, Azure Cloud Shell에 로그인합니다.First, login to Azure Cloud Shell. 서비스 주체를 만들려는 구독을 현재 사용하고 있는지 확인합니다.Verify you are currently using the subscription in which you want the service principal created.

az account show

구독 정보는 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"
  }
}

올바른 구독으로 로그인되지 않은 경우 다음을 실행하여 올바른 구독을 선택합니다.If you're not logged into the correct subscription, select the correct one by running:

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

중요

Azure Portal을 통해 HDInsight Cluster를 만드는 등 다른 방법을 사용해서 HDInsight Resource Provider를 등록하지 않은 경우, 이를 먼저 수행해야 인증할 수 있습니다.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. 이 작업은 Azure Cloud Shell에서 다음 명령을 실행하여 수행할 수 있습니다.This can be done from the Azure Cloud Shell by running the following command:

az provider register --namespace Microsoft.HDInsight

그런 다음 서비스 주체 이름을 선택하고 다음 명령을 사용해서 만듭니다.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

서비스 주체 정보는 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/"
}

아래 Python 코드 조각을 복사하고 서비스 주체를 만들기 위해 명령을 실행한 후 반환된 JSON 문자열을 TENANT_ID, CLIENT_ID, CLIENT_SECRET 및 SUBSCRIPTION_ID에 채웁니다.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)

클러스터 관리Cluster Management

참고

이 섹션에서는 이미 인증이 수행되었고 HDInsightManagementClient 인스턴스가 생성되었으며, client라는 변수로 저장되었다고 가정합니다.This section assumes you have already authenticated and constructed an HDInsightManagementClient instance and store it in a variable called client. HDInsightManagementClient 인증 및 가져오기 지침은 위에 표시된 인증 섹션에서 찾을 수 있습니다.Instructions for authenticating and obtaining an HDInsightManagementClient can be found in the Authentication section above.

클러스터 만들기Create a Cluster

client.clusters.create()을(를) 호출하여 새 클러스터를 만들 수 있습니다.A new cluster can be created by calling client.clusters.create().

샘플Samples

몇 가지 일반적인 유형의 HDInsight 클러스터를 만드는 코드 샘플(HDInsight Python 샘플)도 사용할 수 있습니다.Code samples for creating several common types of HDInsight clusters are available: HDInsight Python Samples.

예Example

이 예제에서는 2개의 헤드 노드 및 1개의 작업자 노드를 사용하여 Spark 클러스터를 만드는 방법을 보여줍니다.This example demonstrates how to create a Spark cluster with 2 head nodes and 1 worker node.

참고

먼저 아래 설명된 대로 리소스 그룹 및 저장소 계정을 만들어야 합니다.You first need to create a Resource Group and Storage Account, as explained below. 이미 만든 경우에는 이 단계를 건너뛸 수 있습니다.If you have already created these, you can skip these steps.

리소스 그룹 만들기Creating a Resource Group

다음을 실행하여 Azure Cloud Shell을 사용해서 리소스 그룹을 만들 수 있습니다.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>
저장소 계정 만들기Creating a Storage Account

다음을 실행하여 Azure Cloud Shell을 사용해서 저장소 계정을 만들 수 있습니다.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>

이제 다음 명령을 사용해서 저장소 계정에 대한 키를 가져옵니다(클러스터를 만들기 위해 필요).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>

아래의 Python 코드 조각은 2개의 헤드 노드 및 1개의 작업자 노드를 사용해서 Spark 클러스터를 만듭니다.The below Python snippet creates a Spark cluster with 2 head nodes and 1 worker node. 주석 설명에 따라 빈 변수를 채우고 특정 요구에 따라 다른 매개변수를 변경합니다.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
    ))

클러스터 세부 정보 가져오기Get Cluster Details

지정된 클러스터에 대한 속성을 가져오려면:To get properties for a given cluster:

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

예Example

get을(를) 사용하여 클러스터 만들기가 성공했는지 확인할 수 있습니다.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)

출력은 다음과 같습니다.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>}

클러스터 나열List Clusters

구독 아래에 클러스터 나열List Clusters Under The Subscription

client.clusters.list()

리소스 그룹별로 클러스터 나열List Clusters By Resource Group

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

참고

list() 및 list_by_resource_group() 모두 ClusterPaged 개체를 반환합니다.Both list() and list_by_resource_group() return a ClusterPaged object. advance_page()를 호출하면 해당 페이지의 클러스터 목록이 반환되고 ClusterPaged 개체가 다음 페이지로 이동합니다.Calling advance_page() returns a list of clusters on that page and advances the ClusterPaged object to the next page. StopIteration 예외가 제기될 때까지 반복할 수 있으며, 더 이상 페이지가 없음을 나타냅니다.This can be repeated until a StopIteration exception is raised, indicating that there are no more pages.

예Example

다음 예제는 현재 구독에 대해 모든 클러스터 속성을 출력합니다.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

클러스터 삭제Delete a Cluster

클러스터를 삭제하려면:To delete a cluster:

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

클러스터 태그 업데이트Update Cluster Tags

지정된 클러스터의 태그를 다음과 같이 업데이트할 수 있습니다.You can update the tags of a given cluster like so:

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

예Example

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

클러스터 크기 조정Resize Cluster

새 크기를 지정하여 작업자 노드의 지정된 클러스터 번호를 크기 조정할 수 있습니다.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>)

클러스터 모니터링Cluster Monitoring

또한 HDInsight 관리 SDK를 사용하여 OMS(Operations Management Suite)를 통해 클러스터에서 모니터링을 관리할 수 있습니다.The HDInsight Management SDK can also be used to manage monitoring on your clusters via the Operations Management Suite (OMS).

OMS 모니터링 사용Enable OMS Monitoring

참고

OMS 모니터링을 사용하려면 기존 Log Analytics 작업 영역이 있어야 합니다.To enable OMS Monitoring, you must have an existing Log Analytics workspace. 아직 작업 영역을 만들지 않은 경우 다음에서 작업 영역을 만드는 방법을 알아볼 수 있습니다. Azure Portal에서 Log Analytics 작업 영역 만들기.If you have not already created one, you can learn how to do that here: Create a Log Analytics workspace in the Azure portal.

클러스터에서 OMS 모니터링을 사용하려면:To enable OMS Monitoring on your cluster:

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

OMS 모니터링의 상태 보기View Status Of OMS Monitoring

클러스터에서 OMS 상태를 가져오려면:To get the status of OMS on your cluster:

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

OMS 모니터링 사용 안 함Disable OMS Monitoring

클러스터에서 OMS를 사용하지 않으려면:To disable OMS on your cluster:

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

스크립트 동작Script Actions

HDInsight는 클러스터 사용자 지정을 위해 사용자 지정 스크립트를 호출하는 스크립트 작업이라고 부르는 구성 메서드를 제공합니다.HDInsight provides a configuration method called script actions that invokes custom scripts to customize the cluster.

참고

스크립트 작업을 사용하는 방법에 대한 자세한 내용은 다음에서 찾을 수 있습니다. 스크립트 작업을 사용하여 Linux 기반 HDInsight 클러스터 사용자 지정.More information on how to use script actions can be found here: Customize Linux-based HDInsight clusters using script actions

스크립트 작업 실행Execute Script Actions

지정된 클러스터에서 스크립트 작업을 실행하려면 다음을 수행합니다.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

스크립트 작업 삭제Delete Script Action

지정된 클러스터에서 지정된 지속형 스크립트 작업을 삭제하려면:To delete a specified persisted script action on a given cluster:

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

지속형 스크립트 작업 나열List Persisted Script Actions

참고

list() 및 list_persisted_scripts()는 RuntimeScriptActionDetailPaged 개체를 반환합니다.list() and list_persisted_scripts() return a RuntimeScriptActionDetailPaged object. advance_page()를 호출하면 해당 페이지의 RuntimeScriptActionDetail 목록이 반환되고 RuntimeScriptActionDetailPaged 개체가 다음 페이지로 이동합니다.Calling advance_page() returns a list of RuntimeScriptActionDetail on that page and advances the RuntimeScriptActionDetailPaged object to the next page. StopIteration 예외가 제기될 때까지 반복할 수 있으며, 더 이상 페이지가 없음을 나타냅니다.This can be repeated until a StopIteration exception is raised, indicating that there are no more pages. 아래 예제를 참조하세요.See the example below.

지정된 클러스터에 대해 모든 지속형 스크립트 작업을 나열하려면:To list all persisted script actions for the specified cluster:

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

예Example

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

모든 스크립트 실행 기록 나열List All Scripts' Execution History

지정된 클러스터에 대해 모든 스크립트 실행 기록을 나열하려면:To list all scripts' execution history for the specified cluster:

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

예Example

이 예제는 모든 과거 스크립트 실행에 대한 모든 세부 정보를 출력합니다.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