Используйте API ARCore в Google Cloud

Выберите платформу:

Функции ARCore, такие как Geospatial API и Cloud Anchors, используют API ARCore, размещенный в Google Cloud. При использовании этих функций ваше приложение использует учетные данные для доступа к сервису ARCore API.

В этом кратком руководстве описано, как настроить ваше приложение для взаимодействия со службой API ARCore, размещенной в Google Cloud.

Создайте новый проект Google Cloud или используйте существующий проект.

If you have an existing project, select it.

Перейдите к выбору проекта

Если у вас нет существующего проекта в Google Cloud, создайте его.

Создать новый проект

Включите API ARCore

Для использования API ARCore необходимо включить его в вашем проекте.

Enable the ARCore API

Настройте способ авторизации.

iOS-приложение может взаимодействовать с API ARCore, используя два разных метода авторизации: авторизацию без ключа (рекомендуемый метод) и авторизацию с помощью ключа API.

  • Авторизация без ключа использует подписанный токен для управления доступом к API. Этот метод требует наличия принадлежащего вам сервера для подписи токенов и управления доступом к API.
  • Ключ API — это строка, идентифицирующая проект Google Cloud. Ключи API обычно не считаются безопасными, поскольку, как правило, доступны клиентам. Рекомендуется использовать авторизацию с помощью токенов для взаимодействия с API ARCore.

Бесключевой доступ

ARCore поддерживает авторизацию вызовов API в iOS с использованием JSON Web Token . Токен должен быть подписан учетной записью сервиса Google.

Для генерации токенов для iOS на вашем сервере должна быть конечная точка, удовлетворяющая следующим требованиям:

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

  • Каждый раз конечная точка должна генерировать новый токен, при условии, что:

    • Каждый пользователь получает уникальный токен.
    • Токены не истекают мгновенно.

Создайте учетную запись службы и ключ подписи.

Выполните следующие шаги, чтобы создать учетную запись службы Google и ключ подписи:

  1. В Google Cloud откройте страницу «Учетные данные».
    Реквизиты для входа
  2. Нажмите «Создать учетные данные» > «Учетная запись службы» .
  3. В разделе «Сведения об учетной записи службы» введите имя для новой учетной записи, затем нажмите «Создать» .
  4. На странице разрешений служебной учетной записи перейдите к раскрывающемуся списку «Выберите роль» . Выберите «Служебные учетные записи» > «Создатель токенов служебных учетных записей» , затем нажмите «Продолжить».
  5. На странице доступа пользователей к этой учетной записи сервиса нажмите «Готово».
  6. On the Credentials page, find the Service Accounts section and click the name of the account you just created.
  7. На странице сведений об учетной записи службы прокрутите вниз до раздела «Ключи» и выберите «Добавить ключ» > «Создать новый ключ» .

  8. Выберите JSON в качестве типа ключа и нажмите «Создать» .

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

Создайте токены на своем сервере.

Для создания новых токенов (JWT) на вашем сервере используйте стандартные библиотеки JWT и JSON-файл, который вы безопасно загрузили из своей новой учетной записи службы.

Создайте токены на своей машине для разработки.

Для генерации JWT на вашей машине разработчика используйте следующую команду oauth2l : 

oauth2l fetch --cache "" --jwt --json $KEYFILE --audience "https://arcore.googleapis.com/"

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

Подпишите токен

Для подписи JWT необходимо использовать алгоритм RS256 и следующие утверждения:

  • iss — Адрес электронной почты служебного аккаунта.
  • sub — Адрес электронной почты служебного аккаунта.
  • iat — Время в формате Unix epoch, в секундах, когда был сгенерирован токен.
  • exp — iat + 3600 (1 час). Время в формате Unix epoch, в секундах, когда истекает срок действия токена.
  • aud — Аудитория. Необходимо установить значение https://arcore.googleapis.com/ .

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

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

Передайте токен в сессии ARCore.

Ваше приложение теперь настроено на использование бесключевой аутентификации.

При передаче токена в сессию обратите внимание на следующее:

  • Если для создания сессии использовался ключ API, ARCore проигнорирует токен и зарегистрирует ошибку.

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

  • ARCore игнорирует токены, содержащие пробелы или специальные символы.

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

Ключ API

  1. В Google Cloud откройте страницу «Учетные данные».
    Реквизиты для входа
  2. Нажмите «Создать учетные данные» , затем выберите «Ключ API» в меню.
    В диалоговом окне создания ключа API отображается строка, соответствующая вашему вновь созданному ключу.
  4. Ознакомьтесь с документацией по ограничениям, связанным с ключами API , чтобы обеспечить безопасность своего ключа API.

Ваше приложение теперь настроено на использование ключей API.

Что дальше?

После настройки авторизации ознакомьтесь со следующими функциями ARCore, которые её используют: