쿼리를 만들어서 효율적으로 Batch 리소스 나열

  • 아티클

대부분의 Azure Batch 애플리케이션은 Batch 서비스를 쿼리하는 모니터링 또는 기타 작업을 수행합니다. 이러한 목록 쿼리는 종종 정기적으로 발생합니다. 예를 들어 작업에서 대기 중인 태스크를 확인하려면 먼저 해당 작업의 모든 태스크에 대한 데이터를 가져와야 합니다. Batch 서비스에서 쿼리에 대해 반환하는 데이터의 양을 줄이면 애플리케이션의 성능이 향상됩니다. 이 문서에서는 효율적인 방법으로 이러한 쿼리를 만들고 실행하는 방법에 대해 설명합니다. Batch .NET 라이브러리를 사용하여 Batch 작업, 태스크, 컴퓨팅 노드 및 기타 리소스에 대해 필터링된 쿼리를 만들 수 있습니다.

참고 항목

Batch 서비스는 작업 내 태스크 개수를 계산하고 Batch 풀의 컴퓨팅 노드 개수를 계산하는 일반적인 시나리오에 대한 API 지원을 제공합니다. 목록 쿼리를 사용하는 대신, 태스크 수 가져오기 및 풀 노드 수 나열 작업을 호출할 수 있습니다. 그러나 이러한 보다 효율적인 작업은 최신이 아닐 수 있는 좀 더 제한된 정보를 반환합니다. 자세한 내용은 상태별 태스크 및 컴퓨팅 노드 개수 계산을 참조하세요.

세부 정보 수준 지정

프로덕션 Batch 애플리케이션에는 작업, 태스크 및 컴퓨팅 노드와 같은 수천 개의 엔터티가 있을 수 있습니다. 리소스에 대해 만드는 각 쿼리에 대해 잠재적으로 많은 양의 데이터가 Batch 서비스에서 애플리케이션으로 이동합니다. 성능 향상을 위해 쿼리가 반환하는 항목 수와 정보를 제한합니다.

이 Batch .NET API 코드 조각은 각 태스크의 속성 모두와 함께 작업과 관련된 모든 태스크를 나열합니다.

// Get a collection of all of the tasks and all of their properties for job-001
IPagedEnumerable<CloudTask> allTasks =
    batchClient.JobOperations.ListTasks("job-001");

세부 정보를 쿼리에 적용하여 정보를 보다 효율적으로 나열합니다. JobOperations.ListTasks 메서드에 ODATADetailLevel 개체를 제공합니다. 이 코드 조각은 완료된 태스크의 ID, 명령줄 및 컴퓨팅 노드 정보 속성만 반환합니다.

// Configure an ODATADetailLevel specifying a subset of tasks and
// their properties to return
ODATADetailLevel detailLevel = new ODATADetailLevel();
detailLevel.FilterClause = "state eq 'completed'";
detailLevel.SelectClause = "id,commandLine,nodeInfo";

// Supply the ODATADetailLevel to the ListTasks method
IPagedEnumerable<CloudTask> completedTasks =
    batchClient.JobOperations.ListTasks("job-001", detailLevel);

이 예제 시나리오에서 수천 개의 태스크가 작업에 있다면 두 번째 쿼리의 결과는 대개 첫 번째 쿼리의 결과보다 훨씬 더 빨리 반환됩니다. Batch .NET API를 사용하여 항목을 나열할 때 ODATADetailLevel을 사용하는 방법에 대한 자세한 내용은 Batch .NET의 효율적인 쿼리 섹션을 참조하세요.

Important

애플리케이션의 최고 효율성과 성능을 위해 항상 .NET API 목록 호출에 ODATADetailLevel 개체를 제공하는 것이 좋습니다. 세부 정보 수준을 지정하여 Batch 서비스 응답 시간을 낮추고, 네트워크 사용률을 개선하며 클라이언트 애플리케이션의 메모리 사용을 최소화하는 데 도움이 될 수 있습니다.

쿼리 문자열 사용

Batch .NET 및 Batch REST API를 사용하여 쿼리가 반환하는 항목 수와 쿼리가 각 항목에 대해 반환하는 정보의 양을 줄일 수 있습니다. 쿼리 범위를 좁히는 데 사용할 수 있는 세 가지 쿼리 문자열 유형은 $filter, $select 및 $expand입니다.

Batch .NET API의 경우 ODATADetailLevel 클래스 속성을 참조하세요. 또한 Batch .NET에서 효율적인 쿼리 섹션을 검토합니다.

