Office 365 DevDays

2017.11.4-6 | 上海

Office 365 DevDays

2017.11.4-6 | 上海

MS-WOPI: Web Application Open Platform Interface

Jinghui Zhang

Software Engineer @Microsoft

Overview

WOPI Flow

WOPI Discovery

REST Protocol

目 录CONTENTS

Overview

• WOPI defines the way that on-premises hosts (e.g. SharePoint)

interact with Office Online Server

• This session is scoped to on-premise scenarios only, which are

documented at MS-WOPI

• The goal is to provide an overview of the MS-WOPI protocol

and demonstrate how it functions

The WOPI Flow

WOPI Source

Host Frame

App Frame

▪ WOPI Source

▪ Access Token

Example Flow: Viewing a File

https://msdn.microsoft.com/en-us/library/hh641756.aspx

WOPI Discovery

…/hosting/discovery

<wopi-discovery><net-zone name="external-https">

<app name="Word" … ><action name="view"

ext="docx"default="true"urlsrc="..."/>

</app></net-zone>

</wopi-discovery>

Host records bindings

between file extensions

and URLs

Discovery XML

<wopi-discovery>

<net-zone name="external-https">

<app name="Word"

favIconUrl="https://.../FavIcon_Word.ico"

checkLicense="true">

<action name="edit"

ext="docx"

requires="update"

urlsrc="https://.../frame.aspx?<ui=UI_LLCC&><rs=DC_LLCC&>"/>

</app>

</net-zone>

</wopi-discovery>

Conventions for <action />

▪ Not a traditional XML schema

▪ Ignore the entry if its name is unknown

▪ Ignore the entry if one of its required capabilities is unknown

▪ urlsrc handling is complicated

The REST Protocol

REST Resource URIs

Resource Description

http://server/<...>/wopi*/...

files/<id> Provides access to information about a file and allows for file-level operations.

folders/<id> Provides access to information about a folder and allows for folder level operations.

files/<id>/contents Provides access to operations that get and update the contents of a file.

folder/<id>/children Provides access to the files and folders in a folder.

The View Flow (again)

1. WOPI host generates Office Online URL based on discovery XML

2. WOPI host navigates a web page to Office Online URL

3. Office Online initiates GET to WOPISource URL• http://server/<...>/wopi*/files/<id>

4. Office Online initiates GET to file contents WOPI endpoint• http://server/<...>/wopi*/files/<id>/contents

5. Office Online renders file

Files

• http://server/<...>/wopi*/files/<id>

• Returns information about the file and permissions that the current user has relative to

that file

• Contains information that the WOPI app may use to modify the user experience

• These are minimal response requirements for a CheckFileInfo request…

{"BaseFileName": "Sample Document.docx", "OwnerId": "johndoe", "Size": 300519,"Version": "GIYDCMBQGAVTAMB2GAYA===="

}

File Contents

• http://server/<...>/wopi*/files/<id>/contents

• GetFile

• PutFile

Files

http://server/<...>/wopi*/files/<id>

Some sample parameters…• CloseUrl

• DownloadUrl

• DisablePrint

• ReadOnly

• SupportsExtendedLockLength

Post Files With X-WOPI-Override

• PutRelativeFile

• Lock

• Unlock

• RefreshLock

• UnlockAndRelock

• ExecuteCellStorageRequest

• ExecuteCellStorageRelativeRequest

• DeleteFile

• ReadSecureStore

• GetRestrictedLink

• RevokeRestrictedLink

POST http://server/<...>/wopi*/files/<id>

Client-side Integration: PostMessage

• Allows hosts to plug into pieces of our UI

• Historically messages have been added ‘as needed’ with little review or consideration

• PostMessage is now a part of our public API, since it is necessary for many basic scenarios

Host Frame

App Frame

Client-side Integration: PostMessage

Example Flow: Share

• Host tells us they want to handle the ‘Share’ message in CheckFileInfo

FileSharingPostMessage = true

• When the Share button is clicked, we send the host the UI_Sharing

message

• The host sends us the Blur_Focus message so we stop aggressively

grabbing focus

• The host displays their Share UI

• When the user is done sharing, the host sends us the Grab_Focus message

Example Messages

Message hosts can send

• Blur_Focus

• Grab_Focus

• Host_PerfTiming

• Host_PostmessageReady

Messages hosts can receive

• File_Rename

• UI_Close

• UI_Edit

• UI_FileVersions

• UI_Sharing

Verifying Requests Are From Us: Proof Keys

• We sign every WOPI request with our private key

• We publish our public key in discovery

• Hosts can use the public key to validate that requests come from us

Office 365 DevDays

Thank you