Azure API Management'ı (APIM) GraphQL için Doku API'siyle tümleştirme

Azure API Management'ın (APIM) GraphQL için Microsoft Fabric API'siyle tümleştirilmesi, güçlü ölçeklenebilirlik ve güvenlik özellikleri sağlayarak API'nizin özelliklerini önemli ölçüde artırır. APIM, Yapı API'si yapılandırmanızı değiştirmeden kimlik yönetimi, hız sınırlama, yanıt önbelleğe alma, tehdit koruması ve merkezi izleme gibi gelişmiş özellikler ekleyen kurumsal düzeyde bir ağ geçidi işlevi görür.

GraphQL isteklerinizi APIM aracılığıyla yönlendirerek, artan trafiği işleyecek şekilde ölçeklendirebilir, gelişmiş güvenlik ilkeleri uygulayabilir ve kuruluşunuz genelindeKI API kullanım desenlerine görünürlük sağlayabilirsiniz.

Bu makale, APIM'yi GraphQL için Doku API'siyle tümleştirme, yönetilen kimlik doğrulamasını yapılandırma ve önbelleğe alma ve hız sınırlama ilkeleri uygulama konusunda size yol gösterir.

GraphQL ile Azure API Management'ı kimler kullanır?

APIM tümleştirmesi şunların için değerlidir:

Kurumsal mimarlar, kuruluş genelinde erişim için merkezi, yönetilen bir API ağ geçidi aracılığıyla Fabric verilerini erişime açan
Fabric kapasitesini ve verilerini korumak için hız sınırlama, önbelleğe alma ve güvenlik ilkeleri uygulayan Fabric yöneticileri
Gelişmiş kimlik doğrulama, yetkilendirme ve tehdit korumasına ihtiyaç duyan BT güvenlik ekipleri için Fabric veri erişimi
Departmanlar ve iş birimlerinde birden çok Fabric GraphQL API'sini yöneten ve yöneten platform ekipleri

Doku GraphQL API'leriniz için hız sınırlama, önbelleğe alma, güvenlik ilkeleri ve merkezi idare gibi kurumsal düzeyde API yönetim özelliklerine ihtiyacınız olduğunda APIM tümleştirmesini kullanın.

Önkoşullar

Başlamadan önce şunların olduğundan emin olun:

GraphQL için bir Fabric API'si zaten oluşturulmuştur. Aksi takdirde GraphQL için API Oluşturma konusuna bakabilir veya GraphQL portalında Örnek SQL Veritabanıyla Başlat seçeneğini kullanabilirsiniz.
Azure API Management örneği. Kurulum yönergeleri için bkz. API Management örneği oluşturma
Yönetilen kimlik oluşturma ve APIM ilkelerini yapılandırma izinleri

Azure API Management'a Fabric GraphQL API ekleme

APIM'yi Doku ile tümleştirmenin ilk adımı GraphQL API'nizi Azure API Management'a aktarmaktır. Bu işlem, Doku veri kaynaklarınıza bağlantıyı sürdürürken istekleri APIM aracılığıyla yönlendiren bir ara sunucu oluşturur. API'yi içeri aktararak kimlik doğrulama ilkeleri, önbelleğe alma ve hız sınırlama gibi kurumsal özellikler eklemenin temelini oluşturursunuz.

İçeri aktarma işlemi, Doku GraphQL API'nizden iki bilgi parçası gerektirir: uç nokta URL'si (APIM istekleri gönderir) ve şema dosyası (API yapısını ve kullanılabilir işlemleri tanımlar).

GraphQL API ayrıntılarınızı dışarı aktarma

İlk olarak, Doku GraphQL API'nizden gerekli bilgileri toplayın:

Doku portalında GraphQL API'nizi açma
Şeritte Uç noktayı kopyala'yı seçerek API'nizin URL'sini alın
GraphQL şema dosyasını yerel cihazınıza indirmek için Şemayı dışarı aktar'ı seçin

API'yi APIM'ye aktarma

Uç nokta URL'niz ve şema dosyanız hazırken, graphQL API'sini APIM'ye kaydedebilirsiniz. Bu, APIM'nin istekleri doğrulamak, belge oluşturmak ve ilkeleri uygulamak için kullandığı bir API tanımı oluşturur. Karşıya yüklediğiniz şema, istemcilerin yürütebileceği sorguları ve mutasyonları tanımlar.

Azure portalında API Management örneğine gidin
API'ler>+ API Ekle'yi seçin
GraphQL simgesini seçin
GraphQL'den oluştur şeması ekranında şunları sağlayın:
- Görünen ad: API için kullanıcı dostu ad
- Ad: API tanımlayıcısı
- GraphQL API uç noktası: Fabric'den kopyaladığınız URL uç noktası
Şemayı karşıya yükle'yi seçin ve indirdiğiniz şema dosyasını seçin

