Общие сведения о портале разработчика

  • Статья

ОБЛАСТЬ ПРИМЕНЕНИЯ: Разработчик | Базовый | Базовая версия 2 | Стандартный | Standard v2 | Премиум

Портал разработчика Управление API — это автоматически созданный полностью настраиваемый веб-сайт с документацией по API. Именно здесь пользователи API могут искать ваши API, учиться их использовать, запрашивать к ним доступ и работать с ними.

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

Примечание.

Недавно мы улучшили интерфейс редактора портала, чтобы повысить производительность и улучшить взаимодействие с любимыми функциями и инструментами. Мы также изменили мини-приложения API и сведений о продукте, чтобы повысить уровень взаимодействия с порталом для посетителей.

Снимок экрана: портал разработчика Управление API.

ОБЛАСТЬ ПРИМЕНЕНИЯ: Разработчик | Базовый | Стандартный | Премиум

Архитектурные решения портала разработчика

Компоненты портала можно логически разделить на две категории: код и содержимое.

Код

Код хранится в репозитории портала разработчика управления API и включает в себя:

  • Мини -приложения — представляют визуальные элементы и объединяют HTML, JavaScript, возможности стилизации, параметры и сопоставление содержимого. Примерами являются изображение, текстовый абзац, форма, список интерфейсов API и т. д.
  • Определения стилей — укажите, как могут быть применены стили мини-приложений
  • Механизм, который создает статические веб-страницы из содержимого портала и написан на JavaScript
  • Визуальный редактор, позволяющий выполнять настройку и разработку в браузере

Содержимое

Содержимое делится на две подкатегории: содержимое портала и данные Управление API.

  • Содержимое портала относится к веб-сайту портала и включает:

    • Страницы — например, Целевая страница, учебники по API, записи в блоге

    • Мультимедиа — изображения, анимация и другое файлового содержимого

    • Макеты — шаблоны, которые соответствуют URL-адресу и определяют, как отображаются страницы

    • Стили — значения для определений стилей, таких как шрифты, цвета и границы

    • Параметры — конфигурации, такие как пиктограмма сайта, метаданные веб-сайта

      Содержимое портала, за исключением носителя, выражается в виде документов JSON.

  • Управление API данные включают такие сущности, как API, операции, продукты и подписки, управляемые в экземпляре Управление API.

Настройка и стиль портала

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

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

Пошаговое руководство по настройке и публикации портала разработчика см. в руководстве по доступу и настройке портала разработчика.