Batch REST API의 경우 Batch REST API 참조를 참조하세요. 쿼리할 리소스에 대해 목록 참조를 찾습니다. 그런 다음, URI 매개 변수 섹션을 검토하여 , $filter, $select 및 $expand에 대한 자세한 내용을 확인합니다. 예를 들어 풀에 대한 URI 매개 변수 - 목록을 참조하세요. 또한 Azure CLI를 사용하여 효율적인 Batch 쿼리를 만드는 방법도 참조하세요.

참고 항목

세 가지 쿼리 문자열 형식 중 하나를 구성할 때 속성 이름 및 사례가 해당 REST API 요소와 일치해야 합니다. 예를 들어 .NET CloudTask 클래스를 사용하는 경우 .NET 속성이 CloudTask.State이더라도 State 대신 state를 지정해야 합니다. 자세한 내용은 .NET 및 REST API 간의 속성 매핑을 참조하세요.

필터

$filter 식 문자열은 반환되는 항목의 수를 줄입니다. 예를 들어 작업과 관련해서 실행 중인 태스크만 나열하거나 태스크를 실행할 준비가 된 컴퓨팅 노드만 나열할 수 있습니다.

이 문자열은 하나 이상의 식으로 구성된 문자열로 구성됩니다. 식은 속성 이름, 연산자, 값으로 이루어져 있습니다. 각 속성에 대해 지원되는 연산자의 경우처럼 지정할 수 있는 속성은 쿼리한 항목 마다 고유합니다. and 및 or 논리 연산자를 사용하면 여러 식을 결합할 수 있습니다.

(state eq 'running') and startswith(id, 'renderTask') 예제는 실행 중인 렌더링 태스크만 나열합니다.

선택

$select 식 문자열은 각 항목에 대해 반환되는 속성 값을 제한합니다. 쉼표로 구분된 속성 이름의 목록을 지정하고 해당 속성 값은 쿼리 결과의 항목에 대해 반환됩니다. 쿼리 중인 엔터티 형식에 대한 속성을 지정할 수 있습니다.

id, state, stateTransitionTime 예제는 각 태스크에 대해 반환되어야 하는 세 가지 속성 값만 지정하고 있습니다.

확장

$expand 식 문자열은 특정 정보를 얻는 데 필요한 API 호출 수를 줄입니다. 이 문자열을 사용하여 단일 API 호출을 통해 각 항목에 대한 자세한 정보를 얻을 수 있습니다. 이 메서드는 API 호출을 줄여 성능을 향상시키는 데 도움이 됩니다. 엔터티 목록을 가져오고 각 목록 항목에 대한 정보를 요청하는 대신 $expand 문자열을 사용합니다.

$select와 비슷하게, $expand는 특정 데이터가 목록 쿼리 결과에 포함되어 있는지 여부를 제어합니다. 모든 속성이 필요하며 select 문자열을 지정하지 않은 경우, 통계 정보를 가져오려면 $expand를 사용해야 합니다. select 문자열을 사용하여 속성 하위 집합을 가져올 경우 select 문자열에서 stats를 지정할 수 있으며 $expand는 지정하지 않아도 됩니다.

이 문자열의 지원되는 용도에는 작업, 작업 일정, 태스크 및 풀 나열이 포함됩니다. 현재 이 문자열은 통계 정보만 지원합니다.

stats 예제는 목록에서 각 항목에 대해 반환되어야 하는 통계 정보를 지정합니다.

filter, select, expand 문자열 규칙

  • filter, select 및 expand 문자열의 속성 이름이 Batch REST API에서와 같이 표시되는지 확인합니다. 이 규칙은 Batch .NET 또는 다른 Batch SDK 중 하나를 사용하는 경우에도 적용됩니다.
  • 모든 속성 이름은 대/소문자를 구분하지만, 속성 값은 대/소문자를 구분하지 않습니다.
  • 날짜/시간 문자열은 두 형식 중 하나가 될 수 있으며 DateTime으로 시작해야 합니다.
    • W3C-DTF 형식 예제: creationTime gt DateTime'2011-05-08T08:49:37Z'
    • RFC 1123 형식 예제: creationTime gt DateTime'Sun, 08 May 2011 08:49:37 GMT'
  • 부울 문자열은 true 또는 false입니다.
  • 잘못된 속성이나 연산자를 지정한 경우 400 (Bad Request) 오류가 발생합니다.

Batch .NET에서 효율적인 쿼리

Batch .NET API 안에서 ODATADetailLevel 클래스는 filter, select 및 expand 문자열을 사용하여 작업을 나열합니다. ODataDetailLevel 클래스에는 세 개의 퍼블릭 문자열 속성이 있습니다. 생성자에서 이러한 속성을 지정하거나 개체에서 직접 속성을 설정할 수 있습니다. 그런 후 ODataDetailLevel 개체를 ListPools, ListJobs 및 ListTasks와 같은 다양한 목록 작업에 매개 변수로 전달합니다.

