Integrar APIM (Gerenciamento de API do Azure) à API do Fabric para GraphQL

A integração do APIM (Gerenciamento de API do Azure) à API do Microsoft Fabric para GraphQL aprimora significativamente os recursos da API fornecendo recursos robustos de escalabilidade e segurança. O APIM atua como um gateway de nível empresarial que adiciona recursos avançados, incluindo gerenciamento de identidade, limitação de taxa, cache de resposta, proteção contra ameaças e monitoramento centralizado, tudo isso sem modificar a configuração da API do Fabric.

Ao rotear suas solicitações do GraphQL por meio do APIM, você pode dimensionar para lidar com o aumento do tráfego, implementar políticas de segurança sofisticadas e obter visibilidade dos padrões de uso da API em toda a sua organização.

Este artigo orienta você pela integração do APIM com a API do Fabric para GraphQL, a configuração da autenticação de identidade gerenciada e a implementação de políticas de cache e limitação de taxa.

Quem usa o Gerenciamento de API do Azure com o GraphQL

A integração do APIM é valiosa para:

  • Arquitetos empresariais expondo dados do Fabric por meio de um gateway de API centralizado e controlado para acesso em toda a organização
  • Administradores do Fabric implementando políticas de limitação de taxas, cache e segurança para proteger a capacidade e os dados do Fabric
  • Equipes de segurança de TI que exigem autenticação avançada, autorização e proteção contra ameaças para acesso a dados do Fabric
  • Equipes de plataforma gerenciando e supervisionando várias APIs do Fabric GraphQL em departamentos e unidades de negócios

Use a integração APIM quando precisar de recursos de gerenciamento de API de nível empresarial, como limitação de taxa, cache, políticas de segurança e gestão centralizada para suas APIs GraphQL do Fabric.

Pré-requisitos

Antes de começar, verifique se você tem:

  • Uma API do Fabric para GraphQL já criada. Caso contrário, consulte Criar uma API para GraphQL ou usar Iniciar com o banco de dados SQL de exemplo no portal da API para GraphQL
  • Uma instância de Gerenciamento de API do Azure. Para obter instruções de instalação, consulte Criar uma instância de Gerenciamento de API
  • Permissões para criar identidades gerenciadas e configurar políticas do APIM

Adicionar uma API do GraphQL do Fabric ao Gerenciamento de API do Azure

A primeira etapa na integração do APIM ao Fabric é importar sua API do GraphQL para o Gerenciamento de API do Azure. Esse processo cria um proxy que roteia solicitações por meio do APIM, mantendo a conexão com suas fontes de dados do Fabric. Ao importar a API, você estabelece a base para adicionar recursos corporativos, como políticas de autenticação, cache e limitação de taxa.

O processo de importação requer duas informações da API do GraphQL do Fabric: a URL do ponto de extremidade (em que o APIM envia solicitações) e o arquivo de esquema (que define a estrutura da API e as operações disponíveis).

Exportar os detalhes da API do GraphQL

Primeiro, colete as informações necessárias da API do GraphQL do Fabric:

  1. Abra a API do GraphQL no portal do Fabric

  2. Na faixa de opções, selecione Copiar ponto de extremidade para obter a URL da API

  3. Selecione Exportar esquema para baixar o arquivo de esquema GraphQL em seu dispositivo local

    Captura de tela da faixa de opções da API para GraphQL.

Importar a API para o APIM

Com a URL do ponto de extremidade e o arquivo de esquema prontos, agora você pode registrar a API do GraphQL no APIM. Isso cria uma definição de API que o APIM usa para validar solicitações, gerar documentação e aplicar políticas. O esquema carregado define quais consultas e mutações os clientes podem executar.

  1. Navegue até a instância de Gerenciamento de API no portal do Azure

  2. Selecionar APIs>+ Adicionar API

  3. Selecione o ícone do GraphQL

  4. Na tela Criar a partir do esquema GraphQL , forneça:

    • Nome de exibição: um nome amigável para a API
    • Nome: o identificador da API
    • Ponto de extremidade da API do GraphQL: a URL do ponto de extremidade copiada do Fabric

  5. Selecione Carregar esquema e escolha o arquivo de esquema que você baixou

    Captura de tela da interface de criação do APIM a partir da tela de esquema do GraphQL.

