Azure veritabanları için Veri API oluşturucusu kullanımıyla ilgili sorunları giderme

Bu makalede, Azure veritabanları için Veri API oluşturucusu'nu kullandığınızda oluşabilecek yaygın hataların çözümleri sağlanır.

Genel uç nokta: HTTP 400 "Hatalı İstek" hatası

Aşağıdaki bölümlerde HTTP 400 "Hatalı İstek" hatasının nedenleri ve çözümleri açıklanmaktadır.

Geçersiz Veri API'si oluşturucu uç noktası

URL yolu bileşeninin tabanı, Veri API'si oluşturucusunun REST veya GraphQL uç noktasına eşlenir. URL yolu bileşeninin tabanı Veri API'si oluşturucusunun çalışma zamanı yapılandırmasında ayarlanan değerle eşleşmediğinde, Veri API oluşturucusu HTTP 400 "Hatalı İstek" hatası döndürür.

GraphQL ve REST uç noktaları için kök yollarını, Veri API oluşturucusunun çalışma zamanı yapılandırmasının runtime bölümünde yapılandırabilirsiniz. REST ve GraphQL uç noktalarının URL yollarını başlatmak için değerleri kullanmanız gerekir.

Örneğin, aşağıdaki yapılandırma REST uç noktasının kök yolu ve /api GraphQL uç noktasının kökü olarak ayarlar/graphql:

"runtime": {
    "rest": {
      "enabled": true,
      "path": "/api"
    },
    "graphql": {
      "allow-introspection": true,
      "enabled": true,
      "path": "/graphql"
    },
    "...": "...",
}

Bu nedenle REST ve GraphQL uç noktaları için URL yollarının başında kullanmanız gereken değerler şunlardır:

/api/<entity>

/graphql

Not

Veritabanı Bağlantıları özelliğini kullanarak Statik Web Uygulamaları ile Veri API'si oluşturucusu kullanılırken, URL yolu ile /data-apibaşlar. Bu değerden sonra istediğiniz uç noktanın değerini ekleyebilirsiniz. Örneğin, /data-api/api/<entity> REST ve /data-api/graphql GraphQL için.

Statik Web Apps Veritabanı Bağlantıları yapılandırma sorunu

Data API builder'ı Statik Web Apps Veritabanı Bağlantıları özelliğiyle kullandığınızda, yanıt gövdesinde "Yanıt durum kodu başarıyı göstermiyor: 400 (Hatalı İstek)" hatasıyla karşılaşırsınız:

{"Message":"{\u0022Message\u0022:\u0022Response status code does not indicate success: 400 (Bad Request).\u0022,\u0022ActivityId\u0022:\u0022<GUID>\u0022}","ActivityId":"<GUID>"}

Bu hata, veritabanınızı bağlarken sağladığınız yapılandırmayla ilgili bir sorun olduğunu gösterebilir.

Bu sorunu çözmek için şu adımları izleyin:

1. Veritabanı kimlik bilgilerinizin sqlcmd veya SQL Server Management Studio (SSMS) gibi bir araçta geçerli olduğunu doğrulayın.
2. Bağlı veritabanının bağlantısını kaldırın/yeniden bağlayın.

Hatayla karşılaşmaya devam ederseniz Azure Veritabanı kaynağınızın ağ sayfasındaki Özel Durumlar için Azure hizmetlerinin ve kaynaklarının bu sunucuya erişmesine izin ver'i seçtiğinizden emin olun. Bu seçenek, güvenlik duvarını diğer müşterilerin aboneliklerinden gelen bağlantılar da dahil olmak üzere herhangi bir Azure hizmetine veya varlığına ayrılan IP adreslerinden bağlantılara izin verecek şekilde yapılandırmaktadır.

REST uç noktası: HTTP 404 "Bulunamadı" hatası

İstenen URL herhangi bir varlıkla ilişkili olmayan bir yolu işaret ederse, bir HTTP 404 hatası döndürülür. Varsayılan olarak, varlığın adı aynı zamanda yol adıdır. Örneğin, yapılandırma dosyasındaki örnek Todo varlığı aşağıdaki örnekte olduğu gibi yapılandırdıysanız:

"Todo": {
      "source": "dbo.todos",
      "...": "..."
    }

Ardından, Todo varlığa aşağıdaki yol üzerinden ulaşılabilir:

/<rest-route>/Todo

Varlık yapılandırmasında rest.path özelliğini todo olarak, aşağıdaki örnekte gösterildiği gibi belirtirseniz:

"Todo": {
    "source": "dbo.todos",
    "rest": {
      "path": "todo"
    },
    "...": "..."
  }

