Azure REST API Başvurusu

Azure REST API Başvurusu'na hoş geldiniz.

Temsili Durum Aktarımı (REST) API'leri, hizmetin kaynaklarına oluşturma/alma/güncelleştirme/silme erişimi sağlayan HTTP işlemleri kümelerini (yöntemler) destekleyen hizmet uç noktalarıdır. Aşağıdaki bölümler size yol gösterecektir:

• REST API istek/yanıt çiftinin temel bileşenleri
• REST isteklerinizin güvenliğini sağlamak için istemci uygulamanızı Azure Active Directory'ye (Azure AD) kaydetme
• REST isteği oluşturma ve gönderme ve yanıtı işlemeye genel bakış

REST API istek/yanıt bileşenleri

REST API isteği/yanıt çifti 5 bileşene ayrılabilir:

1. İstek URI'si, şu şekildedir: {URI-scheme} :// {URI-host} / {resource-path} ? {query-string}. Çoğu dil/çerçeve bunu istek iletisinden ayrı olarak geçirmenizi gerektirdiğinden, bunu burada ayrı olarak çağırdığımıza, ancak aslında istek iletisi üst bilgisine eklendiğini unutmayın.
   • URI şeması: İsteği iletmek için kullanılan protokolü gösterir. Örneğin http veya https olabilir.
   • URI ana bilgisayarı: REST hizmet uç noktasının barındırıldığı sunucunun etki alanı adı veya IP adresi, örneğin graph.microsoft.com
   • Kaynak yolu: Hizmet tarafından bu kaynakların seçilmesini belirlerken kullanılan birden çok segmenti içerebilen kaynağı veya kaynak koleksiyonunu belirtir. Örneğin: beta/applications/00003f25-7e1f-4278-9488-efc7bac53c4a/owners uygulamalar koleksiyonundaki belirli bir uygulamanın sahiplerinin listesini sorgulamak için kullanılabilir.
   • Sorgu dizesi (isteğe bağlı): API sürümü, kaynak seçim ölçütleri vb. gibi ek basit parametreler sağlamak için kullanılır.
2. HTTP isteği ileti üst bilgisi alanları
   • Hizmete ne tür bir işlem istediğinizi belirten gerekli bir HTTP yöntemi (işlem veya fiil olarak da bilinir). Azure REST API'leri GET, HEAD, PUT, POST ve PATCH yöntemlerini destekler.
   • Belirtilen URI ve HTTP yöntemi için gereken isteğe bağlı ek üst bilgi alanları. Örneğin, istek için istemci yetkilendirme bilgilerini içeren taşıyıcı belirteci sağlayan bir Yetkilendirme üst bilgisi.
3. URI ve HTTP işlemini destekleyecek isteğe bağlı HTTP istek iletisi gövdesi alanları. Örneğin, POST işlemleri karmaşık parametreler olarak geçirilen MIME ile kodlanmış nesneleri içerir. Gövde için MIME kodlama türü, POST/PUT işlemleri için istek üst bilgisinde Content-type de belirtilmelidir. Bazı hizmetlerin gibi application/jsonbelirli bir MIME türünü kullanmanızı gerektirdiğini unutmayın.
4. HTTP yanıt iletisi üst bilgisi alanları
   • 2xx başarı kodlarından 4xx/5xx hata kodlarına kadar değişen bir HTTP durum kodu. Alternatif olarak API belgelerinde belirtildiği şekilde hizmet tarafından tanımlanan bir durum kodu da döndürülebilir.
   • İsteğin yanıtını desteklemek için gereken yanıt üst bilgisi gibi Content-type isteğe bağlı ek üst bilgi alanları.
