[MS-STWEB]: Microsoft OneDrive Save to Web SOAP Web Service

4 downloads 112 Views 1MB Size Report
Apr 14, 2016 - The example companies, organizations, products, domain names, e-mail addresses, logos, people ... Reserva
[MS-STWEB]: Microsoft OneDrive Save to Web SOAP Web Service

Intellectual Property Rights Notice for Open Specifications Documentation 

Technical Documentation. Microsoft publishes Open Specifications documentation for protocols, file formats, languages, standards as well as overviews of the interaction among each of these technologies.



Copyrights. This documentation is covered by Microsoft copyrights. Regardless of any other terms that are contained in the terms of use for the Microsoft website that hosts this documentation, you may make copies of it in order to develop implementations of the technologies described in the Open Specifications and may distribute portions of it in your implementations using these technologies or your documentation as necessary to properly document the implementation. You may also distribute in your implementation, with or without modification, any schema, IDL's, or code samples that are included in the documentation. This permission also applies to any documents that are referenced in the Open Specifications.



No Trade Secrets. Microsoft does not claim any trade secret rights in this documentation.



Patents. Microsoft has patents that may cover your implementations of the technologies described in the Open Specifications. Neither this notice nor Microsoft's delivery of the documentation grants any licenses under those or any other Microsoft patents. However, a given Open Specification may be covered by Microsoft Open Specification Promise or the Community Promise. If you would prefer a written license, or if the technologies described in the Open Specifications are not covered by the Open Specifications Promise or Community Promise, as applicable, patent licenses are available by contacting [email protected].



Trademarks. The names of companies and products contained in this documentation may be covered by trademarks or similar intellectual property rights. This notice does not grant any licenses under those rights. For a list of Microsoft trademarks, visit www.microsoft.com/trademarks.



Fictitious Names. The example companies, organizations, products, domain names, e-mail addresses, logos, people, places, and events depicted in this documentation are fictitious. No association with any real company, organization, product, domain name, email address, logo, person, place, or event is intended or should be inferred.

Reservation of Rights. All other rights are reserved, and this notice does not grant any rights other than specifically described above, whether by implication, estoppel, or otherwise. Tools. The Open Specifications do not require the use of Microsoft programming tools or programming environments in order for you to develop an implementation. If you have access to Microsoft programming tools and environments you are free to take advantage of them. Certain Open Specifications are intended for use in conjunction with publicly available standard specifications and network programming art, and assumes that the reader either is familiar with the aforementioned material or has immediate access to it.

1 / 54 [MS-STWEB] - v20160414 Microsoft OneDrive Save to Web SOAP Web Service Copyright © 2016 Microsoft Corporation Release: April 14, 2016

Revision Summary Date

Revision History

Revision Class

Comments

2/19/2010

1.0

Major

Initial Availability

3/31/2010

1.01

Major

Updated and revised the technical content

4/30/2010

1.02

Editorial

Revised and edited the technical content

6/7/2010

1.03

Editorial

Revised and edited the technical content

6/29/2010

1.04

Editorial

Changed language and formatting in the technical content.

7/23/2010

1.05

Minor

Clarified the meaning of the technical content.

9/27/2010

1.05

None

No changes to the meaning, language, or formatting of the technical content.

11/15/2010

1.06

Major

Significantly changed the technical content.

12/17/2010

1.06

None

No changes to the meaning, language, or formatting of the technical content.

3/18/2011

1.7

Minor

Clarified the meaning of the technical content.

6/10/2011

1.7

None

No changes to the meaning, language, or formatting of the technical content.

1/20/2012

2.0

Major

Significantly changed the technical content.

4/11/2012

2.0

None

No changes to the meaning, language, or formatting of the technical content.

7/16/2012

3.0

Major

Significantly changed the technical content.

10/8/2012

3.0

None

No changes to the meaning, language, or formatting of the technical content.

2/11/2013

3.0

None

No changes to the meaning, language, or formatting of the technical content.

7/30/2013

3.1

Minor

Clarified the meaning of the technical content.

11/18/2013

3.2

Minor

Clarified the meaning of the technical content.

2/10/2014

3.2

None

No changes to the meaning, language, or formatting of the technical content.

