Importar uma GraphQL API

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

Pré-requisitos

• Uma instância de gerenciamento de API existente. Crie um, caso ainda não o tenha feito.

• Uma API GraphQL.

• CLI do Azure

  • Use o ambiente Bash no Azure Cloud Shell. Para obter mais informações, consulte Guia de início rápido para Bash no Azure Cloud Shell.

    

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

    • Se estiver a utilizar uma instalação local, inicie sessão no CLI do Azure ao utilizar o comando az login. Para concluir o processo de autenticação, siga os passos apresentados no seu terminal. Para outras opções de entrada, consulte Entrar com a CLI do Azure.

    • Quando solicitado, instale a extensão da CLI do Azure na primeira utilização. Para obter mais informações sobre as extensões, veja Utilizar extensões com o CLI do Azure.

    • Execute o comando az version para localizar a versão e as bibliotecas dependentes instaladas. Para atualizar para a versão mais recente, execute o comando az upgrade.

• Azure PowerShell

  • 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

Portal

1. No portal do Azure, navegue até sua instância de Gerenciamento de API.

2. No menu à esquerda, selecione APIs>+ Add 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 obrigatórios.

   

   Campo	Descrição
   Nome a apresentar	O nome pelo qual sua API GraphQL será exibida.
   Nome	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ê também pode usar um ponto de extremidade GraphQL "swapi" comum, como https://swapi-graphql.azure-api.net/graphql uma demonstração.
   Carregar esquema	Opcionalmente, selecione para 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 do URL	Faça uma seleção 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. Seleção padrão: HTTP(S).
   Sufixo do 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 nesta instância de Gerenciamento de API.
   URL Base	Campo não editável exibindo o URL base da API
   Etiquetas	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?	Selecione esta opção para aplicar um esquema de controle de versão à sua API do GraphQL.

5. Selecione Criar.

6. Depois que a API for criada, procure 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 GraphQL 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 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.

# 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 .

Teste sua 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 GraphQL.

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

5. Em Cabeçalhos:

   1. Selecione o cabeçalho no menu suspenso Nome .
   2. Insira o valor no campo Valor .
   3. Adicione mais cabeçalhos selecionando + Adicionar cabeçalho.
   4. Exclua cabeçalhos usando o ícone da lixeira.

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

7. Em Editor de consultas:

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

Tópicos relacionados

• Limitações de importação de API
• Importar uma especificação de OpenAPI
• Importar uma API SOAP
• Importar uma API de SOAP e converter 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 resoluções de campos
• Importar uma Aplicação de Função do Azure
• Importar uma Aplicação Lógica do Azure
• Importar um serviço do Service Fabric
• Importar uma API OData
• Importar metadados do SAP OData
• Importar uma API gRPC
• Editar uma API

Próximos passos

Transformar e proteger a sua API