Importar uma API do GraphQL

APLICA-SE A: todas as camadas do Gerenciamento de API

No Gerenciamento de API, você pode adicionar uma API do GraphQL em um dos dois modelos: passagem para um ponto de extremidade do GraphQL existente ou importação de um esquema do GraphQL e criação de uma API do GraphQL sintético com resolvedores de campo personalizados. Para obter mais informações, confira a Visão geral do GraphQL.

Neste artigo, você vai:

• Adicionar uma API do GraphQL de passagem à instância do Gerenciamento de API.
• Testar sua API do GraphQL.

Se você quiser importar um esquema graphQL e configurar resolvedores de campo que usam pontos de extremidade da API REST ou SOAP, consulte Importar um esquema graphQL e configurar resolvedores de campo.

Pré-requisitos

• Uma instância de Gerenciamento de API do Azure. Crie uma, se ainda não tiver.

• CLI do Azure, se você quiser usá-la para importar a API.

  • Use o ambiente Bash no Azure Cloud Shell. Para obter mais informações, confira Introdução ao Azure Cloud Shell.

    

  • Se preferir executar os comandos de referência da CLI localmente, instale a CLI do Azure. Para execuções no Windows ou no macOS, considere executar a CLI do Azure em um contêiner do Docker. Para saber mais, confira Como executar a CLI do Azure em um contêiner do Docker.

    • Se estiver usando uma instalação local, entre com a CLI do Azure usando o comando az login. Para concluir o processo de autenticação, siga as etapas exibidas no terminal. Para obter outras opções de entrada, consulte Autenticar no Azure usando a CLI do Azure.

    • Quando solicitado, instale a extensão da CLI do Azure no primeiro uso. Para obter mais informações sobre extensões, confira Usar e gerenciar extensões com a CLI do Azure.

    • Execute az version para localizar a versão e as bibliotecas dependentes que estão instaladas. Para fazer a atualização para a versão mais recente, execute az upgrade.

• Azure PowerShell, se você quiser usá-lo para importar a API.

  • Se você optar por usar o Azure PowerShell localmente:
    • Instale a versão mais recente do módulo do Az PowerShell.
    • Conecte-se à sua conta do Azure usando o cmdlet Connect-AzAccount.
  • Se você optar por usar o Azure Cloud Shell:
    • Confira Visão geral do Azure Cloud Shell para obter mais informações.

Adicionar uma API do GraphQL

Portal

1. No portal do Azure, acesse sua instância de Gerenciamento de API.

2. No painel esquerdo, selecione APIs>APIs.

3. Selecione Adicionar API.

4. Em Definir uma nova API, selecione o bloco do GraphQL .

   

5. Na caixa de diálogo resultante, selecione Completo e insira valores nos campos necessários, conforme descrito na tabela a seguir.

   

   Value	Descrição
   Nome de exibição	O nome pelo qual a API do GraphQL será exibida.
   Nome	O nome bruto da API do GraphQL. Preenche automaticamente conforme você digita o nome de exibição.
   Tipo do GraphQL	Selecione Passagem do GraphQL para importar de um ponto de extremidade da API do GraphQL existente.
   Ponto de extremidade da API do GraphQL	A URL base com o nome do ponto de extremidade da API do GraphQL. Por exemplo: https://example.com/your-GraphQL-name. Você também pode usar um endpoint comum do SWAPI GraphQL, como https://swapi-graphql.azure-api.net/graphql, para fins de demonstração.
   Carregar esquema	Opcionalmente, selecione para carregar o arquivo de esquema para substituir o esquema recuperado do endpoint do GraphQL (se você tiver um).
   Descrição	Adicione uma descrição da sua API.
   Esquema de URL	Selecione um esquema com base no ponto de extremidade do GraphQL. Selecione uma das opções que inclui um esquema de WebSocket (WS ou WSS) se a API do GraphQL incluir o tipo de assinatura. A seleção padrão é HTTP(S).
   Sufixo da URL da API	Adicione um sufixo de URL para identificar a API específica na instância de Gerenciamento de API. Ele deve ser exclusivo na instância de Gerenciamento de API.
   URL base	Campo não editável exibindo a URL base da API.
   Marcas	Opcionalmente, associe sua API do GraphQL a marcas novas ou existentes.
   Produtos	Associe sua API do GraphQL a um produto para publicá-la.
   Controlar a versão desta API?	Marque a caixa de seleção para aplicar um esquema de controle de versão à API do GraphQL.

