Aracılığıyla paylaş

GraphQL introspection ve şema dışa aktarma için Fabric API

GraphQL için Doku API'nizle uygulama oluştururken veya dış araçları tümleştirirken API'nizin yapısını, hangi türlerin kullanılabilir olduğunu, hangi alanları içerdiğini ve birbirleriyle ilişkilerini anlamanız gerekir. İstemci kodu oluştururken, belge oluştururken veya API yönetim araçlarını yapılandırırken şema tanımınıza erişmek önemlidir.

GraphQL için Fabric API'si şema bilgilerini almak için iki tamamlayıcı mekanizma sağlar: programlı çalışma zamanında sorgular için içgözlem ve tam şema dosyasını elde etmek için şema dışarı aktarma. Her iki yöntem de aynı temel şemaya erişmenizi sağlar, ancak her ikisi de farklı iş akışlarına ve kullanım örneklerine hizmet eder.

Tavsiye

İçe dönük işlemlerin nasıl çalıştığını görmek mi istiyorsunuz? Yerel Model Bağlam Protokolü (MCP) sunucusuyla AI Aracılarını GraphQL için Doku API'sine bağlama öğreticisini deneyin. Bu uygulamalı kılavuz, yapay zeka aracılarının doğal dil kullanarak Doku verilerinizi otomatik olarak bulmak ve sorgulamak için içgiriş özelliğini nasıl kullandığını gösterir.

İç gözlem ve şema dışa aktarmayı kimler kullanır?

Kendini sorgulama ve şema dışa aktarma şunlar için değerlidir:

  • Fabric verilerini kullanan ve tür güvenli kod oluşturması gereken uygulama geliştiricileri istemci oluşturuyor.
  • Fabric çalışma alanı katkıcıları mevcut veri yapılarını anlama ve veri erişimini test etme
  • Otomatik tamamlama ve Doku GraphQL API'leri için IntelliSense sağlayan geliştirme araçları ve IDE'ler
  • Fabric GraphQL trafiğini kurumsal düzeyde yönlendiren ve güvenliğini sağlayan Azure API Management tümleştirmeleri
  • Yapı yöneticileri kullanıma sunulan veri yapılarını denetleme ve erişim denetimlerini doğrulama
  • Model Bağlam Protokolü (MCP) kullanarak Fabric verilerini doğal bir şekilde bulmak ve sorgulamak için yapay zeka aracıları ve yardımcıları
  • Power Platform geliştiricileri, tümleştirme oluşturmadan önce Fabric veri şemalarını anlayarak
  • CI/CD işlem hatları Doku GraphQL şema sürümlerini izleme ve ortamlar arasında uyumluluğu doğrulama

Geliştirme araçlarını çalıştırma, yapay zeka aracılarını etkinleştirme veya dinamik istemci özelliklerini uygulama gibi şema bilgilerini çalışma zamanında programlı olarak sorgulamanız gerektiğinde iç gözlem'i seçin. Çevrimdışı kullanım, sürüm denetimi, API ağ geçidi tümleştirmesi veya dış ekiplerle paylaşım için eksiksiz bir şema dosyasına ihtiyacınız olduğunda şema dışarı aktarmayı seçin.

  • introspection: GraphQL standardının bir parçası olan GraphQL introspection sistemini kullanarak şemanızı program aracılığıyla sorgulayabilirsiniz. İçe dönük sorgular türleri, alanları ve ilişkileri dinamik olarak keşfetmenize olanak sağlar ve birçok GraphQL geliştirme aracını destekler.

  • Şema dışarı aktarma: Çevrimdışı kullanım, paylaşım veya araç tümleştirmesi için şema tanımınızın tamamını içeren eksiksiz bir SDL (GraphQL Şema Tanımı Dili) dosyası indirin.

Içgözlem

Varsayılan olarak, GraphQL öğeleri için API'nizde içgörü devre dışı bırakılır. Bu ayar yalnızca çalışma alanı yöneticileri tarafından değiştirilebilir. Diğer tüm kullanıcılar devre dışı bir kaydırıcı görür.

