استفسارات الدُفعات

تدعم واجهة برمجة تطبيقات Azure Monitor Log Analytics إرسال الاستعلامات في دُفعات. تتطلب الاستعلامات الدفعية حاليا مصادقة Microsoft Entra.

تنسيق الطلب

لإرسال الاستعلامات في دفعات، استخدم نقطة نهاية واجهة برمجة التطبيقات، وإضافة $batch في نهاية عنوان URL: https://api.loganalytics.azure.com/v1/$batch.

في حال لم يتم يُدرج أي أسلوب، يتم إرسال الإعدادات الافتراضية في دفعات إلى أسلوب GET. في طلبات GET، تتجاهل واجهة برمجة التطبيقات معلمة النص الأساسي لعنصر الطلب.

يتضمن طلب الدفعة عناوينَ منتظمة للعمليات الأخرى:

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

تنسيق الاستجابة

تنسيق الاستجابة هو صفيف مُماثل من العناصر. مثال: يحتوي العنصر على:

• المعرّف
• التعليمات البرمجية لحالة بروتوكول 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
                            ]
                        ]
                    }
                ]
            }
        }
    ]
}

السلوك والأخطاء

لا يرتبط ترتيب الاستجابات داخل العنصر الذي تم إرجاعه بالترتيب في الطلب. يحدد الوقت المستغرق كل استعلام فردي لإكماله. استخدم المعرّف لتعيين عناصر استجابة الاستعلام للطلبات الأصلية. لا تفترض أن استجاباتِ الاستعلام بالترتيب.

لا يفشل طلب الدُفعة بالكامل إلا في حالة:

• عدم صلاحية تنسيق JSON للحمولة الخارجية.
• فشل المصادقة: لا يوفر المستخدم رمزًا مميزًا للمصادقة، أو الرمز المميز غير صالح.
• لا تحتوي كائنات الطلب الفردية في الدفعة على الخصائص المطلوبة، أو هناك معرفات مكررة.

في ظل هذه الظروف، يختلف شكل الاستجابة عن الحاوية العادية. قد تفشل الكائنات الموجودة داخل كائن الدفعة أو تنجح بشكل مستقل، راجع المثال التالي من الأخطاء.

أمثله علي أخطاء

هذه القائمة هي قائمة غير هائمة من الأمثلة على الأخطاء المحتملة ومعانيها.

• 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 - لم يُوضع. ليس لديك بيانات لواجهة برمجة التطبيقاتِ لسحبها في مخزن النسخ الاحتياطي. كخطأ 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 - فشل حل المورد. المعرف الفريد العمومي الذي يمثل مساحة العمل غير صحيح.

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