Сервистік қолданбалар

Бұл мүмкіндік Кеңейтілген және Оңтайлы тарифтерінде қолжетімді. Негізгі тарифке ауысқан кезде, қолданбаларды басқару мүмкін болмайды, бір ай ішінде олардың тізімін тазартуға ғана болады. Ай аяқталғанда қолданбалар ұйымнан жойылады.

Сервистік қолданбалар API бойынша ұйымдағы пайдаланушылардың ресурстарын басқару үшін қолданылады. Мысалы, олардың көмегімен сіз электрондық пошталардың сақтық көшірмесін жасай аласыз немесе пайдаланушы Күнтізбесіндегі оқиғаларды басқара аласыз. Барлығы ең көбі 20 сервистік қолданба жасауға болады.

Назар аударыңыз

Офертаның 3.7 тармағына сәйкес рұқсат қосылғаннан кейін әкімші бұл туралы барлық пайдаланушыларға хабарлауға және қажет болған жағдайда олардың жазбаша келісімін алуға міндетті (егер бұрын бермеген болса).

Сервистік қолданбаларды қосу

  1. Ұйым иесінің аккаунтына кіріңіз.

  2. Ұйымдағы сервистік қолданбалардың тізімін басқаратын қолданбаны тіркеңіз.

    1. OAuth қолданбасын жасау бетін ашыңыз.

    2. Сервисіңіздің атауын көрсетіңіз және қажет болған жағдайда белгішені тіркеңіз.

    3. Қолданба платформалары блогында Веб-сервистер опциясын таңдаңыз. Redirect URI өрісінде Түзету үшін URL қою сілтемесін басыңыз.

    4. Деректерді пайдалану рұқсаты бөлімінде ұйымдағы сервистік қолданбаларды басқару үшін қажет пайдалану рұқсатын көрсетіңіз:

      • ya360_security:service_applications_read — сервистік қолданбалар тізімін оқу;

      • ya360_security:service_applications_write — сервистік қолданбалар тізімін басқару (оқу және жазу).

    5. Байланыс үшін электрондық поштаңызды қосыңыз. Қолданба жасау түймесін басыңыз. Экранда оның сипаттамасы пайда болады.

    6. ClientID өрісіндегі қолданба идентификаторын көшіріңіз — ол OAuth-токенді алу үшін қажет болады. Алдағы уақытта барлық қолданбаларыңыз бар бетті oauth.yandex.ru/ сілтемесі арқылы аша аласыз.

  3. Кез келген ыңғайлы әдіспен OAuth токенін сұраңыз. Ол ұйымдағы барлық сервистік қолданбаларды одан әрі тіркеу үшін қажет болады.

    Кейінге қалдырылған OAuth токенін қолмен алуға болады:

    1. Мына сілтеме бойынша өтіңіз:

      https://oauth.yandex.ru/authorize?response_type=token&client_id=<main_app_client_id>

      <main_app_client_id> орнына 2.6. тармағындағы ClientID мәнін қойыңыз.

    2. Егер OAuth токені қолданбаңызға бірінші рет берілген, авторизация экраны ашылады. Кіргеннен кейін Яндекс OAuth сізді токені бар парақшаға жібереді. Кейінге қалдырылған токендер туралы толығырақ.

  4. Пайдаланушыларға хабарлаңыз және егер олар бұрын келісім бермеген болса, офертаның 3.7 тармағына сәйкес әкімшіге ресурстарды басқаруға рұқсат беруге келісім алыңыз.

  5. Сервистік қолданбалар функциясын келесі сұрау арқылы іске қосыңыз:

    POST https://api360.yandex.net/security/v1/org/<org_id>/service_applications/activate

    <org_id> орнына ұйымыңыздың идентификаторын қойыңыз.

  6. Сервистік қолданбаны тіркеңіз. Оның көмегімен пайдаланушылардың уақытша OAuth токендерін алуға болады. Уақытша токеннің жарамдылық мерзімі — 1 сағат.

    1. Бөлек OAuth қолданбасын негізгі қолданбаны жасағандай жасаңыз (2-тармақ). Осы қолданбаның пайдалану рұқсаты ретінде API сұрауларында қолданылатын рұқсаттарды көрсетіңіз.

    2. Ұйым үшін алдыңғы қадамдағы қолданбаны сервистік етіп жасаңыз.

      Мысал
      curl --location \