4/30/2014

3.3

Minor

Clarified the meaning of the technical content.

7/31/2014

3.4

Minor

Clarified the meaning of the technical content.

10/30/2014

3.4

None

No changes to the meaning, language, or formatting of the technical content.

3/30/2015

3.4

None

No changes to the meaning, language, or formatting of the technical content.

6/30/2015

4.0

Major

Significantly changed the technical content.

9/4/2015

5.0

Major

Significantly changed the technical content.

4/14/2016

6.0

Major

Significantly changed the technical content. 2 / 54

[MS-STWEB] - v20160414 Microsoft OneDrive Save to Web SOAP Web Service Copyright © 2016 Microsoft Corporation Release: April 14, 2016

Table of Contents 1

Introduction ............................................................................................................ 6 1.1 Glossary ........................................................................................................... 6 1.2 References ........................................................................................................ 7 1.2.1 Normative References ................................................................................... 7 1.2.2 Informative References ................................................................................. 8 1.3 Overview .......................................................................................................... 8 1.4 Relationship to Other Protocols ............................................................................ 8 1.5 Prerequisites/Preconditions ................................................................................. 9 1.6 Applicability Statement ....................................................................................... 9 1.7 Versioning and Capability Negotiation ................................................................... 9 1.8 Vendor-Extensible Fields ..................................................................................... 9 1.9 Standards Assignments....................................................................................... 9

2

Messages ............................................................................................................... 10 2.1 Transport ........................................................................................................ 10 2.1.1 Authorization Discovery ............................................................................... 10 2.2 Common Message Syntax ................................................................................. 10 2.2.1 Namespaces .............................................................................................. 11 2.2.2 Messages................................................................................................... 11 2.2.3 Elements ................................................................................................... 11 2.2.4 Complex Types ........................................................................................... 11 2.2.4.1 ArrayOfstring ........................................................................................ 12 2.2.4.2 Document ............................................................................................ 12 2.2.4.3 Library................................................................................................. 13 2.2.4.4 OperationRequest ................................................................................. 13 2.2.4.5 ServerError .......................................................................................... 14 2.2.4.6 SharedLibrary ....................................................................................... 14 2.2.4.7 SharingLevelInfo ................................................................................... 14 2.2.4.8 TermsOfUseNotSigned ........................................................................... 15 2.2.5 Simple Types ............................................................................................. 15 2.2.5.1 AccessLevel .......................................................................................... 15 2.2.5.2 SharingLevel ........................................................................................ 16 2.2.6 Attributes .................................................................................................. 16 2.2.7 Groups ...................................................................................................... 16 2.2.8 Attribute Groups ......................................................................................... 16

3

Protocol Details ..................................................................................................... 17 3.1 Server Details .................................................................................................. 17 3.1.1 Abstract xmlns:xs="http://www.w3.org/2001/XMLSchema">

string: A single string item.

2.2.4.2 Document Namespace: http://schemas.microsoft.com/clouddocuments Contains information about one file.

AccessLevel: The access level of the file. This field MUST be present. DavUrl: The URL used to access the file via WebDAV, as specified in [RFC4918]. This field MUST be present. DisplayName: The name of the file. This field MUST be present. IsNotebook: Indicates whether the file is a OneNote notebook. This field MUST be present. LastModifiedDate: UTC time when the folder was last modified. This field MUST be present. Owner: The name of the user who created the folder. The field MUST be present. ResourceId: The unique identifier for the file on the server. This field MUST be present. SharingLevelInfo: The sharing level of the file. This field MUST be present. ViewUrl: A URL that can be used to view the file in a web browser, if the file has such a URL; otherwise an empty value. This field MUST be present. WacUrl: A URL that can be used to discover API endpoints on the server. This field MUST be present. WebUrl: A URL that can be used to view the properties of the file. This field MUST be present. 12 / 54 [MS-STWEB] - v20160414 Microsoft OneDrive Save to Web SOAP Web Service Copyright © 2016 Microsoft Corporation Release: April 14, 2016

2.2.4.3 Library Namespace: http://schemas.microsoft.com/clouddocuments Contains information about one folder.

