workbook resource type

Namespace: microsoft.graph

The top-level object that contains related workbook objects such as worksheets, tables, and ranges.

Methods

Method	Return Type	Description
Create	workbookSessionInfo	Create a workbook session to start a persistent or non-persistent session.
Close session	None	Close an existing session.
Refresh session	None	Refresh an existing session.

Properties

None.

Relationships

Relationship	Type	Description
comments	workbookComment collection	Represents a collection of comments in a workbook.
names	workbookNamedItem collection	Represents a collection of workbooks scoped named items (named ranges and constants). Read-only.
operations	workbookOperation collection	The status of workbook operations. Getting an operation collection is not supported, but you can get the status of a long-running operation if the Location header is returned in the response. Read-only.
tables	workbookTable collection	Represents a collection of tables associated with the workbook. Read-only.
worksheets	workbookWorksheet collection	Represents a collection of worksheets associated with the workbook. Read-only.

Functions

Excel functions: Invoke a workbook function using the syntax POST /me/drive/root/workbook/functions/{function-name} and providing the function argument(s) in the body using a JSON object. The function's resulting value and any error strings are returned in the function result object. The error value of null indicates successful execution of the function.

The complete list of supported functions are listed here. Refer to the function signature for specific parameter names and data types.

Important notes:

• The range input parameter is supplied using a range object instead of the range address string.
• The index parameter is 1-indexed unlike the 0-index used in most of the APIs.

Example: vlookup

In an Excel spreadsheet, the vlookup function takes the following arguments:

1. The value you want to look up, also called the lookup value.
2. The range where the lookup value is located. Remember that the lookup value should always be in the first column in the range for VLOOKUP to work correctly. For example, if your lookup value is in cell C2 then your range should start with C.
3. The column number in the range that contains the return value. For example, if you specify B2: D11 as the range, you should count B as the first column, C as the second, and so on.
4. Optionally, you can specify TRUE if you want an approximate match or FALSE if you want an exact match of the return value. If you don't specify anything, the default value will always be TRUE or approximate match.

Inside a cell, the vlookup function looks like this:

=VLOOKUP(lookup value, range containing the lookup value, the column number in the range containing the return value, optionally specify TRUE for approximate match or FALSE for an exact match)

(See the documentation for the VLOOKUP Excel function.)

The example below shows how to call the vlookup function and pass these parameters with the Excel REST API.

Request:

POST https://graph.microsoft.com/beta/me/drive/root:/book1.xlsx:/workbook/functions/vlookup
content-type: Application/Json 
authorization: Bearer {access-token} 
workbook-session-id: {session-id}

{
    "lookupValue": "Temperature",
    "tableArray": { "Address": "Sheet1!E1:G5" },
    "colIndexNum": 2,
    "rangeLookup": false
}

Response:

HTTP code: 200 OK
content-type: application/json;odata.metadata 

{
    "@odata.context": "https://graph.microsoft.com/beta/$metadata#workbookFunctionResult",
    "@odata.type": "#microsoft.graph.workbookFunctionResult",
    "@odata.id": "/users('f6d92604-4b76-4b70-9a4c-93dfbcc054d5')/drive/root/workbook/functions/vlookup()",
    "error": null,
    "value": "28.3"
}

Example: median

In an Excel spreadsheet, the median function takes an array of one or more input ranges.

Inside a cell, the median function looks like this example:

=MEDIAN(A2:A6)

(See the documentation for the MEDIAN Excel function.)

The example below shows how to call the median function and one or more input ranges with the Excel REST API.

Request:

POST https://graph.microsoft.com/beta/me/drive/root:/book1.xlsx:/workbook/functions/median
content-type: Application/Json 
authorization: Bearer {access-token} 
workbook-session-id: {session-id}

{
   "values":[
      {
         "address":"Sheet2!A1:A5"
      },
      {
         "address":"Sheet2!B1:B5"
      }
   ]
}

Response:

HTTP code: 200 OK
content-type: application/json;odata.metadata 

{
  "@odata.context": "https://graph.microsoft.com/beta/$metadata#workbookFunctionResult",
  "@odata.type": "#microsoft.graph.workbookFunctionResult",
  "@odata.id": "/users('2abcad6a-2fca-4b6e-9577-e358a757d77d')/drive/root/workbook/functions/median()",
  "error": null,
  "value": 30
}

JSON representation

{
  "names": [{"@odata.type": "microsoft.graph.workbookNamedItem"}],
  "tables": [{"@odata.type": "microsoft.graph.workbookTable"}],
  "worksheets": [{"@odata.type": "microsoft.graph.workbookWorksheet"}]
}