Rozwiązywanie problemów z użyciem konstruktora interfejsu API danych dla baz danych platformy Azure

Ten artykuł zawiera rozwiązania typowych błędów, które mogą wystąpić podczas korzystania z konstruktora interfejsu API danych dla baz danych platformy Azure.

Ogólny punkt końcowy: błąd HTTP 400 "Nieprawidłowe żądanie"

W poniższych sekcjach opisano przyczyny i rozwiązania błędu HTTP 400 "Nieprawidłowe żądanie".

Nieprawidłowy punkt końcowy konstruktora interfejsu API danych

Podstawa składnika ścieżki adresu URL jest mapowane na punkt końcowy REST lub GraphQL konstruktora interfejsu API danych. Gdy podstawa składnika ścieżki adresu URL nie jest zgodna z wartością ustawioną w konfiguracji środowiska uruchomieniowego konstruktora interfejsu API danych, konstruktor interfejsu API danych zwraca błąd HTTP 400 "Nieprawidłowe żądanie".

Ścieżki główne dla punktów końcowych GraphQL i REST można skonfigurować w runtime sekcji konfiguracji środowiska uruchomieniowego konstruktora interfejsu API danych. Należy użyć wartości, aby rozpocząć ścieżki adresu URL dla punktów końcowych REST i GraphQL.

Na przykład następujące zestawy /api konfiguracji jako ścieżka główna punktu końcowego REST i /graphql jako katalog główny punktu końcowego GraphQL:

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

Dlatego wartości, które należy użyć na początku ścieżek URL dla punktów końcowych REST i GraphQL, to:

/api/<entity>

/graphql

Problem z konfiguracją połączeń bazy danych usługi Static Web Apps

W przypadku korzystania z konstruktora interfejsu API danych z funkcją połączeń bazy danych usługi Static Web Apps występuje błąd "Kod stanu odpowiedzi nie wskazuje powodzenia: 400 (nieprawidłowe żądanie)" w treści odpowiedzi:

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

Ten błąd może wskazywać na problem z konfiguracją podaną podczas łączenia bazy danych.

Aby rozwiązać ten problem, wykonaj poniższe czynności:

1. Sprawdź, czy poświadczenia bazy danych są prawidłowe w narzędziu, takim jak Azure Data Studio lub SQL Server Management Studio (SSMS).
2. Odłącz/połącz ponownie połączoną bazę danych.

Jeśli nadal wystąpi błąd, upewnij się, że wybierzesz pozycję Zezwalaj usługom i zasobom platformy Azure na dostęp do tego serwera dla pozycji Wyjątki na stronie sieciowej zasobu usługi Azure Database. Ta opcja umożliwia skonfigurowanie zapory tak, aby zezwalała na połączenia z adresów IP przydzielonych do dowolnej usługi lub zasobu platformy Azure, w tym połączeń z subskrypcji innych klientów.

Punkt końcowy REST: błąd HTTP 404 "Nie znaleziono"

Jeśli żądany adres URL wskazuje trasę, która nie jest skojarzona z żadną jednostką, zwracany jest błąd HTTP 404. Domyślnie nazwa jednostki jest również nazwą trasy. Jeśli na przykład skonfigurujesz przykładową Todo jednostkę w pliku konfiguracji, tak jak w poniższym przykładzie:

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

Todo Następnie jednostka jest osiągalna za pośrednictwem następującej trasy:

/<rest-route>/Todo

Jeśli określisz rest.path właściwość w konfiguracji jednostki na todowartość , jak pokazano w poniższym przykładzie:

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

Następnie trasa Todo adresu URL jednostki to todo, z wszystkimi małymi literami odpowiadającymi dokładnej wartości zdefiniowanej w konfiguracji środowiska uruchomieniowego:

/<rest-route>/todo

Punkt końcowy graphQL: błąd HTTP 400 "Nieprawidłowe żądanie"

Żądanie GraphQL powoduje błąd HTTP 400 "Nieprawidłowe żądanie" za każdym razem, gdy żądanie GraphQL jest niepoprawnie skonstruowane. Może to być spowodowane nieistnienym polem jednostki lub błędną nazwą jednostki. Konstruktor interfejsu API danych zwraca opisowy błąd i szczegóły błędu w ładunku odpowiedzi.