--request POST 'https://api360.yandex.net/security/v1/org/<org_id>/service_applications' \ 
--header 'Authorization: OAuth <owner_token_to_manage_service_app>’ \
--header 'Content-Type: application/json' \
--data-raw '{ \
  "applications": [ \
    { \
      "id": “<OAuth_service_app_client_id>”, \
      "scopes": [ \
        "cloud_api:disk.app_folder", \
        "cloud_api:disk.read", \
        "cloud_api:disk.write", \
        "cloud_api:disk.info" \
      ] \
    } \
  ] \
}'

      Кодқа мына мәндерді қойыңыз:

      • <org_id> — ұйымыңыздың идентификаторы;

      • <owner_token_to_manage_service_app> — 3-тармақтағы OAuth токені;

      • <OAuth_service_app_client_id> — Сервистік қолданбаның 6.1. тармағындағы ClientID мәні.

    3. Қолданбаның сервистік қолданба ретінде дұрыс қосылғанын тексеріңіз.

      Мысал
      curl --location  \
--request GET 'https://api360.yandex.net/security/v1/org/<org_id>/service_applications'  \ 
--header 'Authorization: OAuth <owner_token_to_manage_service_app>'

    Басқа сервистік қолданбаларды қосу үшін 6-тармақтағы қадамдарды қайталаңыз.

  7. Пайдаланушының уақытша токенін алыңыз. Мұны API сұрауы арқылы жасауға болады:

    POST /token HTTP/1.1
   Host: http://oauth.yandex.ru
   Content-type: application/x-www-form-urlencoded
    Мысал
    curl --location \
--request POST 'https://oauth.yandex.ru/token' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'grant_type=urn:ietf:params:oauth:grant-type:token-exchange' \
--data-urlencode 'client_id=<OAuth_service_app_client_id>' \
--data-urlencode 'client_secret=<OAuth_service_app_client_secret>' \
--data-urlencode 'subject_token=<user_id>' \
--data-urlencode 'subject_token_type=urn:yandex:params:oauth:token-type:uid'

    немесе

    curl --location
--request POST 'https://oauth.yandex.ru/token' \ 
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'grant_type=urn:ietf:params:oauth:grant-type:token-exchange' \
--data-urlencode 'client_id=<OAuth_service_app_client_id>' \
--data-urlencode 'client_secret=<OAuth_service_app_client_secret>' \
--data-urlencode 'subject_token=<user_email>' \
--data-urlencode 'subject_token_type=urn:yandex:params:oauth:token-type:email'

    Кодқа мына мәндерді қойыңыз:

    • <OAuth_service_app_client_id> — Сервистік қолданбаның 6.1. тармағындағы ClientID мәні.

    • <OAuth_service_app_client_secret> — сервистік қолданбаның Client secret;

    • <user_id> — токен алу қажет пайдаланушының идентификаторы;

    • <user_email> — токен алу қажет пайдаланушының username@domain.ru түріндегі электрондық мекенжайы.

    Жауап Яндекс 360 сервистерінің API интерфейстеріне жіберілетін сұрауларда пайдалану қажет токенді қамтиды.

Сервистік қолданбалармен бағдарламалық жұмыс туралы толығырақ ақпарат API 360 анықтамасында сипатталған.

Пайдаланушылар ресурстарымен жұмыс істеу туралы сұраулардың мысалдары

Сервистік қолданбалардың көмегімен алынған уақытша токендер деректердің бэкапы, аудит немесе ақпарат іздеу үшін ұйымдағы кейбір пайдаланушы ресурстарына API арқылы қол жеткізуге мүмкіндік береді.

Яндекс Диск

Яндекс Диск API интерфейсі файлдармен жұмыс істеуге және оларды пайдалану рұқсатын басқаруға арналған. Дискінің API интерфейсіне сұрауларды Полигон сервисі арқылы жіберуге болады.

Мысал

Қызметкердің Диск қызметі туралы метаақпаратты алу сұрауы:

curl --request GET 'https://cloud-api.yandex.net/v1/disk' \ 
--header 'Accept: application/json' \
--header 'Authorization: OAuth <oauth_token>'

<oauth_token> орнына 7-тармақтағы пайдаланушының уақытша токенінің мәнін қойыңыз.

Диск қызметінің REST-API интерфейсімен жұмыс туралы толығырақ ақпарат.

Яндекс Почта

Қолданбалар OAuth протоколы бойынша Яндекс Пошта жәшіктерін пайдалана алады. OAuth-авторизацияны Яндекс Поштаның IMAP- және SMTP-серверлері қолданады.

