Zapytania usługi Batch

Interfejs API usługi Log Analytics usługi Azure Monitor obsługuje łączenie zapytań wsadowych. Zapytania wsadowe wymagają obecnie uwierzytelniania firmy Microsoft Entra.

Format żądania

Aby przeprowadzić zapytania wsadowe, użyj punktu końcowego interfejsu API, dodając $batch na końcu adresu URL: https://api.loganalytics.azure.com/v1/$batch.

Jeśli metoda nie jest dołączona, wsadowanie wartości domyślnych do metody GET. W przypadku żądań GET interfejs API ignoruje parametr treści obiektu żądania.

Żądanie wsadowe zawiera regularne nagłówki dla innych operacji:

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

Treść żądania to tablica obiektów zawierających następujące właściwości:

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

Przykład:

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

Format odpowiedzi

Format odpowiedzi jest podobną tablicą obiektów. Każdy obiekt zawiera:

• Identyfikator
• Kod stanu HTTP określonego zapytania
• Treść zwróconej odpowiedzi dla tego zapytania.

Jeśli zapytanie nie zwróci się pomyślnie, treść odpowiedzi zawiera komunikaty o błędach. Komunikaty o błędach dotyczą tylko poszczególnych zapytań w partii; sama partia zwraca kod stanu niezależnie od zwracanych wartości jej elementów członkowskich. Partia zwraca powodzenie, jeśli partia to:

• Poprawnie sformułowane i poprawnie sformatowane
• Uwierzytelniono
• Uprawniony

Partia zwraca pomyślnie nawet wtedy, gdy wyniki zapytań składowych mogą być kombinacją sukcesów i niepowodzeń.

Przykład:

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

Zachowanie i błędy

Kolejność odpowiedzi wewnątrz zwróconego obiektu nie jest powiązana z kolejnością w żądaniu. Czas potrzebny na określenie poszczególnych zapytań do ukończenia. Użyj identyfikatorów, aby zamapować obiekty odpowiedzi zapytania na oryginalne żądania. Nie zakładaj, że odpowiedzi na zapytania są uporządkowane.

Całe żądanie wsadowe kończy się niepowodzeniem tylko wtedy, gdy:

• Format JSON zewnętrznego ładunku jest nieprawidłowy.
• Uwierzytelnianie kończy się niepowodzeniem: użytkownik nie udostępnia tokenu uwierzytelniania lub token jest nieprawidłowy.
• Pojedyncze obiekty żądań w partii nie mają wymaganych właściwości lub istnieją zduplikowane identyfikatory.

W tych warunkach kształt odpowiedzi różni się od normalnego kontenera. Obiekty zawarte w obiekcie wsadowym mogą niezależnie zakończyć się niepowodzeniem lub powodzeniem. Zobacz następujące przykładowe błędy.

Przykładowe błędy

Ta lista jest niewyczerpaną listą przykładów możliwych błędów i ich znaczenia.

• 400 — Źle sformułowane żądanie. Obiekt żądania zewnętrznego nie był prawidłowym kodem 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 — Dostęp zabroniony. Podany token nie ma dostępu do zasobu, do którego próbujesz uzyskać dostęp. Upewnij się, że żądanie tokenu ma prawidłowy zasób i masz przyznane uprawnienia dla aplikacji Firmy 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 — Nie umieszczono. Nie masz danych dla interfejsu API, aby ściągnąć magazyn kopii zapasowych. Jako błąd 2xx jest to technicznie pomyślne żądanie. Jednak w partii warto zauważyć błąd.

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

• 404 — Nie znaleziono. Ścieżka zapytania nie istnieje. Ten błąd może również wystąpić w partii, jeśli określisz nieprawidłową metodę HTTP w pojedynczym żądaniu.

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

• 400 — Nie można rozpoznać zasobu. Identyfikator GUID reprezentujący obszar roboczy jest niepoprawny.

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