Внимание

  • Для доступа к порталу разработчика издателям API и потребителям требуется сетевое подключение к конечной точке портала разработчика (по умолчанию: https://<apim-instance-name>.portal.azure-api.net) и конечной точке управления Управление API экземпляра (по умолчанию: https://<apim-instance-name>.management.azure-api.net).
  • Для публикации портала разработчика требуется дополнительное подключение к хранилищу BLOB-объектов, управляемому Управление API в регионе "Западная часть США".
  • Если экземпляр Управление API развертывается в виртуальной сети, убедитесь, что имена узлов портала разработчика и конечной точки управления разрешаются правильно и позволяют подключаться к необходимым зависимостям для портала разработчика. Подробнее.

Редактор визуальных элементов

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

Администратор может настроить содержимое портала с помощью визуального редактора.

Снимок экрана: визуальный редактор на портале разработчика.

  • Используйте параметры меню слева для создания или изменения страниц, мультимедиа, макетов, меню, стилей или параметров веб-сайта.

  • Вверху переключитесь между окнами просмотра (для экранов разных размеров) или просматривайте элементы портала, видимые пользователям в разных группах. Например, может потребоваться отобразить определенные страницы только группам, связанным с определенными продуктами, или пользователям, которые могут получить доступ к определенным API.

  • Кроме того, сохраните или отмените внесенные изменения или опубликуйте веб-сайт.

  • Выберите существующие элементы текста и заголовка для редактирования и форматирования содержимого.

  • Добавьте раздел на страницу, наведите указатель мыши на пустую область и щелкните синий значок со знаком плюса. Выберите один из нескольких макетов разделов.

    Снимок экрана: значок раздела добавления на портале разработчика.

  • Добавьте мини-приложение (например, текст, изображение, настраиваемый список мини-приложений или API), наведите указатель мыши на пустую область, а затем щелкните серый значок со знаком плюса.

    Снимок экрана: значок добавления мини-приложения на портале разработчика.

  • Переупорядочение элементов на странице путем перетаскивания.

Макеты и страницы

Макеты определяют способ отображения страниц. Например, в содержимом по умолчанию есть два макета: один применяется к домашней странице, а другой — ко всем остальным страницам. Эти макеты можно изменить и добавить дополнительные макеты в соответствии с вашими потребностями.

Макет применяется к странице путем сопоставления шаблона URL-адреса со страницей. Например, макет с шаблоном /wiki/* URL-адреса применяется к каждой странице /wiki/ с сегментом в URL-адресе: /wiki/getting-started, /wiki/stylesи т. д.

На следующем рисунке содержимое, относящееся к макету, описывается синим цветом, а содержимое для конкретной страницы выделено красным цветом.

Снимок экрана: содержимое макета на портале разработчика.

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

Примечание.

Из-за особенностей интеграции следующие страницы невозможно удалить или разместить под другим URL-адресом: /404, /500, /captcha, /change-password, /config.json, /confirm/invitation, /confirm-v2/identities/basic/signup, /confirm-v2/password, /internal-status-0123456789abcdef, /publish, /signin, /signin-sso, /signup.

Стили

Снимок экрана: руководство по стилю на портале разработчика.

Панель стилей создается с учетом конструкторов. Используйте стили для управления и настройки всех визуальных элементов на портале, таких как шрифты, используемые в заголовках и меню и цветах кнопок. Стили применяются иерархически — многие элементы наследуют свойства других элементов. Например, в элементах кнопок используются цвета текста и фона. Чтобы изменить цвет кнопки, необходимо изменить исходный вариант цвета.

Чтобы изменить вариант, выберите его и выберите "Изменить стиль " в параметрах, которые отображаются в верхней части. После внесения изменений во всплывающем окне закройте его.

Расширение функциональных возможностей портала

В некоторых случаях могут потребоваться функциональные возможности помимо настройки и параметров стиля, поддерживаемых на управляемом портале разработчика. Если вам нужно реализовать особую логику, которая не поддерживается в настройке при поставке, у вас есть несколько вариантов:

Примечание.

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

Управление доступом к содержимому портала

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

Видимость содержимого и доступ

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

Вы также можете управлять тем, как отображается другое содержимое портала (например, страницы и разделы) для разных пользователей на основе их удостоверения. Например, может потребоваться отобразить определенные страницы только пользователям, имеющим доступ к конкретному продукту или API. Кроме того, раздел страницы отображается только для определенных групп пользователей. На портале разработчика есть встроенные элементы управления для этих потребностей.

Примечание.

Элементы управления видимостью и доступом поддерживаются только на управляемом портале разработчика. Они не поддерживаются на локальном портале.

  • При добавлении страницы или изменении параметров существующей страницы выберите в разделе "Доступ " для управления пользователями или группами, которые могут видеть страницу.

    Снимок экрана: параметры управления доступом на странице на портале разработчика.

    Совет

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

  • При выборе содержимого страницы, например раздела страницы, меню или кнопки для редактирования, щелкните значок "Изменить доступ" , чтобы управлять пользователями или группами, которые могут видеть элемент на странице

    Снимок экрана: кнопка

    • Вы можете изменить видимость следующего содержимого страницы: разделы, меню, кнопки и вход для авторизации OAuth.

    • Файлы мультимедиа, такие как изображения на странице, наследуют видимость элементов, содержащих их.

Когда пользователь посещает портал разработчика с применением элементов управления видимостью и доступом:

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

  • Попытка пользователя получить доступ к странице, к ней не разрешена доступ, приводит к ошибке 404 Not Found.

Совет

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

Политика безопасности содержимого

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

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

  1. Перейдите к экземпляру Управления API на портале Azure.
  2. В меню слева на портале разработчика выберите параметры портала.
  3. На вкладке "Политика безопасности содержимого" выберите "Включено".
  4. В разделе "Разрешенные источники" добавьте одно или несколько имен узлов, которые указывают доверенные расположения, из которых портал разработчика может загружать ресурсы. Можно также указать дикий карта символ, чтобы разрешить все поддомены домена. Например, *.contoso.com разрешает все поддомены contoso.com.
  5. Выберите Сохранить.

Интерактивная консоль тестирования

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

Снимок экрана: тестовая консоль на портале разработчика Управление API.

Консоль тестирования поддерживает API с различными моделями авторизации, например API, для которых не требуется авторизация, или требуется ключ подписки или авторизация OAuth 2.0. В последнем случае можно настроить тестовую консоль для создания допустимого маркера OAuth от имени пользователя тестовой консоли. Дополнительные сведения см. в статье "Авторизация тестовой консоли портала разработчика", настроив авторизацию пользователя OAuth 2.0.

Внимание

Чтобы позволить посетителям портала тестировать API через встроенную интерактивную консоль, включите политику CORS (совместного доступа к ресурсам между источниками) в API. Дополнительные сведения см. в разделе "Включение CORS для интерактивной консоли" на портале разработчика Управление API.

Управление регистрациями пользователей и входом

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

Портал поддерживает несколько вариантов регистрации и входа пользователей:

Узнайте больше о параметрах для защиты регистрации пользователей и входа на портал разработчика.

Отчеты для пользователей

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

Примечание.

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

Сохранение и публикация содержимого веб-сайта

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

Сохранить изменения

Снимок экрана: кнопка

Всякий раз, когда вы вносите изменения на портале, его необходимо сохранить вручную, нажав кнопку "Сохранить " в меню вверху или нажав клавиши [CTRL]+[S]. Если вам нужно, можно отменить последние сохраненные изменения. Сохраненные изменения отображаются только для вас и не отображаются посетителям портала, пока вы не опубликуете их.

Примечание.

Портал управляемого разработчика получает и автоматически применяет обновления программного обеспечения. Изменения, сохраненные, но не опубликованные на портале разработчика, остаются в этом состоянии во время обновления.

Публикация портала

Чтобы сделать портал и последние изменения на нем доступными для посетителей, его нужно опубликовать. Вы публикуете портал в административном интерфейсе портала или из портал Azure.

Внимание

Вы должны опубликовать портал в любое время, когда вы хотите предоставить изменения содержимому или стилю портала. Портал также необходимо повторно опубликовать после изменения конфигурации службы Управление API, влияющих на портал разработчика. Например, повторно опубликуйте портал после назначения личного домена, обновления поставщиков удостоверений, настройки делегирования или указания условий входа и использования продукта.

Публикация из административного интерфейса

  1. Убедитесь, что вы сохранили изменения, нажав кнопку "Сохранить ".

  2. В меню в верхней части окна выберите " Опубликовать сайт". Это может занять несколько минут.

    Снимок экрана: кнопка

Публикация с портала Azure

  1. Перейдите к экземпляру Управления API на портале Azure.

  2. В меню слева в разделе Портал разработчика щелкните Обзор портала.

  3. В окне Обзор портала щелкните Опубликовать.

    Снимок экрана: публикация портала разработчика с портал Azure

Восстановление предыдущей версии портала

Каждый раз, когда вы публикуете портал разработчика, сохраняется соответствующая редакция портала. В любое время можно повторно опубликовать предыдущую версию портала. Например, вам может потребоваться откат изменения, введенного при последней публикации портала.

Примечание.

Обновления программного обеспечения портала разработчика применяются автоматически при восстановлении редакции. Изменения, сохраненные, но не опубликованные в административном интерфейсе, остаются в этом состоянии при публикации редакции.

Чтобы восстановить предыдущую версию портала, выполните следующие действия.

  1. Перейдите к экземпляру Управления API на портале Azure.
  2. В меню слева в разделе Портал разработчика щелкните Обзор портала.
  3. На вкладке "Редакции" выберите контекстное меню (...) для изменения, который требуется восстановить, а затем выберите "Сделать текущим" и "Опубликовать".

Сброс портала

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

Примечание.

Сброс портала разработчика не удаляет опубликованную версию портала разработчика.

Чтобы сбросить портал разработчика, выполните следующие действия.

  1. В административном интерфейсе в меню слева от визуального редактора выберите Параметры.
  2. На вкладке "Дополнительно" выберите "Да", сбросить веб-сайт в состояние по умолчанию.
  3. Выберите Сохранить.

Связанный контент

См. дополнительные сведения о портале разработчика:

Обзор других ресурсов