일괄 처리 쿼리

아티클
10/29/2024

Azure Monitor Log Analytics API는 쿼리를 한꺼번에 일괄 처리하도록 지원합니다. 일괄 처리 쿼리에는 현재 Microsoft Entra 인증이 필요합니다.

요청 형식

쿼리를 일괄 처리하려면 API 엔드포인트를 사용하여 https://api.loganalytics.azure.com/v1/$batch URL 끝에 $batch를 추가합니다.

메서드가 포함되어 있지 않으면 기본값을 GET 메서드로 일괄 처리합니다. GET 요청에서 API는 요청 개체의 본문 매개 변수를 무시합니다.

일괄 처리 요청에는 다른 작업에 대한 일반 헤더가 포함됩니다.

Content-Type: application/json
Authorization: Bearer <user token>

요청 본문은 다음 속성을 포함하는 개체의 배열입니다.

id
headers
body
method
path
workspace

예제:

POST https://api.loganalytics.azure.com/v1/$batch
Content-Type: application/json
Authorization: Bearer <user token>
Cache-Control: no-cache
{
    "requests": 
    [
        {
            "id": "1",
            "headers": {
                "Content-Type": "application/json"
            },
            "body": {
                "query": "AzureActivity | summarize count()",
                "timespan": "PT1H"
            },
            "method": "POST",
            "path": "/query",
            "workspace": "workspace-1"
        },
        {
            "id": "2",
            "headers": {
                "Content-Type": "application/json"
            },
            "body": {
                "query": "ApplicationInsights | limit 10",
                "timespan": "PT1H"
            },
            "method": "POST",
            "path": "/fakePath",
            "workspace": "workspace-2"
        }
    ]
}

응답 형식

응답 형식은 유사한 개체의 배열입니다. 각 개체는 다음 속성을 포함합니다.

ID
특정 쿼리의 HTTP 상태 코드
해당 쿼리에 대해 반환된 응답의 본문.

쿼리가 성공적으로 반환되지 않으면 응답 본문에 오류 메시지가 포함됩니다. 오류 메시지는 일괄 처리의 개별 쿼리에만 적용됩니다. 일괄 처리 자체는 멤버의 반환 값과 관계없이 상태 코드를 반환합니다. 일괄 처리가 다음과 같은 경우 일괄 처리가 성공적으로 반환됩니다.

잘 구성되고 적절한 형식이 지정된 경우
인증됨
권한 있음

멤버 쿼리의 결과가 성공과 실패의 혼합일 수 있는 경우에도 일괄 처리가 성공적으로 반환됩니다.

예제:

{
    "responses":
    [
        {
            "id": "2",
            "status": 404,
            "body": {
                "error": {
                    "message": "The requested path does not exist",
                    "code": "PathNotFoundError"
                }
            }
        },
        {
            "id": "1",
            "status": 200,
            "body": {
                "tables": [
                    {
                        "name": "PrimaryResult",
                        "columns": [
                            {
                                "name": "Count",
                                "type": "long"
                            }
                        ],
                        "rows": [
                            [
                                7240
                            ]
                        ]
                    }
                ]
            }
        }
    ]
}

동작 및 오류

반환된 개체 내의 응답 순서는 요청의 순서와 관련이 없습니다. 각 개별 쿼리를 완료하는 데 걸리는 시간이 결정됩니다. ID를 사용하여 쿼리 응답 개체를 원래 요청에 매핑합니다. 쿼리 응답이 순서대로 있다고 생각하지 마세요.

전체 일괄 처리 요청은 다음 경우에만 실패합니다.

외부 페이로드의 JSON 형식이 잘못되었습니다.
인증 실패: 사용자가 인증 토큰을 제공하지 않거나 토큰이 잘못되었습니다.
일괄 처리의 개별 요청 개체에는 필수 속성이 없거나 중복 ID가 있습니다.

이러한 조건에서 응답의 모양은 일반 컨테이너와 다릅니다. 일괄 처리 개체에 포함된 개체는 각각 실패하거나 독립적으로 성공할 수 있습니다. 다음 예제 오류를 참조하세요.

오류 예

이 목록은 가능한 오류의 예와 그 의미에 대한 비동기 목록입니다.

400 - 잘못된 형식의 요청입니다. 외부 요청 개체가 유효한 JSON이 아닙니다.

{
    "error": {
        "message": "The request had some invalid properties",
        "code": "BadArgumentError",
        "innererror": {
            "code": "QueryValidationError",
            "message": "Failed parsing the query",
            "details": [
                {
                    "code": "InvalidJsonBody",
                    "message": "Unexpected end of JSON input",
                    "target": null
                }
            ]
        }
    }
}

403 - 사용할 수 없습니다. 제공된 토큰은 액세스하려는 리소스에 액세스할 수 없습니다. 토큰 요청에 올바른 리소스가 있는지 확인하고 Microsoft Entra 애플리케이션에 대한 권한을 부여했는지 확인합니다.

{
    "error": {
        "message": "The provided authentication is not valid for this resource",
        "code": "InvalidTokenError",
        "innererror": {
            "code": "SignatureVerificationFailed",
            "message": "Could not validate the request"
        }
    }
}

204 - 없습니다. API가 백업 저장소에서 끌어올 데이터가 없습니다. 2xx 오류로, 기술적으로 성공한 요청입니다. 그러나 일괄 처리에서는 오류를 적어 두는 것이 유용합니다.

{
    "responses": [
        {
            "id": "2",
            "status": 204,
            "body": {
                "error": {
                    "code": "WorkspaceNotPlacedError"
                }
            }
        }
    ]
}

404 - 찾을 수 없습니다. 쿼리 경로가 없습니다. 개별 요청에서 잘못된 HTTP 메서드를 지정하는 경우에도 일괄 처리에서 이 오류가 발생할 수 있습니다.

{
    "responses": [
        {
            "id": "1",
            "status": 404,
            "body": {
                "error": {
                    "message": "The requested path does not exist",
                    "code": "PathNotFoundError"
                }
            }
        }
    ]
}

400 - 리소스를 확인하지 못했습니다. 작업 영역을 나타내는 GUID가 잘못되었습니다.

{
    "responses": [
        {
            "id": "1",
            "status": 400,
            "body": {
                "error": {
                    "code": "FailedToResolveResource",
                    "message": "Resource identity could not be resovled"
                }
            }
        }
    ]
}

다음을 통해 공유

일괄 처리 쿼리

요청 형식

응답 형식

동작 및 오류

오류 예

피드백

추가 리소스