Batch sorguları

Azure İzleyici Log Analytics API'si sorguları birlikte toplu olarak çalıştırmayı destekler. Batch sorguları şu anda Microsoft Entra kimlik doğrulaması gerektirir.

İstek biçimi

Sorguları toplu olarak oluşturmak için, URL'nin sonuna $batch ekleyerek API uç noktasını kullanın: https://api.loganalytics.azure.com/v1/$batch.

Hiçbir yöntem dahil değilse, toplu işlem varsayılan olarak GET yöntemine ayarlanır. GET isteklerinde API, istek nesnesinin gövde parametresini yoksayar.

Toplu iş isteği, diğer işlemler için normal üst bilgiler içerir:

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

İsteğin gövdesi, aşağıdaki özellikleri içeren bir nesne dizisidir:

• id
• headers
• body
• method
• path
• workspace

Örnek:

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"
        }
    ]
}

Yanıt biçimi

Yanıt biçimi benzer bir nesne dizisidir. Her nesnenin içeriği:

• Kimlik
• Belirli bir sorgunun HTTP durum kodu
• Bu sorgu için döndürülen yanıtın gövdesi.

Sorgu başarıyla döndürülmezse, yanıt gövdesi hata iletileri içerir. Hata iletileri yalnızca toplu iş içindeki tek tek sorgular için geçerlidir; toplu işleminin kendisi, üyelerinin dönüş değerlerinden bağımsız bir durum kodu döndürür. Toplu iş şu şekildeyse toplu işlem başarıyla döndürülüyor:

• İyi biçimlendirilmiş ve düzgün biçimlendirilmiş
• Kimliği doğrulandı
• Yetkili

Üye sorgularının sonuçları başarı ve başarısızlıkların bir karışımı olabilse bile toplu işlem başarıyla döndürülüyor.

Örnek:

{
    "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
                            ]
                        ]
                    }
                ]
            }
        }
    ]
}

Davranış ve hatalar

Döndürülen nesnenin içindeki yanıtların sırası istekteki sıralamayla ilgili değildir. Gereken süre, her bir sorgunun tamamlanmasını belirler. Sorgu yanıtı nesnelerini özgün isteklerle eşlemek için kimlikleri kullanın. Sorgu yanıtlarının sıralı olduğunu varsaymayın.

Toplu iş isteğinin tamamı yalnızca şu durumlarda başarısız olur:

• Dış yükün JSON biçimi geçerli değil.
• Kimlik doğrulaması başarısız oluyor: Kullanıcı kimlik doğrulama belirteci sağlamaz veya belirteç geçersiz.
• Toplu işteki tek tek istek nesnelerinin gerekli özellikleri yoktur veya yinelenen kimlikler vardır.

Bu koşullar altında, yanıtın şekli normal kapsayıcıdan farklıdır. Batch nesnesinin içinde yer alan nesnelerin her birinin başarısız olabileceği veya bağımsız olarak başarılı olabileceği durumlarda aşağıdaki örnek hatalara bakın.

Örnek hatalar

Bu liste, olası hatalara ve bunların anlamlarına yönelik örneklerin tükenmez bir listesidir.

• 400 - Hatalı biçimlendirilmiş istek. Dış istek nesnesi geçerli JSON değildi.

  {
      "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 - Yasak. Sağlanan belirtecin erişmeye çalıştığınız kaynağa erişimi yok. Belirteç isteğinizin doğru kaynağa sahip olduğundan ve Microsoft Entra uygulamanız için izinler verdiğinden emin olun.

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

• 204 - Yerleştirilmemiş. API'nin yedekleme deposunu çekmesi için veriniz yok. 2xx hatası olarak bu teknik olarak başarılı bir istektir. Ancak toplu işte hataya dikkat etmek yararlı olur.

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

• 404 - Bulunamadı. Sorgu yolu yok. Bu hata, tek tek istekte geçersiz bir HTTP yöntemi belirtirseniz toplu işlemde de oluşabilir.

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

• 400 - Kaynak çözümlenemedi. Çalışma alanını temsil eden GUID yanlış.

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