Zaimportuj API GraphQL

DOTYCZY: Wszystkie warstwy usługi API Management

W usłudze API Management możesz dodać interfejs API GraphQL w jednym z dwóch modeli: przekazywanie do istniejącego punktu końcowego języka GraphQL lub zaimportować schemat GraphQL i utworzyć syntetyczny interfejs API GraphQL z niestandardowymi narzędziami rozpoznawania pól. Aby uzyskać więcej informacji, zobacz Omówienie języka GraphQL.

W tym artykule dowiesz się:

• Dodaj API GraphQL z przekazywaniem do swojej instancji API Management.
• Przetestuj API GraphQL.

Jeśli chcesz zaimportować schemat GraphQL i skonfigurować narzędzia rozpoznawania pól korzystające z punktów końcowych interfejsu API REST lub SOAP, zobacz Importowanie schematu GraphQL i konfigurowanie rozpoznawania pól.

Wymagania wstępne

• Wystąpienie usługi Azure API Management. Utwórz go, jeśli jeszcze tego nie zrobiono.

• Azure CLI, jeśli chcesz go użyć do zaimportowania API.

  • Użyj środowiska Bash w usłudze Azure Cloud Shell. Aby uzyskać więcej informacji, zobacz Get started with Azure Cloud Shell.

    

  • Jeśli wolisz uruchamiać polecenia referencyjne interfejsu wiersza polecenia lokalnie, zainstaluj interfejs wiersza polecenia platformy Azure. Jeśli korzystasz z systemu Windows lub macOS, rozważ uruchomienie interfejsu wiersza polecenia platformy Azure w kontenerze Docker. Aby uzyskać więcej informacji, zobacz Jak uruchomić interfejs wiersza polecenia platformy Azure w kontenerze platformy Docker.

    • Jeśli korzystasz z instalacji lokalnej, zaloguj się do interfejsu wiersza polecenia platformy Azure za pomocą polecenia az login. Aby ukończyć proces uwierzytelniania, wykonaj kroki wyświetlane w terminalu. Aby uzyskać inne opcje logowania, zobacz Uwierzytelnianie na platformie Azure przy użyciu interfejsu wiersza polecenia platformy Azure.

    • Gdy pojawi się monit, zainstaluj rozszerzenie Azure CLI przy pierwszym użyciu. Aby uzyskać więcej informacji na temat rozszerzeń, zobacz Używanie rozszerzeń i zarządzanie nimi za pomocą interfejsu wiersza polecenia platformy Azure.

    • Uruchom polecenie az version, aby znaleźć zainstalowane wersje i biblioteki zależne. Aby uaktualnić do najnowszej wersji, uruchom polecenie az upgrade.

• Program Azure PowerShell, jeśli chcesz go użyć do zaimportowania interfejsu API.

  • Jeśli zdecydujesz się używać programu Azure PowerShell lokalnie:
    • Zainstaluj najnowszą wersję modułu Az programu PowerShell.
    • Połącz się z kontem platformy Azure przy użyciu polecenia cmdlet Connect-AzAccount .
  • Jeśli zdecydujesz się używać usługi Azure Cloud Shell:
    • Aby uzyskać więcej informacji, zobacz Omówienie usługi Azure Cloud Shell .

Dodawanie interfejsu API graphQL

Portal

1. W portalu Azure przejdź do wystąpienia API Management.

2. W okienku po lewej stronie wybierz pozycję Interfejsy API>Interfejsy API.

3. Wybierz pozycję Dodaj interfejs API.

4. W obszarze Definiowanie nowego interfejsu API wybierz kafelek GraphQL .

   