다음 코드 조각에서는 풀의 특정 집합에 대한 통계에 대해 Batch 서비스를 효율적으로 쿼리하기 위해 Batch .NET API를 사용합니다. Batch 사용자는 테스트 및 프로덕션 풀을 가집니다. 테스트 풀 ID는 "test"를 접두사로 사용하고 프로덕션 풀 ID는 "prod"를 접두사로 사용합니다. myBatchClient 는 다음과 같은 BatchClient 클래스의 인스턴스를 적절하게 초기화합니다.

// First we need an ODATADetailLevel instance on which to set the filter, select,
// and expand clause strings
ODATADetailLevel detailLevel = new ODATADetailLevel();

// We want to pull only the "test" pools, so we limit the number of items returned
// by using a FilterClause and specifying that the pool IDs must start with "test"
detailLevel.FilterClause = "startswith(id, 'test')";

// To further limit the data that crosses the wire, configure the SelectClause to
// limit the properties that are returned on each CloudPool object to only
// CloudPool.Id and CloudPool.Statistics
detailLevel.SelectClause = "id, stats";

// Specify the ExpandClause so that the .NET API pulls the statistics for the
// CloudPools in a single underlying REST API call. Note that we use the pool's
// REST API element name "stats" here as opposed to "Statistics" as it appears in
// the .NET API (CloudPool.Statistics)
detailLevel.ExpandClause = "stats";

// Now get our collection of pools, minimizing the amount of data that is returned
// by specifying the detail level that we configured above
List<CloudPool> testPools =
    await myBatchClient.PoolOperations.ListPools(detailLevel).ToListAsync();

팁

Select 및 Expand 절로 구성된 ODATADetailLevel의 인스턴스는 반환되는 데이터의 양을 제한하기 위해 PoolOperations.GetPool과 같은 적절한 Get 메서드에 전달할 수도 있습니다.

Batch REST를 .NET API에 매핑

filter, select 및 expand 문자열의 속성 이름은 이름과 대소문자 모두 해당 REST API 항목을 반영해야 합니다. 다음 표는 .NET과 REST API 간의 매핑을 제공합니다.

filter 문자열 매핑

  • .NET 목록 메서드: 이 열의 각 .NET API 메서드는 ODATADetailLevel 개체를 매개 변수 형태로 수락합니다.
  • REST 목록 요청: 이 열에 나열된 각 REST API 페이지에는 filter 문자열에서 허용되는 속성과 연산을 포함하는 테이블이 있습니다. ODATADetailLevel.FilterClause 문자열을 구성할 때 이 속성 이름과 작업을 사용할 수 있습니다.
.NET 목록 메서드 REST 목록 요청
CertificateOperations.ListCertificates 계정에 인증서 나열
CloudTask.ListNodeFiles 작업과 연관된 파일 나열
JobOperations.ListJobPreparationAndReleaseTaskStatus 작업 준비 및 작업에 대한 작업 릴리스 태스크의 상태 나열
JobOperations.ListJobs 계정에 작업 나열
JobOperations.ListNodeFiles 노드에 파일 나열
JobOperations.ListTasks 작업과 연관된 태스크 나열
JobScheduleOperations.ListJobSchedules 계정에 작업 일정 나열
JobScheduleOperations.ListJobs 작업 일정과 연관된 작업 나열
PoolOperations.ListComputeNodes 풀에 컴퓨팅 노드 나열
PoolOperations.ListPools 계정에 풀 나열

select 문자열 매핑

  • Batch .NET 형식: Batch .NET API 형식.
  • REST API 엔터티: 이 열의 각 페이지에는 형식에 대한 REST API 속성 이름을 나열하는 하나 이상의 표가 들어 있습니다. 이러한 속성 이름은 select 문자열을 구성할 때 사용됩니다. ODATADetailLevel.SelectClause 문자열을 구성할 때 이와 동일한 속성 이름을 사용합니다.
Batch .NET 형식 REST API 엔터티
MSSQLSERVER에 대한 프로토콜 속성 인증서 정보 가져오기
CloudJob 작업 정보 가져오기
CloudJobSchedule 작업 일정 정보 가져오기
ComputeNode 노드 정보 가져오기
CloudPool 풀 정보 가져오기
CloudTask 작업 정보 가져오기

예: filter 문자열 구성

