Связаться с намиПодключиться

Настройка доступа с помощью API-ключа

Статья создана
Обновлена 1 ноября 2024 г.

Для простой и безопасной работы с сервисами Yandex Vision OCR и Yandex Translate рекомендуется использовать авторизацию от имени сервисного аккаунта с помощью API-ключа.

Чтобы настроить авторизацию от имени сервисного аккаунта:

  1. Подготовьте облако к работе.
  2. Создайте сервисный аккаунт.
  3. Назначьте роли сервисному аккаунту.
  4. Создайте API-ключ.

Подготовьте облако к работе

Зарегистрируйтесь в Yandex Cloud и создайте платежный аккаунт:

  1. Перейдите в консоль управления, затем войдите в Yandex Cloud или зарегистрируйтесь.
  2. На странице Yandex Cloud Billing убедитесь, что у вас подключен платежный аккаунт, и он находится в статусе ACTIVE или TRIAL_ACTIVE. Если платежного аккаунта нет, создайте его и привяжите к нему облако.

Если у вас есть активный платежный аккаунт, вы можете создать или выбрать каталог, в котором будет работать ваша инфраструктура, на странице облака.

Подробнее об облаках и каталогах.

Создайте сервисный аккаунт

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

  2. В списке сервисов выберите Identity and Access Management.

  3. Нажмите кнопку Создать сервисный аккаунт.

  4. Введите имя сервисного аккаунта, например sa-api.

    Требования к формату имени:

    • длина — от 3 до 63 символов;
    • может содержать строчные буквы латинского алфавита, цифры и дефисы;
    • первый символ — буква, последний — не дефис.

  5. Нажмите кнопку Создать.

Если у вас еще нет интерфейса командной строки Yandex Cloud, установите и инициализируйте его.

По умолчанию используется каталог, указанный в профиле CLI. Вы можете указать другой каталог с помощью параметра --folder-name или --folder-id.

Выполните команду для создания сервисного аккаунта:

yc iam service-account create --name sa-api

Где --name — имя сервисного аккаунта в формате:

  • длина — от 3 до 63 символов;
  • может содержать строчные буквы латинского алфавита, цифры и дефисы;
  • первый символ — буква, последний — не дефис.

Результат:

id: ajehr0to1g8b********
folder_id: b1gv87ssvu49********
created_at: "2023-03-04T09:03:11.665153755Z"
name: sa-api

Создайте сервисный аккаунт с помощью метода REST API create для ресурса ServiceAccount:

curl \
  --request POST \
  --header 'Content-Type: application/json' \
  --header "Authorization: Bearer <IAM-токен>" \
  --data '{
    "folderId": "<идентификатор_каталога>",
    "name": "<имя_сервисного_аккаунта>",
    "description": "service account for api"
  }' \
  https://iam.api.cloud.yandex.net/iam/v1/serviceAccounts

Где:

  • <IAM-токен> — действующий токен авторизации;

  • <идентификатор_каталога> — идентификатор каталога, в котором размещены сервисы;

  • <имя_сервисного_аккаунта> — имя сервисного аккаунта, например sa-api. Требования к формату имени:

    • длина — от 3 до 63 символов;
    • может содержать строчные буквы латинского алфавита, цифры и дефисы;
    • первый символ — буква, последний — не дефис.

Также сервисный аккаунт можно создать с помощью вызова gRPC ServiceAccountService/Create.

Назначьте роли сервисному аккаунту

  1. На стартовой странице консоли управления выберите каталог.
  2. Перейдите на вкладку Права доступа.
  3. Найдите аккаунт sa-api в списке и нажмите значок .
  4. Нажмите кнопку Изменить роли.
  5. В открывшемся диалоге нажмите кнопку Добавить роль и выберите роль ai.translate.user для Yandex Translate или ai.vision.user для Yandex Vision OCR.
  6. Нажмите кнопку Сохранить.

Выполните команду:

yc resource-manager folder add-access-binding <идентификатор_каталога> \
   --role <идентификатор_роли> \
   --subject serviceAccount:<идентификатор_сервисного_аккаунта>

Где --role — ai.translate.user для Yandex Translate или ai.vision.user для Yandex Vision OCR.

