Azure Sphere Genel API'sine genel bakış

Makale
08/09/2023

Azure Sphere genel API'si, kiracılar, ürünler, dağıtımlar ve cihaz grupları gibi Azure Sphere kaynaklarını oluşturmak ve yönetmek için HTTP işlemlerini destekleyen bir hizmet uç noktaları kümesidir. Azure Sphere genel API'sinde, işlem istekleri ve yanıtları göndermek için REST (REpresentational State Transfer) HTTP protokolü kullanılır. İşlem yanıtında döndürülen veriler JSON (JavaScript Nesne Gösterimi) biçiminde biçimlendirilir. Kullanılabilir işlemler Azure Sphere genel API başvurusunda belgelenmiştir.

Müşteriler, kaynak yönetimi görevlerini gerçekleştirmek için genel API yerine Azure Sphere komut satırı arabirimini (CLI) kullanmayı tercih edebilir. CLI, ortak API'nin program karmaşıklığının çoğunu soyutlayarak işlem isteklerinin ve yanıtlarının gönderilmesini ve alınmasını basitleştirir. CLI komutları görevleri gerçekleştirmek için Azure Sphere genel API'sini kullanır, ancak CLI komutlarının basit söz dizimi bunların kullanımını çok daha kolay hale getirir.

Bazı müşteriler, kaynak yönetimi görevlerini gerçekleştirmek için kendi kullanıcı arabirimini (UI) oluşturmak isteyebilir. Azure Sphere genel API'sini kullanarak özel bir kullanıcı arabirimi oluşturabilirsiniz. Azure Sphere CLI ile özel bir kullanıcı arabirimi oluşturmak mümkün değildir.

REST API isteğinin bileşenleri

REST API isteği aşağıdaki üç bileşene sahiptir:

İstek URI'sini aşağıdaki biçimde belirtin:

VERB https://prod.core.sphere.azure.net/v{version}/{collection}/{id}…[{resourceId} | {collection}]

Parametre:
- collection: Bir veya daha fazla koleksiyon. Birden çok iç içe koleksiyon desteklenir, bu nedenle göreli yollar /collection/id/collection/id içerebilir...
  
  Örnek: /v2/tenants/{tenantId}/devices/{deviceId}/images
- resourceId: Bir koleksiyondaki belirli kaynaklara erişim sağlayan belirli bir kaynağın kimliği.
  
  Örnek: /v2/tenants/{tenantId}/devicegroups/{devicegroupid}
- version: API sürümünü tanımlayan API sürümü. API'ler geliştikçe uygulamanızın veya hizmet kesmenizin oluşmasını önlemek için her API isteğinde bir api sürümü bulunmalıdır.
  
  Örnek: /v2
HTTP isteği ileti üst bilgisi alanları:
- Hizmete ne tür bir işlem istediğinizi bildiren gerekli bir HTTP yöntemi (işlem veya fiil olarak da bilinir).
- Belirtilen URI ve HTTP yönteminin gerektirdiği ek üst bilgi alanları. Özellikle, istek için istemci yetkilendirme belirteci içeren taşıyıcı belirteci sağlayan bir yetkilendirme üst bilgisi.
URI ve HTTP işlemini desteklemek için isteğe bağlı HTTP isteği ileti gövdesi alanları.
- HTTP POST veya PUT işlemleri için gövde, Content-Type istek üst bilgisinde ve uygulama/json'da belirtilmelidir.

REST API yanıtının bileşenleri

REST API yanıtı aşağıdaki iki bileşene sahiptir:

HTTP yanıt iletisi üst bilgisi alanları:
- HTTP durum kodu. Başarılı çağrılar 2xx kodları döndürür; 4xx ve 5xx kodları hata durumlarıdır. Ayrıntılar için Azure Sphere genel API hata kodları bölümüne bakın. Alternatif olarak, Azure Sphere genel API başvurusunda belirtildiği gibi hizmet tanımlı bir durum kodu döndürülebilir.
- İsteğe bağlı ek üst bilgi alanları, istek yanıtını desteklemek için gerekirse content-Type yanıt üst bilgisi gibi.
İsteğe bağlı HTTP yanıt iletisi gövde alanları:
- MIME ile kodlanmış yanıt nesneleri, veri döndüren bir GET yönteminden gelen yanıt gibi HTTP yanıt gövdesinde döndürülebilir. Bu nesneler her zaman Content-Type yanıt üst bilgisi tarafından gösterildiği gibi yapılandırılmış bir JSON biçiminde döndürülür.

İsteğin kimlik doğrulaması

Geçerli bir istekte bulunabilmeniz için uygulamanızın veya hizmetinizin Azure Sphere genel API'siyle kimliğinin doğrulanması gerekir. Aşağıdaki tabloda kimlik doğrulaması yapmanın bazı yolları gösterilmektedir.

Uygulama türü	Açıklama	Örnek	Kimlik doğrulama mekanizması
Etkileşimli istemci tarafı	GUI tabanlı istemci tarafı uygulaması	Cihazları numaralandıran Windows uygulaması	Microsoft Kimlik Doğrulama Kitaplığı (MSAL)
Etkileşimli JavaScript	GUI tabanlı JavaScript uygulaması	Bir cihaz grubu için dağıtımları görüntüleyen AngularJS tek sayfalı uygulama.	MSAL
Etkileşimli web	GUI tabanlı web uygulaması	Derleme özetlerini görüntüleyen özel Web panosu	OAuth 2

Not

Azure Active Directory platformu Microsoft Identity platformuna dönüşiyor. Daha fazla bilgi için bkz. Azure Sphere'deki yenilikler.

Kimlik doğrulama kitaplığı değerleri

