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

أنت الآن بصدد الاطّلاع على مستندات Apigee Edge.
انتقِل إلى مستندات Apigee X. info

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

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

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

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

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

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

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

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

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

الحدود في Apigee Hybrid

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

كيفية إجراء طلب بحث غير متزامن في "إحصاءات Google"

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

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، حدِّد المقاييس والسمات والفلاتر التي تحدّد التقرير.

في ما يلي مثال على ملف 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، يمكنك استخدام واجهة برمجة التطبيقات get results لاسترداد النتائج، حيث يكون معرّف طلب البحث 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، عليك النقر على الزر حفظ وتنزيل. في هذه الحالة، يتم تنزيل ملف 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"
}

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

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

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

في ما يلي وصف للخطوة 1، وهي إرسال طلب البحث.

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

لإرسال طلب بحث عن تقرير غير متزامن لتحقيق الربح، أرسِل طلب 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 بالتوقيت العالمي المتفق عليه (UTC) أو توقيت غرينتش (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