Yönetilen kimlik doğrulamasını yapılandırma

GraphQL API'niz APIM'de kayıtlı olduğuna göre, APIM'nin Doku ile kimlik doğrulamasını yapılandırmanız gerekir. Yönetilen kimlikler, APIM yapılandırmanızda kimlik bilgilerini depolama gereksinimini ortadan kaldıran güvenli, parolasız bir kimlik doğrulama yöntemi sağlar. Azure, kimlik yaşam döngüsünü otomatik olarak yönetir ve belirteç alımını gerçekleştirir, bu da bu yaklaşımı geleneksel kimlik doğrulama yöntemlerine göre hem daha güvenli hem de daha kolay yönetilebilir hale getirir.

Kimlik doğrulama kurulumu üç ana adımdan oluşur: Azure'da yönetilen kimlik oluşturma , Doku çalışma alanınıza ve veri kaynaklarınıza erişme izinleri verme ve APIM'yi Doku'ya istekte bulunurken bu kimliği kullanacak şekilde yapılandırma.

Yönetilen bir kimlik oluşturun ve atayın

İlk olarak, APIM'nin kimlik doğrulaması için kullandığı yönetilen kimliği oluşturun:

Azure portalında kullanıcı tarafından atanan bir yönetilen kimlik oluşturun.
Yönetilen kimliğin İstemci Kimliğini not edin; ilke yapılandırması için istemci kimliğine ihtiyacınız vardır.

"Fabric'de yönetilen kimlik izinlerini ver"

Yönetilen kimliği oluşturduktan sonra, onun Fabric kaynaklarınıza erişmesi için izin vermelisiniz. Yönetilen kimliğin hem GraphQL API öğesinin kendisine hem de bağlandığınız tüm veri kaynaklarına (göl evleri veya ambarlar gibi) erişmesi gerekir. Kimliği çalışma alanı üyesi olarak eklemek en basit yaklaşımdır çünkü çalışma alanındaki tüm öğelere aynı anda erişim verir.

GraphQL API'nizi içeren Fabric çalışma alanını açın
Erişimi yönet'i seçin
En az Katkıda Bulunan rolüne sahip yönetilen kimliği (örneğin apim-id) ekleyin

Tavsiye

Daha ayrıntılı denetim için çalışma alanı düzeyinde erişim yerine doğrudan tek tek Yapı öğelerine (API ve veri kaynaklarına) izin vekleyebilirsiniz. API'niz çoklu oturum açma (SSO) kimlik doğrulaması kullanıyorsa ayrıntılı denetim özellikle önemlidir. Daha fazla bilgi için bkz. Kimlik doğrulaması ve izin özeti.

APIM'yi yönetilen kimliği kullanacak şekilde yapılandırma

Doku'da verilen izinlerle APIM'ye hangi yönetilen kimliğin kullanılacağını bildirmeniz gerekir. Bu ilişkilendirme, APIM'nin kimlik doğrulaması yaparak Fabric GraphQL API'nize istekte bulunmasını sağlar.

Azure portalında APIM örneğine gidin
Güvenlik>Tarafından Yönetilen kimlikler'e gidin
Daha önce oluşturduğunuz kullanıcı tarafından atanan yönetilen kimliği ekleyin

Kimlik doğrulama ilkesi ekleme

Son kimlik doğrulama adımı, yönetilen kimliği kullanarak bir erişim belirteci alıp bu belirteci Fabric'e yönelik isteklere ekleyen bir API Yönetimi politikası eklemektir. Bu ilke, belirteç alma ve yenileme işlemlerini otomatik olarak işleyip her istekte çalışır. İlke, Fabric API kaynağının belirtecini almak için authentication-managed-identity öğesini kullanır ve ardından bunu Authorization üstbilgisine ekler.

APIM'deki GraphQL API'nizde API İlkeleri sekmesini seçin
Gelen işleme ilkesini düzenleme

altına <inbound><base/>aşağıdaki XML'yi ekleyin:

<authentication-managed-identity 
    resource="https://analysis.windows.net/powerbi/api" 
    client-id="YOUR-MANAGED-IDENTITY-CLIENT-ID" 
    output-token-variable-name="token-variable" 
    ignore-error="false" />
<set-header name="Authorization" exists-action="override">
    <value>@("Bearer " + (string)context.Variables["token-variable"])</value>
</set-header>

YOUR-MANAGED-IDENTITY-CLIENT-ID ifadesini yönetilen kimliğinizin İstemci Kimliği ile değiştirin
Politikayı kaydet

Bağlantıyı test edin

Önbelleğe alma ve hız sınırlama eklemeye devam etmeden önce, kimlik doğrulama kurulumunun düzgün çalıştığını doğrulayın. Test artık daha sonra karşılaştığınız sorunların kimlik doğrulaması yapılandırmasıyla ilgili olmamasını sağlar.

