ارتباط و احراز هویت

• احرازهویت و ارتباط با سرویس
• روش احرازهویت جهت ارتباط پایدار و امن
• دریافت توکن ارتباطی (دستی و خودکار)
• سربرگ – Header
• پاسخ صحیح – Response True
• پاسخ نادرست – Response False
• ساخت توکن ارتباطی JWT
• PHP (با استفاده از کتابخانه firebase/php-jwt)
• Python (با استفاده از کتابخانه PyJWT)
• JavaScript (با استفاده از کتابخانه jsonwebtoken)
• Node.js (با استفاده از کتابخانه jsonwebtoken)
• Java (با استفاده از کتابخانه java-jwt)
• مدیریت خطاها – Error handling
• مقدمه ای بر Error Handling
• نحوه نگارش خطاها
• Status Code – کدهای وضعیتی درخواست ها
• خطاهایی که در قالب Response دریافت میشود
• دریافت جزئیات خطا از طریق API
• سربرگ – Header
• مقادیر ارسالی – Request Data
• پاسخ صحیح – Response True
• پاسخ نادرست – Response False
• گرفتن IP آدرس هاست و ارتباطی – Get IP
• دریافت از طریق API
• سربرگ – Header
• مقادیر ارسالی – Request Data
• پاسخ صحیح – Response True
• پاسخ نادرست – Response False
• ساخت لینک – Deep Link (بزودی)
• بزودی…

احرازهویت و ارتباط با سرویس

روش احرازهویت جهت ارتباط پایدار و امن

ارتباط احراز هویت درخواست کننده ها در سامانه ایرپلاس در دو مرحله انجام میشود

مرحله اول دریافت توکن اختصاصی و مدت دار که جهت رمزنگاری بسته ها و بازگشایی توسط هسته مرکزی استفاده میشود که در بخش “دریافت توکن ارتباطی (دستی و خودکار)” انجام میگردد.

مرحله دوم شامل تولید توکن JWT با استفاده از اطلاعات درخواست کننده و توکن دریافت شده در مرحله اول انجام میگردد که در بخش “ساخت توکن ارتباطی JWT“

دریافت توکن ارتباطی (دستی و خودکار)

جهت دریافت توکن سازمانی شما از دو روش میتوانید اقدام نمائید.

روش اول: روش دستی – اخذ از طریق پنل کاربری

در این روش شما میتوانید با مراجعه به بخش میز مدیریتی > توکن اتصال و گزینه ساخت توکن اقدام به دریافت توکن نمائید.

توجه داشته باشید که توکن های دریافتی در بازه زمانی های 1 روزه، 1هفته، 15روزه، 1 ماهه و 3 ماهه عرضه میگردد که همراه با توکن تاریخ انقضأ آن درج خواهد شد شما در هر زمان میتوانید توکن خود را دوباره تولید نمائید و توکن قبلی را منقضی نمائید.

روش دوم: دریافت از طریق API

سربرگ – Header

روش دوم: دریافت از طریق API

در این روش شما باید درخواست خود را از طریق لینک زیر ارسال فرمائید.

{{Api Url}}/token

HEADER
GET /api/reservation/{{Api version}}/token HTTP/1.1
Host: {{Your Host}}
Content-Type: application/json
Domain: {{Your Domain}}

API Url از طریق پنل کاربری قابل مشاهده خواهد بود

پاسخ صحیح – Response True

دریافت این پاسخ با Status Code 200 دریافت خواهد شد.

{
    "payload": {
        "token": "64 character token received",
        "expiration": "Expiration date and time - Gregorian calendar ISO8601"
    },
    "meta": {
        "timestamp": "Timestamp" // Timestamp
    }
}

پاسخ نادرست – Response False

{
  "error": {
    "code":"Error Code"
  },
  "meta": {
    "timestamp": "Timestamp" // Timestamp
  }
}

در صورت مشاهده Status Code 404 URL درخواست خود را به اشتباه وارد نموده اید.

ساخت توکن ارتباطی JWT

JWT در واقع یک توکن امنیتی است که بر پایه فرمت JSON ساخته شده است. این توکن حاوی اطلاعات ضروری کاربر مانند شناسه کاربری، نقش‌ها و سطح دسترسی اوست. جی دبلیو تی به سه بخش سربرگ (Header)، بار (Payload) و امضا (Signature) تقسیم می‌شود. سربرگ شامل الگوریتم امضا و نوع توکن است. بار، اطلاعات کاربر را به صورت JSON در خود جای داده و امضا تضمین‌کننده صحت و درستی اطلاعات است.

