Интеграция службы "Управление API Azure" (APIM) с API Fabric для GraphQL

Интеграция управления API Azure (APIM) с API Microsoft Fabric для GraphQL значительно повышает возможности API, обеспечивая надежную масштабируемость и безопасность. APIM выступает в качестве шлюза корпоративного уровня, который добавляет расширенные возможности, включая управление удостоверениями, ограничение скорости, кэширование ответов, защиту от угроз и централизованный мониторинг— все без изменения конфигурации API Fabric.

Путем маршрутизации запросов GraphQL через APIM можно масштабировать для обработки повышенного трафика, реализации сложных политик безопасности и получения видимости шаблонов использования API в организации.

В этой статье рассматривается интеграция APIM с Fabric API для GraphQL, настройка аутентификации с управляемыми удостоверениями, а также реализация политик кэширования и ограничения скорости.

Кто использует управление API Azure с GraphQL

Интеграция APIM ценна для:

Корпоративные архитекторы , предоставляющие данные Fabric через централизованный, управляемый шлюз API для доступа на уровне организации
Администраторы Структуры реализуют лимитирование скорости передачи данных, кэширование и политики безопасности для защиты вместимости и данных Fabric
ИТ-отделы безопасности , требующие расширенной проверки подлинности, авторизации и защиты от угроз для доступа к данным Fabric
Платформенные команды управляют и контролируют несколькими API GraphQL Fabric в различных отделах и бизнес-единицах

Используйте интеграцию APIM, если вам нужны функции управления API корпоративного уровня, такие как ограничение скорости, кэширование, политики безопасности и централизованное управление для API GraphQL Fabric.

Предпосылки

Прежде чем начать, убедитесь, что у вас есть следующее:

API Fabric для GraphQL уже создан. Если нет, см. статью "Создание API для GraphQL" или используйте пример базы данных SQL на портале API для GraphQL.
Экземпляр Azure API Management. Инструкции по настройке см. в разделе "Создание экземпляра службы управления API"
Разрешения для создания управляемых удостоверений и настройки политик APIM

Добавление API GraphQL Fabric в службу управления API Azure

Первым шагом интеграции APIM с Fabric является импорт API GraphQL в службу управления API Azure. Этот процесс создает прокси-сервер, который направляет запросы через APIM при сохранении подключения к источникам данных Fabric. Импортируя API, вы создаете основу для добавления корпоративных функций, таких как политики проверки подлинности, кэширование и ограничение скорости.

Для процесса импорта требуется два фрагмента информации из API GraphQL Fabric: URL-адрес конечной точки (где APIM отправляет запросы) и файл схемы (который определяет структуру API и доступные операции).

Экспорт сведений о API GraphQL

Сначала соберите необходимые сведения из API GraphQL Fabric:

Открытие API GraphQL на портале Fabric
На ленте выберите " Копировать конечную точку ", чтобы получить URL-адрес API
Выберите "Экспорт схемы ", чтобы скачать файл схемы GraphQL на локальное устройство

Импорт API в APIM

Теперь, когда у вас есть URL-адрес конечной точки и файл схемы, вы можете зарегистрировать API GraphQL в APIM. Это создает определение API, которое APIM использует для проверки запросов, создания документации и применения политик. Передаваемая схема определяет, какие запросы и мутации клиенты могут выполнять.

Перейдите к экземпляру службы "Управление API" на портале Azure
Выбор API>+ Добавление API
Выберите значок GraphQL
На экране "Создание из схемы GraphQL " укажите:
- Отображаемое имя: понятное имя API
- Имя: идентификатор API
- Конечная точка API GraphQL: URL-адрес конечной точки, скопированный из Fabric
Выберите "Отправить схему " и выберите скачанный файл схемы

Настройка проверки подлинности управляемой идентичности

Теперь, когда API GraphQL зарегистрирован в APIM, необходимо настроить способ проверки подлинности APIM в Fabric. Управляемые удостоверения предоставляют безопасный метод проверки подлинности без пароля, который устраняет необходимость хранения учетных данных в конфигурации APIM. Azure автоматически управляет жизненным циклом идентификации и обрабатывает получение маркеров, что делает этот подход более безопасным и простым для обслуживания, чем традиционные методы проверки подлинности.

Настройка проверки подлинности включает три основных этапа: создание управляемого удостоверения в Azure, предоставление ему разрешений на доступ к рабочей области Fabric и источникам данных, а также настройку APIM для использования этого удостоверения при выполнении запросов к Fabric.

Создание и назначение управляемого удостоверения

Сначала создайте управляемое удостоверение, которое APIM использует для проверки подлинности:

Создайте управляемое удостоверение, назначенное пользователем на портале Azure.
Обратите внимание, что идентификатор клиента управляемого удостоверения необходим для конфигурации политики.

Предоставьте разрешения управляемому удостоверению на платформе Fabric

После создания управляемого удостоверения необходимо предоставить ему разрешения для доступа к ресурсам Fabric. Управляемое удостоверение должно иметь доступ как к самому элементу API GraphQL, так и к любым источникам данных, к которым он подключается (например, к лейкхаусам или хранилищам). Добавление идентичности в качестве участника рабочей области является наиболее простым подходом, поскольку это обеспечивает одновременный доступ ко всем элементам рабочей области.

Откройте рабочую область Fabric, содержащую API GraphQL
Выбор "Управление доступом"
Добавьте управляемую идентичность (например, apim-id) с ролью не ниже участника.

Подсказка

Для более детального управления можно предоставить разрешения непосредственно отдельным элементам Fabric (API и его источникам данных) вместо доступа на уровне рабочей области. Гранулярное управление особенно важно, если ваш API использует аутентификацию с одним входом (SSO). Дополнительные сведения см. в сводке по проверке подлинности и разрешениям.

Настройка APIM для использования управляемого удостоверения

Когда разрешения предоставлены в Fabric, необходимо указать APIM, какие управляемые идентификационные данные следует использовать. Эта связь позволяет APIM проходить проверку подлинности в качестве этого удостоверения при выполнении запросов к API GraphQL Fabric.

На портале Azure перейдите к экземпляру APIM
Перейдите в безопасность>управляемые удостоверения
Добавьте управляемое удостоверение, назначенное пользователем ранее

Добавление политики проверки подлинности

Последний шаг проверки подлинности — добавление политики APIM, которая получает токен доступа с помощью управляемого удостоверения и включает его в запросы к Fabric. Эта политика выполняется при каждом запросе, автоматически обрабатывая получение и продление токенов. Политика использует элемент authentication-managed-identity для получения токена для ресурса API Fabric, а затем добавляет его в заголовок Авторизации.

В API GraphQL в APIM выберите вкладку "Политики API "
Редактирование политики входящей обработки

Добавьте следующий XML-код в <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>

Замените YOUR-MANAGED-IDENTITY-CLIENT-ID на идентификатор клиента управляемого удостоверения
Сохранение политики

Проверка подключения

Прежде чем продолжить добавление кэширования и ограничения скорости, убедитесь, что настройка проверки подлинности работает правильно. Теперь тестирование гарантирует, что все проблемы, которые возникают позже, не связаны с конфигурацией проверки подлинности.

В APIM перейдите к API GraphQL
Перейдите на вкладку "Тест"
Выполните пример запроса или модификации для подтверждения работы подключения

Настройка кэширования ответов

Кэширование ответов значительно снижает задержку для вызывающих API и уменьшает нагрузку серверной части на источники данных Fabric. APIM поддерживает встроенные экземпляры кэширования или внешние экземпляры Redis. Для API GraphQL кэширование использует текст запроса (запрос GraphQL) в качестве ключа кэша, гарантируя, что идентичные запросы возвращают кэшированные ответы.

Преимущества кэширования ответов GraphQL:

Снижение задержки: кэшированные ответы возвращаются мгновенно без запроса Fabric
Снижение потребления емкости: Меньше запросов к Fabric, что приводит к сокращению использования CU (единица емкости)
Повышение масштабируемости. Обработка большего числа одновременных пользователей без увеличения нагрузки серверной части

Добавление политики кэширования

Чтобы реализовать кэширование, измените существующую политику проверки подлинности, чтобы добавить логику поиска кэша и хранилища. Политика проверяет наличие кэшированных ответов перед пересылкой запросов в Fabric и сохраняет успешные ответы для дальнейшего использования. В этом примере полной политики показано, как работает проверка подлинности и кэширование:

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

Как работает эта политика:

