Apps — это рекомендуемый способ интеграции с . Apps предлагают множество преимуществ по сравнению с OAuth apps, в том числе:
- Расширенные функции безопасности, такие как точные разрешения, выбор доступа к репозиторию и кратковременные маркеры
- Возможность действовать независимо от имени или от имени пользователя
- Ограничения масштабируемой скорости
- Встроенные веб-перехватчики
Дополнительные сведения см. в разделе Создание приложений .
Ниже приведен обзор переноса данных OAuth app на App. Конкретные шаги зависят от приложения.
Повторно ознакомьтесь с кодом для данных OAuth app. API запрашивает ваши OAuth app поможет вам решить, какие разрешения можно выбрать для ваших App.
Кроме того, существует несколько конечных точек REST API, недоступных для OAuth apps. Убедитесь, что все используемые конечные точки REST доступны для Apps путем проверки AUTOTITLE.
Зарегистрируйте новые данные 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. Дополнительные сведения см. в разделе Выбор разрешений для приложения .
После регистрации 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, чтобы убедиться, что код работает должным образом.
Если вы хотите, чтобы другие учетные записи могли использовать новые данные App, убедитесь, что ваше приложение открыто. Если вы хотите сделать данные App более обнаруживаемыми, перечислите приложение в Marketplace. Дополнительные сведения см. в разделе [AUTOTITLE и Преобразование приложения в общедоступное или частное](/apps/publishing-apps-to--marketplace/-marketplace-overview/about--marketplace).
После подготовки новых данных App попросите пользователей старых OAuth app перейти на новый App. Нет способа автоматической миграции пользователей. Каждый пользователь должен установить и /или авторизовать данные App самостоятельно.
Как владелец приложения, необходимо включить призывы к действию, чтобы поощрять пользователей устанавливать и авторизовать новые App и отменять авторизацию для старых данных OAuth 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. Это поможет вам полностью перейти от OAuth app и поможет защитить данные пользователей. Дополнительные сведения см. в разделе Просмотр авторизованных приложений OAuth.
Необходимо обновить любой пользовательский интерфейс или документацию, связанные с приложением, чтобы отразить изменение от OAuth app на 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)
После перехода пользователей на новые Appследует удалить старые данные OAuth app. Это поможет избежать злоупотреблений учетными данными OAuth app. Это действие также отменит все остальные разрешения OAuth app. Дополнительные сведения см. в разделе Удаление приложения OAuth. Если данные OAuth app перечислены в Marketplace, возможно, вам потребуется связаться с Служба поддержки для удаления приложения из Marketplace.