طلب GET

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

ما هو طلب GET

تسمح طلبات GET المرسلة للواجهة البرمجية بجلب البيانات من الخادم دون تعديلها، عند إرسال هذا الطلب للواجهة البرمجية نحتاج لتضمين عنوان URL لنقطة الوصول المطلوبة، ونرسل المعاملات المطلوبة ضمن عنوان URL لتحديد البيانات المراد الحصول عليها.

طلب GET لعرض صناديق البريد

إذا كان لدينا مركز مساعدة على النطاق example.com، وأردنا عرض كافة صناديق البريد في هذا المركز التي لها الحالة active أو deleted، مع إظهارها بترتيب تنازلي تبعًا لحروف أسماء صناديق البريد، سنرسل طلب GET لنقطة الوصول List all inboxes، ويمكن إرسال هذا الطلب بعدة طرق:

إرسال الطلب باستخدام cURL

نكتب أوامر cURL وفق الصيغة العامة التالية:

curl [options...] <url>

نمرر في القسم options عدة خيارات مثل:

• header-- لتمرير معلومات إضافية في ترويسة الطلب، كمفتاح الواجهة، أو نوع المحتوى
• globoff-- لتعطيل ميزة globbing في حال تضمن عنوان الطلب أقواس مثل [] أو {}
• output-- لحفظ الاستجابة في ملف بدل عرضها على الشاشة

لنكتب طلب cURL للحصول على معلومات صناديق البريد:

curl \
--header "Authorization: Bearer YOUR_API_KEY" \
--header "Content-Type: application/json" \
--globoff \
 "https://example.com/api/agent/v1/inboxes?domain=example.com&statuses[]=active&statuses[]=deleted&sort=name.desc"

ننتبه لصحة كتابة معاملات الاستعلام، فأي خطأ إملائي كتبديل قيمة المعامل active إلى Active يعني أن الواجهة لن تعطينا الاستجابة المطلوبة.

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

{
  "data": [
    {   
      "id": "1010",
      "name": "الصندوق الوارد",
      "description": "الصندوق الوارد الرئيسي",
      "slug": "الصندوق-الوارد",
      "send_autoresponse": false,
      "autoresponse_text": "مرحباً بك، لقد تم استلام رسالتك وسيتم مراجعتها في أسرع وقت ممكن",
      "forward_email": "support@example.com",
      "conversations_count": null,
      ...
      ...
      ...
      "agents": [],
      "sort": 1,
      "type": "default",
      "status": "active",
      "send_rating_request": true,
      "rating_message": "تقييم تجربتك يساعدنا على تحسين مستوى الخدمة",
      "created_at": "2021-11-23T13:28:12+00:00",
      "updated_at": "2021-11-23T13:28:12+00:00"
    }
  ],
  "total_count": 2,
  "has_more": false
}

يدل المتغير المنطقي has_more في نهاية أسطر الاستجابة إن كان هناك بيانات إضافية متاحة للاسترجاع أم لا، فالقيمة false تعني أن جميع النتائج قد ظهرت في الاستجابة، والقيمة true تعني وجود نتائج إضافية لم تظهر في الاستجابة، يمكن تمرير معامل ترقيم الصفحات limit ضمن الطلب، وضبطه بقيمة مناسبة لعرض جميع النتائج، كما يمكن الاستعانة بقيمة total_count الظاهرة في الاستجابة لمعرفة القيمة الملائمة للمعامل limit.

إرسال الطلب باستخدام لغات البرمجة

سنستعرض صيغة الطلب GET لإجراء الاستعلام السابق لعرض صناديق البريد بأكثر من لغة برمجة

1. بايثون

تُستخدم المكتبة requests لإرسال طلبات HTTP بلغة بايثون إلى الواجهات البرمجية، وتُكتب طلبات GET بالصيغة التالية:

import requests
url = "https://example.com/api/agent/v1/inboxes?statuses[]=default&statuses[]=spam&sort=name.desc"
payload = {}
headers = {
'Authorization': 'Bearer YOUR_API_KEY'
}
response = requests.request("GET", url, headers=headers, data=payload)
print(response.text)

Node.js .2

يمكن استخدام عدة مكتبات لإرسال طلبات GET بواسطة Node.js نذكر منها Request و Unirest و Native و Axios، اخترنا في مثالنا التالي المكتبة Request:

var request = require('request');
var options = {
  'method': 'GET',
  'url': 'example.com/api/agent/v1/inboxes?statuses[]=default&statuses[]=spam&sort=name.desc',
  'headers': {
    'Authorization': 'Bearer YOUR_API_KEY'
      }
};
request(options, function (error, response) {
  if (error) throw new Error(error);
  console.log(response.body);
});

3. روبي

تعتمد لغة روبي المكتبة Ruby Net::HTTP للتعامل مع طلبات HTTP المرسلة للواجهات البرمجية، وهذا مثال على صيغة الطلب GET باستخدامها:

var request = require('request');
var options = {
  'method': 'GET',
  'url': 'https://example.com/api/agent/v1/inboxes?statuses[]=default&statuses[]=spam&sort=name.desc',
  'headers': {
    'Authorization': 'Bearer YOUR_API_KEY'
      }
};
request(options, function (error, response) {
  if (error) throw new Error(error);
  console.log(response.body);
});

4. جافا

توفر لغة جافا مكتبتين لإرسال طلبات HTTP هما Unirest و OkHttp، وقد استخدمنا المكتبة Unirest لكتابة المثال التالي:

Unirest.setTimeouts(0, 0);
HttpResponse<String> response = Unirest.get("https://example.com/api/agent/v1/inboxes?statuses[]=default&statuses[]=spam&sort=name.desc")
  .header("Authorization", "Bearer YOUR_API_KEY")
  .asString();

PHP .5

توفر PHP عدة أدوات للتعامل مع طلبات HTTP المرسلة للواجهات البرمجية، أبرزها المكتبة cURL والمكتبة Guzzle والحزمة HTTP_Request2 والإضافة pecl_http extension، اخترنا هنا المكتبة PHP cURL لكتابة الطلب:

<?php
$curl = curl_init();
curl_setopt_array($curl, array(
    CURLOPT_URL => 'example.com/api/agent/v1/inboxes?statuses[]=default&statuses[]=spam&sort=name.desc',
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_ENCODING => '',
    CURLOPT_MAXREDIRS => 10,
    CURLOPT_TIMEOUT => 0,
    CURLOPT_FOLLOWLOCATION => true,
    CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
    CURLOPT_CUSTOMREQUEST => 'GET',
    CURLOPT_HTTPHEADER => array(
        'Authorization: Bearer YOUR_API_KEY'
    ),
));
$response = curl_exec($curl);
curl_close($curl);
echo $response;