Примеры использования API Яндекс Вики

В этом разделе приведены примеры скриптов на языке Python, которые используют API Яндекс Вики для управления формами и ответами.

Во всех примерах для аутентификации используется OAuth или IAM-токен. Получение токена описано в разделе Доступ к API.

1. Создать страницу и добавить контент

Ниже продемонстрируем пример скрипта, который выполняет действия:

  • Создание новой страницы
  • Изменение контента страницы
  • Получение атрибутов страницы по ее супертегу (пути)

В примере предполагаем, что для авторизации используется OAuth-токен (см. Получить доступ к API по протоколу OAuth).

Текст скрипта api_example_1.py
import os
import requests
import sys

WIKI_PUBLIC_API = 'https://api.wiki.yandex.net/v1'
WIKI_TOKEN = os.environ.get('WIKI_TOKEN')


def create_wiki_page(
    *, supertag: str,
    org_id: str,
    title: str,
    content: str,
) -> int:
    """
    Создать новую страницу

    Параметры:
    - supertag: супертег (слаг) создаваемой страницы
    - org_id: код организации
    - title: заголовок страницы
    - content: текст страницы
    """
    url = f'{WIKI_PUBLIC_API}/pages'
    headers = {
        'Authorization': f'OAuth {WIKI_TOKEN}',
        'X-Org-Id': org_id,
    }
    body = {
        'page_type': 'wysiwyg',
        'slug': supertag,
        'title': title,
        'content': content,
    }
    response = requests.post(url, json=body, headers=headers)
    if response.status_code != 200:
        return None

    res = response.json()
    return res.get('id')


def change_wiki_page(
    *, page_id: int,
    org_id: str,
    title: str = None,
    content: str = None,
) -> bool:
    """
    Изменить существующую страницу

    Параметры:
    - page_id: код страницы
    - org_id: код организации
    - title: заголовок страницы
    - content: текст страницы
    """
    url = f'{WIKI_PUBLIC_API}/pages/{page_id}'
    headers = {
        'Authorization': f'OAuth {WIKI_TOKEN}',
        'X-Org-Id': org_id,
    }
    body = {}
    if title:
        body['title'] = title
    if content:
        body['content'] = content
    response = requests.post(url, json=body, headers=headers)
    return response.status_code == 200


def append_wiki_page_content(
    *, page_id: int,
    org_id: str,
    content: str,
    location: str = None,
) -> bool:
    """
    Добавить контент на существующую страницу

    Параметры:
    - page_id: код страницы
    - org_id: код организации
    - content: текст для вставки
    - location: позиция для вставки текста,
      возможна вставка в начало страницы `top`, в конец страницы `bottom`
      или под якорь, например `#fragment`
    """
    url = f'{WIKI_PUBLIC_API}/pages/{page_id}/append-content'
    headers = {
        'Authorization': f'OAuth {WIKI_TOKEN}',
        'X-Org-Id': org_id,
    }
    body = {
        'content': content,
    }
    if location in ('top', 'bottom'):
        body['body'] = {'location': location}
    elif isinstance(location, str) and location.startswith('#'):
        body['anchor'] = {'name': location}
    else:
        body['body'] = {'location': 'bottom'}
    response = requests.post(url, json=body, headers=headers)
    return response.status_code == 200


def get_wiki_page_attributes(
    *, supertag: str,
    org_id: str,
) -> int:
    """
    Получить атрибуты существующей страницы по ее супертегу

    Параметры:
    - supertag: супертег (слаг) существующей страницы
    - org_id: код организации
    """
    url = f'{WIKI_PUBLIC_API}/pages'
    params = {
        'slug': supertag,
    }
    headers = {
        'Authorization': f'OAuth {WIKI_TOKEN}',
        'X-Org-Id': org_id,
    }
    response = requests.get(url, params=params, headers=headers)
    if response.status_code == 200:
        return response.json()


