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

يتم الآن عرض مستندات 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: المعاملات في الدقيقة

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

طلب بحث

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 بالتوقيت العالمي المُتّفق عليه/توقيت غرينيتش ويمكن أن تتضمّن أوقاتًا.

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