ODATADetailLevel.FilterClause에 대한 필터 문자열을 생성하려면 해당 REST API 페이지를 찾습니다. 선택 가능한 속성 및 지원되는 연산자는 첫 번째 다중 행 테이블에 있습니다. 예를 들어, 종료 코드가 0이 아닌 모든 태스크를 검색하려면 작업과 연결된 태스크 목록에서 적용 가능한 속성 문자열과 허용 가능한 연산자를 확인합니다.

속성 허용되는 연산 Type
executionInfo/exitCode eq, ge, gt, le , lt Int

관련 필터 문자열은 다음과 같습니다.

(executionInfo/exitCode lt 0) or (executionInfo/exitCode gt 0)

예: select 문자열 구성

ODATADetailLevel.SelectClause를 생성하려면 나열할 엔터티에 해당하는 REST API 페이지를 찾습니다. 선택 가능한 속성 및 지원되는 연산자는 첫 번째 다중 행 테이블에 있습니다. 예를 들어, 목록의 각 태스크에 대해 ID 및 명령줄만 검색하려면 태스크에 대한 정보 가져오기를 확인합니다.

속성 Type 주의
id String The ID of the task.
commandLine String The command line of the task.

관련된 select 문자열은 다음과 같습니다.

id, commandLine

코드 샘플

효율적인 목록 쿼리

EfficientListQueries 샘플 프로젝트는 효율적인 목록 쿼리가 애플리케이션 성능에 어떤 영향을 미치는지를 보여 줍니다. 이 C# 콘솔 애플리케이션은 많은 작업을 만들고 또 작업에 추가합니다. 그런 다음, 애플리케이션은 JobOperations.ListTasks 메서드를 여러 번 호출하고 ODATADetailLevel 개체를 전달합니다. 이러한 개체는 다양한 데이터 크기가 반환되도록 하기 위해 여러 다른 속성 값으로 구성됩니다. 이러한 샘플은 다음과 비슷한 출력을 생성합니다.

Adding 5000 tasks to job jobEffQuery...
5000 tasks added in 00:00:47.3467587, hit ENTER to query tasks...

4943 tasks retrieved in 00:00:04.3408081 (ExpandClause:  | FilterClause: state eq 'active' | SelectClause: id,state)
0 tasks retrieved in 00:00:00.2662920 (ExpandClause:  | FilterClause: state eq 'running' | SelectClause: id,state)
59 tasks retrieved in 00:00:00.3337760 (ExpandClause:  | FilterClause: state eq 'completed' | SelectClause: id,state)
5000 tasks retrieved in 00:00:04.1429881 (ExpandClause:  | FilterClause:  | SelectClause: id,state)
5000 tasks retrieved in 00:00:15.1016127 (ExpandClause:  | FilterClause:  | SelectClause: id,state,environmentSettings)
5000 tasks retrieved in 00:00:17.0548145 (ExpandClause: stats | FilterClause:  | SelectClause: )

Sample complete, hit ENTER to continue...

이 예제에서는 반환되는 항목 수와 속성을 제한하여 쿼리 응답 시간을 크게 낮출 수 있음을 보여 줍니다. 이 샘플 프로젝트와 다른 샘플 프로젝트가 GitHub의 azure-batch-samples 리포지토리에 있습니다.

BatchMetrics 라이브러리

다음 BatchMetrics 샘플 프로젝트는 배치 API를 사용하여 Azure Batch 작업 진행률을 효율적으로 모니터링하는 방법을 보여 줍니다.

이 샘플에는 자체 프로젝트에 통합할 수 있는 .NET 클래스 라이브러리 프로젝트가 포함되어 있습니다. 라이브러리 사용을 연습하고 시연하는 간단한 명령줄 프로그램도 있습니다.

프로젝트 내의 샘플 애플리케이션은 다음 작업을 보여 줍니다.

  • 필요한 속성에 대해서만 다운로드하기 위해 특정 특성 선택
  • 마지막 쿼리 이후에 변경 내용만 다운로드하기 위해 상태 전환 시간에서 필터링

예를 들어 다음 메서드는 BatchMetrics 라이브러리에 나타납니다. 쿼리되는 엔터티에 대해 id 및 state 속성만 가져와야 한다고 지정하는 ODATADetailLevel을 반환합니다. 또한 지정된 DateTime 매개 변수로 인해 상태가 변경된 엔터티만을 반환해야 한다고 지정합니다.

internal static ODATADetailLevel OnlyChangedAfter(DateTime time)
{
    return new ODATADetailLevel(
        selectClause: "id, state",
        filterClause: string.Format("stateTransitionTime gt DateTime'{0:o}'", time)
    );
}

다음 단계