Перенос приложений OAuth в приложения

Преимущества миграции с OAuth apps на Apps

Apps — это рекомендуемый способ интеграции с . Apps предлагают множество преимуществ по сравнению с OAuth apps, в том числе:

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

Дополнительные сведения см. в разделе Создание приложений .

Преобразование данных OAuth app в App

Ниже приведен обзор переноса данных OAuth app на App. Конкретные шаги зависят от приложения.

1. Просмотрите данные OAuth app

Повторно ознакомьтесь с кодом для данных OAuth app. API запрашивает ваши OAuth app поможет вам решить, какие разрешения можно выбрать для ваших App.

Кроме того, существует несколько конечных точек REST API, недоступных для OAuth apps. Убедитесь, что все используемые конечные точки REST доступны для Apps путем проверки AUTOTITLE.

2. Регистрация App

Зарегистрируйте новые данные App. Дополнительные сведения см. в разделе Регистрация приложения .

По сравнению с параметрами OAuth app, у вас больше контроля над параметрами App. Ниже приведены некоторые ключевые дополнения.

В отличие от OAuth app, который всегда выступает от имени пользователя, вы можете выполнить действия от имени пользователя App. Если вы не хотите, чтобы новые данные App могли выполнять действия от имени пользователя, можно пропустить параметры "Идентификация и авторизация пользователей". Дополнительные сведения см. в разделе Сведения о проверке подлинности с помощью приложения .
Веб-перехватчики можно использовать для уведомления App при возникновении определенных событий. В отличие от веб-перехватчиков для OAuth apps, которые необходимо настроить с помощью API для каждого репозитория или организации, веб-перехватчики встроены в Apps. При регистрации данных Appможно выбрать события веб-перехватчика, которые вы хотите получить. Кроме того, если ваш OAuth app в настоящее время использует опрос для определения того, произошло ли событие, рассмотрите возможность подписки на веб-перехватчики, чтобы помочь App оставаться в пределах ограничения скорости. Дополнительные сведения см. в разделе Использование веб-перехватчиков с приложениями .
При использовании OAuth appзапрашивает области, когда пользователь авторизует приложение. При использовании Appукажите разрешения в параметрах приложения. Эти разрешения более детализированные, чем области, и позволяют выбирать только необходимые приложения разрешения. Кроме того, эти разрешения сопоставляются с конечными точками REST API и событиями веб-перехватчика, поэтому вы можете легко определить, какие разрешения требуются App для доступа к определенной конечной точке REST API или подписке на конкретный веб-перехватчик. Разрешения в настоящее время не документируются для запросов GraphQL. Дополнительные сведения см. в разделе Выбор разрешений для приложения .

3. Изменение кода для приложения

После регистрации Appадаптируйте код из старых OAuth app для работы с новыми данными App.

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

Вам потребуется обновить код приложения для обработки проверки подлинности API для App. App может пройти проверку подлинности тремя способами:

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

Если вы используете официальную библиотеку Octokit.js данных , можно использовать встроенный App объект для проверки подлинности. Примеры см. в разделе [AUTOTITLE и Скриптирование с помощью REST API и JavaScript](/apps/creating--apps/guides/building-a--app-that-responds-to-webhook-events).

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

Просмотрите различия в ограничениях скорости между OAuth apps и Apps. Apps используют скользящие правила для ограничений скорости, которые могут увеличиваться на основе числа репозиториев и числа пользователей в организации. Дополнительные сведения см. в разделе Ограничения скорости для приложений .

По возможности рекомендуется использовать условные запросы и подписку на веб-перехватчики вместо опроса, чтобы помочь вам оставаться в пределах скорости. Дополнительные сведения об условных запросах см. в разделе Рекомендации по использованию REST API. Дополнительные сведения об использовании веб-перехватчиков с данными Appсм. в разделе [AUTOTITLE и Использование веб-перехватчиков с приложениями ](/apps/creating--apps/guides/building-a--app-that-responds-to-webhook-events).

Тестирование кода

Проверьте новые данные App, чтобы убедиться, что код работает должным образом.

4. Публикуйте новые данные App

Если вы хотите, чтобы другие учетные записи могли использовать новые данные App, убедитесь, что ваше приложение открыто. Если вы хотите сделать данные App более обнаруживаемыми, перечислите приложение в Marketplace. Дополнительные сведения см. в разделе [AUTOTITLE и Преобразование приложения в общедоступное или частное](/apps/publishing-apps-to--marketplace/-marketplace-overview/about--marketplace).