def main():
    if len(sys.argv) < 2:
        sys.exit(1)
    org_id = sys.argv[1]

    supertag = 'users/test/pageone'

    # создадим новую страницу
    new_page_id = create_wiki_page(
        supertag=supertag,
        title='Страница 1',
        content=(
            'Lorem ipsum dolor sit amet, consectetur adipiscing elit, '
            'sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.\n'
        ),
        org_id=org_id,
    )
    if new_page_id:
        print(f'создана страница с кодом {new_page_id}')

    # перепишем контент страницы (важно, метод меняет всю страницу)
    is_changed = change_wiki_page(
        page_id=new_page_id,
        org_id=org_id,
        title='Страница номер один',
        content=(
            'Lorem ipsum dolor sit amet, consectetur adipiscing elit, '
            'sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.\n'
            'Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris '
            'nisi ut aliquip ex ea commodo consequat.\n'
            'Duis aute irure dolor in reprehenderit in voluptate velit esse cillum '
            'dolore eu fugiat nulla pariatur.\n'
            'Excepteur sint occaecat cupidatat non proident, '
            'sunt in culpa qui officia deserunt mollit anim id est laborum.\n'
        ),
    )
    if is_changed:
        print('контент страницы переписан')


    # получим атрибуты страницы по ее супертегу
    page_attributes = get_wiki_page_attributes(
        supertag=supertag,
        org_id=org_id,
    )
    if not page_attributes:
        print('вики страница не найдена')
        sys.exit(1)
    page_id = page_attributes.get('id')
    print(f'найдена страница с кодом {page_id}')


if __name__ == '__main__':
    main()

Пример запуска скрипта (в качестве аргумента передается код организации):

$ WIKI_TOKEN=$(cat .wiki-token) python api_example_1.py 'd3509bd2-b226-421a-94f1-1bf5b0e5fbf3'
создана страница с кодом 464211
контент страницы переписан
найдена страница с кодом 464211

2. Создать динамическую таблицу, добавить столбцы и строки

Ниже продемонстрируем пример скрипта, который выполняет действия:

  • Добавление новой динамической таблицы на существующую страницу
  • Добавление в таблицу колонок и строк
  • Изменение ячеек строки
  • Публикация таблицы на странице

В примере предполагаем, что для авторизации используется IAM-токен (см. Получить доступ к API по IAM-токену).

Текст скрипта api_example_2.py
import os
import requests
import sys

WIKI_PUBLIC_API = 'https://api.wiki.yandex.net/v1'
WIKI_TOKEN = os.environ.get('WIKI_TOKEN')

def get_wiki_page_attributes(
    *, supertag: str,
    org_id: str,
) -> int:
    """
    Получить атрибуты существующей страницы по ее супертегу

    Параметры:
    - supertag: супертег (слаг) существующей страницы
    - org_id: код организации
    """
    url = f'{WIKI_PUBLIC_API}/pages'
    params = {
        'slug': supertag,
    }
    headers = {
        'Authorization': f'Bearer {WIKI_TOKEN}',
        'X-Org-Id': org_id,
    }
    response = requests.get(url, params=params, headers=headers)
    if response.status_code == 200:
        return response.json()


def create_wiki_grid(
    *, page_id: int,
    title: str,
    org_id: str,
) -> int:
    """
    Создать новую таблицу

    Параметры:
    - page_id: код страницы
    - org_id: код организации
    - title: заголовок таблицы

    Важно, после создания таблица доступна только через интерфейс просмотра ресурсов,
    ее еще нужно добавить на страницу.
    """
    url = f'{WIKI_PUBLIC_API}/grids'
    body = {
        'page': {'id': page_id},
        'title': title,
    }
    headers = {
        'Authorization': f'Bearer {WIKI_TOKEN}',
        'X-Org-Id': org_id,
    }
    response = requests.post(url, json=body, headers=headers)
    if response.status_code == 200:
        res = response.json()
        return res.get('id')


def insert_grid_columns(
    *, grid_id: str,
    org_id: str,
    columns: list[dict],
) -> bool:
    """
    Добавить колонки в таблицу

    Параметры:
    - grid_id: код таблицы
    - org_id: код организации
    - columns: список колонок для добавления
    """
    url = f'{WIKI_PUBLIC_API}/grids/{grid_id}/columns'
    body = {
        'columns': columns,
    }
    headers = {
        'Authorization': f'Bearer {WIKI_TOKEN}',
        'X-Org-Id': org_id,
    }
    response = requests.post(url, json=body, headers=headers)
    return response.status_code == 200