Назначьте сервисному аккаунту роль с помощью метода REST API setAccessBindings для ресурса ServiceAccount:

curl \
  --request POST \
  --header "Content-Type: application/json" \
  --header "Authorization: Bearer <IAM-токен>" \
  --data '{
    "accessBindingDeltas": [{
      "action": "ADD",
      "accessBinding": {
        "roleId": "<идентификатор_роли>",
        "subject": {
          "id": "<идентификатор_сервисного_аккаунта>",
          "type": "serviceAccount"
          }
        }
      }
    ]
   }' \
  https://resource-manager.api.cloud.yandex.net/resource-manager/v1/folders/<идентификатор_каталога>:updateAccessBindings

Где:

  • <IAM-токен> — действующий токен авторизации.
  • <идентификатор_роли> — ai.translate.user для Yandex Translate или ai.vision.user для Yandex Vision OCR.
  • <идентификатор_сервисного_аккаунта> — идентификатор сервисного аккаунта sa-api.

Также назначить сервисному аккаунту роль можно с помощью вызова gRPC ServiceAccountService/SetAccessBindings.

Создайте API-ключ

  1. В консоли управления перейдите в каталог, которому принадлежит сервисный аккаунт.
  2. В списке сервисов выберите Identity and Access Management.
  3. На панели слева выберите Сервисные аккаунты.
  4. Выберите сервисный аккаунт, для которого вы хотите создать API-ключ. При необходимости создайте новый сервисный аккаунт.
  5. На панели сверху нажмите кнопку Создать новый ключ и выберите пункт Создать API-ключ.
  6. Задайте описание ключа, чтобы потом было проще найти его в консоли управления.
  7. (Опционально) Выберите Область действия. Подробнее про области действия см. в разделе API-ключи с ограничениями области и срока действия.
  8. (Опционально) Укажите Срок действия.
  9. Нажмите кнопку Создать.
  10. Сохраните идентификатор и секретный ключ.

Внимание

После закрытия диалога значение ключа будет недоступно.

По умолчанию используется каталог, указанный в профиле CLI. Вы можете указать другой каталог с помощью параметра --folder-name или --folder-id.

  1. Посмотрите описание команды создания API-ключа:

    yc iam api-key create --help

  2. Выберите сервисный аккаунт, например sa-api:

    yc iam service-account list

    Результат:

    +----------------------+------------------+-------------------------------+
|          ID          |       NAME       |          DESCRIPTION          |
+----------------------+------------------+-------------------------------+
| aje6o61dvog2******** | sa-api           |                               |
+----------------------+------------------+-------------------------------+

  3. Создайте API-ключ для сервисного аккаунта sa-api и запишите ответ в файл:

    yc iam api-key create --service-account-name sa-api > api-key.yaml

    В ответе в свойстве secret будет содержаться API-ключ:

    api_key:
  id: ajeke74kbp5b********
  service_account_id: ajepg0mjt06********
  created_at: "2019-04-09T08:41:27Z"
secret: AQVN1HHJReSrfo9jU3aopsXrJyfq_UHs********

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

Создайте API-ключ с помощью метода REST API create для ресурса ApiKey:

curl \
  --request POST \
  --header "Content-Type: application/json" \
  --header "Authorization: Bearer <IAM-токен>" \
  --data "{ \"serviceAccountId\": \"<идентификатор_сервисного_аккаунта>\" }" \
  https://iam.api.cloud.yandex.net/iam/v1/apiKeys

Где:

  • <IAM-токен> — действующий токен авторизации.
  • <идентификатор_сервисного_аккаунта> — идентификатор сервисного аккаунта sa-api.

Также API-ключ можно создать с помощью вызова gRPC API ApiKeyService/Create.

Теперь вы можете отправлять запросы в сервисы Yandex Vision OCR и Yandex Translate от имени сервисного аккаунта.

Полученный API-ключ указывайте при обращении к ресурсам Yandex Cloud через API. Передайте API-ключ в заголовке Authorization в следующем формате:

Authorization: Api-Key <API-ключ>
Предыдущая
Получение списка поддерживаемых языков
Следующая
Обзор