Ardından, Todo varlığının URL yolu, çalışma zamanı yapılandırmasında tanımlanan tam değerle eşleşen tüm küçük harflerle todo şeklindedir.

/<rest-route>/todo

GraphQL uç noktası: HTTP 400 "Hatalı İstek" hatası

GraphQL isteği, GraphQL isteği her yanlış oluşturulduğunda HTTP 400 "Hatalı İstek" hatasıyla sonuçlanır. Bunun nedeni var olmayan bir varlık alanı veya yanlış yazılmış bir varlık adı olabilir. Veri API oluşturucusu, yanıt yükünde açıklayıcı bir hata ve hata ayrıntıları döndürür.

GraphQL uç noktasına bir GET istek gönderdiğinizde, döndürülen hatanın yanıt gövdesi "Parametre sorgusunun veya parametre kimliğinin ayarlanması gerekir". GraphQL isteklerinizi HTTP POSTkullanarak gönderdiğinizden emin olun.

GraphQL uç noktası: HTTP 404 "Bulunamadı" hatası

GraphQL isteğinin HTTP POST yöntemi kullanılarak yapılandırılmış GraphQL uç noktasına gönderildiğinden emin olun. Varsayılan olarak, GraphQL uç noktası yolu şeklindedir /graphql.

GraphQL uç noktası: "Sorgu nesne türünün geçerli olması için en az bir alan tanımlaması gerekir" hatası

Veri API'si oluşturucusu başlatma işlemi çalışma zamanı yapılandırmanıza göre bir GraphQL şeması oluşturamadığında şu hata iletisini alırsınız:

Sorgu nesne türünün geçerli olması için en az bir alan tanımlaması gerekir.

GraphQL belirtimi, GraphQL şemasında en az bir Query nesnenin tanımlanmasını gerektirir. Çalışma zamanı yapılandırmanızın aşağıdaki koşullardan birini karşıladığını doğrulamanız gerekir:

• Eylem read en az bir GraphQL özellikli varlık için tanımlanır. GraphQL varlıklarda varsayılan olarak etkindir, bu nedenle bu önlemi{"graphql": false} yapılandırılmış bir varlığa uygulamadığınızdan emin olun.