Мысал

IMAP протоколы бойынша пайдаланушыдағы хаттарды есептеуге арналған Python скриптісі:

import imaplib

def generate_oauth2_string(username, access_token):
    auth_string = 'user=%s\1auth=Bearer %s\1\1' % (username, access_token)
    return auth_string

def get_imap_connector(username="<user_email>", token="<oauth_token>"):
    auth_string = generate_oauth2_string(username, token)
    imap_connector = imaplib.IMAP4_SSL("imap.yandex.com", 993)
    imap_connector.authenticate('XOAUTH2', lambda x: auth_string)
    return imap_connector

def get_total_emails(imap_connector):
    mailboxes = []
    ttl_emails = 0
    for mailbox in imap_connector.list()[1]:
        mailboxes.append(mailbox.decode("utf-8").split()[-1].replace('"', ''))
        for mailbox in mailboxes:
            try:
                imap_connector.select(mailbox)
                resp_code, mail_count = imap_connector.select(mailbox=mailbox, readonly=True)
                ttl_emails += int(mail_count[0].decode("utf-8"))
            except imaplib.IMAP4.error:
                print(f"Folder: {folder} Error reading emails")
            except ValueError:
                print(f"Folder: {folder} Error reading emails")
    user_logout(imap_connector)
    return ttl_emails

get_total_emails(get_imap_connector())

Кодқа мына мәндерді қойыңыз:

  • <user_email> — деректерді алу қажет пайдаланушының username@domain.ru түріндегі электрондық мекенжайы.
  • <oauth_token> — 7-тармақтағы пайдаланушының уақытша токені;

Пошталық протоколдар жұмысы туралы толығырақ IMAP сипаттамасынан және SMTP сипаттамасынан қараңыз.

Яндекс Күнтізбе

OAuth токендерін пайдалану арқылы CalDAV протоколы бойынша пайдаланушылардың Яндекс Күнтізбесімен өзара әрекеттесуге болады.

Мысал 1

Таңдалған пайдаланушы Күнтізбесін жоюға арналған Python скриптісі:

import caldav

def get_principal(username, leg_token):
    client = caldav.DAVClient(url="https://caldav.yandex.ru/", username=username, password=leg_token)
    principal = client.principal()
    return principal

my_principal = get_principal("<user_email>", "<oauth_token>")

def find_delete_calendar(my_principal, calendar_name="Мой календарь"):
    try:
        calendar = my_principal.calendar(name=calendar_name)
        assert calendar
        print(f"We found an existing calendar with name {calendar_name}, now deleting it")
        calendar.delete()
    except caldav.error.NotFoundError:
        print("Calendar was not found")

find_delete_calendar(my_principal)

Кодқа мына мәндерді қойыңыз:

  • <user_email> — деректерді алу қажет пайдаланушының username@domain.ru түріндегі электрондық мекенжайы;

  • <oauth_token> — 7-тармақтағы пайдаланушының уақытша токені;

Ескерту

Егер әкімші пайдаланушы күнтізбесін жойса, оны әкімші де, пайдаланушының өзі де қалпына келтіре алмайды.

Мысал 2

Телекөпірдегі бейнекездесуге сілтеме жасай отырып, күнтізбеде кездесу жасау сұраулары:

  • Бір реттік оқиғаға арналған конференция.

    curl -v "https://caldav.yandex.ru/calendars/<user_email>/events-default/<event_uid>.ics" \
-H "Authorization: OAuth <oauth_token>" \
-H "Content-type: text/ics" \
-X PUT \
--data-binary "
BEGIN:VCALENDAR
BEGIN:VEVENT
X-TELEMOST-REQUIRED:TRUE
DESCRIPTION:Single event
UID:<event_uid>
DTSTART:20230417T120000Z
END:VEVENT
END:VCALENDAR"

    Кодқа мына мәндерді қойыңыз:

    • <user_email> — деректерді алу қажет пайдаланушының username@domain.ru түріндегі электрондық мекенжайы.
    • <event_uid> — кездесу және файл атауының идентификаторы (мысалы, a5e3e7b0-dd11-11ed).
    • <oauth_token> — 7-тармақтағы пайдаланушының уақытша токені;

    Сәтті жауаптың үлгісі:

    HTTP/1.1 201 Created

    curl -v "https://caldav.yandex.ru/calendars/<user_email>/events-default/<event_uid>.ics" \
  -H "Authorization: OAuth <oauth_token>"

    Кодқа мына мәндерді қойыңыз:

    • <user_email> — деректерді алу қажет пайдаланушының username@domain.ru түріндегі электрондық мекенжайы;

    • <event_uid> — кездесу және файл атауының идентификаторы (мысалы, a5e3e7b0-dd11-11ed).

    • <oauth_token> — 7-тармақтағы пайдаланушының уақытша токені;

    Сәтті жауаптың үлгісі:

    HTTP/1.1 200 OK
