مشاركة عبر

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

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

في هذا البرنامج التعليمي، تتعلم كيفية:

  • قم بتنزيل ساعي البريد.
  • قم بإعداد ساعي البريد لتوقيع طلبات HTTP.
  • قم بتقديم طلب ضد واجهة برمجة تطبيقات الرسائل القصيرة لخدمات الاتصالات لإرسال رسالة.

Prerequisites

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

قم بتنزيل Postman وتثبيته

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

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

لقطة شاشة توضح شاشة بدء ساعي البريد حيث يمكنك إنشاء حساب أو الانتقال مباشرة إلى التطبيق.

بعد إنشاء حساب أو تخطي الخطوة، سترى الآن الشاشة الرئيسية لساعي البريد.

إنشاء مجموعة ساعي بريد وتكوينها

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

لقطة شاشة تعرض شاشة ساعي البريد الرئيسية مع تمييز علامة التبويب المجموعات.

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

لقطة شاشة تظهر ساعي البريد مع فتح مجموعة خدمات الاتصالات وتمييز اسم المجموعة.

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

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

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

لقطة شاشة توضح ساعي البريد مع علامة التبويب متغيرات خدمات الاتصالات.

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

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

في علامة التبويب المتغيرات ، أدخل هذه القيم في عمود القيمة الأولية . حدد Persist All في الزاوية العلوية اليمنى. عند تكوينه بشكل صحيح ، يجب أن يبدو جزء Postman الخاص بك مثل الصورة التالية.

لقطة شاشة توضح ساعي البريد مع متغيرات مجموعة خدمات الاتصالات التي تم إعدادها بشكل صحيح.

لمعرفة المزيد حول المتغيرات، راجع وثائق ساعي البريد.

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

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

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

لقطة شاشة توضح ساعي البريد مع علامة التبويب البرنامج النصي للطلب المسبق لمجموعات خدمات الاتصالات.

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

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

تتمثل الخطوة الأولى في إنشاء سلسلة التوقيت العالمي المنسق (UTC) وإضافتها إلى Date رأس 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 by 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, by 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 by 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, by 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. للبدء، حدد علامة الجمع (+) بجوار مجموعة خدمات الاتصالات.

لقطة شاشة توضح علامة ساعي البريد زائد (+).

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

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

لقطة شاشة تعرض طلب ساعي البريد مع تعيين النوع إلى POST وتعيين عنوان URL بشكل صحيح.

في علامة التبويب النص الأساسي للطلب، حدد خام. في القائمة المنسدلة على يسار الصفحة، حدد JSON.

لقطة شاشة توضح تعيين نص الطلب إلى 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>"
        }
    ]
}

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

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

لقطة شاشة تعرض الزر حفظ لطلب ساعي البريد.

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

لقطة شاشة تعرض مربع الحوار Saman Save Request مع تحديد مجموعة Communication Services.

إرسال طلب

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

لقطة شاشة تعرض طلب ساعي البريد مع تمييز الزر إرسال.

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

لقطة شاشة تعرض طلب ساعي البريد الذي تم إرساله بنجاح مع رمز الحالة 202.

تلقى الهاتف المحمول الذي يمتلك الرقم الذي قدمته في القيمة to أيضا رسالة نصية قصيرة. لديك الآن تكوين ساعي بريد وظيفي يمكنه التحدث إلى خدمات الاتصالات وإرسال رسائل SMS.

المحتوى ذو الصلة

  • Last updated on