Importar uma API do GraphQL

APLICA-SE A: Todas as camadas de gerenciamento de API

No Gerenciamento de API, você pode adicionar uma API GraphQL em um de dois modelos: passar para um ponto de extremidade GraphQL existente ou importar um esquema GraphQL e criar uma API GraphQL sintética com resolvedores de campo personalizados. Para obter mais informações, consulte a visão geral do GraphQL.

Neste artigo, você:

• Adicione uma API GraphQL de passagem à sua instância de Gerenciamento de API.
• Teste sua API GraphQL.

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

Pré-requisitos

• Uma instância de Gerenciamento de API do Azure. Crie um, caso ainda não o tenha feito.

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

  • Utilize o ambiente Bash no Azure Cloud Shell. Para mais informações, veja Get started with Azure Cloud Shell.

    

  • Se preferir executar comandos de referência da CLI localmente, instale o CLI do Azure. Se estiver a usar Windows ou macOS, considere executar o Azure CLI num contentor Docker. Para obter mais informações, consulte Como executar a CLI do Azure em um contêiner do Docker.

    • Se você estiver usando uma instalação local, entre na CLI do Azure usando o comando az login . Para concluir o processo de autenticação, siga os passos exibidos no seu terminal. Para outras opções de entrada, consulte Autenticar no Azure usando a CLI do Azure.

    • Quando solicitado, instale a extensão do Azure CLI na primeira utilização. Para obter mais informações sobre extensões, consulte Usar e gerenciar extensões com a CLI do Azure.

    • Execute az version para descobrir a versão e as bibliotecas dependentes que estão instaladas. Para atualizar 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 Az PowerShell.
    • Conecte-se à sua conta do Azure usando o cmdlet Connect-AzAccount .
  • Se você optar por usar o Azure Cloud Shell:
    • Consulte Visão geral do Azure Cloud Shell para obter mais informações.

Adicionar uma API GraphQL

Portais

1. No portal do Azure, vá para 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 GraphQL .

   

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

   

   Valor	Descrição
   Nome de exibição	O nome pelo qual sua API GraphQL será exibida.
   Nome	O nome bruto da API GraphQL. Preenche automaticamente à medida que você digita o nome para exibição.
   Tipo GraphQL	Selecione Pass-through GraphQL para importar de um ponto de extremidade existente da API GraphQL.
   Ponto de extremidade da API GraphQL	A URL base com o nome do ponto de extremidade da API GraphQL. Por exemplo: https://example.com/your-GraphQL-name. Você pode também utilizar um endpoint SWAPI GraphQL comum como https://swapi-graphql.azure-api.net/graphql para demonstração.
   Carregar esquema	Opcionalmente, selecione carregar seu arquivo de esquema para substituir o esquema recuperado do ponto de extremidade GraphQL (se você tiver um).
   Descrição	Adicione uma descrição da sua API.
   Esquema do URL	Selecione um esquema com base no seu endpoint GraphQL. Selecione uma das opções que inclui um esquema WebSocket (WS ou WSS) se sua API GraphQL incluir o tipo de assinatura. A seleção padrão é HTTP(S).
   Sufixo do 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 o URL base da API.
   Etiquetas	Opcionalmente, associe sua API do GraphQL a tags novas ou existentes.
   Produtos	Associe sua API GraphQL a um produto para publicá-la.
   Versão desta API?	Marque a caixa de seleção para aplicar um esquema de controle de versão à sua API do GraphQL.

6. Selecione Criar.

7. Depois que a API for criada, revise 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 GraphQL 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 cmdlet Import-AzApiManagementApi Azure PowerShell para importar uma API de passagem GraphQL 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.

Teste sua 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 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 da lixeira.

6. Se você adicionou um produto à sua API do 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 aparecem 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 passe valores diferentes.

9. Selecione Enviar.

10. Veja a resposta.

    

11. Repita as etapas anteriores para testar cargas úteis diferentes.

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

Testar uma subscrição

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

1. Certifique-se de que sua API permita um esquema de URL WebSocket (WS ou WSS) apropriado para sua API. Você pode habilitar essa configuração na guia Configurações .

2. Configure uma consulta de assinatura no editor de consultas e selecione Conectar para estabelecer uma conexão WebSocket com o serviço de back-end.

   

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

   

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

   

Proteja sua API GraphQL

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

Conteúdo relacionado

• Limitações de importação de API
• Importar uma especificação de OpenAPI
• Importar uma API SOAP
• Importe uma API SOAP e converta-a em REST
• Importar uma API do Serviço de Aplicativo
• Importar uma API de aplicativo de contêiner
• Importar uma API WebSocket
• Importar uma GraphQL API
• Importar um esquema de GraphQL e configurar resolveres de campos
• Importar uma API de aplicativo de função
• Importar uma API de aplicativo lógico
• Importar um serviço do tipo Service Fabric
• Importar uma API do Azure AI Foundry
• Importar uma API OpenAI do Azure
• 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 gRPC
• Editar uma API