APIM'de GraphQL API'nize gidin
Test sekmesine gitme
Bağlantının çalıştığını onaylamak için örnek bir sorgu veya mutasyon yürütme

Yanıt önbelleğe almayı yapılandırma

Yanıt önbelleğe alma, API çağıranların gecikme süresini önemli ölçüde azaltır ve Doku veri kaynaklarınızdaki arka uç yükünü azaltır. APIM yerleşik önbelleğe almayı veya dış Redis örneklerini destekler. GraphQL API'leri için önbelleğe alma, önbellek anahtarı olarak istek gövdesini (GraphQL sorgusu) kullanır ve aynı sorguların önbelleğe alınmış yanıtlar döndürmesini sağlar.

GraphQL yanıtlarını önbelleğe almanın avantajları:

Azaltılmış gecikme süresi: Önbelleğe alınan yanıtlar Doku'yu sorgulamadan anında döndürülüyor
Daha düşük kapasite tüketimi: Dokuya yönelik daha az istek CU (kapasite birimi) kullanımını azaltır
Daha iyi ölçeklenebilirlik: Arka uç yükünü artırmadan daha fazla eşzamanlı kullanıcıyı işleme

Önbelleğe alma ilkesi ekleme

Önbelleğe alma işlemini uygulamak için, mevcut kimlik doğrulama ilkesini değiştirerek önbellek arama ve depolama mantığını ekliyorsunuz. İlke, istekleri Fabric'e iletmeden önce önbelleğe alınmış yanıtları denetler ve ileride kullanmak üzere başarılı yanıtları depolar. Bu eksiksiz ilke örneği, kimlik doğrulaması ve önbelleğe alma işleminin birlikte nasıl çalıştığını gösterir:

<policies>
    <inbound>
        <base />
        <!-- Authenticate with managed identity -->
        <authentication-managed-identity 
            resource="https://analysis.windows.net/powerbi/api" 
            client-id="YOUR-MANAGED-IDENTITY-CLIENT-ID" 
            output-token-variable-name="token-variable" 
            ignore-error="false" />
        <set-header name="Authorization" exists-action="override">
            <value>@("Bearer " + (string)context.Variables["token-variable"])</value>
        </set-header>
        <!-- Check if response is cached -->
        <cache-lookup-value 
            key="@(context.Request.Body.As<String>(preserveContent: true))" 
            variable-name="cachedResponse" 
            default-value="not_exists" />
    </inbound>
    <backend>
        <!-- Only forward request if not cached -->
        <choose>
            <when condition="@(context.Variables.GetValueOrDefault<string>("cachedResponse") == "not_exists")">
                <forward-request />
            </when>
        </choose>
    </backend>
    <outbound>
        <base />
        <choose>
            <!-- Return cached response if it exists -->
            <when condition="@(context.Variables.GetValueOrDefault<string>("cachedResponse") != "not_exists")">
                <set-body>@(context.Variables.GetValueOrDefault<string>("cachedResponse"))</set-body>
            </when>
            <!-- Cache successful responses for 60 seconds -->
            <when condition="@((context.Response.StatusCode == 200) && (context.Variables.GetValueOrDefault<string>("cachedResponse") == "not_exists"))">
                <cache-store-value 
                    key="@(context.Request.Body.As<String>(preserveContent: true))" 
                    value="@(context.Response.Body.As<string>(preserveContent: true))" 
                    duration="60" />
            </when>
        </choose>
    </outbound>
    <on-error>
        <base />
    </on-error>
</policies>

Bu ilke nasıl çalışır:

Gelen: Yönetilen kimlikle kimlik doğrulaması yapar ve yanıtın GraphQL sorgusuna göre önbelleğe alınıp alınmadığını denetler
Backend: Önbelleğe alınmış bir yanıt varsa isteği Fabric'e iletmeyi atlar
Giden: Önbelleğe alınmış yanıtları döndürür veya 60 saniye boyunca yeni başarılı yanıtları önbelleğe alır

Önbelleğe alma işleminin çalıştığını doğrulama

İsteklerin önbelleğe alındığını onaylamak için:

APIM'de aynı GraphQL sorgusunu iki kez yürütün
Önbellek isabetlerini görmek için API çağrısını izleyin

Önbellek süresini iyileştirme

Örnekte 60 saniyelik önbellek süresi kullanılır. Veri yenileme gereksinimlerinize göre süreyi ayarlayın:

Yüksek frekanslı güncelleştirmeler: Sık değişen veriler için daha kısa süreler (10-30 saniye) kullanın
Statik veya başvuru verileri: Seyrek değişen veriler için daha uzun süreler (5-60 dakika) kullanın
Gerçek zamanlı gereksinimler: Her zaman en son verileri döndürmesi gereken sorguları önbelleğe alma