JWT چگونه کار میکند؟

فرآیند کار JWT به شرح زیر است:

درخواست ورود

کاربر با وارد کردن نام کاربری و رمز عبور خود در مرحله قبل اقدام به دریافت توکن نموده است. و هسته مرکزی با توجه به اطلاعات اراسلی و دسترسی های مجاز کاربر اثدام به تولید توکن میکند.

تولید توکن JWT توسط درخواست کننده

درخواست کننده باید در این مرحله با توجه به اطلاعات زیر توکن JWT خود را ایجاد نموده و بعنوان کلید دسترسی جهت ارتباط با هسته مرکزی در HEADER درخواست های خود آن را ارسال نماید.

اعتبارسنجی توکن JWT

در درخواست‌های بعدی، سرور توکن JWT را دریافت کرده و اعتبار آن را بررسی می‌کند. در صورتیکه توکن معتبر باشد، به کاربر اجازه دسترسی به منابع داده می‌شود.

در حال حاضر اعتبار توکن های JWT بمدت 7 روز می باشد. که البته این موضوع بسته به توکن تولید شده در مرحله اول هم دارد در صورتی که توکن تولید شده در مرحله اول اعتباری کمتر از 7 روز داشته باشد انقضأ توکن JWT به همان میزان در نظر گرفته خواهد شد.

ساختار JSON Web Token چگونه است؟

ساختار JWT به سه بخش تقسیم می‌شود که با . (dot) از هم جدا می‌شوند:

• Header
• Payload
• Signature

و ساختاری شبیه به xxxxx.yyyyy.zzzzz

Header چیست؟

Header از دو بخش تشکیل شده است که بخش اول الگوریتم آن را تعیین می‌کند و بخش دوم نوع آن را مشخص می‌کند، که طبیعتاََ JWT است.

این ساختار JSON با Base64Url رمز گذاری شده است تا به بخش اول آن شکل بدهد، منظور از بخش اول xxxxx.yyyyy.zzzzz است.

برای مثال:  

{
    "alg": "HS256",
    "typ": "JWT"
}

{
    "iss": "Your domain",
    "aud": "Your level",
    "iat": "Timestamp",
    "uuid": "Your ID",
    "uip": "Your IP"
}

HMACSHA256(base64UrlEncode(header) + "." + base64UrlEncode(payload),token)

PHP (با استفاده از کتابخانه firebase/php-jwt)

جهت سهولت در کار با توکن های JWT چند نمونه کد از زبان های مختلف برای شما آماده شده است

<?php
require 'vendor/autoload.php';
use \Firebase\JWT\JWT;

$key = "your_secret_key";
$header = [
    "alg" => "HS256",
    "typ" => "JWT"
];
$payload = [
    "iss" => "Your domain",
    "aud" => "Your level",
    "iat" => time(),
    "uuid" => "Your ID",
    "uip" => "Your IP"
];

$jwt = JWT::encode($payload, $key, 'HS256');
echo $jwt;
?>

Python (با استفاده از کتابخانه PyJWT)

import jwt
import time

key = "your_secret_key"
header = {
    "alg": "HS256",
    "typ": "JWT"
}
payload = {
    "iss": "Your domain",
    "aud": "Your level",
    "iat": int(time.time()),
    "uuid": "Your ID",
    "uip": "Your IP"
}

token = jwt.encode(payload, key, algorithm='HS256', headers=header)
print(token)

JavaScript (با استفاده از کتابخانه jsonwebtoken)

const jwt = require('jsonwebtoken');

const key = "your_secret_key";
const header = {
    "alg": "HS256",
    "typ": "JWT"
};
const payload = {
    "iss": "Your domain",
    "aud": "Your level",
    "iat": Math.floor(Date.now() / 1000),
    "uuid": "Your ID",
    "uip": "Your IP"
};

const token = jwt.sign(payload, key, { algorithm: 'HS256', header: header });
console.log(token);

Node.js (با استفاده از کتابخانه jsonwebtoken)

const jwt = require('jsonwebtoken');