6. Selecione Criar.

7. Depois que a API for criada, examine ou modifique o esquema na guia Esquema .

CLI do Azure

O exemplo a seguir usa o comando az apim api import para importar uma API de passagem do GraphQL a partir da URL especificada para uma instância de Gerenciamento de API chamada 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

Depois de importar a API, você pode atualizar as configurações usando o comando az apim api update , se necessário.

PowerShell

O exemplo a seguir usa o comando Import-AzApiManagementApi do cmdlet do Azure PowerShell para importar uma API de passagem do GraphQL a partir da URL especificada para uma instância de Gerenciamento de API chamada 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

Depois de importar a API, você pode atualizar as configurações usando o cmdlet Set-AzApiManagementApi , se necessário.

Testar a API do GraphQL

1. Vá para sua instância de Gerenciamento de API.

2. No painel esquerdo, na seção APIs , selecione APIs.

3. Em Todas as APIs, selecione sua API do GraphQL.

4. Selecione a guia Teste para acessar o console de teste.

5. Em Cabeçalhos:

   1. Selecione o cabeçalho no menu Nome .
   2. Insira o valor na caixa Valor .
   3. Adicione mais cabeçalhos selecionando Adicionar cabeçalho.
   4. Exclua cabeçalhos usando o botão de lixeira.

6. Se você adicionou um produto à sua API GraphQL, adicione um escopo de produto em Aplicar escopo do produto.

7. No editor de Consultas, siga um destes procedimentos:

   1. Selecione pelo menos um campo ou subcampo na lista no menu à esquerda do editor. Os campos e subcampos selecionados são exibidos no editor de consultas.

   2. Comece a digitar no editor de consultas para compor uma consulta.

      

8. Em Variáveis de consulta, adicione variáveis para reutilizar a mesma consulta ou mutação e passar valores diferentes.

9. Selecione Enviar.

10. Veja a Resposta.

    

11. Repita as etapas anteriores para testar cargas diferentes.

12. Quando terminar de testar, saia do console de teste.

Testar uma assinatura

Se a API do GraphQL der suporte a uma assinatura, você poderá testá-la no console de teste.

1. Verifique se a API permite um esquema de URL do WebSocket (WS ou WSS) apropriado para sua API. Você pode habilitar essa configuração na guia Configurações.

2. Criar uma solicitação de assinatura no Editor de solicitações e, em seguida, selecionar Conexão para estabelecer uma conexão WebSocket para o serviço back-end.

   

3. Examine os detalhes da conexão no painel Assinatura.

   

4. Os eventos assinados aparecem no painel Assinatura. A conexão WebSocket é mantida até que você a desconecte ou se conecte a uma nova assinatura do WebSocket.

   

Proteger a API do GraphQL

Proteja sua API GraphQL aplicando as políticas existentes de autenticação e autorização e uma política de validação GraphQL para proteger contra ataques específicos do GraphQL.

Conteúdo relacionado

• Limitações de importação da API
• Importar uma especificação de OpenAPI
• Importar uma API SOAP
• Importar uma API SOAP e convertê-la em REST
• Importar uma API do Serviço de Aplicativo
• Importar uma API de aplicativo de contêiner
• Importar uma API WebSocket
• Importar uma API GraphQL
• Importar um esquema do GraphQL e configurar os resolvedores de campo
• Importar uma API de aplicativo de funções
• Importar uma API de aplicativo lógico
• Importar um serviço do Service Fabric
• Importar uma API do Azure AI Foundry
• Importe uma API Azure OpenAI
• Importar uma API LLM
• Importar uma API OData
• Exportar uma API REST como um servidor MCP
• Expor um servidor MCP existente
• Importar uma API de agente A2A
• Importar metadados do SAP OData
• Importar uma API do gRPC
• Editar uma API