البرنامج التعليمي: التوقيع وتقديم الطلبات مع Postman

في هذا البرنامج التعليمي، سنقوم بإعداد واستخدام Postman لتقديم طلب ضد خدمات الاتصالات Azure باستخدام HTTP. بحلول نهاية هذا البرنامج التعليمي، ستقوم بنجاح بإرسال رسالة SMS باستخدام خدمات الاتصالات وPostman. ستتمكن بعد ذلك من استخدام Postman لاستكشاف واجهات برمجة التطبيقات الأخرى داخل خدمات الاتصالات Azure.

في هذا البرنامج التعليمي سنقوم بـ:

• تحميل Postman
• إعداد Postman لتوقيع طلبات HTTP
• إجراء طلب مقابل API SMS خدمات الاتصالات لإرسال رسالة.

المتطلبات الأساسية

• حساب Azure مع اشتراك نشط. لمزيد من التفاصيل، راجع إنشاء حساب مجانًا. يمنحك الحساب المجاني 200 دولار في رصيد Azure لتجربة أي مجموعة من الخدمات.
• مورد "خدمات الاتصال" النشطة وسلسلة الاتصال. إنشاء مورد Communication Services.
• رقم هاتف Azure Communication Services يمكنه إرسال رسائل SMS، راجع الحصول على رقم هاتف للحصول على رقم هاتف.

تحميل وتثبيت Postman

Postman، هو تطبيق سطح المكتب الذي هو قادر على إجراء طلبات API مقابل أي API HTTP. يستخدم عادة لاختبار واستكشاف واجهات برمجة التطبيقات. سنقوم بتحميل أحدث إصدار سطح المكتب من موقع الويب Postman. Postman لديه إصدارات Windows وماك ولينكس قم بتحميل النسخة المناسبة لنظام التشغيل الخاص بك. بمجرد التحميل افتح التطبيق. سيتم تقديم شاشة البدء، والتي تطلب منك تسجيل الدخول أو إنشاء حساب Postman. إنشاء حساب اختياري ويمكن تخطيه بالنقر على رابط "التخطي والذهاب إلى التطبيق". سيؤدي إنشاء حساب إلى حفظ إعدادات طلب واجهة برمجة التطبيقات إلى Postman، والذي يمكن أن يسمح لك بعد ذلك بالتقاط طلباتك على أجهزة كمبيوتر أخرى.

بمجرد إنشاء حساب أو تخطي إنشاء حساب، يجب أن ترى الآن النافذة الرئيسية لـ Postman.

إنشاء مجموعة Postman وتكوينها

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

بمجرد تحديدها، انقر فوق "إنشاء مجموعة جديدة"، لبدء عملية إنشاء المجموعة. سيتم فتح علامة تبويب جديدة في منطقة مركز Postman. سم المجموعة ما تريد. هنا تسمى المجموعة "Azure Communication Services":

بمجرد إنشاء المجموعة الخاصة بك وتسميتها، تكون جاهزًا لتكوينها.

إضافة متغيرات المجموعة

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

عند علامة تبويب الجمع، قم بإنشاء متغيرين:

• المفتاح - يجب أن يكون هذا المتغير أحد مفاتيحك من الصفحة الرئيسية لخدمات الاتصالات Azure داخل مدخل Azure. على سبيل المثال، oW...A==
• نقطة النهاية - يجب أن يكون هذا المتغير نقطة نهاية خدمات الاتصال Azure من صفحة المفتاح. تأكد من إزالة المائل الزائد. على سبيل المثال، https://contoso.communication.azure.com

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

يمكنك معرفة المزيد عن المتغيرات من خلال قراءة وثائق Postman عليها.

إنشاء برنامج نصي للطلب المسبق

الخطوة التالية هي إنشاء برنامج نصي للطلب المسبق داخل Postman. برنامج نصي للطلب المسبق، هو برنامج نصي يعمل قبل كل طلب في Postman ويمكنه تعديل معلمات الطلب أو تغييرها نيابة عنك. سنستخدم هذا لتوقيع طلبات HTTP الخاصة بنا بحيث يمكن تخويلها من قبل خدمات اتصالات Azure. لمزيد من المعلومات حول متطلبات التوقيع، يمكنك قراءة دليلنا حول المصادقة.

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

في هذا التبويب الفرعي، يمكنك إنشاء برنامج نصي للطلب المسبق عن طريق إدخاله في منطقة النص أدناه. قد يكون من الأسهل كتابة هذا، ضمن محرر التعليمات البرمجية الكاملة مثل Visual Studio Code قبل لصقه عند اكتماله. سنتطرق لكل جزء من البرنامج النصي في هذا البرنامج التعليمي. لا تتردد في التخطي حتى النهاية إذا كنت ترغب في مجرد نسخه إلى Postman والبدء. لنبدأ بكتابة البرنامج النصي.