5. W wyświetlonym oknie dialogowym wybierz pozycję Pełne, a następnie wprowadź wartości w wymaganych polach, zgodnie z opisem w poniższej tabeli.

   

   Wartość	opis
   Nazwa wyświetlana	Nazwa, za pomocą której zostanie wyświetlony interfejs API GraphQL.
   Nazwa/nazwisko	Nieprzetworzona nazwa interfejsu API GraphQL. Automatycznie wypełniana podczas wpisywania nazwy wyświetlanej.
   Typ GraphQL	Aby zaimportować z istniejącego punktu końcowego interfejsu API GraphQL, wybierz opcję Pass-through GraphQL.
   Punkt końcowy interfejsu API graphQL	Podstawowy adres URL z nazwą punktu końcowego interfejsu API GraphQL. Na przykład: https://example.com/your-GraphQL-name. Możesz również użyć wspólnego punktu końcowego SWAPI GraphQL, takiego jak https://swapi-graphql.azure-api.net/graphql, w celach demonstracyjnych.
   Przekazywanie schematu	Opcjonalnie wybierz, czy chcesz przekazać plik schematu, aby zastąpić schemat pobrany z punktu końcowego GraphQL (jeśli taki posiadasz).
   Opis	Dodaj opis interfejsu API.
   Schemat adresu URL	Wybierz schemat oparty na punkcie końcowym GraphQL. Wybierz jedną z opcji obejmujących schemat protokołu WebSocket (WS lub WSS), jeśli interfejs API GraphQL zawiera typ subskrypcji. Domyślnym wyborem jest HTTP(S)..
   Sufiks adresu URL interfejsu API	Dodaj sufiks adresu URL, aby zidentyfikować określony interfejs API w wystąpieniu usługi API Management. Musi być unikalne w instancji usługi API Management.
   Podstawowy adres URL	Pole niezmienialne wyświetlające podstawowy adres URL interfejsu API.
   Tagi	Opcjonalnie skojarz interfejs API graphQL z nowymi lub istniejącymi tagami.
   Produkty	Skojarz interfejs API GraphQL z produktem, aby go opublikować.
   Czy chcesz utworzyć wersję tego interfejsu API?	Zaznacz pole wyboru, aby zastosować schemat przechowywania wersji do interfejsu API GraphQL.

6. Wybierz pozycję Utwórz.

7. Po utworzeniu interfejsu API przejrzyj lub zmodyfikuj schemat na karcie Schemat .

Interfejs wiersza polecenia platformy Azure

W poniższym przykładzie użyto polecenia az apim api import do zaimportowania interfejsu API passthrough GraphQL z podanego adresu URL do instancji zarządzania API o nazwie apim-hello-world.

# Details specific to API Management instance.
APIMServiceName="apim-hello-world"
ResourceGroupName="myResourceGroup"

# API-specific details.
APIId="my-graphql-api"
APIPath="myapi"
DisplayName="MyGraphQLAPI"
SpecificationFormat="GraphQL"
SpecificationURL="<GraphQL backend endpoint>"

# Import API.
az apim api import \
    --path $APIPath \
    --resource-group $ResourceGroupName \
    --service-name $APIMServiceName --api-id $APIId \
    --display-name $DisplayName --specification-format $SpecificationFormat \
    --specification-url $SpecificationURL

Po zaimportowaniu interfejsu API możesz zaktualizować ustawienia przy użyciu polecenia az apim api update , jeśli to konieczne.

PowerShell

W poniższym przykładzie użyto polecenia cmdlet Import-AzApiManagementApi programu Azure PowerShell do zaimportowania API typu passthrough GraphQL z określonego adresu URL do wystąpienia usługi API Management o nazwie apim-hello-world.

# Details specific to API Management instance.
$apimServiceName = "apim-hello-world"
$resourceGroupName = "myResourceGroup"

# API-specific details.
$apiId = "my-graphql-api"
$apiPath = "myapi"
$specificationFormat = "GraphQL"
$specificationUrl = "<GraphQL backend endpoint>"

# Get context of the API Management instance. 
$context = New-AzApiManagementContext -ResourceGroupName $resourceGroupName -ServiceName $apimServiceName

# Import API.
Import-AzApiManagementApi -Context $context -ApiId $apiId -SpecificationFormat $specificationFormat -SpecificationUrl $specificationUrl -Path $apiPath