def insert_grid_rows(
    *, grid_id: str,
    org_id: str,
    rows: list[dict],
) -> bool:
    """
    Добавить строки в таблицу

    Параметры:
    - grid_id: код таблицы
    - org_id: код организации
    - rows: список строк для добавления
    """
    url = f'{WIKI_PUBLIC_API}/grids/{grid_id}/rows'
    body = {
        'rows': rows,
    }
    headers = {
        'Authorization': f'Bearer {WIKI_TOKEN}',
        'X-Org-Id': org_id,
    }
    response = requests.post(url, json=body, headers=headers)
    return response.status_code == 200


def change_grid_cells(
    *, grid_id: str,
    org_id: str,
    cells: list[dict],
) -> bool:
    """
    Изменить ячейки в таблице

    Параметры:
    - grid_id: код таблицы
    - org_id: код организации
    - cells: список ячеек для изменения
    """
    url = f'{WIKI_PUBLIC_API}/grids/{grid_id}/cells'
    body = {
        'cells': cells,
    }
    headers = {
        'Authorization': f'Bearer {WIKI_TOKEN}',
        'X-Org-Id': org_id,
    }
    response = requests.post(url, json=body, headers=headers)
    return response.status_code == 200


def main():
    if len(sys.argv) < 2:
        sys.exit(1)
    org_id = sys.argv[1]

    supertag = 'users/test/pageone'

    # получим атрибуты страницы по ее супертегу
    page_attributes = get_wiki_page_attributes(
        supertag=supertag,
        org_id=org_id,
    )
    if not page_attributes:
        print('вики страница не найдена')
        sys.exit(1)
    page_id = page_attributes.get('id')
    print(f'найдена страница с кодом {page_id}')

    # создадим новую таблицу
    grid_id = create_wiki_grid(
        page_id=page_id,
        title='Новая таблица',
        org_id=org_id,
    )
    if grid_id:
        print(f'создана таблица с кодом {grid_id}')

    # добавим колонки в новую таблицу, колонки могут иметь разный тип
    is_changed = insert_grid_columns(
        grid_id=grid_id,
        org_id=org_id,
        columns=[
            {
                'slug': 'id',
                'title': 'ID',
                'type': 'number',
                'required': True,
            },
            {
                'slug': 'name',
                'title': 'Name',
                'type': 'string',
                'required': False,
            },
        ],
    )
    if is_changed:
        print('в таблицу добавлены новые колонки')

    # добавим строки в новую таблицу
    is_changed = insert_grid_rows(
        grid_id=grid_id,
        org_id=org_id,
        rows=[
            {'id': 1, 'name': 'Один'},
            {'id': 2, 'name': 'Два'},
            {'id': 3, 'name': 'Три'},
            {'id': 4, 'name': 'Четыре'},
            {'id': 5, 'name': 'Пять'},
        ],
    )
    if is_changed:
        print('в таблицу добавлены новые строки')

    # изменим ячейки на второй строке в таблице
    is_changed = change_grid_cells(
        grid_id=grid_id,
        org_id=org_id,
        cells=[
            {'row_id': 2, 'column_slug': 'id', 'value': 22},
            {'row_id': 2, 'column_slug': 'name', 'value': 'Двадцать два'},
        ],
    )
    if is_changed:
        print('в таблице изменена вторая строка')

    # поместим новую таблицу в конец страницы
    is_changed = append_wiki_page_content(
        page_id=page_id,
        org_id=org_id,
        content=f'\n{{% wgrid id="{grid_id}" %}}',
    )
    if is_changed:
        print('в конец страницы добавлена созданная таблица')


if __name__ == '__main__':
    main()

$ WIKI_TOKEN=$(cat .wiki-token) python api_example_2.py 'd3509bd2-b226-421a-94f1-1bf5b0e5fbf3'
найдена страница с кодом 464211
создана таблица с кодом 252a78f2-90c2-43ba-a608-df7da23f1fd2
в таблицу добавлены новые колонки
в таблицу добавлены новые строки
в таблице изменена вторая строка
в конец страницы добавлена созданная таблица
Предыдущая
Доступ к API
Следующая
Обзор