Configurar a autenticação de identidade gerenciada

Agora que a API do GraphQL está registrada no APIM, você precisa configurar como o APIM se autentica com o Fabric. As identidades gerenciadas fornecem um método de autenticação seguro e sem senha que elimina a necessidade de armazenar credenciais na configuração do APIM. O Azure gerencia automaticamente o ciclo de vida de identidade e lida com a aquisição de tokens, tornando essa abordagem mais segura e fácil de manter do que os métodos tradicionais de autenticação.

A configuração de autenticação envolve três etapas principais: criar a identidade gerenciada no Azure, conceder permissões para acessar o workspace do Fabric e fontes de dados e configurar o APIM para usar essa identidade ao fazer solicitações ao Fabric.

Criar e atribuir uma identidade gerenciada

Primeiro, crie a identidade gerenciada que o APIM usa para autenticar:

  1. Crie uma identidade gerenciada atribuída pelo usuário no portal do Azure.
  2. Observe a ID do cliente da identidade gerenciada: você precisa da ID do cliente para a configuração da política.

Conceder as permissões de identidade gerenciada no Fabric

Depois de criar a identidade gerenciada, você deve conceder a ela permissões para acessar os recursos do Fabric. A identidade gerenciada precisa de acesso tanto ao próprio item da API GraphQL quanto a quaisquer fontes de dados às quais se conecta (como lakehouses ou warehouses). Adicionar a identidade como um membro do workspace é a abordagem mais simples porque concede acesso a todos os itens no workspace de uma só vez.

  1. Abra o workspace do Fabric que contém a API do GraphQL
  2. Selecione Gerenciar acesso
  3. Adicionar a identidade gerenciada (por exemplo, apim-id) com pelo menos a função Contribuidor

Captura de tela das permissões da área de trabalho.

Dica

Para um controle mais granular, você pode conceder permissões diretamente a itens individuais do Fabric (a API e suas fontes de dados) em vez de acesso no nível do workspace. O controle granular é especialmente importante se sua API usa autenticação de SSO (logon único). Para obter mais informações, consulte Autenticação e resumo de permissões.

Configurar o APIM para usar a identidade gerenciada

Com as permissões concedidas no Fabric, você precisa informar à APIM qual identidade gerenciada usar. Essa associação permite que o APIM se autentique como essa identidade ao fazer solicitações para sua API do GraphQL do Fabric.

  1. No portal do Azure, navegue até a instância do APIM
  2. Ir para Segurança>Identidades gerenciadas
  3. Adicione a identidade gerenciada atribuída ao usuário que você criou anteriormente

Adicionar política de autenticação

A etapa final de autenticação é adicionar uma política APIM que obtém um token de acesso usando a identidade gerenciada e a inclui em solicitações ao Fabric. Essa política é executada em todas as solicitações, gerenciando automaticamente a aquisição e renovação do token. A política usa o authentication-managed-identity elemento para obter um token para o recurso de API do Fabric e, em seguida, adiciona-o ao cabeçalho autorização.

  1. Na API do GraphQL no APIM, selecione a guia Políticas de API

  2. Editar a política de processamento de entrada

  3. Adicione o seguinte XML em <inbound><base/>:

    <authentication-managed-identity 
    resource="https://analysis.windows.net/powerbi/api" 
    client-id="YOUR-MANAGED-IDENTITY-CLIENT-ID" 
    output-token-variable-name="token-variable" 
    ignore-error="false" />
<set-header name="Authorization" exists-action="override">
    <value>@("Bearer " + (string)context.Variables["token-variable"])</value>
</set-header>

  4. Substitua YOUR-MANAGED-IDENTITY-CLIENT-ID pelo ID do cliente da identidade gerenciada

  5. Salvar a política

Testar a conexão