AccessLevel: The access level of the folder. This field MUST be present. DavUrl: The URL used to access the folder via WebDAV, as specified in [RFC4918]. This field MUST be present. DisplayName: The name of the folder. This field MUST be present. SharingLevelInfo: The sharing level of the folder. This field MUST be present. WebUrl: The URL used to access the folder via HTTP or HTTPS. This field MUST be present. ResourceId: The unique identifier for the folder on the server. This field MUST be present. LastModifiedDate: UTC time when the folder was last modified. This field MUST be present.

2.2.4.4 OperationRequest Namespace: http://schemas.microsoft.com/clouddocuments Basic information shared between various requests.

ClientAppId: Information about the identity and version of the client. This string is informational for the server. The format and content are determined by the client. Market: The client's preferred language culture for strings returned by the server. If this field exists it MUST contain one of the following: 

A value constructed as specified in [RFC4646]



The value "x-none"



An empty string

13 / 54 [MS-STWEB] - v20160414 Microsoft OneDrive Save to Web SOAP Web Service Copyright © 2016 Microsoft Corporation Release: April 14, 2016

The server returns strings, such as the value of the Description field in SharedLibrary, that are intended for display to the user. The server returns these strings in the language most similar to that requested by the client for which the server has localized resources. If the client passes the value "xnone" or an empty string, the server returns the strings in a default language that is chosen by the server. SkyDocsServiceVersion: The requested version of the service. If this field exists it MUST have a value of "v1.0".

2.2.4.5 ServerError Namespace: http://schemas.microsoft.com/clouddocuments Failure information returned when a server error occurs.

FailureDetail: A description of the error. This field MUST be present. MachineName: The name of the server which caused the error. This field MUST be present.

2.2.4.6 SharedLibrary Namespace: http://schemas.microsoft.com/clouddocuments Information appended to a normal Library to describe a folder shared by a user.

Owner: The name of the user who shared the folder. This field MUST be present.

2.2.4.7 SharingLevelInfo Namespace: http://schemas.microsoft.com/clouddocuments A combination of the sharing level and a description of the sharing level for a folder.

14 / 54 [MS-STWEB] - v20160414 Microsoft OneDrive Save to Web SOAP Web Service Copyright © 2016 Microsoft Corporation Release: April 14, 2016

Description: A description of the sharing level suitable for display to the user. This field MUST be present. Level: The sharing level. This field MUST be present.

2.2.4.8 TermsOfUseNotSigned Namespace: http://schemas.microsoft.com/clouddocuments A SOAP fault returned when a user has not yet signed the Terms of Use agreement.

TermsOfUseUrl: A URL for the user to sign the Terms of Use agreement. This field MUST be present.

2.2.5 Simple Types The following table summarizes the set of common XML schema simple type definitions defined by this specification. XML schema simple type definitions that are specific to a particular operation are described with the operation. Simple type

Description

AccessLevel

This type is an enumeration of access levels that describe a folder. A given access level also applies to all folders which are descendants of the given folder.

SharingLevel

This type is an enumeration of sharing levels that can describe a folder.

2.2.5.1 AccessLevel Namespace: http://schemas.microsoft.com/clouddocuments This type is an enumeration of access levels that describe a folder. A given access level also applies to all folders which are descendants of the given folder.

The following table specifies the allowable values for the AccessLevel simple type.

15 / 54 [MS-STWEB] - v20160414 Microsoft OneDrive Save to Web SOAP Web Service Copyright © 2016 Microsoft Corporation Release: April 14, 2016

Value

Meaning

Read

The user can open files from the folder but cannot save files to it.

ReadWrite

The user can open and save files in the folder.

None

The user cannot open or save files in the folder.

2.2.5.2 SharingLevel Namespace: http://schemas.microsoft.com/clouddocuments This type is an enumeration of sharing levels that can describe a folder.

The following table specifies the allowable values for the SharingLevel simple type. Value

Meaning

Public

The folder is shared with everyone.

Private

The folder is shared with no one.

Shared

The folder is shared with at least one person.

PublicUnlisted

The folder requires a special token to access it. The mechanics of this token are outside the scope of this document.

2.2.6 Attributes This specification does not define any common XML schema attribute definitions.

