استخدام واجهة برمجة التطبيقات والتقارير غير المتزامنة

يتم الآن عرض مستندات Apigee Edge.
انتقِل إلى مستندات Apigee X. معلومات

توفر Edge Analytics مجموعة غنية من لوحات البيانات التفاعلية وأدوات إنشاء التقارير المخصصة والإمكانيات ذات الصلة. ومع ذلك، يُقصَد أن تكون هذه الميزات تفاعلية: يجب إرسال طلب لواجهة برمجة التطبيقات أو واجهة المستخدم ويتم حظر الطلب إلى أن يقدم خادم الإحصاءات ردًّا عليه.

ومع ذلك، يمكن أن تنتهي مهلة طلبات الإحصاءات إذا استغرق اكتمالها وقتًا طويلاً جدًا. إذا كان طلب الاستعلام يحتاج إلى معالجة كمية كبيرة من البيانات (على سبيل المثال، 100 من غيغابايت)، فقد تفشل بسبب انتهاء المهلة.

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

• تحليل وإنشاء التقارير التي تمتد لفترات زمنية كبيرة.
• تحليل البيانات باستخدام مجموعة متنوعة من سمات التجميع والقيود الأخرى التي تزيد من تعقيد طلب البحث.
• إدارة طلبات البحث عندما تجد أن أحجام البيانات قد زادت بشكل كبير لبعض المستخدمين أو المؤسسات.

يصف هذا المستند كيفية إجراء طلبات بحث غير متزامنة باستخدام واجهة برمجة التطبيقات. يمكنك أيضًا استخدام واجهة المستخدم، كما هو موضح في تشغيل تقرير مخصص.

مقارنة واجهة برمجة التطبيقات لإعداد التقارير بواجهة المستخدم

إنشاء تقارير مخصّصة وإدارتها توضّح كيفية استخدام واجهة مستخدم Edge لإنشاء تقارير مخصّصة وتشغيلها. يمكنك تشغيل هذه التقارير بشكل متزامن أو غير متزامن.

وتسري معظم المفاهيم المتعلقة بإنشاء تقارير مخصّصة من خلال واجهة المستخدم على استخدام واجهة برمجة التطبيقات. ويعني ذلك أنّه عند إنشاء تقارير مخصّصة باستخدام واجهة برمجة التطبيقات، عليك تحديد metrics والسمات والفلاتر المضمّنة في Edge، وأي مقاييس مخصّصة أنشأتها باستخدام سياسة StatisticsCollector.

تكمن الاختلافات الرئيسية بين التقارير التي تم إنشاؤها في واجهة المستخدم وواجهة برمجة التطبيقات في أنّ التقارير التي يتم إنشاؤها باستخدام واجهة برمجة التطبيقات تتم كتابتها في ملفات بتنسيق CSV أو JSON (محدّدة بسطور جديدة) بدلاً من تقرير مرئي يتم عرضه في واجهة المستخدم.

الحدود القصوى المسموح بها في نظام Apigee المختلط

يفرض نظام Apigee المختلط بحد أقصى قدره 30 ميغابايت على مجموعة بيانات النتائج.

كيفية إنشاء طلب بحث غير متزامن عن الإحصاءات

يتم إجراء طلبات بحث غير متزامنة عن الإحصاءات في ثلاث خطوات:

1. أرسِل طلب البحث.

2. اطّلِع على حالة طلب البحث.

3. استرجع نتائج طلب البحث.

الخطوة 1. إرسال طلب البحث

يجب إرسال طلب POST إلى واجهة برمجة التطبيقات /queries. تطلب واجهة برمجة التطبيقات هذه من Edge معالجة طلبك في الخلفية. إذا نجح إرسال الاستعلام، فإن واجهة برمجة التطبيقات تعرض الحالة 201 ومعرفًا ستستخدمه للإشارة إلى الاستعلام في الخطوات اللاحقة.

مثلاً:

curl -X POST -H "Content-Type:application/json"
https://api.enterprise.apigee.com/v1/organizations/myorg/environments/myenv/queries -d @json-query-file
-u orgAdminEmail:password

نص الطلب هو وصف JSON لطلب البحث. في نص JSON، حدِّد metrics والسمات والفلاتر التي تحدّد التقرير.

في ما يلي مثال على ملف json-query-file:

{ 
   "metrics":  [
     {
         "name": "message_count",
         "function": "sum",
         "alias": "sum_txn"
    }
        ],
    "dimensions": ["apiproxy"],
    "timeRange": "last24hours",
    "limit": 14400,
    "filter":"(message_count ge 0)"         
}

يمكنك الاطّلاع على القسم لمحة عن نص الطلب أدناه للحصول على وصف كامل لبنية نص الطلب.

نموذج إجابة:

لاحظ أن معرف طلب البحث 9cfc0d85-0f30-46d6-ae6f-318d0cb961bd يتم تضمينه في الإجابة. بالإضافة إلى حالة HTTP 201، تعني state لـ enqueued أن الطلب نجح.

HTTP/1.1 201 Created

{  
  "self":"/organizations/myorg/environments/myenv/queries/9cfc0d85-0f30-46d6-ae6f-318d0cb961bd",
  "created":"2018-05-10T07:11:10Z",
  "state":"enqueued",
  "error":"false",
}

الخطوة 2. التعرُّف على حالة طلب البحث

يمكنك إجراء استدعاء باستخدام GET لطلب حالة الطلب. أنت تقدم معرف الاستعلام الذي تم عرضه من استدعاء POST. مثلاً:

curl -X GET -H "Content-Type:application/json"
https://api.enterprise.apigee.com/v1/organizations/myorg/environments/myenv/queries/9cfc0d85-0f30-46d6-ae6f-318d0cb961bd
-u email:password

نماذج الإجابات:

إذا كان طلب البحث لا يزال قيد التقدم، ستتلقى ردًا مثل هذا، حيث تكون قيمة state running:

{
    "self": "/organizations/myorg/environments/myenv/queries/1577884c-4f48-4735-9728-5da4b05876ab",
    "state": "running",
    "created": "2018-02-23T14:07:27Z",
    "updated": "2018-02-23T14:07:54Z"
}

بعد إكمال الاستعلام بنجاح، سيظهر لك رد مثل هذا، حيث يتم ضبط state على completed:

{
      "self": "/organizations/myorg/environments/myenv/queries/9cfc0d85-0f30-46d6-ae6f-318d0cb961bd",
      "state": "completed",
      "result": {
        "self": "/organizations/myorg/environments/myenv/queries/9cfc0d85-0f30-46d6-ae6f-318d0cb961bd/result",
        "expires": "2017-05-22T14:56:31Z"
      },
      "resultRows": 1,
      "resultFileSize": "922KB",
      "executionTime": "11 sec",
      "created": "2018-05-10T07:11:10Z",
      "updated": "2018-05-10T07:13:22Z"
}

الخطوة 3. استرداد نتائج طلب البحث

بعد أن تكون حالة طلب البحث هي completed، يمكنك استخدام واجهة برمجة التطبيقات الحصول على النتائج لاسترداد النتائج، حيث يكون معرّف طلب البحث 9cfc0d85-0f30-46d6-ae6f-318d0cb961bd مرة أخرى.

curl -X GET -H "Content-Type:application/json" -O -J https://api.enterprise.apigee.com/v1/organizations/myorg/environments/myenv/queries/9cfc0d85-0f30-46d6-ae6f-318d0cb961bd/result
-u email:password

لاسترداد الملف الذي تم تنزيله، يتعين عليك تهيئة الأداة التي تستخدمها بحيث تحفظ الملف الذي تم تنزيله على نظامك. مثلاً:

