Публикация API Microsoft Azure Data Manager для энергетики в защищенном шлюзе API
Azure Управление API выступает в качестве важного посредника между клиентскими приложениями и внутренними API. Это упрощает доступ клиентов к службам, скрывая технические сведения и предоставляя организациям контроль над безопасностью API.
Публикуя API Azure Data Manager для энергетики через Azure Управление API, вы можете использовать Azure Data Manager for Energy Приватный канал для частного трафика и полностью удалить прямой общедоступный доступ к экземпляру.
В этой статье описывается, как настроить Azure Управление API для защиты API Azure Data Manager для энергетики.
Необходимые компоненты
Для выполнения этого пошагового руководства вам потребуются следующие компоненты, средства и сведения:
Виртуальная сеть с двумя подсетями доступна, одна для частной конечной точки Azure Data Manager для энергетики и другая для внедрения виртуальных сетей Azure Управление API.
Диспетчер данных Azure для энергетики, настроенный с помощью приватного канала , развернутого в подсети.
Azure Управление API подготовлен и развернут в виртуальной сети с помощью внедрения виртуальной сети. Выберите внешний режим или см. раздел "Другие параметры" для внутреннего режима.
Редактор кода, например Visual Studio Code для изменения спецификаций Azure Data Manager for Energy OpenAPI для каждого из опубликованных API.
Скачайте спецификации Azure Data Manager для Energy OpenAPI из репозитория GitHub adme-samples . Перейдите в каталог rest apis и выберите соответствующую версию приложения.
Из регистрации приложения для приложения Azure Data Manager для энергетики, которое использовалось во время подготовки, обратите внимание на идентификатор клиента и идентификатор клиента:
Подготовка экземпляра Управление API
Чтобы внести изменения конфигурации в экземпляр Azure Управление API, выполните следующие действия.
В области "Все ресурсы" выберите экземпляр Azure Управление API, используемый для этого пошагового руководства.
Перейдите на страницу параметров продуктов, выбрав ее из группирования параметров API:
На странице "Продукты" нажмите кнопку "Добавить", чтобы создать новый продукт. Продукты Azure Управление API позволяют создавать слабо связанные группы API, которые могут управляться и управляться вместе. Мы создадим продукт для наших API-интерфейсов Azure Data Manager для энергетики.
На странице "Добавление продукта" введите значения, описанные в следующей таблице, чтобы создать продукт.
Параметр Значение Отображаемое имя. "Azure Data Manager for Energy Product" Идентификатор "adme-product" Description Введите описание, указывающее разработчикам, какие API мы группируем Опубликованные Установите этот флажок, чтобы опубликовать создаваемый продукт Требуется подписка Установите этот флажок, чтобы предоставить базовую авторизацию для наших API Запрос утверждения При необходимости выберите, нужно ли администратору просматривать и принимать или отклонять попытки подписки на этот продукт. Если не выбрано, попытки подписки автоматически утверждены. Ограничение числа подписок При необходимости ограничьте число одновременных подписок. Юридические условия При необходимости определите условия использования для продукта, который подписчики должны принять для использования продукта. Программные интерфейсы Эту функцию можно игнорировать. Мы свяжите API далее в этой статье Нажмите Создать, чтобы создать продукт.
После завершения создания продукта портал возвращает вас на страницу "Продукты". Выберите созданный продукт Azure Data Manager для энергетического продукта, чтобы перейти на страницу ресурсов продукта. Выберите пункт меню параметров политик в меню параметров.
В области входящего трафика выберите <значок /> , который позволяет изменять политики для продукта. Вы добавите три набора политик для повышения безопасности решения:
- Проверка маркера идентификатора записи, чтобы убедиться, что запросы без проверки подлинности перехватываются в шлюзе API
- Квота и ограничение скорости для контроля скорости запросов и общих запросов и данных, передаваемых
- Задайте для удаления заголовков, возвращаемых внутренними API, которые могут выявить конфиденциальные сведения для потенциальных плохих субъектов.
Добавьте следующую политику маркера validate-azure-ad в нашу конфигурацию в входящих тегах и под базовым тегом. Обязательно обновите шаблон с помощью сведений об идентификаторе приложения Microsoft Entra ID, указанных в предварительных требованиях.
<validate-azure-ad-token tenant-id="INSERT_TENANT_ID"> <client-application-ids> <application-id>INSERT_APP_ID</application-id> </client-application-ids> </validate-azure-ad-token>Под политикой маркера validate-azure-ad добавьте следующиеполитики квоты и ограничения скорости. Обновите значения конфигурации политики соответствующим образом для потребителей.
<rate-limit calls="20" renewal-period="90" remaining-calls-variable-name="remainingCallsPerSubscription"/> <quota calls="10000" bandwidth="40000" renewal-period="3600" />В исходящий раздел редактора политик и под базовым тегом добавьте следующие политики set-header.
<set-header name="x-envoy-upstream-service-time" exists-action="delete" /> <set-header name="x-internal-uri-pattern" exists-action="delete" />Нажмите Сохранить, чтобы подтвердить изменения.
Вернитесь к ресурсу Управление API в портал Azure. Выберите пункт меню Backends и нажмите кнопку +Добавить.
В модале серверной части введите значения, описанные в следующей таблице, чтобы создать серверную часть.
Параметр Значение Имя. "adme-backend" Description Введите описание, указывающее разработчикам, что эта серверная часть связана с API Azure Data Manager для энергетики Тип Пользовательский URL-адрес URL-адрес среды выполнения Введите _ex диспетчера данных Azure для URI энергетики. https://INSERT_ADME_NAME.energy.azure.com/Проверка цепочки сертификатов Флажок установлен Проверка имени сертификата Флажок установлен 
Нажмите кнопку "Создать", чтобы создать серверную часть. Эта только что созданная серверная часть будет использоваться в следующем разделе при публикации API.
Импорт API-интерфейсов Azure Data Manager для энергетики
Выполните следующие действия, чтобы импортировать, настроить и опубликовать API Azure Data Manager для энергетики в шлюзе Azure Управление API:
Вернитесь к экземпляру Azure Управление API, используемому в последнем разделе.
Выберите пункт меню API в меню, а затем нажмите кнопку +Добавить API .
Выберите OpenAPI в заголовке создания из заголовка определения .
В модальном окне создания из спецификации OpenAPI выберите полный переключатель.
Найдите спецификации OpenAPI, скачанные в рамках предварительных требований, и откройте спецификацию схемы с помощью выбранного редактора кода. Найдите слово "сервер" и запишите URL-адрес сервера в файле ex. /api/schema-service/v1/.
Выберите файл и выберите спецификацию API схемы . После завершения отправки модальное окно загружает некоторые значения из спецификации.
Для других полей введите значения, описанные в следующей таблице:
Параметр Значение Включение необходимых параметров запроса в шаблоны операций Флажок установлен Показать имя Введите отображаемое имя, которое имеет смысл для разработчиков приложений , например Azure Data Manager для службы схемы энергетики Имя. Управление API предлагает имя кебаб-регистра. При необходимости имя может быть изменено, но оно должно быть уникальным для экземпляра. Description Спецификация OpenAPI может определить описание, если поэтому описание автоматически заполняется. При необходимости обновите описание для каждого варианта использования. Схема URL-адреса Выберите "Оба" Суффикс URL-адреса API Введите суффикс для всех API-интерфейсов Azure Data Manager для энергетики (например, adme). Затем введите URL-адрес сервера из шага 5. Окончательное значение должно выглядеть как /adme/api/schema-service/v1/. Суффикс позволяет нам соответствовать существующим клиентам и пакетам средств разработки программного обеспечения, которые обычно подключаются к API Azure Data Manager для энергетики напрямую. Теги При необходимости введите теги Продукты Выберите продукт Azure Data Manager для энергетики, созданный в предыдущем разделе. Внимание
Проверка суффикса URL-адреса API является распространенной причиной ошибок при публикации API Azure Data Manager для энергетических API
Нажмите кнопку "Создать", чтобы создать фасад API.
Выберите только что созданный фасад API схемы из списка API и выберите все операции в списке операций . В области входящего трафика выберите <значок />значок, чтобы изменить документ политики.
Чтобы настроить API, добавьте два набора политик:
- Настройка серверной службы для маршрутизации запросов к экземпляру Azure Data Manager для энергии
- Переопределите универсальный код ресурса (URI), чтобы удалить префикс adme и создать запрос к внутреннему API. Эта инструкция политики использует выражения политики для динамического добавления значения шаблона URL-адреса текущей операции в URL-адрес сервера.
Запишите URL-адрес сервера на шаге 5. Под базовым тегом в разделе входящего трафика вставьте следующие две инструкции политики.
<set-backend-service backend-id="adme-backend" /><!-- replace the '/api/schema-service/v1' with the server URL for this API specification you noted in step 5 --> <rewrite-uri template="@{return "/api/schema-service/v1"+context.Operation.UrlTemplate;}" />Нажмите Сохранить, чтобы подтвердить изменения.
Проверьте API, выбрав операцию ПОЛУЧЕНИЯ сведений о версии из списка операций. Затем выберите вкладку "Тест", чтобы перейти в консоль тестирования Azure Управление API.
Введите значения, описанные в следующей таблице. Создайте маркер проверки подлинности для Azure Data Manager для энергетики. Нажмите кнопку "Отправить ", чтобы протестировать API.
Параметр Значение data-partition-id Идентификатор секции данных для экземпляра Azure Data Manager для энергетики Продукт Выберите созданный ранее продукт Azure Data Manager для энергетики Авторизация "Носитель" и созданный маркер проверки подлинности 
Если API настроен правильно, вы увидите ответ HTTP 200 — ОК , похожий на снимок экрана. Если нет, проверка раздел "Устранение неполадок".
Повторите описанные выше действия для каждого API Azure Data Manager для энергетики и связанной спецификации.
Устранение неполадок
При тестировании API через Azure Управление API при возникновении ошибок они обычно указывают на проблемы с конфигурацией. На основе ошибки просмотрите возможные шаги разрешения.
| Код | Сообщение об ошибке | Сведения |
|---|---|---|
HTTP 401 Unauthorized |
Invalid Azure AD JWT |
Убедитесь, что у вас есть допустимый заголовок проверки подлинности для клиента и клиентского приложения Microsoft Entra ID для экземпляра Azure Data Manager для энергетики. |
HTTP 401 Unauthorized |
Azure AD JWT not present |
Убедитесь, что заголовок проверки подлинности добавлен в тестовый запрос. |
HTTP 404 Not Found |
Эта ошибка обычно означает, что запрос к внутреннему API выполняется в неправильный URL-адрес. Трассируйте запрос API в Управление API, чтобы понять, какой URL-адрес создается для внутреннего запроса и убедиться, что он действителен. В противном случае дважды проверка политику перезаписи URL-адресов или серверную часть. | |
HTTP 500 Internal Server Error |
Internal server error |
Эта ошибка обычно отражает проблему, связанную с запросами к внутреннему API. Как правило, в этом сценарии проблема связана со службами доменных имен (DNS). Убедитесь, что в виртуальной сети настроена частная зона DNS или есть соответствующие серверы пересылки. Трассируйте запрос API в Управление API, чтобы понять, какой внутренний запрос был сделан и какие ошибки Управление API отчеты при попытке сделать запрос. |
Другие вопросы
Управление API режим внутренней виртуальной сети
Внутренний режим полностью изолирует azure Управление API вместо предоставления конечных точек через общедоступный IP-адрес. В этой конфигурации организации могут убедиться, что весь диспетчер данных Azure для энергетики является внутренним. Так как Azure Data Manager для энергетики — это решение для совместной работы с партнерами и клиентами, это может оказаться не полезным.
Шлюз приложений с брандмауэром веб-приложения
Вместо использования режима внутренней виртуальной сети многие организации предпочитают применять защищенный механизм обратного прокси-сервера для предоставления внутреннего режима Azure Управление API экземпляру внешних партнеров и клиентов. Экземпляр внутреннего режима остается полностью изолированным с жестко контролируемым входящего трафика, который должен проходить через прокси-сервер.
приложение Azure шлюз — это общая служба, используемая в качестве обратного прокси-сервера. приложение Azure шлюз также имеет возможность брандмауэра веб-приложений (WAF), который активно обнаруживает потенциальные атаки на уязвимости в приложениях и API.
Настройка Azure Управление API с помощью личного домена
Еще одной общей особенностью этой архитектуры является применение личного домена к API. Хотя Azure Data Manager для энергетики не поддерживает эту функцию, вы можете настроить личный домен в Azure Управление API.
Сертификат для домена является обязательным условием. Однако Azure Управление API поддерживает создание бесплатных управляемых сертификатов для личного домена.