Servis uygulamaları

1. Kurum sahibinin kullanıcı hesabına giriş yapın.

2. Kurumunuzda servis uygulamalarının listesini yönetecek olan uygulamayı kaydedin.

   1. OAuth uygulaması oluşturma sayfasına gidin.
   2. Servisin adını girin ve gerekirse simge ekleyin.
   3. Uygulama platformları bölümünde Web servisleri’ni seçin. Redirect URI alanında, Hata Ayıklama için URL’yi yaz bağlantısına tıklayın.
   4. Veri erişimi bölümünde, kurumda servis uygulamalarını yönetmek için gerekli olan erişim izinlerini belirtin:

      • ya360_security:service_applications_read: Servis uygulaması listesini okuma,
      • ya360_security:service_applications_write: Servis uygulaması listesini yönetme (okuma ve kayıt).
   5. İletişim için e-posta adresi belirtin. Sayfanın alt kısmında, Uygulama Oluştur’a tıklayın. Uygulamanın açıklaması ekranınızda görüntülenir.
   6. ClientID alanındaki uygulama kimlik belirleyicisini (ID'sini) kopyalayın: Bu ID, OAuth token'ı almanız için gereklidir. Uygulamalarınızın tam listesini oauth.yandex.ru adresinde bulabilirsiniz.
3. İlgili olan herhangi bir yöntemle OAuth tokeni isteyin. Bu token, daha sonra kurumunuzda tüm servis uygulamalarını kaydetmeniz için gerekli olur.

   Hata ayıklama OAuth token'ı manuel olarak alınabilir:

   1. Bağlantıdan geçiş yapın

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

      <main_app_client_id> yerine 2.6 maddesindeki ClientID değerini kullanın.

   2. OAuth token'ı uygulamanıza ilk kez veriliyorsa kullanıcı girişi ekranı açılır. Giriş yapıldıktan sonra Yandex OAuth sizi token'ı içeren sayfaya yönlendirir. Hata ayıklama tokenleri hakında daha fazla bilgi.
4. Kullanıcıları bilgilendirin ve daha önce onay vermemişlerse Ticari teklifin 3.7 maddesine uygun olarak kaynaklarını yönetmek üzere yönetici erişimi için onaylarını alın.

5. Şu sorguyu kullanarak servis uygulama özelliğini etkinleştirin:

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

   <org_id> yerine kurum ID'nizi girin.

6. Servis uygulamasının kaydını yapın. Servis uygulaması yardımıyla geçici kullanıcı OAuth token'ları alabilirsiniz. Geçici token'ın geçerlilik süresi 1 saattir.

   1. Ana uygulamayı oluştururken yaptığınız gibi ayrı bir OAuth uygulaması oluşturun (madde 2). Bu uygulamanın erişim izinleri olarak API isteklerinde kullanılacak olan erişim izinlerini kullanın.

   2. Bir önceki adımdaki uygulamayı kurumunuz için servis uygulaması yapın.

      Örnek

      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" \
            ] \
          } \
        ] \
      }'
      Copied to clipboard

      Kodda şu değerleri kullanın:

      • <org_id>: Kurum ID'niz,
      • <owner_token_to_manage_service_app>: Madde 3'teki OAuth token'ı,
      • <OAuth_service_app_client_id>: Madde 6.1'deki servis uygulaması ClientID'si,

   3. Uygulamanın, bir servis uygulaması olarak doğru eklendiğinden emin olun.

      Örnek

      curl --location  \
      --request GET 'https://api360.yandex.net/security/v1/org/<org_id>/service_applications'  \
      --header 'Authorization: OAuth <owner_token_to_manage_service_app>'
      Copied to clipboard

   Diğer servis uygulamalarını bağlamak için Madde 6'daki adımları tekrarlayın.

7. Geçici kullanıcı token'ını alın. Bunu şu API sorgusu ile yapabilirsiniz:

   POST /token HTTP/1.1
      Host: http://oauth.yandex.ru
      Content-type: application/x-www-form-urlencoded
   Copied to clipboard

   Örnek

   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'
   Copied to clipboard

   veya

   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'
   Copied to clipboard

   Kodda şu değerleri kullanın:

   • <OAuth_service_app_client_id>: Madde 6.1'deki servis uygulaması ClientID'si,
   • <OAuth_service_app_client_secret>: Servis uygulamasının Client secret'i,
   • <user_id>: Token almak istediğiniz kullanıcının kimlik belirleyicisi (ID'si),
   • <user_email>: Token almak istediğiniz kullanıcının username@domain.ru şeklindeki e-posta adresi.

   Yanıtı, Yandex 360 servislerinin API'lerine yönelik olan sorgularda kullanılması gereken token'ı içerecek.

Servis uygulamalarıyla programlar aracılığıyla çalışma ayrıntıları API 360 Rehberi'nde açıklanır.

Servis uygulamaları aracılığıyla elde edilen geçici token'lar örneğin veri yedekleme, denetim veya bilgi arama amacıyla API üzerinden kurumdaki belirli kullanıcı kaynaklarına erişmeyi sağlar.

Yandex Disk

Yandex Disk API'si dosyalarla çalışmak ve bunlara erişimi yönetmek için kullanılır. Yandex Disk API'sine sorgu göndermek için Polygon servisini kullanabilirsiniz.

Örnek

Çalışanın Disk'i hakkında meta bilgi isteme:

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

<oauth_token> yerine geçici kullanıcı token'ının Madde 7'deki değerini kullanın.

Yandex Disk REST-API ile çalışma ayrıntıları.

Yandex Mail

Uygulamalar, OAuth protokolünü kullanarak Yandex Mail e-posta kutularına erişebilir. Yandex Mail IMAP ve SMTP sunucuları OAuth kullanıcı kimlik doğrulamasını destekler.

Örnek

Kullanıcı e-postalarının IMAP protokolü aracılığıyla sayılması için Python komut dosyası:

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())
Copied to clipboard

Kodda şu değerleri kullanın:

• <user_email>: Veri almak istediğiniz kullanıcının username@domain.ru şeklindeki e-posta adresi,
• <oauth_token>: Madde 7'deki geçici kullanıcı token'ı.

E-posta protokollerinin nasıl çalıştığı hakkında daha fazla bilgi için IMAP açıklamasına ve SMTP spesifikasyonuna bakın.

Yandex Takvim

OAuth token'larını kullanarak CalDAV protokolü üzerinden kullanıcıların Yandex Takvim'leri ile etkileşimde bulunabilirsiniz.

Örnek 1

Seçilen kullanıcı takvimini silmeyi sağlayan Python komut dosyası:

import caldav

def get_principal(username, leg_token):
    client = caldav.DAVClient(url=url, 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)
Copied to clipboard

Kodda şu değerleri kullanın:

• <user_email>: Veri almak istediğiniz kullanıcının username@domain.ru şeklindeki e-posta adresi,
• <oauth_token>: Madde 7'deki geçici kullanıcı token'ı.

Not. Yönetici tarafından silinmiş olan kullanıcı takvimini daha sonra ne yönetici ne de kullanıcı geri yükleyebilir.

Örnek 2

Yandex Takvim'de, Yandex Telemost'taki bir görüntülü toplantıya bağlantı içeren bir toplantı oluşturma istekleri:

• Tek bir etkinlik için konferans.

  • Oluşturma
  • Alım

  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"
  Copied to clipboard

  Kodda şu değerleri kullanın:

  • <user_email>: Veri almak istediğiniz kullanıcının username@domain.ru şeklindeki e-posta adresi,
  • <event_uid>: Toplantının ve dosya adının ID'si (örneğin: a5e3e7b0-dd11-11ed);
  • <oauth_token>: Madde 7'deki geçici kullanıcı token'ı.

  Başarılı bir yanıtın örneği:

  HTTP/1.1 201 Created

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

  Kodda şu değerleri kullanın:

  • <user_email>: Veri almak istediğiniz kullanıcının username@domain.ru şeklindeki e-posta adresi,
  • <event_uid>: Toplantının ve dosya adının ID'si (örneğin: a5e3e7b0-dd11-11ed);
  • <oauth_token>: Madde 7'deki geçici kullanıcı token'ı.

  Başarılı bir yanıtın örneği:

  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
• Tekrarlanan bir etkinlik için konferans.

  • Oluşturma
  • Alım

  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"
  Copied to clipboard

  Kodda şu değerleri kullanın:

  • <user_email>: Veri almak istediğiniz kullanıcının username@domain.ru şeklindeki e-posta adresi,
  • <event_uid>: Toplantının ve dosya adının ID'si (örneğin: a5e3e7b0-dd11-11ed);
  • <oauth_token>: Madde 7'deki geçici kullanıcı token'ı.

  Başarılı bir yanıtın örneği:

  HTTP/1.1 201 Created

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

  Kodda şu değerleri kullanın:

  • <user_email>: Veri almak istediğiniz kullanıcının username@domain.ru şeklindeki e-posta adresi,
  • <event_uid>: Toplantının ve dosya adının ID'si (örneğin: a5e3e7b0-dd11-11ed);
  • <oauth_token>: Madde 7'deki geçici kullanıcı token'ı.

  Başarılı bir yanıtın örneği:

  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

Takvim etkinliği oluşturmak veya düzenlemek için bir PUT sorgusu gönderilirken istemci, VEVENT öğelerinin içine standart olmayan bir X-TELEMOST-REQUIRED özelliği ekler. Böyle bir sorgu alan sunucu, Yandex Telemost'taki görüntülü toplantıya yönlendiren bir bağlantı oluşturur ve bunu metin biçiminde toplantı açıklamasına ekler.

İstemci randevuları okurken sunucu X-TELEMOST-REQUIRED özelliğini belirtmez. Ancak Yandex Telemost'taki görüntülü toplantıya yönlendiren bağlantı oluşturulduysa, sunucu bu bağlantıyı standart olmayan X-TELEMOST-CONFERENCE özelliğinin içinde geri gönderir.

CalDAV protokolü ile çalışma ayrıntıları için bu protokolün spesifikasyonunu inceleyin.