Öğretici: Postman ile imzalama ve istekte bulunma

Bu öğreticide, HTTP kullanarak Azure İletişim Hizmetleri karşı istekte bulunmak için Postman'i ayarlayıp kullanacağız. Bu öğreticinin sonunda İletişim Hizmetleri'ni ve Postman'i kullanarak başarıyla bir SMS iletisi göndermiş olacaksınız. Daha sonra postman kullanarak Azure İletişim Hizmetleri içindeki diğer API'leri keşfedebileceksiniz.

Bu öğreticide şunları yapacağız:

Önkoşullar

• Etkin aboneliği olan bir Azure hesabı. Ayrıntılar için bkz. Ücretsiz hesap oluşturma. Ücretsiz hesap, dilediğiniz hizmetleri bir arada deneyebilmeniz için 200 ABD Doları Azure kredisi sunar.
• Etkin bir İletişim Hizmetleri kaynağı ve bağlantı dizesi. İletişim Hizmetleri kaynağı oluşturmayı öğrenin.
• SMS mesajı gönderebilen bir Azure İletişim Hizmetleri Telefon numarası almak için Telefon numarası alma bölümüne bakın.

Postman'i indirme ve yükleme

Postman, herhangi bir HTTP API'sine yönelik API istekleri gönderebilen bir masaüstü uygulamasıdır. Genellikle API'leri test edip keşfetmek için kullanılır. Postman'in web sitesinden en son Masaüstü sürümünü indireceğiz. Postman'in Windows, Mac ve Linux sürümleri vardır, bu nedenle işletim sisteminize uygun sürümü indirin. İndirildikten sonra uygulamayı açın. Oturum açmanızı veya Postman hesabı oluşturmanızı isteyen bir başlangıç ekranı açılır. Hesap oluşturma isteğe bağlıdır ve "Atla ve uygulamaya git" bağlantısına tıklanarak atlanabilir. Hesap oluşturmak API istek ayarlarınızı Postman'a kaydeder ve bu sayede isteklerinizi diğer bilgisayarlardan alabilirsiniz.

Hesap oluşturduktan veya hesap oluşturmayı atladıktan sonra Postman'in ana penceresini görmeniz gerekir.

Postman koleksiyonu oluşturma ve yapılandırma

Postman, istekleri birçok şekilde düzenleyebilir. Bu öğreticinin amaçları doğrultusunda. Bir Postman Koleksiyonu oluşturacağız. Bunu yapmak için uygulamanın sol tarafındaki koleksiyonlar düğmesini seçin:

Seçildikten sonra koleksiyon oluşturma işlemini başlatmak için "Yeni Koleksiyon Oluştur"a tıklayın. Postman'in orta alanında yeni bir sekme açılır. Koleksiyona istediğiniz adı verin. Burada koleksiyon "Azure İletişim Hizmetleri" olarak adlandırılır:

Koleksiyonunuz oluşturulduktan ve adlandırıldıktan sonra yapılandırmaya hazır olursunuz.

Koleksiyon değişkenleri ekleme

Kimlik doğrulamasını işlemek ve istekleri kolaylaştırmak için yeni oluşturulan İletişim Hizmetleri koleksiyonunda iki koleksiyon değişkeni belirteceğiz. Bu değişkenler İletişim Hizmetleri koleksiyonunuzdaki tüm istekler için kullanılabilir. Değişken oluşturmaya başlamak için Koleksiyonun Değişkeninin Sekmesi'ni ziyaret edin.

Koleksiyon sekmesine geçtikten sonra iki değişken oluşturun:

• key - Bu değişken, Azure portal içindeki Azure İletişim Hizmetleri anahtar sayfanızdaki anahtarlarınızdan biri olmalıdır. Örneğin, oW...A==.
• endpoint - Bu değişken, anahtar sayfasından Azure İletişim Hizmetleri uç noktanız olmalıdır. Sondaki eğik çizgiyi kaldırdığınızdan emin olun. Örneğin, https://contoso.communication.azure.com.

Bu değerleri değişkenler ekranının "Başlangıç Değeri" sütununa girin. Girdikten sonra, sağdaki tablonun hemen üstündeki "Tümünü Kalıcı Hale Al" düğmesine basın. Doğru yapılandırıldığında Postman ekranınız şuna benzer olmalıdır:

Postman'in bunlarla ilgili belgelerini okuyarak değişkenler hakkında daha fazla bilgi edinebilirsiniz.

İstek öncesi betiği oluşturma

Sonraki adım Postman içinde bir ön istek Betiği oluşturmaktır. İstek öncesi betik, Postman'daki her istek öncesinde çalışan ve sizin adınıza istek parametrelerini değiştirebilen veya değiştirebilen bir betiktir. Http isteklerimizin Azure İletişim Hizmetleri tarafından yetkilendirilebilmesi için bunu kullanarak imzalayacağız. İmzalama gereksinimleri hakkında daha fazla bilgi için kimlik doğrulaması kılavuzumuzu okuyabilirsiniz.

Bu betiği koleksiyon içindeki herhangi bir istekte çalışacak şekilde Koleksiyon içinde oluşturacağız. Bunu yapmak için koleksiyon sekmesinde "İstek Öncesi Betik" Alt Sekmesine tıklayın.

Bu Alt Sekmede, istek öncesi betiği aşağıdaki metin alanına girerek oluşturabilirsiniz. Tamamlandığında yapıştırmadan önce Visual Studio Code gibi tam bir kod düzenleyicisinde bunu yazmak daha kolay olabilir. Bu öğreticide betiğin her bir bölümünü inceleyeceğiz. Postman'e kopyalayıp başlamak isterseniz sona atlayabilirsiniz. Şimdi betiği yazmaya başlayalım.