Antes de continuar a adicionar o cache e a limitação de taxa, verifique se a configuração de autenticação funciona corretamente. O teste agora garante que todos os problemas encontrados posteriormente não estejam relacionados à configuração de autenticação.

  1. No APIM, navegue até sua API do GraphQL
  2. Vá para a guia Teste
  3. Executar uma consulta de exemplo ou mutação para confirmar se a conexão funciona

Captura de tela do teste bem-sucedido no portal do APIM.

Configurar o cache de resposta

O cache de resposta reduz significativamente a latência para os chamadores de API e diminui a carga de back-end em suas fontes de dados do Fabric. O APIM dá suporte ao cache interno ou a instâncias externas do Redis. Para APIs do GraphQL, o cache usa o corpo da solicitação (a consulta GraphQL) como a chave de cache, garantindo que consultas idênticas retornem respostas armazenadas em cache.

Benefícios do cache de respostas do GraphQL:

  • Latência reduzida: as respostas armazenadas em cache retornam instantaneamente sem consultar o Fabric
  • Menor consumo de capacidade: menos solicitações ao Fabric reduzem o uso de CU (unidade de capacidade)
  • Melhor escalabilidade: lidar com usuários mais simultâneos sem aumentar a carga de back-end

Adicionar política de cache

Para implementar o cache, modifique a política de autenticação existente para adicionar a pesquisa de cache e a lógica de armazenamento. A política verifica se há respostas armazenadas em cache antes de encaminhar solicitações para o Fabric e armazena respostas bem-sucedidas para uso futuro. Este exemplo de política completa mostra como a autenticação e o cache funcionam juntos:

<policies>
    <inbound>
        <base />
        <!-- Authenticate with managed identity -->
        <authentication-managed-identity 
            resource="https://analysis.windows.net/powerbi/api" 
            client-id="YOUR-MANAGED-IDENTITY-CLIENT-ID" 
            output-token-variable-name="token-variable" 
            ignore-error="false" />
        <set-header name="Authorization" exists-action="override">
            <value>@("Bearer " + (string)context.Variables["token-variable"])</value>
        </set-header>
        <!-- Check if response is cached -->
        <cache-lookup-value 
            key="@(context.Request.Body.As<String>(preserveContent: true))" 
            variable-name="cachedResponse" 
            default-value="not_exists" />
    </inbound>
    <backend>
        <!-- Only forward request if not cached -->
        <choose>
            <when condition="@(context.Variables.GetValueOrDefault<string>("cachedResponse") == "not_exists")">
                <forward-request />
            </when>
        </choose>
    </backend>
    <outbound>
        <base />
        <choose>
            <!-- Return cached response if it exists -->
            <when condition="@(context.Variables.GetValueOrDefault<string>("cachedResponse") != "not_exists")">
                <set-body>@(context.Variables.GetValueOrDefault<string>("cachedResponse"))</set-body>
            </when>
            <!-- Cache successful responses for 60 seconds -->
            <when condition="@((context.Response.StatusCode == 200) && (context.Variables.GetValueOrDefault<string>("cachedResponse") == "not_exists"))">
                <cache-store-value 
                    key="@(context.Request.Body.As<String>(preserveContent: true))" 
                    value="@(context.Response.Body.As<string>(preserveContent: true))" 
                    duration="60" />
            </when>
        </choose>
    </outbound>
    <on-error>
        <base />
    </on-error>
</policies>

Como essa política funciona:

  1. Entrada: autentica-se com identidade gerenciada e verifica se a resposta está armazenada em cache com base na consulta GraphQL
  2. Back-end: ignora o encaminhamento da solicitação para o Fabric se houver uma resposta armazenada em cache
  3. Saída: Retorna respostas armazenadas em cache ou armazena em cache novas respostas bem-sucedidas por 60 segundos

Verificar se o cache está funcionando

Para confirmar se as solicitações estão sendo armazenadas em cache:

  1. No APIM, execute a mesma consulta GraphQL duas vezes

  2. Rastrear a chamada à API para ver ocorrências de cache

    Captura de tela do cache atingido no portal do APIM.

Otimizar a duração do cache