Входящий трафик: выполняет проверку подлинности с помощью управляемого удостоверения и проверяет, кэшируется ли ответ на основе запроса GraphQL.
Серверная часть: пропускает перенаправление запроса в Fabric, если кэшированный ответ существует
Исходящий трафик: возвращает кэшированные ответы или кэширует новые успешные ответы в течение 60 секунд.

Проверка работы кэширования

Чтобы подтвердить, что запросы кэшируются:

В APIM выполните один и тот же запрос GraphQL дважды
Трассировка вызова API, чтобы увидеть попадания в кэш

Оптимизация длительности кэша

В примере используется 60-секундная длительность кэша. Настройте длительность на основе требований к свежести данных:

Обновления высокой частоты: используйте более короткие длительности (10–30 секунд) для часто изменяющихся данных
Статические или эталонные данные: используйте более длительные сроки (5–60 минут) для данных, которые редко изменяются.
Требования в режиме реального времени: не кэшируйте запросы, которые всегда должны возвращать последние данные.

Дополнительные сценарии кэширования, включая недопустимое кэширование и конфигурацию внешнего Redis, см. в политиках кэширования APIM.

Ограничение скорости

Можно ограничить количество вызовов API, которые клиент может выполнять в определенный период времени. Вы можете добавить ниже <inbound><base/> запись политики ограничения трафика, которая разрешает не более двух вызовов каждые 60 секунд для данного пользователя.

<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" />

После отправки более двух вызовов API в минуту вы получите сообщение об ошибке:

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

Дополнительные сведения о настройке политик ограничения скорости в APIM см. в документации.

Лучшие практики

При интеграции APIM с API Fabric для GraphQL следуйте приведенным ниже рекомендациям.

Безопасность

Используйте управляемые удостоверения: Предпочитайте управляемые удостоверения в отличие от ключей API или строк подключения для проверки подлинности.
Реализуйте минимальные привилегии: предоставьте только минимальные разрешения, необходимые для управляемого удостоверения.
Включение только HTTPS: настройте APIM для отклонения HTTP-запросов и принудительного применения HTTPS
Проверка входных данных. Использование политик APIM для проверки запросов GraphQL перед пересылкой в Fabric

Performance

Кэширование часто запрашиваемых данных: определение часто используемых запросов и установка соответствующих продолжительностей кэширования
Мониторинг частоты попаданий в кэш: использование аналитики APIM для отслеживания эффективности кэша
Оптимизация лимитов запросов: сбалансировать взаимодействие пользователей с защитой производительности
Используйте региональное развертывание: развертывайте APIM в том же регионе, что и емкость Fabric

Мониторинг и управление

Включение диагностики: настройка ведения журнала диагностики APIM для отслеживания использования API
Настройка оповещений: создание оповещений для нарушений ограничения скорости и ошибок
Версионирование ваших API: Используйте версионирование в APIM для управления изменениями, которые могут нарушить совместимость
Документируйте API: используйте портал разработчика APIM для предоставления документации по API

Оптимизация затрат

Оптимизация лимитов скорости: задайте ограничения, которые соответствуют уровню емкости.
Мониторинг использования емкости: отслеживание использования емкости как APIM, так и Fabric
Стратегическое использование кэширования: балансируйте требования к свежести с экономией емкости
Просмотр шаблонов использования. Регулярно анализируйте, какие запросы потребляют больше всего ресурсов

Сводка

Интеграция API Microsoft Fabric GraphQL с Azure API Management объединяет мощные возможности работы с данными Fabric с возможностями шлюза корпоративного уровня в APIM. Эта комбинация обеспечивает следующее:

Улучшенная безопасность: удостоверение управляемой идентичности, защита от угроз и управление доступом на основе политик доступа
Улучшенная масштабируемость: кэширование ответов, ограничение скорости и распределение нагрузки между несколькими внутренними серверами
Улучшенная производительность: снижение задержки с помощью кэширования и оптимизации маршрутизации запросов
Централизованное управление: единый мониторинг, управление версиями и управление в нескольких API
Управление затратами: ограничение скорости и кэширование снижает потребление емкости Fabric

Следуя инструкциям по настройке и рекомендациям в этой статье, вы можете создать надежный, безопасный и масштабируемый уровень API, поддерживающий рабочие нагрузки в организации.

Обратная связь

Были ли сведения на этой странице полезными?

Last updated on 2026-01-21