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

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

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

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

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

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

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

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

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

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

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

الحدود في Apigee Hybrid

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

كيفية إجراء طلب بحث غير متزامن في "إحصاءات 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)/توقيت غرينتش، ويمكن أن تتضمّن الأوقات.

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