• إذا كنت تستخدم cURL، يمكنك استخدام خيارات -O -J كما هو موضّح أعلاه.

• إذا كنت تستخدم Postman، ستحتاج إلى تحديد الزر Save and Download (حفظ وتنزيل). في هذه الحالة، يتم تنزيل ملف ZIP باسم response.

• إذا كنت تستخدم متصفّح Chrome، يتم قبول عملية التنزيل تلقائيًا.

إذا نجح الطلب وكانت هناك مجموعة نتائج بقيمة غير صفرية، يتم تنزيل النتيجة إلى العميل كملف JSON مضغوط (محدّد بفواصل جديدة). سيكون اسم الملف الذي تم تنزيله:

OfflineQueryResult-<query-id>.zip

مثلاً:

OfflineQueryResult-9cfc0d85-0f30-46d6-ae6f-318d0cb961bd.zip

يحتوي ملف ZIP على ملف أرشيف .gz لنتائج JSON. للوصول إلى ملف JSON، يُرجى فك ضغط ملف التنزيل، ثم استخدام الأمر gzip لاستخراج ملف JSON:

unzip OfflineQueryResult-9cfc0d85-0f30-46d6-ae6f-318d0cb961bd.zip
gzip -d QueryResult-9cfc0d85-0f30-46d6-ae6f-318d0cb961bd-000000000000.json.gz

لمحة عن نص الطلب

يوضّح هذا القسم كل معلّمة يمكنك استخدامها في نص طلب JSON لطلب بحث. لمعرفة تفاصيل عن المقاييس والسمات التي يمكنك استخدامها في طلب البحث، يُرجى الاطّلاع على مرجع "إحصاءات Google".

{  
   "metrics":[  
      {  
        "name":"metric_name",
        "function":"aggregation_function",
        "alias":"metric_dispaly_name_in_results",
        "operator":"post_processing_operator",
        "value":"post_processing_operand"
      },
   ...
   ],
   "dimensions":[  
      "dimension_name",
      ...
   ],
   "timeRange":"time_range",
   "limit":results_limit,
   "filter":"filter",
   "groupByTimeUnit": "grouping",
   "outputFormat": "format",
   "csvDelimiter": "delimiter"
}

"metrics":[  
  {  
    "name":"response_processing_latency",
    "function":"avg",
    "alias":"average_response_time_in_seconds",
    "operator":"/",
    "value":"1000"
  }
]

"timeRange": {
    "start": "2018-07-29T00:13:00Z",
    "end": "2018-08-01T00:18:00Z"
}

بنية تعبير الفلتر

يصف هذا القسم المرجعي الرموز المميّزة التي يمكنك استخدامها لإنشاء تعبيرات فلاتر في نص الطلب. على سبيل المثال، يستخدم التعبير التالي الرمز المميز "ge" (أكبر من أو يساوي):

"filter":"(message_count ge 0)"

(apiproxy in 'ethorapi','weather-api')

(apiproxy in 'ethorapi')

(apiproxy in 'Search','ViewItem')

(response_status_code in 400,401,500,501)

(response_status_code notin 400,401,500,501)

(response_status_code eq 504)

(apiproxy eq 'non-prod')

(response_status_code ne 500)

(apiproxy ne 'non-prod')

(response_status_code gt 500)

(response_status_code lt 500)

(target_response_code ge 400)

(target_response_code le 300)

(apiproxy like '%buy%')

(apiproxy like '%item')

(apiproxy like 'Prod%')

(apiproxy not like '%buy%')

(apiproxy not like '%item')

(apiproxy not like 'Prod%')

(target_response_code gt 399) and (response_status_code ge 400)

(response_size ge 1000) or (response_status_code eq 500)

القيود والإعدادات التلقائية

في ما يلي قائمة بالقيود والإعدادات الافتراضية لميزة معالجة طلبات البحث غير المتزامنة.

لمحة عن نتائج طلب البحث

