Aracılığıyla paylaş

Eğitim: Postman ile imzalama ve istek yapma

Bu öğreticide, HTTP kullanarak Azure İletişim Hizmetleri'ne yönelik istekte bulunmak için Postman'i ayarlayıp kullanacaksınız. Bu öğreticinin sonunda İletişim Hizmetleri'ni ve Postman'i kullanarak kısa mesaj hizmeti (SMS) iletisini başarıyla gönderebilirsiniz. Ardından İletişim Hizmetleri'ndeki diğer API'leri keşfetmek için Postman'i kullanabilirsiniz.

Bu öğreticide aşağıdakilerin nasıl yapılacağını öğreneceksiniz:

  • Postman'i indirin.
  • Postman'i HTTP isteklerini imzalayacak şekilde ayarlayın.
  • İleti göndermek için İletişim Hizmetleri SMS API'sine karşı bir istekte bulunın.

Önkoşullar

Postman'i indirme ve yükleme

Postman, herhangi bir HTTP API'sine yönelik API istekleri gönderebilen bir masaüstü uygulamasıdır. Postman, API'leri test ve araştırmak için yaygın olarak kullanılır. Bu öğreticide Postman web sitesinden en son masaüstü sürümünü indirebilirsiniz. Postman'in Windows, Mac ve Linux sürümleri vardır, bu nedenle işletim sisteminize uygun sürümü indirin.

İndirme işlemi tamamlandıktan sonra uygulamayı açın. Başlangıç ekranı oturum açmanızı veya postman hesabı oluşturmanızı ister. Hesap oluşturmak isteğe bağlıdır ve Atla ve uygulamaya git'i seçerek hesabı atlayabilirsiniz. Hesap oluşturmak API isteği ayarlarınızı Postman'a kaydeder. Ardından isteklerinizi diğer bilgisayarlardan alabilirsiniz.

Bir hesap oluşturabileceğiniz veya doğrudan uygulamaya gidebileceğiniz Postman başlangıç ekranını gösteren ekran görüntüsü.

Bir hesap oluşturduktan veya adımı atladıktan sonra Postman'in ana ekranını görürsünüz.

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şturursunuz. Bu görevi yapmak için uygulamanın sol tarafında Koleksiyonlar'ı seçin.

Koleksiyonlar sekmesinin vurgulandığı Postman ana ekranını gösteren ekran görüntüsü.

Koleksiyon oluşturma işlemini başlatmak için Yeni Koleksiyon Oluştur'u seçin. Postman'in orta alanında koleksiyonu adlandırdığınız yeni bir sekme açılır. Burada koleksiyona Azure İletişim Hizmetleri adı verilmiştir.

İletişim Hizmetleri koleksiyonunun açık olduğu ve koleksiyonun adının vurgulandığı Postman'i gösteren ekran görüntüsü.

Koleksiyonunuzu oluşturup adlandırdı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 koleksiyonu içinde iki koleksiyon değişkeni belirtirsiniz. Bu değişkenler, koleksiyonunuzdaki tüm istekler için kullanılabilir. Değişken oluşturmaya başlamak için Değişkenler sekmesini seçin.

İletişim Hizmetleri Değişkenleri sekmesini içeren Postman'i gösteren ekran görüntüsü.

Koleksiyonlar sekmesinde iki değişken oluşturun:

  • key: Bu değişken, Azure portalındaki İletişim Hizmetleri Anahtarı sayfanızdaki anahtarlarınızdan biri olmalıdır. oW...A== bunun bir örneğidir.
  • uç nokta: Bu değişken , Anahtar sayfasından İletişim Hizmetleri uç noktalarınız olmalıdır. Sondaki eğik çizgiyi kaldırdığınızdan emin olun. https://contoso.communication.azure.com bunun bir örneğidir.

Değişkenler sekmesinde, bu değerleri İlk Değer sütununa girin. Sağ üst köşedeki Tümünü Kalıcı Hale Getirin'i seçin. Doğru yapılandırıldığında Postman bölmeniz aşağıdaki görüntüye benzer olmalıdır.

İletişim Hizmetleri koleksiyon değişkenlerinin doğru şekilde ayarlandığı Postman'i gösteren ekran görüntüsü.

Değişkenler hakkında daha fazla bilgi edinmek için Postman belgelerine bakın.

Ön sorgu betiği oluştur

Sonraki adım Postman'da bir ön sorgu betiği oluşturmaktır. Postman'daki her istek öncesinde bir ön istek betiği çalıştırılır. sizin için istek parametrelerini değiştirebilir veya değiştirebilir. Bu betiği, İletişim Hizmetleri'nin HTTP isteklerinizi onaylaması için imzalamak amacıyla kullanırsınız. İmzalama gereksinimleri hakkında daha fazla bilgi için kimlik doğrulama kılavuzumuza bakın.

Bu betiği, koleksiyondaki herhangi bir istekte otomatik olarak çalışacak şekilde koleksiyonda oluşturursunuz. Bu adımı gerçekleştirmek için Koleksiyonlar sekmesinde Ön İstek Betiği'ni seçin.

Postman'da İletişim Hizmetleri Koleksiyonları Ön İstek Betiği sekmesini gösteren ekran görüntüsü.