كتابة البرنامج النصي للطلب المسبق

أول شيء سنقوم به هو إنشاء سلسلة التوقيت العالمي المنسق (UTC) وإضافة هذا إلى رأس HTTP "التاريخ". نقوم أيضًا بتخزين هذه السلسلة في متغير لاستخدامه لاحقا عند التوقيع:

// Set the Date header to our Date as a UTC String.
const dateStr = new Date().toUTCString();
pm.request.headers.upsert({key:'Date', value: dateStr});

بعد ذلك، سنقوم بتجزئة نص الطلب باستخدام SHA 256 ووضعه في الرأس x-ms-content-sha256. Postman يتضمن بعض المكتبات القياسية لتجزئة وتوقيع على الصعيد العالمي، لذلك نحن لسنا بحاجة إلى تثبيتها أو طلبها:

// Hash the request body using SHA256 and encode it as Base64
const hashedBodyStr = CryptoJS.SHA256(pm.request.body.raw).toString(CryptoJS.enc.Base64)
// And add that to the header x-ms-content-sha256
pm.request.headers.upsert({
    key:'x-ms-content-sha256',
    value: hashedBodyStr
});

الآن، سنستخدم متغير نقطة النهاية المحدد مسبقًا لتمييز قيمة رأس مضيف HTTP. نحن بحاجة إلى القيام بذلك حيث لم يتم تعيين رأس المضيف حتى بعد معالجة هذا البرنامج النصي:

// Get our previously specified endpoint variable
const endpoint = pm.variables.get('endpoint')
// Remove the https, prefix to create a suitable "Host" value
const hostStr = endpoint.replace('https://','');

مع هذه المعلومات التي تم إنشاؤها، يمكننا الآن إنشاء السلسلة، التي سنقوم بتوقيعها لطلب HTTP، وتتكون هذه السلسلة من عدة قيم تم إنشاؤها مسبقًا:

// This gets the part of our URL that is after the endpoint, for example in https://contoso.communication.azure.com/sms, it will get '/sms'
const url = pm.request.url.toString().replace('{{endpoint}}','');

// Construct our string which we'll sign, using various previously created values.
const stringToSign = pm.request.method + '\n' + url + '\n' + dateStr + ';' + hostStr + ';' + hashedBodyStr;

وأخيرًا، نحن بحاجة إلى توقيع هذه السلسلة باستخدام مفتاح خدمات الاتصالات لدينا ومن ثم إضافة ذلك إلى طلبنا في الرأس Authorization:

// Decode our access key from previously created variables, into bytes from base64.
const key = CryptoJS.enc.Base64.parse(pm.variables.get('key'));
// Sign our previously calculated string with HMAC 256 and our key. Convert it to Base64.
const signature = CryptoJS.HmacSHA256(stringToSign, key).toString(CryptoJS.enc.Base64);

// Add our final signature in Base64 to the authorization header of the request.
pm.request.headers.upsert({
    key:'Authorization',
    value: "HMAC-SHA256 SignedHeaders=date;host;x-ms-content-sha256&Signature=" + signature
});

البرنامج النصي النهائي للطلب المسبق

يجب أن يبدو النص النهائي للطلب المسبق على ما يلي:

// Set the Date header to our Date as a UTC String.
const dateStr = new Date().toUTCString();
pm.request.headers.upsert({key:'Date', value: dateStr});

// Hash the request body using SHA256 and encode it as Base64
const hashedBodyStr = CryptoJS.SHA256(pm.request.body.raw).toString(CryptoJS.enc.Base64)
// And add that to the header x-ms-content-sha256
pm.request.headers.upsert({
    key:'x-ms-content-sha256',
    value: hashedBodyStr
});

// Get our previously specified endpoint variable
const endpoint = pm.variables.get('endpoint')
// Remove the https, prefix to create a suitable "Host" value
const hostStr = endpoint.replace('https://','');

// This gets the part of our URL that is after the endpoint, for example in https://contoso.communication.azure.com/sms, it will get '/sms'
const url = pm.request.url.toString().replace('{{endpoint}}','');

// Construct our string which we'll sign, using various previously created values.
const stringToSign = pm.request.method + '\n' + url + '\n' + dateStr + ';' + hostStr + ';' + hashedBodyStr;