في ما يلي مثال على نتيجة بتنسيق JSON. يتكوّن الناتج من صفوف JSON مفصولة بمحدِّد سطر جديد:

{"message_count":"10209","apiproxy":"guest-auth-v3","hour":"2018-08-07 19:26:00 UTC"}
{"message_count":"2462","apiproxy":"carts-v2","hour":"2018-08-06 13:16:00 UTC"}    
…

ويمكنك استرجاع النتائج من عنوان URL حتى تاريخ انتهاء صلاحية البيانات في المستودع. يُرجى الاطّلاع على القيود والإعدادات التلقائية.

أمثلة

المثال 1: مجموع أعداد الرسائل

طلب بحث للحصول على مجموع أعداد الرسائل خلال آخر 60 دقيقة

طلب بحث

curl -X POST -H "Content-Type: application/json" -H "Accept: application/json"
https://api.enterprise.apigee.com/v1/organizations/myorg/environments/test/queries"
-d @last60minutes.json
-u orgAdminEmail:password

نص الطلب من last60minutes.json

{  
   "metrics":[  
      {  
         "name":"message_count",
         "function":"sum"
      }
   ],
   "dimensions":[  
      "apiproxy"
   ],
   "groupByTimeUnit":"minute",
   "limit":1000,
   "timeRange":"last60minutes"
}

المثال 2: نطاق زمني مخصّص

طلب بحث باستخدام نطاق زمني مخصص

طلب بحث

curl -X POST -H "Content-Type: application/json" -H "Accept: application/json"
https://api.enterprise.apigee.com/v1 /organizations/myorg/environments/test/queries"
-d @last60minutes.json
-u orgAdminEmail:password

نص الطلب من last60minutes.json

{  
   "metrics":[  
      {  
         "name":"message_count",
         "function":"sum"
      },
      {  
         "name":"total_response_time",
         "function":"avg",
         "alias":"average_response_time"
      }
   ],
   "dimensions":[  
      "apiproxy"
   ],
   "groupByTimeUnit":"minute",
   "limit":1000,
   "timeRange":{  
      "start":"2018-11-01T11:00:00Z",
      "end":"2018-11-30T11:00:00Z"
   }
}

المثال 3: المعاملات في الدقيقة

طلب بحث عن المقياس للمعاملات في الدقيقة (tpm).

طلب بحث

curl -X POST -H "Content-Type: application/json" -H "Accept: application/json"
https://api.enterprise.apigee.com/v1/organizations/myorg/environments/test/queries"
-d @tpm.json
-u orgAdminEmail:password

نص الطلب من tpm.json

{  
   "metrics":[  
      {  
         "name":"tpm"
      }
   ],
   "dimensions":[  
      "apiproxy"
   ],
   "groupByTimeUnit":"minute",
   "limit":1000,
   "timeRange":{  
      "start":"2018-07-01T11:00:00Z",
      "end":"2018-07-30T11:00:00Z"
   }
}

نموذج نتيجة

مقتطف من ملف النتائج:

{"tpm":149995.0,"apiproxy":"proxy_1","minute":"2018-07-06 12:16:00 UTC"}
{"tpm":149998.0,"apiproxy":"proxy_1","minute":"2018-07-09 15:12:00 UTC"}
{"tpm":3.0,"apiproxy":"proxy_2","minute":"2018-07-11 16:18:00 UTC"}
{"tpm":148916.0,"apiproxy":"proxy_1","minute":"2018-07-15 17:14:00 UTC"}
{"tpm":150002.0,"apiproxy":"proxy_1","minute":"2018-07-18 18:11:00 UTC"}
...

المثال 4: استخدام تعبير فلتر

طلب بحث باستخدام تعبير فلتر يستخدم عامل تشغيل منطقي.

طلب بحث

curl -X POST -H "Content-Type:application/json"
https://api.enterprise.apigee.com/v1/organizations/myorg/environments/test/queries"
-d @filterCombo.json
-u orgAdminEmail:password