O exemplo usa uma duração de cache de 60 segundos. Ajuste a duração com base nos requisitos de atualização de dados:

  • Atualizações de alta frequência: use durações mais curtas (10 a 30 segundos) para alterar dados com frequência
  • Dados estáticos ou de referência: use durações mais longas (5 a 60 minutos) para dados que são alterados com pouca frequência
  • Requisitos em tempo real: não armazene consultas em cache que sempre devem retornar os dados mais recentes

Para cenários avançados de cache, incluindo a invalidação de cache e a configuração externa do Redis, consulte as políticas de cache do APIM.

Limitação de taxa

Você pode limitar o número de chamadas à API que um cliente pode fazer em um período de tempo específico. Aqui está um exemplo de entrada de política de limitação de taxa que você pode adicionar abaixo <inbound><base/> que impõe no máximo duas chamadas a cada 60 segundos para um determinado usuário:

<rate-limit-by-key 
    calls="2" 
    renewal-period="60" 
    counter-key="@(context.Request.Headers.GetValueOrDefault("Authorization"))" 
    increment-condition="@(context.Response.StatusCode == 200)" 
    remaining-calls-variable-name="remainingCallsPerUser" />

Depois de enviar mais de duas chamadas à API em um minuto, você receberá uma mensagem de erro:

{
    "statusCode": 429,
    "message": "Rate limit is exceeded. Try again in 58 seconds."
}

Para obter mais informações sobre como configurar políticas de limitação de taxa no APIM, consulte a documentação.

Práticas recomendadas

Ao integrar o APIM à API do Fabric para GraphQL, siga estas recomendações:

Segurança

  • Usar identidades gerenciadas: preferir identidades gerenciadas em vez de chaves de API ou cadeias de conexão para autenticação
  • Implementar privilégios mínimos: conceda apenas as permissões mínimas necessárias para a identidade gerenciada
  • Habilitar somente HTTPS: configurar o APIM para rejeitar solicitações HTTP e impor HTTPS
  • Validar entradas: usar políticas APIM para validar consultas GraphQL antes de encaminhar para o Fabric

Performance

  • Armazenar em cache dados acessados com frequência: identificar consultas comuns e definir as durações de cache apropriadas
  • Monitorar as taxas de acerto do cache: use a análise de APIM para monitorar a eficácia do cache
  • Otimizar limites de taxa: balancear a experiência do usuário com a proteção de capacidade
  • Usar a implantação regional: implantar o APIM na mesma região que a capacidade do Fabric

Monitoramento e governança

  • Habilitar o diagnóstico: configurar o log de diagnóstico do APIM para acompanhar o uso da API
  • Configurar alertas: criar alertas para violações e erros de limite de taxa
  • Versionar suas APIs: Usar o controle de versão do APIM para gerenciar quaisquer alterações disruptivas
  • Documente suas APIs: use o portal do desenvolvedor do APIM para fornecer a documentação da API

Otimização de custos

  • Ajuste os limites de taxa: defina limites que se alinhem à camada de capacidade
  • Monitorar o consumo de capacidade: acompanhar o uso da capacidade do APIM e do Fabric
  • Usar o cache estrategicamente: balancear os requisitos de atualização com economia de capacidade
  • Examinar padrões de uso: analisar regularmente quais consultas consomem a maioria dos recursos

Resumo

Integrar a API do Fabric para GraphQL com o Gerenciamento de API do Azure une as poderosas capacidades de dados do Fabric com os recursos de gateway de API de nível empresarial do APIM. Essa combinação fornece:

  • Segurança aprimorada: autenticação de identidade gerenciada, proteção contra ameaças e controle de acesso baseado em política
  • Escalabilidade aprimorada: cache de resposta, limitação de taxa e distribuição de carga em vários back-ends
  • Melhor desempenho: latência reduzida por meio de cache e roteamento de solicitação otimizado
  • Governança centralizada: monitoramento unificado, controle de versão e gerenciamento em várias APIs
  • Controle de custo: limitação de taxa e cache reduzem o consumo de capacidade do Fabric

Seguindo as etapas de configuração e as práticas recomendadas neste artigo, você pode criar uma camada de API robusta, segura e escalonável que dá suporte a cargas de trabalho de produção em toda a sua organização.

Conteúdo relacionado

  • Last updated on