2.2.7 Groups This specification does not define any common XML schema group definitions.

2.2.8 Attribute Groups This specification does not define any common XML schema attribute group definitions.

16 / 54 [MS-STWEB] - v20160414 Microsoft OneDrive Save to Web SOAP Web Service Copyright © 2016 Microsoft Corporation Release: April 14, 2016

3

Protocol Details

In the following sections, the schema definition might differ from the processing rules imposed by the protocol. The WSDL in this specification matches the WSDL that shipped with the product and provides a base description of the schema. The text that introduces the WSDL might specify differences that reflect actual Microsoft product behavior. For example, the schema definition might allow for an element to be empty, null, or not present but the behavior of the protocol as specified restricts the same elements to being non-empty, not null, and present. The client side of this protocol simply passes calls through, and no additional timers or other state is required. Calls made by the higher-layer protocol or application are passed directly to the transport, and the results returned by the transport are passed directly back to the higher-layer protocol or application.

3.1

Server Details

3.1.1 Abstract xmlns:wsdl="http://schemas.xmlsoap.org/wsdl/">

GetChangesSinceToken requests incremental changes to a specified folder via synchronization tokens. A synchronization token is a string generated by the server to identify the complete listing and timestamps of every file and folder contained by a specified folder at a specified time. A client uses this string to request the server for the set of files and folders that have been added, modified, or deleted in the specified folder at the time of the request relative to the time specified by the synchronization token. The format of the string is specified by the server implementing synchronization tokens and can be opaque to clients, except that an empty string requests the complete folder listing at the time of the request. The client MUST first issue a request with an empty synchronization token; and the server returns the set of all files and folders contained by the specified folder, plus a synchronization token for the set. The client can then issue a GetChangesSinceToken request with this synchronization token; and the server returns only the set of files and folders that have changed, plus a new synchronization token for the updated set. If the synchronization token in the request is not considered valid by the server (such as the synchronization token being too old), the server MUST return an empty set and empty synchronization token, which specifies that the client MUST issue a new request with an empty synchronization token. The client MUST wait at least the number of seconds specified by the MinAmIAloneSyncInterval, MinBackgroundSyncInterval, and MinRealtimeSyncInterval elements before issuing a new request as specified by these elements. Otherwise, the client will place an unnecessary load on the server.

3.1.4.1.1 Messages The following table summarizes the set of WSDL message definitions that are specific to this operation. Message

Description

GetChangesSinceTokenRequest

The request WSDL message for the GetChangesSinceToken WSDL operation.

GetChangesSinceTokenResponse

The response WSDL message for the GetChangesSinceToken WSDL operation.

18 / 54 [MS-STWEB] - v20160414 Microsoft OneDrive Save to Web SOAP Web Service Copyright © 2016 Microsoft Corporation Release: April 14, 2016

3.1.4.1.1.1

GetChangesSinceTokenRequest

The request WSDL message for the GetChangesSinceToken WSDL operation. The SOAP action value is: GetChangesSinceToken

The SOAP body contains the GetChangesSinceTokenRequest element.

3.1.4.1.1.2

GetChangesSinceTokenResponse

The response WSDL message for the GetChangesSinceToken WSDL operation. The SOAP body contains the GetChangesSinceTokenResponse element.

3.1.4.1.2 Elements The following table summarizes the XML schema element definitions that are specific to this operation. Element

Description

GetChangesSinceTokenRequest

The input xmlns:xs="http://www.w3.org/2001/XMLSchema">

BaseRequest: An OperationRequest element (section 2.2.4.4) that specifies basic information about the request. DavUrl: Specifies the WebDAV URL of the folder to get the file and folder listing for. MUST be a direct child of a Library folder. SyncToken: Specifies a synchronization token. If SyncToken is empty or null, then the response MUST return every file and folder contained in the folder specified by DavUrl. Otherwise MUST be a synchronization token returned by a previous GetChangesSinceToken operation (section 3.1.4.1) against the same DavUrl as specified by GetChangesSinceTokenResponse.SyncToken (section 3.1.4.1.2.2), and the server MUST return the set of files and folders that have changed since the given synchronization token if the synchronization token is still valid.

3.1.4.1.2.2

