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:

Abra a API do GraphQL no portal do Fabric
Na faixa de opções, selecione Copiar ponto de extremidade para obter a URL da API
Selecione Exportar esquema para baixar o arquivo de esquema GraphQL em seu dispositivo local

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.

Navegue até a instância de Gerenciamento de API no portal do Azure
Selecionar APIs>+ Adicionar API
Selecione o ícone do GraphQL
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
Selecione Carregar esquema e escolha o arquivo de esquema que você baixou

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:

Crie uma identidade gerenciada atribuída pelo usuário no portal do Azure.
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.

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

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.

No portal do Azure, navegue até a instância do APIM
Ir para Segurança>Identidades gerenciadas
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.

Na API do GraphQL no APIM, selecione a guia Políticas de API
Editar a política de processamento de entrada

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>

Substitua YOUR-MANAGED-IDENTITY-CLIENT-ID pelo ID do cliente da identidade gerenciada
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.

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

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:

Entrada: autentica-se com identidade gerenciada e verifica se a resposta está armazenada em cache com base na consulta GraphQL
Back-end: ignora o encaminhamento da solicitação para o Fabric se houver uma resposta armazenada em cache
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:

No APIM, execute a mesma consulta GraphQL duas vezes
Rastrear a chamada à API para ver ocorrências de cache

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

A integração da API do Microsoft Fabric para GraphQL ao Gerenciamento de API do Azure reúne os poderosos recursos de dados do Fabric com os recursos de gateway de API de nível empresarial da 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.

Comentários

Esta página foi útil?

Last updated on 2026-01-21