طلب POST

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

ما هو طلب POST

تسمح طلبات POST المرسلة للواجهة البرمجية بإنشاء أو تعديل البيانات على الخادم، بدلاً من مجرد استرجاعها كما في طلب GET، عند إرسال الطلب للواجهة البرمجية نحتاج لتضمين عنوان URL لنقطة الوصول المطلوبة، وإرسال البيانات عبر جسم الطلب.

طلب POST لإنشاء فريق جديد

إذا كان لدينا مركز مساعدة على النطاق example.com، وأردنا إنشاء فريق جديد في هذا المركز ومنحه صلاحيات الوصول إلى بيانات جهات الاتصال وبيانات الشركات، سنرسل طلب POST لنقطة الوصول Create a team، يمكن إرسال هذا الطلب بعدة طرق.

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

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

curl [options...] <url>

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

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

فيما يلي طلب cURL لإنشاء فريق جديد في مركز المساعدة:

curl --header 'Content-Type: application/json' \
     --header 'Authorization: Bearer YOUR_API_KEY' \
     -X POST \
     --data '{
         "name": "فريق المبيعات",
         "status": "active",
         "description": "فريق المبيعات",
         "permissions": ["contact", "company"],
         "inbox_ids": [1010]
     }' \
     'https://example.com/api/agent/v1/teams'

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

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

1. بايثون

سنعتمد المكتبة requests لإرسال الطلب POST إلى واجهة زيتون البرمجية كما يلي:

import requests
url = "https://example.com/api/agent/v1/teams"
payload = {'name': 'team name',
'status': 'active', 'permissions[]': 'company',
'inbox_ids[]': '1010'
}
files=[
]
headers = {
  'Authorization': 'Bearer YOUR_API_KEY'}
response = requests.request("POST", url, headers=headers, data=payload, files=files)

2. Node.js

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

var request = require('request');
var options = {
  'method': 'POST',
  'url': 'https://example.com/api/agent/v1/teams',
  'headers': {
    'Authorization': 'Bearer YOUR_API_KEY'
}
 formData: {
    'name': 'team name',
    'description': 'team description',
    'status': 'active',
    'permissions[]': 'company',
    'inbox_ids[]': '1010'
  }
};
request(options, function (error, response) {
  if (error) throw new Error(error);
  console.log(response.body);
});

3. روبي

يمكنك استخدام المكتبة Net::HTTP لإرسال طلب POST إلى الواجهة البرمجية:

require "uri"
require "net/http"
url = URI("https://example.com/api/agent/v1/teams")
https = Net::HTTP.new(url.host, url.port)
https.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Authorization"] = "Bearer YOUR_API_KEY"
form_data = [['name', 'team name'],['description', 'team description'],['status', 'active'],['permissions[]', 'company'],['inbox_ids[]', '1010']]
request.set_form form_data, 'multipart/form-data'
response = https.request(request)
puts response.read_body

4. جافا

يمكنك استخدام المكتبة JAVA Unirest لإرسال الطلب POST للواجهة البرمجية كما يلي:

Unirest.setTimeouts(0, 0);
HttpResponse<String> response = Unirest.post("https://example.com/api/agent/v1/teams")
  .header("Authorization", "Bearer YOUR_API_KEY")
.multiPartContent()
  .field("name", "team name")
  .field("description", "team description")
  .field("status", "active")
  .field("permissions[]", "company")
  .field("inbox_ids[]", "1010")
  .asString();
HttpResponse<String> response = Unirest.post("https://example.com/api/agent/v1/teams")

5. PHP

يمكنك إرسال الطلبات إلى واجهة زيتون البرمجية بلغة PHP باستخدام cURL أو Guzzle أو HTTP_Request2 أو pecl_http. اخترنا هنا cURL لإرسال الطلب:

<?php
$curl = curl_init();
curl_setopt_array($curl, array(
  CURLOPT_URL => 'https://example.com/api/agent/v1/teams',
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => '',
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 0,
  CURLOPT_FOLLOWLOCATION => true,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => 'POST',
  CURLOPT_POSTFIELDS => array(
      'name' => 'team name',
      'status' => 'active',
      'description' => 'This is a description of the team',
      'permissions' => ['contact', 'company'],
      'inbox_ids' => [1010]
  ),
  CURLOPT_HTTPHEADER => array(
    'Authorization: Bearer YOUR_API_KEYd'
 ),
));
$response = curl_exec($curl);
curl_close($curl);
echo $response;