طلب POST

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

ما هو طلب POST

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

إنشاء فريق جديد

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

باستخدام cURL

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

curl [options...] <url>

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

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

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

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

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

سنستعرض صيغة الطلب 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;