WOPI REST конечные точки

    При хранение файлов, WOPI-хост должен предоставлять информацию об этих файлах и их содержимом в виде специальных URL-адресов, так как WOPI использует REST-интерфейс обратного вызова(REST-based callback interface). WOPI-хост предоставляет REST API для работы с файлами для клиентов WOPI(AlterOffice Online). Не все операции и конечные точки нужно реализовывать, однако для всех действий необходимы операции CheckFileInfo и GetFile. Каждая конечная точка WOPI поддерживает ряд операций, которые указываются в заголовке запроса X-WOPI-Override. Параметры для каждой операции передаются в HTTP-заголовках, которые начинаются с X-WOPI-. Для выполнения операции WOPI необходимо отправить запрос на соответствующую конечную точку REST и передать соответствующие значения HTTP-заголовков с запросом.

    URLs конечных точек


    URL-адрес конечных точек хоста WOPI должен начинаться с /wopi. Например, следующие URL-адреса являются допустимыми для конечной точки содержимого файла с идентификатором abc123:


    Следующие URL-адреса недопустимы:


    Конечная точка Files


    Конечная точка "Files" обеспечивает доступ к операциям с файлами.

    URL


    /wopi/files/(file_id)

    Доступные операции:

    • CheckFileInfo - Одна из самых важных операций, должна быть реализована для всех действий WOPI. Возвращает информацию о файле, разрешения пользователя, возможности WOPI-хоста в отношении файла.
    Запрос:
    GET /wopi/files/(file_id)

    Параметры:
    • file_id(string) - идентификатор файла.
    • access_token(string) - токен доступа. Необходим для проверки авторизованности запроса.
    Заголовки запросов:
    • X-WOPI-SessionContext -  значение контекста сеанса, если оно было указано в исходном URL-адресе WOPI.

    Конечная точка File contents

    Конечная точка "File contents" обеспечивает доступ к получению и обновлению содержимого файла.

    URL


    /wopi/files/(file_id)/contents

    Доступные операции:

    • GetFile - Позволяет получить файл с хоста.
    Запрос:
    GET /wopi/files/(file_id)/contents

    Параметры:
    • file_id(string) - идентификатор файла.
    • access_token(string) - токен доступа. Необходим для проверки авторизованности запроса.

    Заголовки запросов:

    • WOPI-MaxExpectedSize - Необязательный заголовок. Целое число, указывающее верхнюю границу ожидаемого размера запрашиваемого файла. Если это значение не указано в запросе, хост должен использовать максимальное значение 4-байтового целого числа. Если запрашиваемый файл больше этого значения, хост должен ответить с кодом ошибки 412.

    Заголовки ответов:
    • X-WOPI-ItemVersion -  Необязательный заголовок. Строковое значение, указывающее версию файла. Его значение должно быть таким же, как значение "Version" в "CheckFileInfo".

    • PutFile - Обновляет бинарное содержимое файла.
    Запрос:
    POST /wopi/files/(file_id)/contents

    Параметры:
    • file_id(string) - идентификатор файла.
    • access_token(string) - токен доступа. Необходим для проверки авторизованности запроса.

    Заголовки запросов:

    • X-WOPI-Override - Обязательный заголовок. Строковое значение - PUT. 

    • X-WOPI-Lock - Строковое значение, предоставленное WOPI-клиентом в предыдущем запросе Lock. Этот заголовок не включается при создании документа. 

    • X-WOPI-Editors - Строковое значение, разделенное запятыми, содержащее идентификаторы пользователей, которые внесли изменения в документ в этом запросе.

    • X-COOL-WOPI-IsModifiedByUser - указывает, изменил ли пользователь документ перед сохранением («true») или он просто нажал кнопку «Сохранить» без каких-либо изменений («false»).

    • X-COOL-WOPI-IsAutosave - указывает, запускается ли PutFile автоматическим сохранением («true») или явной операцией пользователя (кнопка «Сохранить» или пункт меню) («false»).

    • X-COOL-WOPI-IsExitSave - указывает, будет ли запускаться автоматическое сохранение при закрытии вкладки/браузера(«true») или нет («false»).

    Заголовки ответов:

    • X-WOPI-Lock - Строковое значение, идентифицирующее текущую блокировку файла. Всегда должен быть  включен при ответе на запрос с кодом ошибки - 409 Conflict. Не должен включаться при ответе на запрос с кодом - 200 OK.

    • X-WOPI-LockFailureReason -   Необязательный заголовок. Строковое значение, указывающее причину неудачи блокировки. Этот заголовок может быть включен при ответе на запрос с кодом ошибки 409 Conflict. Нет стандарта для форматирования этой строки, и ее следует использовать только для целей журналирования.

    • X-WOPI-ItemVersion -  Необязательный заголовок. Строковое значение, указывающее версию файла. Его значение должно быть таким же, как значение "Version" в "CheckFileInfo".

    Вы можете ознакомиться со всеми операциями и конечными точками в документации протокола WOPI, доступной на: WOPI REST API Reference | Microsoft Learn
    Опубликовано