Şimdi metin alanına girerek bir ön sorgu betiği oluşturacaksınız. Yapıştırmadan önce Visual Studio Code gibi tam bir kod düzenleyicisine yazarsanız bu adım daha kolay olabilir. Bu öğretici, senaryo sürecinin her bölümünde size yol gösterir. Komut dosyasını direkt Postman'e kopyalamak ve kullanmaya başlamak istiyorsanız sonuna geçebilirsiniz. Senaryo yazmaya başlayalım.

Ön sorgu betiğini yazma

İlk adım, Eşgüdümlü Evrensel Saat (UTC) dizesi oluşturmak ve bunu HTTP üst bilgisine Date eklemektir. Bu dizeyi daha sonra imzalarken kullanmak için bir değişkende depolayın.

// 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, istek gövdesini SHA 256 kullanarak hash edin ve x-ms-content-sha256 başlığına yerleştirin. Postman, genel olarak karma oluşturma ve imzalama için bazı standart kitaplıklar içerdiği için bunları yüklemenize veya gerektirmenize gerek yoktur.

// 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 Konağı üst bilgisinin değerini ayırt etmek için önceden belirttiğiniz uç nokta değişkenini kullanın. Host üst bilgisi, bu betik işlendiği sırada ayarlanmamıştır.

// 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 bilgilerle artık HTTP isteği için imzaladığınız dizeyi oluşturabilirsiniz. Dize, önceden 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, by using various previously created values.
const stringToSign = pm.request.method + '\n' + url + '\n' + dateStr + ';' + hostStr + ';' + hashedBodyStr;

Son olarak, İletişim Hizmetleri anahtarınızı kullanarak bu dizeyi imzalarsınız. Ardından üst bilgideki Authorization isteğinize bu anahtarı ekleyin.

// 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 ön sorgu betiği

Son ön inceleme betiği şu örneğe benzer olmalıdır:

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

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

Postman'de, İletişim Hizmetleri koleksiyonuna ait girilmiş bir ön sorgu betiğini gösteren ekran görüntüsü.

Girdikten sonra Ctrl+S tuşlarına basın veya Kaydet'i seçerek betiği koleksiyona kaydedin.

Postman ön istek betiğini Kaydet düğmesini gösteren ekran görüntüsü.

Postman'de istek oluşturma

Artık her şey ayarlandı, Postman'da bir İletişim Hizmetleri isteği oluşturmaya hazırsınız. Başlamak için İletişim Hizmetleri koleksiyonunun yanındaki artı işaretini (+) seçin.

Postman artı işaretini (+) gösteren ekran görüntüsü.

Postman'da isteğiniz için yeni bir sekme oluşturdunuz ve şimdi bunu yapılandırmanız gerekiyor. SMS Gönderme API'sine karşı bir istekte bulunursunuz, bu nedenle yardım için bu API'nin belgelerine başvurdığınızdan emin olun. Postman isteğini yapılandıralım.

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

Türü POST ve URL'si doğru ayarlanmış bir Postman isteğini gösteren ekran görüntüsü.

İsteğin Gövde sekmesinde ham öğesini seçin. Sağdaki açılan listede JSON'ı seçin.

İstek gövdesini ham ve JSON olarak ayarlamayı gösteren ekran görüntüsü.

JSON biçiminde bilgi göndermek ve almak için isteği yapılandırmışsınız.

Metin alanına aşağıdaki biçimde bir istek gövdesi girin:

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

İletişim Hizmetleri portalında from değeri için bir telefon numarası almanız gerekir, daha önce belirtildiği gibi. Ülke kodunuzun ön ekiyle birlikte ve boşluksuz olarak girin. +15555551234 bunun bir örneğidir. Göndermek istediğiniz message olabilir, ancak Hello from Azure Communication Services iyi bir örnektir. to değeri, SMS mesajlarını alabilmeniz için erişiminiz olan bir telefon olmalıdır. Kendi cep telefonunuzu kullanmak iyi bir fikirdir.

Bu isteği daha önce oluşturduğunuz İletişim Hizmetleri koleksiyonuna kaydedin. Bu adım, daha önce oluşturduğunuz değişkenleri ve ön sorgu betiğini almasını sağlar. İstek alanının sağ üst kısmında Kaydet'i seçin.

Postman isteğinin Kaydet düğmesini gösteren ekran görüntüsü.

Görüntülenen iletişim kutusu, isteği neyle çağırmak istediğinizi ve nereye kaydetmek istediğinizi sorar. İstediğiniz her şeyi adlandırabilirsiniz, ancak iletişim kutusunun alt yarısında İletişim Hizmetleri koleksiyonunuzu seçtiğinizden emin olun.

İletişim Hizmetleri koleksiyonunun seçili olduğu Postman Kaydetme İsteği iletişim kutusunu gösteren ekran görüntüsü.

İstek gönderme

Artık her şey ayarlandıysa, isteği gönderebilir ve telefonunuza bir SMS mesajı alabilirsiniz. Bu adımı gerçekleştirmek için isteğinizin seçili olduğundan emin olun ve gönder'i seçin.

Gönder düğmesinin vurgulandığı bir Postman isteğini gösteren ekran görüntüsü.

Her şey yolunda gittiyse, İletişim Hizmetleri'nden gelen yanıtı (202 durum kodu) görürsünüz.

202 durum koduyla başarıyla gönderilen bir Postman isteğini gösteren ekran görüntüsü.

Değerde to sağladığınız numaranın sahibi olan cep telefonu bir SMS iletisi de aldı. Artık İletişim Hizmetleri ile iletişim kurabilen ve SMS mesajları gönderebilen işlevsel bir Postman yapılandırmanız var.

İlgili içerik