Po wysłaniu GET żądania do punktu końcowego graphQL treść odpowiedzi zwróconych stanów błędu: "Zapytanie parametru lub identyfikator parametru musi być ustawiony". Pamiętaj, aby wysłać żądania GraphQL przy użyciu protokołu HTTP POST.

Punkt końcowy graphQL: błąd HTTP 404 "Nie znaleziono"

Upewnij się, że żądanie GraphQL jest wysyłane do skonfigurowanego punktu końcowego graphQL przy użyciu metody HTTP POST . Domyślnie trasa punktu końcowego GraphQL to /graphql.

Punkt końcowy GraphQL: błąd "Zapytanie typu obiektu musi zdefiniować co najmniej jedno pole, aby było prawidłowe"

Gdy uruchomienie konstruktora interfejsu API danych nie może wygenerować schematu GraphQL na podstawie konfiguracji środowiska uruchomieniowego, zostanie wyświetlony komunikat o błędzie:

Typ obiektu Zapytanie musi zdefiniować co najmniej jedno pole, aby było prawidłowe.

Specyfikacja GraphQL wymaga zdefiniowania co najmniej jednego Query obiektu w schemacie GraphQL. Należy sprawdzić, czy konfiguracja środowiska uruchomieniowego spełnia jeden z następujących warunków:

• Akcja jest zdefiniowana read dla co najmniej jednej jednostki z obsługą języka GraphQL. Język GraphQL jest domyślnie włączony dla jednostek, dlatego upewnij się, że nie zastosowano tego ograniczenia ryzyka do jednostki skonfigurowanej za pomocą polecenia {"graphql": false}.