GetChangesSinceTokenResponse 19 / 54

[MS-STWEB] - v20160414 Microsoft OneDrive Save to Web SOAP Web Service Copyright © 2016 Microsoft Corporation Release: April 14, 2016

The GetChangesSinceTokenResponse element specifies the result xmlns:xs="http://www.w3.org/2001/XMLSchema"> 44 / 54 [MS-STWEB] - v20160414 Microsoft OneDrive Save to Web SOAP Web Service Copyright © 2016 Microsoft Corporation Release: April 14, 2016



45 / 54 [MS-STWEB] - v20160414 Microsoft OneDrive Save to Web SOAP Web Service Copyright © 2016 Microsoft Corporation Release: April 14, 2016

46 / 54 [MS-STWEB] - v20160414 Microsoft OneDrive Save to Web SOAP Web Service Copyright © 2016 Microsoft Corporation Release: April 14, 2016

47 / 54 [MS-STWEB] - v20160414 Microsoft OneDrive Save to Web SOAP Web Service Copyright © 2016 Microsoft Corporation Release: April 14, 2016



48 / 54 [MS-STWEB] - v20160414 Microsoft OneDrive Save to Web SOAP Web Service Copyright © 2016 Microsoft Corporation Release: April 14, 2016

7

Appendix B: Full XML Schema

For ease of implementation, the following is the full XML schema for this protocol.

49 / 54 [MS-STWEB] - v20160414 Microsoft OneDrive Save to Web SOAP Web Service Copyright © 2016 Microsoft Corporation Release: April 14, 2016

8

Appendix C: Product Behavior

The information in this specification is applicable to the following Microsoft products or supplemental software. References to product versions include released service packs. 

Microsoft Office 2010 suites



Microsoft Office 2013



Microsoft Office 2016



Windows 8.1 Update



Windows 10 operating system

Exceptions, if any, are noted below. If a service pack or Quick Fix Engineering (QFE) number appears with the product version, behavior changed in that service pack or QFE. The new behavior also applies to subsequent service packs of the product unless otherwise specified. If a product edition appears with the product version, behavior is different in that product edition. Unless otherwise specified, any statement of optional behavior in this specification that is prescribed using the terms SHOULD or SHOULD NOT implies product behavior in accordance with the SHOULD or SHOULD NOT prescription. Unless otherwise specified, the term MAY implies that the product does not follow the prescription. Section 2.1.1: Microsoft OneNote 2010 and Microsoft OneDrive use XOffice_Authorization_Check. Section 3.1.4: The GetNotebooks operation is only used in Microsoft OneNote 2013. Section 3.1.4: The ResolveWebUrl operation is only used in OneNote 2013. Section 3.1.4.3: The GetNotebooks operation is only used in OneNote 2013. Section 3.1.4.6: The ResolveWebUrl operation is only used in OneNote 2013.

50 / 54 [MS-STWEB] - v20160414 Microsoft OneDrive Save to Web SOAP Web Service Copyright © 2016 Microsoft Corporation Release: April 14, 2016

9

Change Tracking

This section identifies changes that were made to this document since the last release. Changes are classified as New, Major, Minor, Editorial, or No change. The revision class New means that a new document is being released. The revision class Major means that the technical content in the document was significantly revised. Major changes affect protocol interoperability or implementation. Examples of major changes are: 

A document revision that incorporates changes to interoperability requirements or functionality.



The removal of a document from the documentation set.

The revision class Minor means that the meaning of the technical content was clarified. Minor changes do not affect protocol interoperability or implementation. Examples of minor changes are updates to clarify ambiguity at the sentence, paragraph, or table level. The revision class Editorial means that the formatting in the technical content was changed. Editorial changes apply to grammatical, formatting, and style issues. The revision class No change means that no new technical changes were introduced. Minor editorial and formatting changes may have been made, but the technical content of the document is identical to the last released version. Major and minor changes can be described further using the following change types: 

New content added.



Content updated.



Content removed.



New product behavior note added.



Product behavior note updated.



Product behavior note removed.



New protocol syntax added.



Protocol syntax updated.



Protocol syntax removed.



New content added due to protocol revision.



Content updated due to protocol revision.



Content removed due to protocol revision.