const key = "your_secret_key";
const header = {
    "alg": "HS256",
    "typ": "JWT"
};
const payload = {
    "iss": "Your domain",
    "aud": "Your level",
    "iat": Math.floor(Date.now() / 1000),
    "uuid": "Your ID",
    "uip": "Your IP"
};

const token = jwt.sign(payload, key, { algorithm: 'HS256', header: header });
console.log(token);

Java (با استفاده از کتابخانه java-jwt)

import com.auth0.jwt.JWT;
import com.auth0.jwt.algorithms.Algorithm;

import java.util.Date;

public class Main {
    public static void main(String[] args) {
        String key = "your_secret_key";
        Algorithm algorithm = Algorithm.HMAC256(key);

        String token = JWT.create()
                .withIssuer("Your domain")
                .withAudience("Your level")
                .withIssuedAt(new Date())
                .withClaim("uuid", "Your ID")
                .withClaim("uip", "Your IP")
                .sign(algorithm);

        System.out.println(token);
    }
}

مدیریت خطاها – Error handling

مقدمه ای بر Error Handling

قبل از هر چیز لازم است بدانیم مدیریت خطا یا error handling به چه معناست. این اصطلاح به واکنش و مکانیسم‌های بازیابی نرم‌افزار در صورت بروز خطا اشاره می‌کند. به عبارت دیگر این کار فرآیندی است که شامل پیش‌بینی دقیق، شناسایی و رفع خطاها در برنامه‌ها است.

اجرای منظم یک برنامه از طریق مدیریت خطا آسان‌تر است. وقتی صحبت از رویکردهای خطا handling می‌شود، بسیاری از برنامه‌ها با مشکلات معماری نرم‌افزار مواجه می‌شوند.

توجه داشته باشید که API AirPlus کامل منطق بر اصول RESTful API نوشته شده است پس بنابراین پاسخ تمام درخواست ها با Status Code مورد نظر خود ارسال خواهد شد و مدیریت این Status Code ها یا هما کدهای وضعیتی در برنامه شما الزامیست.

طبق اصول کلی تمام پاسخ های صحیح با کد وضعیتی 200 ارسال خواهند شد.

اما اتوماسیون ایرپلاس در زمینه مدیریت خطاها هم مستندات جامع و کاربردی را تهیه نموده است.

نحوه نگارش خطاها

پاسخ نادرست – Response False یا همان مشکل در ارسال اطلاعات

{
    "status": false,
    "time": "Timestamp", // Timestamp
    "code": "Error Code"
}

Status Code – کدهای وضعیتی درخواست ها

وضعیت 200

کد وضعیت 200 OK نشان می‌دهد که سرور درخواست ارسال‌شده را به‌درستی دریافت و پردازش کرده و پاسخ مورد انتظار را بدون هیچ‌گونه خطا بازگردانده است. به‌ عبارت‌ دیگر، زمانی که مرورگر با کد 200 مواجه می‌شود، یعنی صفحهٔ وب یا منبع درخواست‌شده به‌درستی بارگذاری شده است. شما با مواجه شدن با وضعیت 200 بدون هیچ مشکلی میتوانید دیتاهای مورد نظر خود را استخراج نمائید و به فرایند خود ادامه دهید.

وضعیت 201

کد 201 به معنای موفقیت در ایجاد یک منبع جدید در وب توسط وب‌سرور استفاده می‌شود. این کد وضعیت نشان‌دهنده این است که وب‌سرور با موفقیت درخواست POST (ایجاد منبع) یا PUT (به‌روزرسانی منبع) را پردازش کرده و یک منبع جدید ایجاد کرده است. این منبع معمولاً با یک URI (شناسه منابع یکتا) جدید معرفی می‌شود که به عنوان پاسخ به کلاینت ارسال می‌شود. این URI معمولاً به کلاینت امکان می‌دهد که به سرعت به منبع جدید دسترسی پیدا کند.

بطور مثال در زمان خرید بلیت در صورتی که خرید شما بدون هیچ مشکلی صورت بگیرد وضعیت 201یه معنای ایجاد این آیتم در وب سرور مرکزی دریافت خواهد شد.

وضعیت 204

کد 204 اعلام می‌کند که سرور درخواست کاربر را به خوبی برآورده کرده است اما محتوای جدیدی در پاسخ به درخواست در دسترس نیست.