BEGIN:VCALENDAR
...
BEGIN:VEVENT
DTSTART:20230417T120000Z
DTEND:20230417T120000Z
SUMMARY:Без названия
UID:a5e3e7b0-dd11-11ed
DESCRIPTION:Link to video conference: https://telemost.yandex.ru/j/78566269088286\n\nSingle event 
X-TELEMOST-CONFERENCE:https://telemost.yandex.ru/j/78566269088286
...
END:VEVENT
END:VCALENDAR

  • Қайталатын оқиғаға арналған конференция.

    curl -v "https://caldav.yandex.ru/calendars/<user_email>/events-default/<event_uid>.ics" \
-H "Authorization: OAuth <oauth_token>" \
-H "Content-type: text/ics" \
-X PUT \
--data-binary "
BEGIN:VCALENDAR
BEGIN:VEVENT
X-TELEMOST-REQUIRED:TRUE
DESCRIPTION:Weekly event
UID:<event_uid>
DTSTART:20230411T200000Z
RRULE:FREQ=WEEKLY
END:VEVENT
END:VCALENDAR"

    Кодқа мына мәндерді қойыңыз:

    • <user_email> — деректерді алу қажет пайдаланушының username@domain.ru түріндегі электрондық мекенжайы;

    • <event_uid> — кездесу және файл атауының идентификаторы (мысалы, a5e3e7b0-dd11-11ed).

    • <oauth_token> — 7-тармақтағы пайдаланушының уақытша токені;

    Сәтті жауаптың үлгісі:

    HTTP/1.1 201 Created

    curl -v "https://caldav.yandex.ru/calendars/<user_email>/events-default/<event_uid>.ics" \
  -H "Authorization: OAuth <oauth_token>"

    Кодқа мына мәндерді қойыңыз:

    • <user_email> — деректерді алу қажет пайдаланушының username@domain.ru түріндегі электрондық мекенжайы;

    • <event_uid> — кездесу және файл атауының идентификаторы (мысалы, a5e3e7b0-dd11-11ed).

    • <oauth_token> — 7-тармақтағы пайдаланушының уақытша токені;

    Сәтті жауаптың үлгісі:

    BEGIN:VCALENDAR
...
BEGIN:VEVENT
RECURRENCE-ID:20230411T200000Z
X-TELEMOST-CONFERENCE:https://telemost.yandex.ru/j/39864310386563
DESCRIPTION:Бейнекездесу сілтемесі: https://telemost.yandex.ru/j/39864310386563\n\nWeekly event 
...
END:VEVENT
BEGIN:VEVENT
RRULE:FREQ=WEEKLY;BYDAY=TU;INTERVAL=1
DESCRIPTION:Бейнекездесу сілтемесі: https://telemost.yandex.ru/j/39864310386563\n\nWeekly event 
...
END:VEVENT

Күнтізбеде оқиғаны жасау немесе өзгерту үшін PUT сұрауын жіберген кезде, клиент VEVENT құрамдастарының ішіне стандартты емес x-TELEMOST-REQUIREDсипатын қосады. Сервер осындай сұрауды ала отырып, Телекөпірдегі бейнекездесуге сілтеме жасайды және оны мәтін түрінде кездесудің сипаттамасына қосады.

Клиент кездесулерді оқығанда сервер X-TELEMOST-REQUIRED сипатын көрсетпейді. Бірақ, егер Телекөпірдегі сілтеме жасалған болса, бұл сілтемені стандартты емес X-TELEMOST-CONFERENCE сипатына қайтарады.

CalDAV протоколымен жұмыс істеу туралы толығырақ ақпаратты оның сипаттамаларынан қараңыз.

Қолдау қызметіне жазу

Белгілі бір пайдаланушы атынан деректерді пайдалануға мүмкіндік беретін арнайы код.

Пошталық сервер мен клиент арасында күнтізбе және мекенжайлар кітапшасы деректерін синхрондау протоколы.

Алдыңғы
Шығыс поштадағы деректердің тарап кетуінен қорғау
Келесі
API сценарийлері