New protocol syntax added due to protocol revision.



Protocol syntax updated due to protocol revision.



Protocol syntax removed due to protocol revision.



Obsolete document removed.

Editorial changes are always classified with the change type Editorially updated. Some important terms used in the change type descriptions are defined as follows: 51 / 54 [MS-STWEB] - v20160414 Microsoft OneDrive Save to Web SOAP Web Service Copyright © 2016 Microsoft Corporation Release: April 14, 2016



Protocol syntax refers to data elements (such as packets, structures, enumerations, and methods) as well as interfaces.



Protocol revision refers to changes made to a protocol that affect the bits that are sent over the wire.

The changes made to this document are listed in the following table. For more information, please contact [email protected]. Section

Tracking number (if applicable) and description

Major change (Y or N)

Change type

8 Appendix C: Product Behavior

Updated product behavior section to accurately reflect supported products.

Y

Product behavior note updated.

52 / 54 [MS-STWEB] - v20160414 Microsoft OneDrive Save to Web SOAP Web Service Copyright © 2016 Microsoft Corporation Release: April 14, 2016

10 Index A Abstract data model server 17 AccessLevel simple type 15 Applicability 9 ArrayOfstring complex type 12 Attribute groups 16 Attributes 16 Authorization discovery 10

Library complex type 13 Local events server 37

M

Data model - abstract server 17 Document complex type 12

Message processing server 17 Messages AccessLevel simple type 15 ArrayOfstring complex type 12 attribute groups 16 attributes 16 authorization discovery 10 complex types 11 Document complex type 12 elements 11 enumerated 11 groups 16 Library complex type 13 namespaces 11 OperationRequest complex type 13 ServerError complex type 14 SharedLibrary complex type 14 SharingLevel simple type 16 SharingLevelInfo complex type 14 simple types 15 syntax 10 TermsOfUseNotSigned complex type 15 transport 10

E

N

Events local - server 37 timer - server 37 Examples protocol 38

Namespaces 11 Normative references 7

C Capability negotiation 9 Change tracking 51 Complex types 11 ArrayOfstring 12 Document 12 Library 13 OperationRequest 13 ServerError 14 SharedLibrary 14 SharingLevelInfo 14 TermsOfUseNotSigned 15

D

F Fields - vendor-extensible 9 Full WSDL 41 Full XML schema 49

G Glossary 6 Groups 16

I Implementer - security considerations 40 Index of security parameters 40 Informative references 8 Initialization server 17 Introduction 6

L

O OperationRequest complex type 13 Operations GetChangesSinceToken 18 GetItemInfo 21 GetNotebooks 24 GetProductInfo 28 GetWebAccountInfo 30 ResolveWebUrl 35 Overview (synopsis) 8

P Parameters - security index 40 Preconditions 9 Prerequisites 9 Product behavior 50 Protocol Details overview 17 Protocol examples 38

R References 7 53 / 54

[MS-STWEB] - v20160414 Microsoft OneDrive Save to Web SOAP Web Service Copyright © 2016 Microsoft Corporation Release: April 14, 2016

informative 8 normative 7 Relationship to other protocols 8

S Security implementer considerations 40 parameter index 40 Sequencing rules server 17 Server abstract data model 17 GetChangesSinceToken operation 18 GetItemInfo operation 21 GetNotebooks operation 24 GetProductInfo operation 28 GetWebAccountInfo operation 30 initialization 17 local events 37 message processing 17 ResolveWebUrl operation 35 sequencing rules 17 timer events 37 timers 17 ServerError complex type 14 SharedLibrary complex type 14 SharingLevel simple type 16 SharingLevelInfo complex type 14 Simple types 15 AccessLevel 15 SharingLevel 16 Standards assignments 9 Syntax messages - overview 10

T TermsOfUseNotSigned complex type 15 Timer events server 37 Timers server 17 Tracking changes 51 Transport 10 Types complex 11 simple 15

V Vendor-extensible fields 9 Versioning 9

W WSDL 41

X XML schema 49

54 / 54 [MS-STWEB] - v20160414 Microsoft OneDrive Save to Web SOAP Web Service Copyright © 2016 Microsoft Corporation Release: April 14, 2016