// Decode our access key from previously created variables, into bytes from base64.
const key = CryptoJS.enc.Base64.parse(pm.variables.get('key'));
// Sign our previously calculated string with HMAC 256 and our key. Convert it to Base64.
const signature = CryptoJS.HmacSHA256(stringToSign, key).toString(CryptoJS.enc.Base64);

// Add our final signature in Base64 to the authorization header of the request.
pm.request.headers.upsert({
    key:'Authorization',
    value: "HMAC-SHA256 SignedHeaders=date;host;x-ms-content-sha256&Signature=" + signature
});

أدخل أو الصق هذا البرنامج النصي النهائي، في منطقة النص ضمن علامة التبويب البرنامج النصي للطلب المسبق:

بمجرد إدخالها، اضغط CTRL + S أو اضغط على زر الحفظ وهذا سيوفر البرنامج النصي إلى المجموعة.

إنشاء طلب في Postman

الآن بعد أن تم إعداد كل شيء، نحن على استعداد لإنشاء طلب خدمات الاتصالات داخل Postman. للبدء انقر فوق رمز plus(+) بجوار مجموعة خدمات الاتصال:

سيؤدي ذلك إلى إنشاء علامة تبويب جديدة لطلبنا داخل Postman. مع إنشائها نحن بحاجة إلى تكوينها. سنقوم بتقديم طلب مقابل API إرسال SMS لذا تأكد من الرجوع إلى الوثائق الخاصة بواجهة برمجة التطبيقات هذه للحصول على المساعدة. لنهيئ طلب Postman.

ابدأ بالإعداد، نوع الطلب إلى POST وإدخال {{endpoint}}/sms?api-version=2021-03-07 في عنوان URL للطلب. يستخدم عنوان URL هذا المتغير الذي تم إنشاؤه مسبقًا endpoint لإرساله تلقائيًا إلى مورد خدمات الاتصالات.

الآن حدد علامة التبويب "نص" للطلب ثم قم بتغيير زر الاختيار أسفل إلى "raw". على اليمين، هناك قائمة منسدلة فيها "نص"، قم بتغييره إلى JSON:

سيؤدي ذلك إلى تكوين طلب إرسال المعلومات وتلقيها بتنسيق JSON.

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

{
    "from":"<Your Azure Communication Services Telephone Number>",
    "message":"<The message you'd like to send>",
    "smsRecipients": [
        {
            "to":"<The number you'd like to send the message to>"
        }
    ]
}

بالنسبة إلى قيمة "من"، ستحتاج إلى الحصول على رقم هاتف في بوابة خدمات الاتصالات Azure كما ذكر سابقًا. أدخله بدون أي مسافات وبادئ برمز بلدك. على سبيل المثال: +15555551234. يمكن أن تكون "رسالتك" هي كل ما ترغب في إرساله ولكن Hello from Azure Communication Services مثال جيد. يجب أن تكون قيمة "إلى" هاتفًا يمكنك الوصول إليه ويمكنه تلقي رسائل SMS. استخدام هاتفك النقال هو فكرة جيدة.

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

سيؤدي ذلك إلى ظهور نافذة حوار تسألك، ما الذي ترغب في الاتصال به، والمكان الذي تريد حفظه فيه. يمكنك تسميته أي شيء تريده ولكن تأكد من تحديد مجموعة خدمات الاتصال في النصف السفلي من مربع الحوار:

إرسال طلب

الآن بعد أن تم إعداد كل شيء، يجب أن تكون قادرًا على إرسال الطلب والحصول على رسالة SMS على هاتفك. للقيام بذلك، تأكد من تحديد الطلب الذي تم إنشاؤه ثم اضغط على الزر "إرسال" على اليمين:

إذا سارت الأمور على ما يرام، يجب أن تشاهد الآن الاستجابة من خدمات الاتصالات، والتي يجب أن تكون رمز الحالة 202:

الهاتف المحمول، الذي يملك الرقم الذي قدمته في قيمة "إلى"، كان ينبغي أن يتلقى أيضًا رسالة SMS. لديك الآن تكوين Postman وظيفي يمكنه التحدث إلى خدمات اتصالات Azure وإرسال رسائل SMS.

الخطوات التالية

استكشاف واجهات برمجة التطبيقات لخدمات الاتصالات Azure اقرأ المزيد عن المصادقةتعرف على المزيد عن Postmane

قد ترغب أيضًا في:

• إضافة دردشة إلى تطبيقك
• إنشاء رموز مميزة لوصول المستخدم
• التعرف على تصميم العميل والخادم
• التعرف على المصادقة