• Gdy uwidaczniasz tylko procedury składowane, zdefiniuj { "graphql": { "operation": query" } } co najmniej jedną jednostkę procedury składowanej, która zastępuje domyślny typ mutationoperacji GraphQL procedury składowanej .

  Musisz mieć co najmniej jedną procedurę składowaną, która tylko odczytuje i nie modyfikuje danych. W przeciwnym razie generowanie schematu GraphQL kończy się niepowodzeniem z powodu pustego query pola w schemacie.

Punkt końcowy GraphQL: introspection nie działa z punktem końcowym GraphQL

Narzędzia, które obsługują narzędzie GraphQL, zwykle używają introspekcji schematu GraphQL bez konieczności dodatkowej konfiguracji. Upewnij się, że właściwość konfiguracji allow-introspection środowiska uruchomieniowego jest ustawiona na true runtime.graphql wartość w sekcji konfiguracji. Na przykład:

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

Punkt końcowy GraphQL: "Operacja <mutacji operation_name> powiodła się, ale bieżący użytkownik nie ma autoryzacji do wyświetlania odpowiedzi z powodu braku uprawnień do odczytu"

W przypadku operacji mutacji GraphQL w celu otrzymania prawidłowej odpowiedzi należy skonfigurować uprawnienia do odczytu oprócz odpowiedniego typu operacji mutacji — tworzenia, aktualizowania i usuwania. Jak sugeruje błąd, operacja mutacji (create/update/delete) zakończyła się pomyślnie w warstwie bazy danych, ale brak uprawnień do odczytu spowodował, że konstruktor interfejsu API danych zwrócił komunikat o błędzie. Dlatego należy skonfigurować uprawnienia do odczytu w roli "Anonimowe" lub rolę, z którą chcesz wykonać operację mutacji.

Błąd ogólny: błąd HTTP 500 zwracany przez żądania

Błędy HTTP 500 wskazują, że konstruktor interfejsu API danych nie może prawidłowo działać w bazie danych zaplecza. Upewnij się, że spełniono następujące warunki:

• Konstruktor interfejsu API danych nadal może łączyć się ze skonfigurowaną bazą danych.
• Obiekty bazy danych używane przez konstruktora interfejsu API danych są nadal dostępne i dostępne.

Aby zezwolić konstruktorowi interfejsu API danych na zwracanie określonych błędów bazy danych w odpowiedziach, ustaw runtime.host.mode właściwość konfiguracji na development:

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

Domyślnie konstruktor interfejsu API danych jest uruchamiany z ustawioną runtime.host.mode wartością production. W production trybie konstruktor interfejsu API danych nie zwraca szczegółowych błędów w ładunku odpowiedzi.

W obu development production trybach konstruktor interfejsu API danych zapisuje szczegółowe błędy w konsoli, aby ułatwić rozwiązywanie problemów.

Ogólne błędy spowodowane nieuwierzytelnionymi i nieautoryzowanymi żądaniami

Błąd HTTP 401 "Brak autoryzacji"

Błędy HTTP 401 występują, gdy punkt końcowy i jednostka, do którego uzyskuje się dostęp, wymagają uwierzytelniania, a obiekt żądającego nie dostarcza prawidłowych metadanych uwierzytelniania w żądaniu.

Podczas konfigurowania konstruktora interfejsu API danych do korzystania z uwierzytelniania identyfikatora Entra firmy Microsoft żądania powodują błędy HTTP 401, gdy podany token elementu nośnego (dostęp) jest nieprawidłowy. Token dostępu może być nieprawidłowy z wielu powodów. Oto niektóre z nich:

• Token dostępu wygasł.
• Token dostępu nie jest przeznaczony dla interfejsu API konstruktora interfejsu API danych (niewłaściwi odbiorcy tokenu dostępu).
• Token dostępu nie jest tworzony przez oczekiwany urząd (nieprawidłowy wystawca tokenu dostępu).

Aby rozwiązać ten błąd, upewnij się, że zostały spełnione następujące warunki:

• Token dostępu jest generowany przy użyciu issuer wartości zdefiniowanej authentication w sekcji konfiguracji środowiska uruchomieniowego.

• Token dostępu jest generowany dla audience wartości zdefiniowanej authentication w sekcji konfiguracji środowiska uruchomieniowego.

Oto przykładowa konfiguracja:

"authentication": {
    "provider": "AzureAD",
    "jwt": {
        "issuer": "https://login.microsoftonline.com/24c24d79-9790-4a32-bbb4-a5a5c3ffedd5/v2.0/",
        "audience": "b455fa3c-15fa-4864-8bcd-88fd83d686f3"
    }
}

Musisz wygenerować prawidłowy token dla zdefiniowanej grupy odbiorców. Korzystając z interfejsu wiersza polecenia platformy Azure, możesz uzyskać token dostępu, określając odbiorców w parametrze resource :

az account get-access-token --resource "b455fa3c-15fa-4864-8bcd-88fd83d686f3"

Błąd HTTP 403 "Zabronione"

Jeśli wyślesz uwierzytelnione żądanie przy użyciu integracji usługi Static Web Apps lub identyfikatora Entra firmy Microsoft, może zostać wyświetlony błąd HTTP 403 "Zabronione". Ten błąd wskazuje, że próbujesz użyć roli, która nie istnieje w pliku konfiguracji.

Ten błąd występuje, gdy:

• Nie podajesz nagłówka X-MS-API-ROLE HTTP określającego nazwę roli.

  Ponieważ uwierzytelnione żądania są wykonywane w kontekście roli authenticated systemu domyślnie, ten scenariusz ma zastosowanie tylko wtedy, gdy używasz roli niesystemowej (nie authenticated ani anonymous).

• Rola zdefiniowana w nagłówku X-MS-API-ROLE nie jest skonfigurowana w pliku konfiguracji środowiska uruchomieniowego konstruktora interfejsu API danych.

• Rola zdefiniowana w nagłówku X-MS-API-ROLE nie jest zgodna z rolą w tokenie dostępu.

Na przykład w poniższym pliku konfiguracji środowiska uruchomieniowego rola role1 jest zdefiniowana, dlatego należy podać X-MS-API-ROLE nagłówek HTTP z wartością role1.

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

Informacje

• Rozwiązywanie problemów z instalacją konstruktora interfejsu API danych dla baz danych platformy Azure
• Znane problemy w repozytorium GitHub Azure/data-api-builder

Następny krok

Jeśli problem nie został rozwiązany, prześlij opinię lub zgłoś go w dyskusjach dotyczących narzędzia data-api-builder.

Skontaktuj się z nami, aby uzyskać pomoc

Jeśli masz pytania lub potrzebujesz pomocy, utwórz wniosek o pomoc techniczną lub zadaj pytanie w społeczności wsparcia dla platformy Azure. Możesz również przesłać opinię o produkcie do społeczności opinii na temat platformy Azure.