بطور مثال شما زمانی که از API بازکردن قفل رزرو استفاده میکنید در صورت موفق بودن پاسخ برای شما با وضعیت 204 ارسال خواهد شد.

وضعیت 207

Status Code 207 Multi-Status یکی از کدهای وضعیت پروتکل HTTP است که معمولاً در پاسخ به درخواست‌های مربوط به WebDAV استفاده می‌شود. این کد نشان می‌دهد که سرور پاسخ‌های متعددی را برای یک درخواست واحد بازگردانده است.

در صورتی که شما مواردی را (بیشتر از یک آیتم) در درخواست خود جهت انجام عملیات ارسال فرمائید. پاسخ شما در صورتی که با خطا اولیه مواجه نشود اما به هر دلیلی مانند تکراری بودن و یا هر مورد دیگری ارسال شده باشد وضعیت کد 207 دریافت می شود و این به این معناست که قسمتی از درخواست انجام شده و قسمتی دیگر بنا به دلایل مشخص رد شده است.

کد وضعیت روشی برای اطلاع‌رسانی شما در مورد وضعیت درخواست است. این کد وضعیت معمولاً به دو صورت ارسال می‌شود. وضعیت 200 که نشان‌دهنده درست بودن همه مراحل درخواست و پاسخ سرور است و کد وضعیت 500 یا Error 500 که نشان‌دهنده بروز مشکل در پاسخ به درخواست است و یا کدهای دیگر که در زیر به جزئیات آن پرداخته ایم.

وضعیت 500

ارور 500 یک کد خطای HTTP status code است به این معنی که مشکلی در سرور وب‌سایت رخ داده، اما سرور نمی‌تواند بگوید مشکل دقیقاً چیست. کد وضعیت 500 (ارور داخلی سرور) نشان می‌دهد که سرور با شرایط غیرمنتظره‌ای مواجه شده که مانع از انجام درخواست شما می‌شود. هنگامی که از یک وب‌سایت بازدید می‌کنید، مرورگر شما درخواستی را به سروری که سایت در آن میزبانی می‌شود ارسال می‌کند. سرور این درخواست را دریافت کرده، آن را پردازش کرده و منابع درخواستی را به همراه یک هدر HTTP باز می‌فرستد. این هدر کد وضعیت HTTP (response code in the Hypertext Transfer Protocol) را نیز شامل می‌شود.

جهت حفظ ارتباط پایدار در صورتی که با این خطا مواجه شده اید، لطفا از طریق Base URL پشتیبان درخواست خود را ارسال نمائید. قابل ذکر است استفاده از سرور پشتیبان در شرایط معمولی توصیه نمیگردد.
سرور پشتیبان روشی جامع و کامل جهت ایجاد ارتباطی پایدار می باشد.

این خطا در صورتی که سرور اصلی پاسخگو نباشد ایجاد میگردد.

وضعیت 400

  ارور 400 که به  Bad Request 400  نیز معروف است به عنوان خطای کاربر یا کلاینت توسط سرور مرکزی شناخته می‌شود. زمانی که کاربران یک درخواست اشتباه را به سرور ارسال می‌کنند و سرور نمی‌تواند جوابی برای آن درخواست پیدا کند این خطا را به کاربر نشان می‌دهد. در واقع ارور 400 به کاربران نشان می‌دهد که درخواست آنها با موفقیت به سرور ارسال نشده است یا درخواست آنها نادرست بوده است. سرور نمی‌تواند درخواست کاربر را به دلیل وجود خطای کلاینت پردازش کند. به همین دلیل این موضوع را با ارسال پیام‌های مانند invalid request message framing یا deceptive request routing به کاربر نشان می‌دهد. دلایل مختلفی وجود دارد که باعث ایجاد خطا در ارسال درخواست کاربران به سرورها می‌شود.

وضعیت 404

ارور 404 خطای عدم یافتن مسیر و یا صفحه مورد نظر می باشد. در سرویس API ما در صورتی که شما آدرس URL مورد نظر را بصورت صحیح وارد ننمائید با این خطا مواجه میشوید.

در صورت بروز این خطا لطفا یکبار دیگر آدرس URL ارسالی خود را بررسی فرمائید.

در بعضی از شرایط امکان این وجود دارد که در مهلت تعیین شده جهت جابجایی آدرس Base شما اقدام نکرده باشید و سرور مورد نظر دیگر در آن ورژن پاسخگو درخواست های شما نباشد.