İçe çekmeyi etkinleştirmek için:

  1. Üstteki menüden API Ayarları dişli simgesini seçin.

    Ayarlar dişli düğmesini gösteren portal çubuğunu gösteren ekran görüntüsü.

  2. Sol gezinti bölmesinden giriş sayfasını seçin.

    İçe dönük ayar kaydırıcısını gösteren ekran görüntüsü.

  3. İncelemeyi etkinleştirmek için anahtarı seçin. İçe aktarmayı etkinleştirmek, şema bilgilerini API uç noktasına erişimi olan tüm kullanıcılara gösterir.

  4. Bir onay iletişim kutusu görüntülenir. İntrospeksiyonu etkinleştirmek için Onayla veya onu devre dışı bırakmak için İptal seçin.

    İçe dönük onayı etkinleştir iletişim kutusunu gösteren ekran görüntüsü.

İçe dönük sorgu örneği

Şemadan kullanılabilir türleri almak için giriş sorgusunun hızlı bir örneği aşağıda verilmiştir:

  1. GraphQL düzenleyicisinde yeni bir sorgu oluşturun. Yeni bir sorgu sekmesi açmak için var olan sekmelerin yanındaki artı + simgesini seçin.

    GraphQL düzenleyicisindeki yeni sorgu düğmesini gösteren ekran görüntüsü.

  2. Düzenleyicide aşağıdaki introspection sorgusunu girin:

    query {
    __schema {
        types{
            name
        }
    }
}

  3. Sorguyu yürütmek için Çalıştır düğmesini seçin.

  4. Sonuçlar bölmesinde şemada tanımlanan tüm türlerin listesi görüntülenir.

    İçe dönük sorgu örneğini gösteren ekran görüntüsü.

İçe dönük sorgular büyük miktarda bilgi döndürebilir. İsteğinizi daha spesifik hale getirerek sorguladığınız şeyin kapsamını daraltabilirsiniz. Örneğin, tüm türleri sorgulamak yerine belirli bir türü sorgulayabilirsiniz:

query {
    __type(name: "ProductCategory") {
        name
        kind
        fields {
            name
            type {
                name
            }
        }
    }
}

Sorgu çalıştırıldığında türü hakkında ProductCategory ayrıntılı bilgiler döndürülüyor:

{
  "data": {
    "__type": {
      "name": "ProductCategory",
      "kind": "OBJECT",
      "fields": [
        {
          "name": "ProductCategoryID",
          "type": {
            "name": null
          }
        },
        {
          "name": "ParentProductCategoryID",
          "type": {
            "name": "Int"
          }
        },
        {
          "name": "Name",
          "type": {
            "name": "String"
          }
        },
        {
          "name": "rowguid",
          "type": {
            "name": null
          }
        },
        {
          "name": "ModifiedDate",
          "type": {
            "name": null
          }
        }
      ]
    }
  }
}

İç gözlem sonuçlarını işlerken sık kullanılan filtreleme desenleri şunlardır:

  • Çift alt çizgiyle (__) başlayan türleri, yani GraphQL sistem türlerini, dışlama.
  • Gibi belirli ön eklerle başlayan türleri dahil edin ProductCategory

Bu örnekler, herhangi bir GraphQL uygulamasında çalışan standart GraphQL introspection söz dizimini gösterir. Bu genel bakış, temel içgözlem desenlerini kapsar. İçgözlem sistemi, gelişmiş sorgulama teknikleri ve ek yetenekler hakkında ayrıntılı bilgi için GraphQL Foundation'ın içgözlem konusundaki resmi belgelerine bakın.

Şemayı dışarı aktarma

Şema tanımınızın tam, çevrimdışı bir kopyasına ihtiyacınız olduğunda, doğrudan Doku portalından şema dışarı aktarma özelliğini kullanın. GraphQL için API'nizi açın ve araç çubuğundan Şemayı dışarı aktar'ı seçin. Tarayıcınız, tam şema tanımınızı içeren bir SDL (Şema Tanım Dili) dosyası indirir.

Şemayı dışarı aktar düğmesini gösteren ekran görüntüsü.

SDL dosyasını anlama

Dışarı aktarılan dosya, API'nizin türlerini, alanlarını ve ilişkilerini tanımlayan, insan tarafından okunabilir bir biçim olan GraphQL'in Şema Tanım Dili'ni (SDL) kullanır. SDL dosyası şunları içerir:

  • Veri varlıklarınızı kendi alanlarıyla temsil eden nesne türleri
  • Verilerin nasıl alındığını tanımlayan sorgu işlemleri
  • Verileri oluşturmak, güncelleştirmek veya silmek için mutasyon işlemleri
  • Verilen alan parametreleri giriş parametrelerini ve bunların türlerini belirtir.
  • Her bir öğe için belge sağlayan tür açıklamaları

Şema yapınızı gözden geçirmek için SDL dosyasını herhangi bir metin düzenleyicisinde açabilirsiniz. Bu özellikle API yüzeyini uygulamalarınızla tümleştirmeden önce tam olarak anlamak için kullanışlıdır.

Dışarı aktarılan şemayı kullanma

Dışarı aktarılan SDL dosyası için yaygın kullanım örnekleri şunlardır:

  • API ağ geçidi tümleştirmesi: Kimlik doğrulaması, hız sınırlama ve önbelleğe alma eklemek için Azure API Management'a aktarma
  • Geliştirme ortamı kurulumu: Visual Studio Code'da IntelliSense'i otomatik tamamlama ve doğrulama için yapılandırma
  • Sürüm denetimi: Zaman içinde şema gelişimini izlemek için Git'e veya diğer kaynak denetim sistemlerine işleme
  • Ekip işbirliği: API yapınızı anlaması gereken dış iş ortaklarıyla veya geliştirme ekipleriyle paylaşma
  • Kod oluşturma: TypeScript, C#, Java veya diğer dillerde tür açısından güvenli istemciler oluşturmak için GraphQL kod oluşturucularıyla kullanın
  • Belgeler: GraphQL Voyager veya GraphQL Markdown gibi araçları kullanarak API başvuru belgeleri oluşturma

Şema dışa aktarma, introspection sorgularından farklı olarak API'nizin iç gözlem ayarlarına bakılmaksızın introspection özelliğinin etkinleştirilmesini gerektirmez ve çalışır. Bu, şema tanımınıza yönetim ve geliştirme amacıyla erişmenin güvenilir bir yoludur.

Şema değişikliklerini yönetme

GraphQL şemaları, API'nize yeni türler, alanlar veya özellikler eklediğinizde zaman içinde gelişebilir. Şema değiştiğinde, dışarı aktarılan SDL dosyaları eski hale gelir. Şu uygulamaları göz önünde bulundurun:

  • Değişikliklerden sonra yeniden dışarı aktarma: Doku'da API şemanızı her değiştirdiğinizde yeni bir SDL dosyası indirin. Şema değişiklikleri veri kaynakları eklemeyi, kullanıma sunulan türleri değiştirmeyi veya alan tanımlarını güncelleştirmeyi içerir.
  • Sürüm denetimi: Dışarı aktarılan her şemayı açıklayıcı işleme iletileriyle kaynak denetim sisteminize işleyin. Bu, şema evriminin denetim kaydını oluşturur ve gerekirse geri almayı etkinleştirir.
  • İletişim: Dış ekipler veya uygulamalar şemanıza bağlıysa, önemli değişiklikleri onlara bildirin. GraphQL mevcut sorguları bozmadan ek değişiklikleri desteklerken, alanları kaldırmak veya yeniden adlandırmak istemcileri etkileyebilir.
  • Otomasyon: CI/CD işlem hatlarında, belgelerin ve araçların API'nizle eşitlenmiş kalmasını sağlamak için dağıtım sürecinizin bir parçası olarak şema dışarı aktarmalarını otomatikleştirmeyi göz önünde bulundurun.

API şemasını değiştirmekle sorumlu olan kişi (genellikle veri mühendisi veya API geliştiricisi) Doku API'si ile buna bağlı dış sistemler arasında tutarlılığı korumak için güncelleştirilmiş şemayı dışarı aktarıp sürüme geçirmelidir.

İlgili içerik

  • Last updated on