Önbellek geçersiz kılınması ve dış Redis yapılandırması gibi gelişmiş önbelleğe alma senaryoları için bkz. APIM önbelleğe alma ilkeleri.

Hız sınırlaması

bir istemcinin belirli bir zaman aralığında gerçekleştirebileceği API çağrılarının sayısını sınırlayabilirsiniz. Aşağıda, belirli bir kullanıcı için her 60 saniyede bir en fazla iki çağrıyı zorunlu kılan, aşağıda <inbound><base/> ekleyebileceğiniz bir örnek hız sınırlama ilkesi girişi verilmiştir:

<rate-limit-by-key 
    calls="2" 
    renewal-period="60" 
    counter-key="@(context.Request.Headers.GetValueOrDefault("Authorization"))" 
    increment-condition="@(context.Response.StatusCode == 200)" 
    remaining-calls-variable-name="remainingCallsPerUser" />

Bir dakikada ikiden fazla API çağrısı gönderdikten sonra bir hata iletisi alırsınız:

{
    "statusCode": 429,
    "message": "Rate limit is exceeded. Try again in 58 seconds."
}

APIM'de hız sınırlama ilkelerini yapılandırma hakkında daha fazla bilgi için belgelere bakın.

En iyi yöntemler

APIM'yi GraphQL için Doku API'siyle tümleştirirken şu önerileri izleyin:

Security

Yönetilen kimlikleri kullanma: Kimlik doğrulaması için API anahtarları veya bağlantı dizeleri yerine yönetilen kimlikleri tercih edin
En az ayrıcalık uygulama: Yönetilen kimlik için yalnızca gereken en düşük izinleri verme
Yalnızca HTTPS'yi etkinleştirme: APIM'yi HTTP isteklerini reddedecek ve HTTPS'yi zorunlu kacak şekilde yapılandırma
Girişleri doğrulama: GraphQL sorgularını Fabric’e iletmeden önce doğrulamak için APIM ilkelerini kullanın

Performance

Sık erişilen verileri önbelleğe alma: Yaygın sorguları tanımlama ve uygun önbellek sürelerini ayarlama
Önbellek isabet oranlarını izleme: Önbellek verimliliğini izlemek için APIM analizini kullanma
Hız sınırlarını iyileştirme: Kapasite koruması ile kullanıcı deneyimini dengeleme
Bölgesel dağıtımı kullanma: APIM'yi Doku kapasitenizle aynı bölgede dağıtma

İzleme ve idare

Tanılamayı etkinleştirme: API kullanımını izlemek için APIM tanılama günlüğünü yapılandırma
Uyarıları ayarlama: Hız sınırı ihlalleri ve hataları için uyarılar oluşturma
API'lerinizi sürümleme: Hataya neden olan değişiklikleri yönetmek için APIM sürümü oluşturma özelliğini kullanın
API'lerinizi belgeleme: API belgeleri sağlamak için APIM'nin geliştirici portalını kullanma

Maliyet optimizasyonu

Doğru boyut hız sınırları: Kapasite katmanınızla uyumlu sınırlar ayarlayın
Kapasite tüketimini izleme: Hem APIM hem de Doku kapasite kullanımını izleme
Önbelleğe alma özelliğini stratejik olarak kullanma: Kapasite tasarrufu ile yenilik gereksinimlerini dengeleme
Kullanım desenlerini gözden geçirme: En çok kaynağı tüketen sorguları düzenli olarak analiz etme

Özet

GraphQL için Microsoft Fabric API'sini Azure API Management ile tümleştirmek, Fabric'in güçlü veri özelliklerini APIM'nin kurumsal sınıf API ağ geçidi özellikleriyle bir araya getirir. Bu birleşimde aşağıdakiler sağlanır:

Gelişmiş güvenlik: Yönetilen kimlik doğrulaması, tehdit koruması ve ilke tabanlı erişim denetimi
Geliştirilmiş ölçeklenebilirlik: Birden çok arka uçta yanıt önbelleğe alma, hız sınırlama ve yük dağıtımı
Daha iyi performans: Önbelleğe alma ve iyileştirilmiş istek yönlendirmesi sayesinde daha düşük gecikme süresi
Merkezi idare: Birden çok API arasında birleşik izleme, sürüm oluşturma ve yönetim
Maliyet denetimi: Hız sınırlama ve önbelleğe alma, Kumaş kapasitesi tüketimini azaltır

Bu makaledeki yapılandırma adımlarını ve en iyi yöntemleri izleyerek, kuruluşunuz genelindeki üretim iş yüklerini destekleyen sağlam, güvenli ve ölçeklenebilir bir API katmanı oluşturabilirsiniz.

Geri Bildirim

Bu sayfayı yararlı buldunuz mu?

Last updated on 2026-01-20