وضعیت 405

ارور 405 نشان دهنده این موضوع است که سرور مرکزی متد ارسالی مورد استفاده را نپذیرفته است و یکی از ارورهای سمت کلاینت به شمار می رود. به عبارتی این ارور نشان می دهد که درخواست به دسترسی ارسال شده است و وب سرور نیز این درخواست را تشخیص داده است اما متد به کار رفته را قبول نکرده است که در نتیجه کاربر قادر به مشاهده صفحه مورد نظر نخواهد بود و با ارور Method Not Allowed مواجه خواهد شد.

وضعیت 409

Status Code 409 Conflict یکی از کدهای وضعیت HTTP است که به معنای وجود تعارض یا مشکل در درخواست ارسالی توسط کلاینت است. این کد نشان‌دهنده‌ی این است که درخواست کلاینت نمی‌تواند به‌درستی اجرا شود زیرا با وضعیت جاری سرور یا منابع موجود تعارض دارد.

به طور مثال در صورتی که شما آیتمی تکراری جهت ثبت ارسال نمائید با وضعیت کد 409 مواجه می شود و این به معنی تکراری بودن آیتم می باشد.

وضعیت 422

Status Code 422 Unprocessable Entity یکی از کدهای وضعیت HTTP است که به معنای “موجودیتی که قابل پردازش نیست” است. این کد معمولاً زمانی استفاده می‌شود که درخواست ارسال‌شده از نظر ساختاری صحیح است (یعنی درخواست به درستی فرمت شده و اطلاعات ضروری را شامل می‌شود)، اما سرور قادر به پردازش آن نیست به دلیل اینکه داده‌های درخواست با مشکلات منطقی یا اعتبارسنجی مواجه هستند.

خطاهایی که در قالب Response دریافت میشود

این خطا ها در قالب Response False بصورت کد دریافت میشوند که میتوانید در متن خطا ها و راه حل آنها را در جدول زیر مشاهده نمائید.

در ضمن میتوانید از طریق API زیر بصورت داینامیک این خطاها را دریافت و مدیریت نمائید.

دریافت جزئیات خطا از طریق API

سربرگ – Header

در این روش شما باید درخواست خود را از طریق لینک زیر ارسال فرمائید.

{{Api Url}}/error-handling

HEADER
GET /api/reservation/{{Api version}}/error-handling HTTP/1.1
Host: {{Your Host}}
Authorization: Bearer JWTToken
Content-Type: application/json
Domain: {{Your Domain}}

API Url از طریق پنل کاربری قابل مشاهده خواهد بود

مقادیر ارسالی – Request Data

{
    "code": "Error Code"
}

پاسخ صحیح – Response True

دریافت این پاسخ با Status Code 200 دریافت خواهد شد.

{
    "status": true,
    "time": "Timestamp", // Timestamp
    "data": [
        {
            "title": "Error title in Persian",
            "solution": "How to solve errors in Persian"
        },
        ...
    ]
}

پاسخ نادرست – Response False

{
    "status": false,
    "time": "Timestamp", // Timestamp
    "code": "Error Code"
}

گرفتن IP آدرس هاست و ارتباطی – Get IP

دریافت از طریق API

توضیحات ارسال درخواست

سربرگ – Header

در این روش شما باید درخواست خود را از طریق لینک زیر ارسال فرمائید.

{{Api Url}}/ip

HEADER
GET /api/reservation/{{Api version}}/ip HTTP/1.1
Host: {{Your Host}}
Content-Type: application/json
Domain: {{Your Domain}}

API Url از طریق پنل کاربری قابل مشاهده خواهد بود

مقادیر ارسالی – Request Data

این API نیازی به ارسال داده ندارد.

پاسخ صحیح – Response True

دریافت این پاسخ با Status Code 200 دریافت خواهد شد.

{
    "payload": {
        "host": "192.168.0.5",
        "ip": "192.168.0.170"
    },
    "meta": {
       "timestamp": "Timestamp" // Timestamp
    }
}

پاسخ نادرست – Response False

{
  "error": {
    "code":"Error Code"
  },
  "meta": {
    "timestamp": "Timestamp" // Timestamp
  }
}

در صورت مشاهده Status Code 404 URL درخواست خود را به اشتباه وارد نموده اید.

ساخت لینک – Deep Link (بزودی)

بزودی…