Po zaimportowaniu interfejsu API możesz zaktualizować ustawienia przy użyciu polecenia cmdlet Set-AzApiManagementApi , jeśli to konieczne.

Przetestuj swoje API GraphQL

1. Przejdź do wystąpienia usługi API Management.

2. W okienku po lewej stronie w sekcji Interfejsy API wybierz pozycję Interfejsy API.

3. W obszarze Wszystkie interfejsy API wybierz interfejs API GraphQL.

4. Wybierz kartę Test, aby uzyskać dostęp do konsoli testowej.

5. W obszarze Nagłówki:

   1. Wybierz nagłówek z menu Nazwa .
   2. Wprowadź wartość w polu Wartość .
   3. Dodaj więcej nagłówków, wybierając pozycję Dodaj nagłówek.
   4. Usuń nagłówki, korzystając z przycisku do kosza.

6. Jeśli dodano produkt do interfejsu API graphQL, dodaj zakres produktu w obszarze Zastosuj zakres produktu.

7. W edytorze zapytań wykonaj jedną z następujących czynności:

   1. Wybierz co najmniej jedno pole lub pole podrzędne z listy w menu po lewej stronie edytora. Wybrane pola i pola podrzędne są wyświetlane w edytorze zapytań.

   2. Zacznij wpisywać w edytorze zapytań, aby utworzyć zapytanie.

      

8. W sekcji Zmienne zapytania, dodaj zmienne, aby ponownie użyć tego samego zapytania lub mutacji i przekazać różne wartości.

9. Wybierz Wyślij.

10. Wyświetl odpowiedź.

    

11. Powtórz powyższe kroki, aby przetestować różne ładunki.

12. Po zakończeniu testowania zamknij konsolę testową.

Testowanie subskrypcji

Jeśli interfejs API graphQL obsługuje subskrypcję, możesz ją przetestować w konsoli testowej.

1. Upewnij się, że interfejs API zezwala na schemat adresów URL protokołu WebSocket (WS lub WSS), który jest odpowiedni dla twojego interfejsu API. To ustawienie można włączyć na karcie Ustawienia .

2. Skonfiguruj zapytanie subskrypcji w edytorze zapytań, a następnie wybierz pozycję Połącz , aby ustanowić połączenie protokołu WebSocket z usługą zaplecza.

   

3. Przejrzyj szczegóły połączenia w okienku Subskrypcja.

   

4. Zdarzenia subskrybowane są wyświetlane w okienku Subskrypcja . Połączenie protokołu WebSocket jest utrzymywane do momentu jego rozłączenia lub nawiązania połączenia z nową subskrypcją protokołu WebSocket.

   

Zabezpiecz swój interfejs API GraphQL

Zabezpiecz interfejs API graphQL, stosując zarówno istniejące zasady uwierzytelniania, jak i autoryzacji oraz zasady weryfikacji graphQL w celu ochrony przed atakami specyficznymi dla języka GraphQL.

Powiązana zawartość

• Ograniczenia importu interfejsu API
• Importowanie specyfikacji interfejsu OpenAPI
• Importuj interfejs API SOAP
• Importowanie interfejsu API protokołu SOAP i przekształcenie go na interfejs API REST
• Importowanie API usługi App Service
• Importowanie interfejsu API aplikacji kontenera
• Zaimportuj interfejs API WebSocket
• Importuj GraphQL API
• Importowanie schematu GraphQL i konfigurowanie rozpoznawania pól
• Zaimportuj API aplikacji funkcji
• Importowanie interfejsu API aplikacji logicznej
• Importowanie usługi Service Fabric
• Importowanie interfejsu API usługi Azure AI Foundry
• Importowanie interfejsu API usługi Azure OpenAI
• Importowanie interfejsu API LLM
• Importowanie interfejsu API OData
• Eksportowanie interfejsu API REST jako serwera MCP
• Uwidacznia istniejący serwer MCP
• Importowanie interfejsu API agenta A2A
• Importowanie metadanych sap OData
• Importowanie interfejsu API gRPC
• Edytowanie interfejsu API