5. İsteğe bağlı HTTP yanıt iletisi gövde alanları
   • MIME ile kodlanmış yanıt nesneleri HTTP yanıt gövdesinde döndürülebilir; örneğin, veri döndüren bir GET yönteminden gelen yanıt. Bunlar genellikle yanıt üst bilgisi tarafından Content-type gösterildiği gibi JSON veya XML olarak yapılandırılmış bir biçimde döndürülür. Örneğin, Azure AD erişim belirteci istenirken, yanıt gövdesinde bir veri koleksiyonundaki çeşitli ad/değer eşleştirilmiş nesnelerden biri olan öğesi olarak access_token döndürülür. Bu örnekte, bir yanıt üst bilgisi Content-Type: application/json de eklenecektir.

İstemci uygulamanızı Azure AD kaydetme

Çoğu Azure hizmeti (Azure Resource Manager sağlayıcıları ve klasik Hizmet Yönetimi API'leri gibi), hizmetin API'sini çağırmadan önce istemci kodunuzun geçerli kimlik bilgileriyle kimlik doğrulamasına ihtiyaç duyar. Kimlik doğrulaması çeşitli aktörler arasında Azure AD tarafından koordine edilir ve bu da istemcinize kimlik doğrulaması/yetkilendirme kanıtı olarak bir erişim belirteci sağlar. Ardından belirteç, sonraki tüm REST API isteklerinin HTTP Yetkilendirmesi üst bilgisinde Azure hizmetine gönderilir. Belirtecin talepleri de hizmete bilgi sağlayarak istemciyi doğrulamasını ve gerekli yetkilendirmeyi gerçekleştirmesini sağlar.

Tümleşik Azure AD kimlik doğrulamasını kullanmayan bir REST API kullanıyorsanız veya istemcinizi zaten kaydettiyseniz İstek oluşturma bölümüne atlayabilirsiniz.

Önkoşullar

İstemci uygulamanızın kimlik yapılandırmasını çalışma zamanından önce Azure AD bir kiracıya kaydederek Azure AD olarak bilinen bir hale getirmesi gerekir. İstemcinizi Azure AD kaydetmeden önce göz önünde bulundurmanız gereken öğelerin listesi aşağıdadır:

• Henüz bir Azure AD kiracınız yoksa bkz. Azure Active Directory kiracısını alma.
• OAuth2 Yetkilendirme Çerçevesi'ne göre Azure AD 2 istemci türünü destekler. Her birinin anlaşılması, senaryonuza en uygun olan senaryoya karar vermenize yardımcı olur:
  • web/gizli istemciler (bir web sunucusunda çalışır) kendi kimlikleri (hizmet/daemon) altında kaynaklara erişebilir veya oturum açmış kullanıcının kimliği (yani web uygulaması) altındaki kaynaklara erişmek için temsilci yetkilendirmesi alabilir. Yalnızca bir web istemcisi, erişim belirteci almak için Azure AD kimlik doğrulaması sırasında kendi kimlik bilgilerini güvenli bir şekilde koruyup sunma özelliğine sahiptir.
  • yerel/genel istemciler (bir cihazda yüklü/çalışır), kullanıcı adına erişim belirteci almak için oturum açmış kullanıcının kimliğini kullanarak yalnızca temsilci yetkilendirmesi altındaki kaynaklara erişebilir.
• Kayıt işlemi, uygulamanın kayıtlı olduğu Azure AD kiracısında 2 ilgili nesne oluşturur: uygulama nesnesi ve hizmet sorumlusu nesnesi. Bu bileşenler ve çalışma zamanında nasıl kullanıldıkları hakkında daha fazla arka plan için lütfen Azure Active Directory'deki uygulama ve hizmet sorumlusu nesnelerini gözden geçirin.

Artık istemci uygulamanızı Azure AD kaydetmeye hazırız.

İstemci kaydı

Azure Resource Manager REST API'sine erişecek bir istemciyi kaydetmek için bkz. Adım adım kayıt yönergeleri için kaynaklara erişebilen Active Directory uygulaması ve hizmet sorumlusu oluşturmak için portalı kullanma. Bu makale (kaydı otomatikleştirmek için PowerShell ve CLI sürümlerinde de kullanılabilir) şunları nasıl yapacağınızı gösterir:

• istemci uygulamasını Azure AD ile kaydetme
• istemcinin Azure Resource Manager API'sine erişmesine izin vermek için izin isteklerini ayarlama
• İstemciyi yetkilendirmek için Azure Resource Manager Rol Tabanlı Access Control (RBAC) ayarlarını yapılandırma

Diğer tüm istemciler için bkz. Uygulamaları Azure Active Directory ile tümleştirme. Bu makalede şunların nasıl yapıldığını öğreneceksiniz:

• "Uygulama ekleme" bölümünde istemci uygulamasını Azure AD ile kaydetme
• "Uygulamayı güncelleştirme" bölümünde gizli anahtar oluşturma (web istemcisi kaydediyorsanız)
• "Uygulama güncelleştirme" bölümünde API tarafından gerekli kılınan izin isteklerini ekleyin

İstemci uygulamanızın kaydını tamamladığınıza göre, rest isteğini oluşturacağınız ve yanıtı işleyebileceğiniz istemci kodunuza geçebiliriz.

İsteği oluşturma

Bu bölüm, daha önce ele aldığımız 5 bileşenin ilk 3'lerini kapsar. İlk olarak, istek iletisi üst bilgimizi derlemek için kullanacağımız erişim belirtecini Azure AD edinmemiz gerekir.

Erişim belirteci alma

Geçerli bir istemci kaydına sahip olduktan sonra, erişim belirteci almak için Azure AD ile tümleştirmenin temelde 2 yolu vardır:

• Azure AD platform/dilden bağımsız OAuth2 hizmet uç noktalarını kullanırız. Kullandığınız Azure REST API uç noktaları gibi, bu bölümde sağlanan yönergeler Azure AD uç noktalarını kullanırken istemcinizin platformu veya dili/betiği hakkında hiçbir varsayımda bulunmaz; yalnızca Azure AD https istekleri gönderebileceği/alabileceği ve yanıt iletisini ayrıştırabileceğidir.
• Platforma/dile özgü Microsoft Kimlik Doğrulama Kitaplıkları (MSAL). Kitaplıklar, OAuth2 uç nokta istekleri için zaman uyumsuz sarmalayıcılar ve önbelleğe alma ve yenileme belirteç yönetimi gibi güçlü belirteç işleme özellikleri sağlar. Başvuru belgeleri, kitaplık indirmeleri ve örnek kod gibi diğer ayrıntılar için bkz. Microsoft Kimlik Doğrulama Kitaplıkları.

İstemcinizin kimliğini doğrulamak ve erişim belirteci almak için kullanacağınız 2 Azure AD uç noktası, OAuth2 /authorize ve /token uç noktalar olarak adlandırılır. Bunları nasıl kullanacağınız, uygulamanızın kaydına ve uygulamanızı çalışma zamanında desteklemek için ihtiyacınız olan OAuth2 yetkilendirme verme akışının türüne bağlıdır. Bu makalenin amaçları doğrultusunda, istemcinizin şu yetkilendirme verme akışlarından birini kullanacağını varsayacağız: yetkilendirme kodu veya istemci kimlik bilgileri. Kalan bölümlerde kullanacağınız erişim belirtecini almak için senaryonuza en uygun olanın yönergelerini izleyin.

Yetkilendirme kodu verme (etkileşimli istemciler)

Bu izin hem web hem de yerel istemciler tarafından kullanılabilir ve istemci uygulamasına kaynak erişimi atamak için oturum açmış bir kullanıcının kimlik bilgilerini gerektirir. Bir yetkilendirme kodu (kullanıcı oturum açma/onayına yanıt olarak) almak için uç noktayı, ardından /token erişim belirteci için yetkilendirme kodunu değiştirmek için uç noktayı kullanır/authorize.

1. İlk olarak istemcinizin Azure AD yetkilendirme kodu istemesi gerekir. Uç noktaya HTTPS GET isteğinin biçimi ve örnek istek/yanıt iletileri hakkında ayrıntılı bilgi için /authorize bkz. Yetkilendirme kodu isteme. URI, istemci uygulamanıza özgü aşağıdakiler de dahil olmak üzere sorgu dizesi parametrelerini içerir:

   • client_id - Uygulama kimliği olarak da bilinen bu, yukarıdaki bölümde kaydolduğunda istemci uygulamanıza atanan GUID'dir

   • redirect_uri - istemci uygulamanızın kaydı sırasında belirtilen yanıt/yeniden yönlendirme URI'lerinin URL ile kodlanmış bir sürümü ... Geçirdiğiniz değerin kaydınızla tam olarak eşleşmesi gerektiğini unutmayın!

   • resource - çağırdığınız REST API tarafından belirtilen URL ile kodlanmış tanımlayıcı URI'si. Web/REST API'leri (kaynak uygulamaları olarak da bilinir) yapılandırmalarında bir veya daha fazla uygulama kimliği URI'sini kullanıma açabilir. Örnek:

     • Azure Resource Manager sağlayıcısı (ve klasik Hizmet Yönetimi) API'lerinin kullanımıhttps://management.core.windows.net/
     • Diğer tüm kaynaklar için Azure portal API belgelerine veya kaynak uygulamasının yapılandırmasına bakın. Daha fazla ayrıntı için Azure AD uygulama nesnesinin özelliğine deidentifierUris bakın.

   Uç noktaya yapılan /authorize istek ilk olarak son kullanıcının kimliğini doğrulamak için bir oturum açma istemi tetikler. Geri alabileceğiniz yanıt, içinde redirect_uribelirttiğiniz URI'ye yeniden yönlendirme (302) olarak teslim edilecek. Yanıt üst bilgisi iletisi, yeniden yönlendirme URI'sini ve ardından 2. adım için ihtiyacınız olacak yetkilendirme kodunu içeren sorgu parametresini içeren bir code alan içerirlocation.

2. Ardından, istemcinizin erişim belirteci için yetkilendirme kodunu kullanması gerekir. Uç noktaya HTTPS POST isteğinin biçimi ve örnek istek/yanıt iletileri hakkında ayrıntılı bilgi için bkz. Erişim belirteci istemek için /token yetkilendirme kodunu kullanma. Bu bir POST isteği olduğundan, bu kez uygulamaya özgü parametrelerinizi istek gövdesinde paketleyeceksiniz. Yukarıda bahsedilenlerden bazılarına (diğer yenileriyle birlikte) ek olarak:

   • code - Bu, 1. adımda aldığınız yetkilendirme kodunu içeren sorgu parametresidir.
   • client_secret - Bu parametreye yalnızca istemciniz bir web uygulaması olarak yapılandırıldıysa ihtiyacınız olacaktır. Bu, istemci kaydında daha önce oluşturduğunuz gizli dizi/anahtar değeriyle aynıdır.

İstemci kimlik bilgileri verme (etkileşimli olmayan istemciler)

Bu izin yalnızca web istemcileri tarafından kullanılabilir ve uygulamanın, kayıt zamanında sağlanan istemcinin kendi kimlik bilgilerini kullanarak kaynaklara doğrudan erişmesine (kullanıcı temsilcisi olmadan) izin verir. Genellikle bir daemon/hizmet olarak çalışan etkileşimli olmayan istemciler (UI olmadan) tarafından kullanılır ve erişim belirteci almak için yalnızca /token uç noktayı gerektirir.

Bu iznin istemci/kaynak etkileşimleri, yetkilendirme kodu verme işleminin 2. adımına çok benzer. Uç noktaya HTTPS POST isteğinin biçimi ve örnek istek/yanıt iletileri hakkında ayrıntılı bilgi için lütfen İstemci kimlik bilgilerini kullanarak hizmete hizmet çağrıları bölümündeki "Erişim Belirteci /token İste" bölümüne bakın.

İstek iletisini derleme

Çoğu programlama dilinin/çerçevenin ve betik oluşturma ortamlarının istek iletisini derlemeyi ve göndermeyi kolaylaştırdığını unutmayın. Genellikle isteğin oluşturulmasını/biçimlendirmesini soyutlayan bir web/HTTP sınıfı veya API sağlayarak istemci kodunun yazılmasını kolaylaştırır (örneğin, .NET Framework HttpWebRequest sınıfı). Kısaca, isteğin yalnızca önemli öğelerini ele alacağız, bunun çoğunun sizin için ele alınacağı göz önünde bulundurulduğunda.

İstek URI'si

Tüm güvenli REST istekleri, hassas bilgilerin iletilmesi/alınması nedeniyle istek ve yanıtı güvenli bir kanalla sağlayarak URI şeması için HTTPS protokolünü gerektirir. Bu bilgiler (örneğin: Azure AD yetkilendirme kodu, erişim/taşıyıcı belirteci, hassas istek/yanıt verileri) daha düşük bir aktarım katmanı tarafından şifrelenerek iletilerin gizliliğini güvence altına alır.

Hizmetinizin istek URI'sinin geri kalanı (konak, kaynak yolu ve gerekli sorgu dizesi parametreleri) ilgili REST API belirtimine göre belirlenir. Örneğin, Azure Resource Manager sağlayıcı API'leri kullanırhttps://management.azure.com/, klasik Azure Hizmet Yönetimi API'leri kullanırhttps://management.core.windows.net/, her ikisi de bir api-version sorgu dizesi parametresi gerektirir vb.

İstek üst bilgisi

İstek URI'si, hizmetinizin REST API belirtimi ve HTTP belirtimi tarafından belirlenen ek alanlarla birlikte istek iletisi üst bilgisinde paketlenir. İsteğinizde ihtiyaç duyabileceğiniz bazı yaygın üst bilgi alanları şunlardır:

• Authorization: daha önce Azure AD alınan isteğin güvenliğini sağlamak için OAuth2 taşıyıcı belirtecini içerir
• Content-Type: genellikle "application/json" (JSON biçiminde ad/değer çiftleri) olarak ayarlanır ve istek gövdesinin MIME türünü belirtir.
• Host: Bu, REST hizmet uç noktasının barındırıldığı sunucunun etki alanı adı veya IP adresidir

İstek gövdesi

Daha önce belirtildiği gibi, istekte bulunduğunuz işleme ve parametre gereksinimlerine bağlı olarak istek iletisi gövdesi isteğe bağlıdır. Gerekirse, istediğiniz hizmetin API belirtimi de kodlamayı ve biçimi belirtir.

İstek gövdesi üst bilgiden boş bir satırla ayrılır ve üst bilgi alanı başına Content-Type biçimlendirilmelidir. "application/json" biçimli gövde örneği aşağıdaki gibi görünür:

{
  "<name>": "<value>"
}

İsteği gönderme

Hizmetin istek URI'sine sahip olduğunuza ve ilgili istek iletisi üst bilgisini/gövdesini oluşturduğunuza göre, isteği REST hizmet uç noktasına göndermeye hazırsınız demektir.

Örneğin, Azure Resource Manager sağlayıcısı için https GET istek yöntemi aşağıdakine benzer istek üst bilgisi alanları kullanılarak gönderilebilir, ancak istek gövdesinin boş olduğuna dikkat edin:

GET /subscriptions?api-version=2014-04-01-preview HTTP/1.1
Authorization: Bearer <bearer-token>
Host: management.azure.com

<no body>

Azure Resource Manager sağlayıcısı için https PUT istek yöntemi de aşağıdakine benzer istek üst bilgisi VE gövde alanları kullanılarak gönderilebilir:

PUT /subscriptions/03f09293-ce69-483a-a092-d06ea46dfb8c/resourcegroups/ExampleResourceGroup?api-version=2016-02-01  HTTP/1.1
Authorization: Bearer <bearer-token>
Content-Length: 29
Content-Type: application/json
Host: management.azure.com

{
  "location": "West US"
}

İsteği yaptıktan sonra yanıt iletisi üst bilgisi ve isteğe bağlı gövde döndürülür.

Yanıt iletisini işleme

Şimdi 5 bileşenin son 2'siyle bitireceğiz.

Yanıtı işlemek için yanıt üst bilgisini ve isteğe bağlı olarak yanıt gövdesini ayrıştırmalısınız (isteğe bağlı olarak). Yukarıda sağlanan HTTPS GET örneğinde, bir kullanıcının abonelik listesini almak için /subscriptions uç noktasını kullandık. Yanıtın başarılı olduğunu varsayarsak, aşağıdakine benzer yanıt üst bilgisi alanları almalıdır:

HTTP/1.1 200 OK
Content-Length: 303
Content-Type: application/json;

ve Azure aboneliklerinin listesini ve JSON biçiminde kodlanmış tek tek özelliklerini içeren yanıt gövdesine benzer:

{
    "value":[
        {
        "id":"/subscriptions/04f09293-ce69-583a-a091-z06ea46dfb8c",
        "subscriptionId":"04f09293-ce69-583a-a091-z06ea46dfb8c",
        "displayName":"My Azure Subscription",
        "state":"Enabled",
        "subscriptionPolicies":{
            "locationPlacementId":"Public_2015-09-01",
            "quotaId":"MSDN_2014-05-01",
            "spendingLimit":"On"}
        }
    ]
}

Benzer şekilde, HTTPS PUT örneği için aşağıdakine benzer bir yanıt üst bilgisi almalı ve "ExampleResourceGroup" ekleme put işlemimizin başarılı olduğunu onaylamamız gerekir:

HTTP/1.1 200 OK
Content-Length: 193
Content-Type: application/json;

ve aşağıdakine benzer şekilde JSON biçiminde kodlanmış yeni eklenen kaynak grubumuzun içeriğini onaylayan bir yanıt gövdesi:

{
    "id":"/subscriptions/03f09293-ce69-483a-a092-d06ea46dfb8c/resourceGroups/ExampleResourceGroup",
    "name":"ExampleResourceGroup",
    "location":"westus",
    "properties":
        {
        "provisioningState":"Succeeded"
        }
}

İstekte olduğu gibi, çoğu programlama dili/çerçeve yanıt iletisini işlemeyi kolaylaştırır. Genellikle bu bilgileri isteğin ardından uygulamanıza döndürerek bunu türü/yapılandırılmış biçimde işlemenizi sağlar. Temel olarak, yanıt üst bilgisindeki HTTP durum kodunu onaylamak ve başarılı olursa yanıt gövdesini API belirtimine (veya Content-Type ve Content-Length yanıt üst bilgisi alanlarına) göre ayrıştırmak ilginizi çekecektir.

İşte bu kadar! Azure AD uygulamanızı kaydettikten ve erişim belirteci alma ve HTTP istekleri oluşturma ve işlemeye yönelik bileşenli bir teknik oluşturduktan sonra, yeni REST API'lerinden yararlanmak için kodunuzu çoğaltmak oldukça kolaydır.

İlgili içerik

• HowTo ve QuickStart makalelerinin kapsamlı dizini ve örnek kod dahil olmak üzere uygulama kaydı ve Azure AD programlama modeli hakkında daha fazla bilgi için bkz. Microsoft kimlik platformu (geliştiriciler için Azure Active Directory).
• HTTP isteklerini/yanıtlarını test etmek için bkz.
  • Fiddler. Fiddler, REST isteklerinizi kesebilen ve HTTP isteğini ve yanıt iletilerini tanılamayı kolaylaştıran ücretsiz bir web hata ayıklama ara sunucusudur.
  • JWT Kod Çözücü ve JWT.io; bu sayede talepleri taşıyıcı belirtecinize hızlı ve kolay bir şekilde atarak içeriklerini doğrulayabilirsiniz.

Geri bildirim sağlamak ve içeriğimizi geliştirmemize ve şekillendirmemize yardımcı olmak için lütfen bu makaleyi izleyen LiveFyre yorumları bölümünü kullanın.