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 usando pontos de extremidade REST ou SOAP API, consulte Importar um esquema GraphQL e configurar os resolvedores de campo.

Pré-requisitos

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

• Uma API do GraphQL.

• CLI do Azure

  • Use o ambiente Bash no Azure Cloud Shell. Para obter mais informações, confira Início Rápido para Bash no 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 obter mais informações, 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 ver outras opções de entrada, confira Conectar-se com 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 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.

• PowerShell do Azure

  • 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, navegue até a instância do Gerenciamento de API.

2. No menu à esquerda, selecione APIs>+Adicionar API.

3. Em Definir uma nova API, selecione o ícone GraphQL.

   

4. Na caixa de diálogo, selecione Completo e preencha os campos de formulário necessários.

   

   Campo	Description
   Nome de exibição	O nome pelo qual a API do GraphQL será exibida.
   Nome	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 o ponto de extremidade "swapi" comum do GraphQL, como https://swapi-graphql.azure-api.net/graphql, como demonstração.
   Carregar esquema	Opcionalmente, selecione procurar e carregar seu arquivo de esquema para substituir o esquema recuperado do ponto de extremidade GraphQL (se disponível).
   Descrição	Adicione uma descrição da sua API.
   Esquema de URL	Faça uma seleção 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. Seleção padrão: HTTP(S).
   Sufixo da URL da API	Adicione um sufixo de URL para identificar essa API específica nesta instância de Gerenciamento de API. Ele deve ser exclusivo nessa instância do Gerenciamento de API.
   URL base	Campo não editável exibindo a URL base da API
   Marcas	Associe sua API do GraphQL a marcações novas ou existentes.
   Produtos	Associe sua API do GraphQL a um produto para publicá-la.
   Controlar a versão desta API?	Selecione para aplicar um esquema de controle de versão à API do GraphQL.

5. Selecione Criar.

6. Depois que a API for criada, navegue ou modifique o esquema na guia Design.

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.

# API Management service-specific details
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, se necessário, você pode atualizar as configurações usando o comando az apim api update.

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.

# API Management service-specific details
$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, se necessário, você pode atualizar as configurações usando o cmdlet Set-AzApiManagementApi.

Testar a API do GraphQL

1. Navegue até sua instância de Gerenciamento de API.

2. No menu de navegação lateral, 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 menu suspenso Nome.
   2. Insira o valor para o campo Valor.
   3. Adicione mais cabeçalhos selecionando + Adicionar cabeçalho.
   4. Exclua os cabeçalhos usando o ícone da lixeira.

6. Se você adicionou um produto à API do GraphQL, aplique o escopo do produto em Aplicar escopo do produto.

7. Em Editor de consultas, faça o seguinte:

   1. Selecione pelo menos um campo ou subcampo da lista no menu lateral. 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 o teste for concluído, 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 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.

Tópicos relacionados

• Limitações de importação da API
• Importar uma especificação de OpenAPI
• Importar uma API SOAP
• Importar uma API SOAP e converter em REST
• Importar uma API do Serviço de Aplicativo
• Importar uma API do Aplicativo de Contêiner
• Importar uma API WebSocket
• Importar uma API do GraphQL
• Importar um esquema do GraphQL e configurar resolvedores de campo
• Importar um Aplicativo de Funções do Azure
• Importar um Aplicativo Lógico do Azure
• Importar um serviço do Service Fabric
• Importar uma API do OpenAI do Azure
• Importar uma API de OData
• Importar metadados do SAP OData
• Importar uma API do gRPC
• Editar uma API

Próximas etapas

Transformar e proteger uma API publicada