Skip to content

Latest commit

 

History

History
118 lines (60 loc) · 8.26 KB

access.md

File metadata and controls

118 lines (60 loc) · 8.26 KB
Raw
sourcePath
ru/tracker/api-ref/concepts/access.md

Доступ к API

Для доступа приложений к {{ api-name }} используется авторизация по протоколу OAuth 2.0.

Если ваше приложение написано на языке Python, для вызова API вы можете использовать Python-клиент.

В запросах к {{ api-short-name }} указывайте заголовки:

  • Host: {{ host }}

  • Authorization: OAuth <OAuth-токен> — при доступе по протоколу OAuth 2.0.

    Authorization: Bearer <IAM-токен> — при доступе при помощи IAM-токена.

  • X-Org-ID или X-Cloud-Org-ID: <идентификатор_организации>

    Если у вас только организация {{ org-full-name }}, используйте заголовок X-Cloud-Org-ID, если только {{ ya-360 }} или оба типа организаций — X-Org-ID.

    Скопировать идентификатор организации можно на [странице организаций {{ tracker-name }}]({{ link-tracker }}admin/orgs).

Получить доступ к API по протоколу OAuth 2.0 {#section_about_OAuth}

Протокол OAuth 2.0 позволяет приложениям работать с сервисами Яндекса от имени пользователя. С базовыми принципами OAuth, а также с особенностями реализации протокола в Яндексе вы можете ознакомиться в [документации сервиса OAuth для Яндекс ID]({{ link-OAuth-dev-guide }}).

Чтобы получить доступ к {{ api-name }}:

  1. [Зарегистрируйте]({{ link-OAuth-register }}/#access-note) приложение в сервисе [Яндекс OAuth]({{ link-OAuth }}):

    1. Перейдите по прямой ссылке [{{ link-OAuth }}client/new/]({{ link-OAuth }}client/new/).

    2. В разделе Платформы приложения выберите платформу и укажите ее параметры.

      Если вы разрабатываете или тестируете приложение, используйте [отладочный токен]({{ link-OAuth-debug-token }}). Для получения такого токена выберите Веб-сервисы и в поле Redirect URI подставьте значение по умолчанию, которое появится в подсказке Подставить URL для отладки: {{ link-OAuth }}verification_code.

    3. В разделе Доступ к данным выберите доступы к {{ tracker-name }}, которые необходимы приложению:

      • Запись в трекер (tracker:write) — все операции с данными: создание, удаление, редактирование.

      • Чтение из трекера (tracker:read) — только чтение данных.

  2. Получите OAuth-токен:

    1. В личном кабинете [Яндекс OAuth]({{ link-OAuth }}) выберите созданное ранее приложение и скопируйте его идентификатор из поля ClientID. Затем сформируйте ссылку для запроса токена:

      {{ link-OAuth }}authorize?response_type=token&client_id=<идентификатор_приложения>

    2. Перейдите по ссылке и скопируйте OAuth-токен.

    {% note tip %}

    Если для получения OAuth-токена вам требуется код подтверждения от пользователя, используйте инструкции в разделе [Запрос OAuth-токена при помощи кода подтверждения]({{ link-OAuth-codes }}).

    {% endnote %}

  3. Полученный токен используйте в заголовке Authorization в запросах к API {{ tracker-name }}. OAuth-токен предоставляет те же права, которые есть у аккаунта пользователя в {{ tracker-name }}. Например, если у пользователя нет прав на изменение настроек очереди, соответствующие запросы к API будут недоступны.

  4. Чтобы проверить наличие доступа к API, выполните запрос информации о текущем пользователе. Если доступ не был получен, запрос вернет ответ с кодом 401 Unauthorized.

Получить доступ к API по IAM-токену {#iam-token}

IAM-токен — уникальная последовательность символов, которая выдается пользователю после прохождения аутентификации. С помощью этого токена пользователь авторизуется в {{ api-name }} и выполняет операции с ресурсами. Подробнее об этом способе аутентификации читайте в документации сервиса идентификации и контроля доступа.

{% note info %}

IAM-токен действует не больше {{ iam-token-lifetime }} и ограничен временем жизни cookie у федерации. После истечения срока жизни вернется ошибка с кодом 401 Unauthorized.

{% endnote %}

Python-клиент {#section_about_python_client}

При разработке приложений на языке Python вы можете использовать пакет yandex_tracker_client — клиент, который облегчает работу с {{ api-short-name }}.

Чтобы начать пользоваться клиентом:

  1. Скачайте и установите на свой компьютер актуальную версию Python с сайта https://www.python.org/downloads/.

  2. В командной строке вашей ОС выполните команду:

    pip install yandex_tracker_client

  3. Получите OAuth-токен и идентификатор организации для доступа к API.

    Чтобы узнать идентификатор организации, перейдите на [страницу настроек {{ tracker-name }}]({{ link-settings }}). Идентификатор указан в поле ID организации для API.

  4. Инициализируйте клиент в коде вашей программы:

    from yandex_tracker_client import TrackerClient
client = TrackerClient(token=<OAuth-токен>, org_id=<идентификатор_организации>)

    Здесь <OAuth-токен> — ваш OAuth-токен, а <идентификатор_организации> — идентификатор организации.

В клиенте используйте такой же формат данных, как в API {{ tracker-name }}.

Подробнее о работе клиента и условиях использования читайте на его странице в GitHub: https://github.com/yandex/yandex_tracker_client.