• Yalnızca saklı yordamları kullanıma sunarken, varsayılan saklı yordam GraphQL işlem türünü geçersiz kılan en az bir saklı yordam varlığında { "graphql": { "operation": query" } } tanımlayın mutation.

  Yalnızca verileri okuyan ve değiştirmeyen en az bir saklı yordamınız olmalıdır. Aksi takdirde GraphQL şema oluşturma işlemi şemadaki boş query bir alan nedeniyle başarısız olur.

GraphQL uç noktası: Introspection, GraphQL uç noktasıyla çalışmıyor

GraphQL'i destekleyen araçlar, normalde ek bir kurulum gerektirmeden, GraphQL şeması sorgulamasını kullanır. Yapılandırma bölümünde çalışma zamanı yapılandırma özelliğini allow-introspectiontrue olarak ayarladığınızdan runtime.graphql emin olun. Örneğin:

"runtime": {
    "...": "...",
    "graphql": {
      "allow-introspection": true,
      "enabled": true,
      "path": "/graphql"
    },
    "...": "..."
}

GraphQL uç noktası: "Mutasyon işlemi <operation_name> başarılı oldu, ancak geçerli kullanıcı okuma izinlerinin olmaması nedeniyle yanıtı görüntüleme yetkisine sahip değil" hatası

GraphQL mutasyonu işleminin geçerli bir yanıt alması için ilgili mutasyon işlem türüne (oluşturma, güncelleştirme ve silme) ek olarak okuma izinleri yapılandırılmalıdır. Hatadan da anlaşılacağı gibi, mutasyon işlemi (oluşturma/güncelleştirme/silme) veritabanı katmanında başarılı oldu, ancak okuma izninin olmaması Data API oluşturucusunun hata iletisi döndürmesine neden oldu. Bu nedenle, "Anonim" rolünde veya mutasyon işlemini yürütmek istediğiniz rolde okuma izinlerini yapılandırdığınızdan emin olun.

Genel hata: İstekler tarafından döndürülen HTTP 500 hatası

HTTP 500 hataları, Veri API oluşturucusunun arka uç veritabanında düzgün çalışamadığını gösterir. Aşağıdaki koşulları karşıladığınızdan emin olun:

• Veri API'sini oluşturucusu yapılandırılan veritabanına bağlanmaya devam edebilir.
• Veri API oluşturucusu tarafından kullanılan veritabanı nesneleri hala kullanılabilir ve erişilebilir durumdadır.

Veri API oluşturucusunun yanıtlarda belirli veritabanı hataları döndürmesine izin vermek için yapılandırma özelliğini olarak runtime.host.modeayarlayındevelopment:

"runtime": {
    [...]
    "host": {
        "mode": "development",
        [...]
    }
}

Varsayılan olarak, Veri API oluşturucusu runtime.host.mode olarak ayarlanmıştır ve production ile çalışır. Veri API oluşturucusu production modunda yanıt yükünde ayrıntılı hatalar döndürmez.

Her iki development ve production modunda da, Veri API oluşturucu, sorun gidermeye yardımcı olmak için konsola hataları ayrıntılı olarak yazar.

Kimliği doğrulanmamış ve yetkisiz isteklerden kaynaklanan genel hatalar

HTTP 401 "Yetkisiz" hatası

HTTP 401 hataları, erişilen uç nokta ve varlık kimlik doğrulaması gerektirdiğinde ve istek sahibi isteğinde geçerli kimlik doğrulama meta verileri sağlamadığında oluşur.

Veri API'si oluşturucusunu Microsoft Entra Id kimlik doğrulamasını kullanacak şekilde yapılandırdığınızda, sağlanan taşıyıcı (erişim) belirteci geçersiz olduğunda istekleriniz HTTP 401 hatalarıyla sonuçlanır. Erişim belirteci birçok nedenden dolayı geçersiz olabilir. Bunlardan bazıları şunlardır:

• Erişim belirtecinin süresi doldu.
• Erişim belirteci, Veri API'si oluşturucusunun API'sine (yanlış erişim belirteci hedef kitlesi) yönelik değildir.
• Erişim belirteci beklenen yetkili (geçersiz erişim belirteci veren) tarafından oluşturulmaz.

Bu hatayı çözmek için aşağıdaki koşulları karşıladığından emin olun:

• Çalışma zamanı yapılandırmasının issuer bölümünde tanımlanan authentication değeri kullanarak bir erişim belirteci oluşturursunuz.

• Erişim anahtarınız, çalışma zamanı yapılandırmasının audience bölümünde tanımlı authentication değeri için oluşturulmuştur.

Aşağıda örnek bir yapılandırma verilmişti:

"authentication": {
    "provider": "AzureAD",
    "jwt": {
        "issuer": "https://login.microsoftonline.com/24c24d79-9790-4a32-bbb4-a5a5c3ffedd5/v2.0/",
        "audience": "00001111-aaaa-2222-bbbb-3333cccc4444"
    }
}

Tanımlı hedef kitle için geçerli bir belirteç oluşturmanız gerekir. Azure CLI'yı kullanırken, parametresinde resource hedef kitleyi belirterek bir erişim belirteci alabilirsiniz:

az account get-access-token --resource "00001111-aaaa-2222-bbbb-3333cccc4444"

HTTP 403 "Yasak" hatası

Statik Web Apps tümleştirmesi veya Microsoft Entra Id kullanarak kimliği doğrulanmış bir istek gönderirseniz, HTTP 403 "Yasak" hatası alabilirsiniz. Bu hata, yapılandırma dosyasında var olmayan bir rol kullanmaya çalıştığınızı gösterir.

Bu hata şu durumlarda oluşur:

• Rol adı belirten bir X-MS-API-ROLE HTTP üst bilgisi sağlamazsınız.

  Kimliği doğrulanmış istekler varsayılan olarak sistem rolü authenticated bağlamında yürütülür, bu senaryo yalnızca sistem dışı bir rol kullandığınızda (veya authenticateddeğilanonymous) geçerli olur.

• X-MS-API-ROLE üst bilgisinde tanımladığınız rol, Data API builder'ın çalışma zamanı yapılandırma dosyasında yapılandırılmamış.

• Üst bilgide X-MS-API-ROLE tanımladığınız rol, erişim belirtecindeki rolle eşleşmiyor.

Örneğin, aşağıdaki çalışma zamanı yapılandırma dosyasında rol role1 tanımlanır, bu nedenle X-MS-API-ROLE değeri ile bir role1 HTTP üstbilgisini sağlamalısınız.

Not

Rol adı eşleştirme, büyük/küçük harfe duyarlıdır.

"Todo": {
    "role": "role1",
    "actions": [ "*" ]
}

Kaynaklar

• Azure veritabanları için Veri API oluşturucusu yükleme sorunlarını giderme
• Azure/data-api-builder GitHub deposundaki bilinen sorunlar

Sonraki adım

Sorununuz çözülmezse, geri bildirim sağlayın veya data-api-builder Tartışmaları'nda bildirin.