5. Указание пользователям перенести

После подготовки новых данных App попросите пользователей старых OAuth app перейти на новый App. Нет способа автоматической миграции пользователей. Каждый пользователь должен установить и /или авторизовать данные App самостоятельно.

Как владелец приложения, необходимо включить призывы к действию, чтобы поощрять пользователей устанавливать и авторизовать новые App и отменять авторизацию для старых данных OAuth app. Также следует обновить любую документацию или элементы пользовательского интерфейса.

Запрос пользователей на установку App

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

Чтобы помочь пользователям установить App, можно добавить ссылку на веб-страницу приложения, которую пользователи могут щелкнуть, чтобы установить App. Формат URL-адреса установки .https://.com/apps/YOUR_APP_NAME/installations/new Замените YOUR_APP_NAME вялым именем App, которое можно найти в поле "Общедоступная ссылка" на странице параметров для App.

Чтобы предварительно выбрать все репозитории, к которой у вас есть доступ к OAuth app, можно добавить /permissions и запросить параметры к URL-адресу установки. Это помогает пользователям предоставлять доступ к репозиториям App, к которым уже есть доступ к OAuth app . Параметры запроса:

suggested_target_id: идентификатор пользователя или организации, устанавливающей данные App. Этот параметр является обязательным.
repository_ids[]: идентификаторы репозитория, которые нужно выбрать для установки. Если опущено, выбраны все репозитории. Максимальное число репозиториев, которые можно предварительно выбрать, — 100. Чтобы получить список репозиториев, к которым имеет доступ OAuth app, используйте репозитории List для конечных точек, прошедших проверку подлинности пользователей и репозиториев организации.

Например: https://.com/apps/YOUR_APP_NAME/installations/new/permissions?suggested_target_id=ID_OF_USER_OR_ORG&repository_ids[]=REPO_A_ID&repository_ids[]=REPO_B_ID.

Дополнительные сведения об установке Appsсм. в разделе AUTOTITLE, Установка приложения из Marketplace для организаций, [AUTOTITLE и Установка собственного приложения .](/apps/using--apps/installing-a--app-from--marketplace-for-your-personal-account)

Запрос пользователей на авторизацию приложения

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

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

Дополнительные сведения об авторизации Appsсм. в разделе Авторизация приложений .

Обновление любых интерфейсов или документации

Необходимо обновить любой пользовательский интерфейс или документацию, связанные с приложением, чтобы отразить изменение от OAuth app на App.

6. Удаление веб-перехватчиков для старых данных OAuth app

Когда пользователь устанавливает App и предоставляет доступ к репозиторию, необходимо удалить все веб-перехватчики для старых данных OAuth app. Если новые App и старые OAuth app отвечают на веб-перехватчики для того же события, пользователь может наблюдать за повторяющимся поведением.

Чтобы удалить веб-перехватчики репозитория, можно прослушивать installation_repositories веб-перехватчик с added помощью действия. Когда данные App получают это событие, можно использовать REST API для удаления веб-перехватчика в этих репозиториях для OAuth app. Дополнительные сведения см. в разделе [AUTOTITLE и События и полезные данные веб-перехватчика](/rest/webhooks#delete-a-repository-webhook).

Аналогичным образом, чтобы удалить веб-перехватчики организации, вы можете прослушивать installation веб-перехватчик с created помощью действия. Когда данные App получают это событие для организации, вы можете использовать REST API для удаления веб-перехватчика в этой организации и соответствующих репозиториев для OAuth app. Дополнительные сведения см. в разделе AUTOTITLE, [AUTOTITLE[ и Конечные точки REST API для веб-перехватчиков репозитория](/rest/orgs/webhooks#delete-an-organization-webhook).](/webhooks-and-events/webhooks/webhook-events-and-payloads?actionType=created#installation)

7. Удаление старых данных OAuth app

После перехода пользователей на новые Appследует удалить старые данные OAuth app. Это поможет избежать злоупотреблений учетными данными OAuth app. Это действие также отменит все остальные разрешения OAuth app. Дополнительные сведения см. в разделе Удаление приложения OAuth. Если данные OAuth app перечислены в Marketplace, возможно, вам потребуется связаться с Служба поддержки для удаления приложения из Marketplace.