نص الطلب من filterCombo.json

{  
   "metrics":[  
      {  
         "name":"message_count",
         "function":"sum"
      },
      {  
         "name":"total_response_time",
         "function":"avg",
         "alias":"average_response_time"
      }
   ],
   "filter":"(apiproxy ne \u0027proxy_1\u0027) and (apiproxy ne \u0027proxy_2\u0027)",
   "dimensions":[  
      "apiproxy"
   ],
   "groupByTimeUnit":"minute",
   "limit":1000,
   "timeRange":{  
      "start":"2018-11-01T11:00:00Z",
      "end":"2018-11-30T11:00:00Z"
   }
}

المثال 5: تمرير التعبير في معلمة المقاييس

طلب بحث يحتوي على تعبير يتم تمريره كجزء من مَعلمة المقاييس. يمكنك استخدام تعبيرات بسيطة ذات عامل واحد فقط.

طلب بحث

curl -X POST -H "Content-Type:application/json"
https://api.enterprise.apigee.com/v1/organizations/myorg/environments/test/queries" 
-d @metricsExpression.json
-u orgAdminEmail:password

نص الطلب من MetricsExpression.json

{  
   "metrics":[  
      {  
         "name":"message_count",
         "function":"sum",
         "operator":"/",
         "value":"7"
      }
   ],
   "dimensions":[  
      "apiproxy"
   ],
   "groupByTimeUnit":"minute",
   "limit":10,
   "timeRange":"last60minutes"
}

كيفية إنشاء طلب بحث عن تقرير تحقيق الربح غير المتزامن

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

كما هو الحال مع طلبات البحث غير المتزامنة في الإحصاءات، يمكنك إجراء طلبات بحث غير متزامنة عن تقرير تحقيق الربح باتّباع ثلاث خطوات: (1) إرسال طلب البحث و(2) الحصول على حالة طلب البحث و (3) استرداد نتائج طلب البحث.

يتم توضيح الخطوة الأولى أدناه، وهي إرسال طلب البحث.

الخطوتان 2 و3 هي نفسها الخطوات نفسها المتعلقة بطلبات بحث الإحصاءات غير المتزامنة. ولمزيد من المعلومات، اطّلِع على المقالة كيفية إجراء طلب بحث غير متزامن عن الإحصاءات.

لإرسال طلب بشأن تقرير تحقيق الربح غير المتزامن، يُرجى إصدار طلب POST إلى /mint/organizations/org_id/async-reports.

يمكنك اختياريًا تحديد البيئة من خلال تمرير مَعلمة طلب البحث environment. إذا لم يتم تحديد ذلك، سيتم ضبط مَعلمة طلب البحث تلقائيًا على prod. مثلاً:

/mint/organizations/org_id/async-reports?environment=prod

في نص الطلب، حدِّد معايير البحث التالية.

"devCriteria":[{
    "id":"RtHAeZ6LtkSbEH56",
    "orgId":"my_org"}
]

على سبيل المثال، ينشئ الطلب التالي تقريرًا لتحقيق الربح غير المتزامن لشهر حزيران (يونيو) 2017 لمنتج واجهة برمجة التطبيقات والرقم التعريفي للمطوِّر المحدّد. يتم الإبلاغ عن تواريخ وأوقات fromDate وtoDate بالتوقيت العالمي المنسّق/GMT ويمكن أن تتضمن أوقاتًا.

curl -H "Content-Type:application/json" -X POST -d \
'{
      "fromDate":"2017-06-01 00:00:00",
      "toDate":"2017-06-30 00:00:00",    
     "productIds": [
        "a_product"
    ],
    "devCriteria": [{
        "id": "AbstTzpnZZMEDwjc",
        "orgId": "myorg"
    }]

 }' \
"https://api.enterprise.apigee.com/v1/mint/organizations/myorg/async-reports?environment=prod" \
-u orgAdminEmail:password