İstek öncesi betiği yazma

İlk olarak Eşgüdümlü Evrensel Saat (UTC) dizesi oluşturup bunu "Tarih" HTTP Üst Bilgisine ekleyeceğiz. Ayrıca bu dizeyi daha sonra imzalarken kullanmak üzere bir değişkende depolarız:

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

Ardından SHA 256 kullanarak istek gövdesini karma olarak kullanıp üst bilgisine x-ms-content-sha256 yerleştireceğiz. Postman, genel olarak karma oluşturma ve imzalama için bazı standart kitaplıklar içerdiği için bunları yüklememiz veya gerektirmemiz gerekmez:

// 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
});

Şimdi, HTTP Ana Bilgisayarı üst bilgisinin değerini ayırt etmek için daha önce belirtilen uç nokta değişkenimizi kullanacağız. Bu betik işleninceye kadar Konak üst bilgisi ayarlanmadığından bunu yapmamız gerekir:

// 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://','');

Bu bilgiler oluşturulduktan sonra artık HTTP İsteği için imzalayacağımız dizeyi oluşturabiliriz. Bu dize daha önce oluşturulmuş birkaç değerden oluşur:

// 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;

Son olarak, İletişim Hizmetleri anahtarımızı kullanarak bu dizeyi imzalamamız ve bunu üst bilgideki Authorization isteğimize eklememiz gerekir:

// 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
});

Son istek öncesi betiği

İstek öncesi betiğin son örneği şöyle görünmelidir:

// 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
});

Bu son betiği İstek Öncesi Betik Sekmesindeki metin alanına girin veya yapıştırın:

Girdikten sonra CTRL + S tuşlarına basın veya kaydet düğmesine basın; bu işlem betiği koleksiyona kaydeder.

Postman'de istek oluşturma

Artık her şey ayarlandı, Postman içinde bir İletişim Hizmetleri isteği oluşturmaya hazırız. Başlamak için İletişim Hizmetleri Koleksiyonu'nu yanındaki artı(+) simgesine tıklayın:

Bu işlem Postman içinde isteğimiz için yeni bir sekme oluşturur. Oluşturulduktan sonra yapılandırmamız gerekir. SMS Gönderme API'sine yönelik bir istekte bulunacağız, bu nedenle yardım için bu API'nin belgelerine bakın. Şimdi Postman'ın isteğini yapılandıralım.

başlangıç olarak istek türünü POST olarak ayarlayın ve istek URL'si alanına girin {{endpoint}}/sms?api-version=2021-03-07 . Bu URL, İletişim Hizmetleri kaynağınıza otomatik olarak göndermek için daha önce oluşturduğumuz endpoint değişkeni kullanır.

Şimdi isteğin Gövde sekmesini seçin ve altındaki radyo düğmesini "ham" olarak değiştirin. Sağ tarafta "Metin" yazan bir açılan liste vardır ve bunu JSON olarak değiştirin:

Bu işlem, JSON biçiminde bilgi göndermek ve almak için isteği yapılandıracaktır.

Aşağıdaki metin alanında bir istek gövdesi girmeniz gerekir; bu, aşağıdaki biçimde olmalıdır:

{
    "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>"
        }
    ]
}

"Kimden" değeri için, daha önce belirtildiği gibi Azure İletişim Hizmetleri Portalı'nda bir telefon numarası almanız gerekir. Bunu boşluk bırakmadan ve ülke kodunuzla ön ek olarak girin. Örneğin: +15555551234. "İletiniz" göndermek istediğiniz gibi olabilir, ancak Hello from Azure Communication Services iyi bir örnektir. "To" değeri, SMS mesajları alabilen erişiminiz olan bir telefon olmalıdır. Kendi cep telefonunuzu kullanmak iyi bir fikirdir.

Girdikten sonra, bu isteği daha önce oluşturduğumuz İletişim Hizmetleri Koleksiyonuna kaydetmemiz gerekir. Bu, daha önce oluşturduğumuz değişkenleri ve istek öncesi betiği almasını sağlar. Bunu yapmak için, istek alanının sağ üst kısmındaki "kaydet" düğmesine tıklayın.

Bu, isteği ne olarak çağırmak istediğinizi ve nereye kaydetmek istediğinizi soran bir iletişim penceresi görünür. İstediğiniz gibi adlandırabilirsiniz ancak iletişim kutusunun alt yarısında İletişim Hizmetleri koleksiyonunuzu seçtiğinizden emin olun:

İstek gönderme

Artık her şey ayarlandıysa, isteği gönderebilmeli ve telefonunuza bir SMS mesajı alabilmelisiniz. Bunu yapmak için, oluşturduğunuz isteğin seçili olduğundan emin olun ve ardından sağ taraftaki "Gönder" düğmesine basın:

Her şey yolunda gittiyse İletişim Hizmetleri'nden 202 Durum kodu olması gereken yanıtı görmeniz gerekir:

"To" değerinde sağladığınız numaranın sahibi olan Cep telefonu da bir SMS mesajı almış olmalıdır. Artık Azure İletişim Hizmetleri konuşabilen ve SMS mesajları gönderebilen işlevsel bir Postman yapılandırmanız var.

Sonraki adımlar

Ayrıca şunları da yapmak isteyebilirsiniz:

• Uygulamanıza sohbet ekleme
• Kullanıcı erişim belirteçleri oluşturma
• İstemci ve sunucu mimarisi hakkında bilgi edinin
• Kimlik doğrulaması hakkında bilgi edinin