Kimlik doğrulaması için kullanılacak taşıyıcı belirteci almak için Microsoft Kimlik Doğrulama Kitaplıklarını (MSAL) çağırırsanız, dört değer sağlamanız gerekir:

Azure Sphere istemci uygulaması kimliği: 0B1C8F7E-28D2-4378-97E2-7D7D63F7C87F (başarılı kimlik doğrulaması için gereklidir)
Kullanıcının kapsamı: https://sphere.azure.net/api/user_impersonation
Azure Sphere Kiracı Kimliği: 7d71c83c-ccdf-45b7-b3c9-9c41b94406d9
Azure Sphere API uç noktası: https://prod.core.sphere.azure.net/

Kimlik doğrulaması hakkında daha fazla bilgi için bkz. Microsoft Kimlik Doğrulama Kitaplığı (MSAL) ve Kimlik doğrulama akışları.

İstekte bulunma

Azure Sphere ile kimlik doğrulaması yaptıktan sonra istekte bulunabilir ve yanıt alabilirsiniz.

Aşağıdaki C# örneği, istekte bulunmak için HttpClient sınıfını kullanır.

namespace SpherePublicAPISample
{
    using System;
    using System.Collections.Generic;
    using System.Net.Http;
    using System.Net.Http.Headers;
    using System.Threading;
    using System.Threading.Tasks;
    // You install the Microsoft.Identity.Client reference by using Nuget,
    // starting at https://www.nuget.org/packages/Microsoft.Identity.Client.
    // Follow the instructions to install using Package Manager.
    using Microsoft.Identity.Client;

    class Program
    {
        // Azure Sphere Public API resource URI
        private readonly List<string> Scopes = new List<string>() { "https://sphere.azure.net/api/user_impersonation" };

        // Azure Sphere Public API client application ID.
        private const string ClientApplicationId = "0b1c8f7e-28d2-4378-97e2-7d7d63f7c87f";

        // Azure Sphere Tenant ID.
        public const string Tenant = "7d71c83c-ccdf-45b7-b3c9-9c41b94406d9";

        // Azure Sphere Public API URI
        private static readonly Uri AzureSphereApiUri = new Uri("https://prod.core.sphere.azure.net/");

        // Program entry-point.
        // returns Zero on success, otherwise non-zero.
        private static int Main()
        {
            try
            {
                CancellationTokenSource cancellationTokenSource = new CancellationTokenSource();

                Program program = new Program();

                program.ExecuteAsync(cancellationTokenSource.Token)
                    .GetAwaiter()
                    .GetResult();

                Console.ReadLine();
            }
            catch (Exception ex)
            {
                Console.Error.WriteLine(ex.ToString());
                return -1;
            }
            return 0;
        } // end of main

        private async Task ExecuteAsync(CancellationToken cancellationToken)
        {
            IPublicClientApplication publicClientApp = PublicClientApplicationBuilder
                .Create(ClientApplicationId)
                .WithAuthority(AzureCloudInstance.AzurePublic, Tenant)
                .WithRedirectUri("http://localhost")
                .Build();

            AuthenticationResult authResult = await publicClientApp.AcquireTokenInteractive(Scopes)
                .ExecuteAsync();

            string accessToken = authResult.AccessToken;

            // Call the Azure Sphere API to get tenants available to the authenticated user.
            string result = await GetAsync(accessToken, "v2/tenants", cancellationToken);

            Console.WriteLine(result);
        } // end of ExecuteAsync method

        private async Task<string> GetAsync(string accessToken, string relativeUrl, CancellationToken cancellationToken)
        {
            using (HttpClient client = new HttpClient())
            {
                client.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Bearer", accessToken);

                Uri uri = new Uri(AzureSphereApiUri, relativeUrl);

                using (HttpResponseMessage response = await client.GetAsync(uri, cancellationToken))
                {
                    response.EnsureSuccessStatusCode();
                    return await response.Content.ReadAsStringAsync();
                }
            }
        } // end of GetAsync method

    } // end of class Program
}

Yanıt alma

Her çağrı aşağıdaki biçimde bir JSON yanıtı döndürür:

[{"Id":"{tenantId}","Name":"Contoso","Roles":null}]

Azure Sphere genel API hata kodları

Azure Sphere genel API'sinde aşağıdaki hata kodları döndürülüyor:

400 - Hatalı İstek
404 - Bulunamadı
409 - Çakışma
410 - Gitti
429 - Çok Fazla İstek
500 - İç Sunucu Hatası

Hataları işleme yönergeleri aşağıdaki bölümde verilmiştir. Belirli hata kodları hakkında ayrıntılı bilgi için bkz. RFC 7231.

Hata işleme kılavuzu

4xx hataları: Hatalı biçimlendirilmiş istekler hatalara neden olabilir. İstek söz diziminizi ve geçirilen verileri denetleyin.

429 hataları: Azure Sphere hizmetlerini dağıtılmış hizmet reddi (DDoS) saldırılarına karşı korumak için, hizmetlerimize çok sayıda çağrıda bulunan cihazları, kullanıcıları veya kiracıları izler ve kısıtlarız. 429 hata iletisi, cihazın, kullanıcının veya kiracının kısa bir süre içinde Azure Sphere hizmetini çok fazla kez çağırmaya çalıştığını gösterir. Azure Sphere hizmetini yeniden çağırmadan önce lütfen bekleyin.

500 hata: Bazen geçici sunucu hataları oluşabilir. Sunucu hatası alırsanız, hatanın giderilip giderimediğini görmek için isteği birkaç kez yeniden deneyin.

CORS desteği

Bu sürümde Bölgeler Arası Kaynak Paylaşımı (CORS) desteklenmez.