Travailler avec Excel dans Microsoft Graph
Importante
Les API sous la version /beta dans Microsoft Graph sont susceptibles d’être modifiées. L’utilisation de ces API dans des applications de production n’est pas prise en charge. Pour déterminer si une API est disponible dans v1.0, utilisez le sélecteur Version .
Vous pouvez utiliser Microsoft Graph pour autoriser les applications web et mobiles à lire et à modifier des classeurs Excel stockés sur OneDrive, SharePoint ou d’autres plateformes de stockage prises en charge. La ressource Workbook (ou fichier Excel) contient toutes les autres ressources Excel via des relations. Vous pouvez accéder à un classeur via l’API lecteur en identifiant l’emplacement du fichier dans l’URL. Par exemple :
https://graph.microsoft.com/beta/me/drive/items/{id}/workbook/
https://graph.microsoft.com/beta/me/drive/root:/{item-path}:/workbook/
Vous pouvez accéder à un ensemble d’objets Excel (tels que Tableau, Plage ou Graphique) en utilisant les API REST standard pour effectuer des opérations de création, de lecture, de mise à jour et de suppression (CRUD) sur le classeur. Par exemple, https://graph.microsoft.com/beta/me/drive/items/{id}/workbook/
renvoie une collection d’objets de feuille de calcul qui font partie du classeur.
Note: L’API REST Excel prend uniquement en charge les classeurs au format de fichier Office Open XML. Les .xls classeurs d’extension ne sont pas pris en charge.
Autorisation et étendues
Vous pouvez utiliser le point de terminaison Microsoft Entra v.20 pour authentifier les API Excel. Toutes les API nécessitent l’en-tête HTTP Authorization: Bearer {access-token}.
L’une des étendues d’autorisation suivantes est requise pour utiliser la ressource Excel :
- Files.Read
- Files.ReadWrite
Sessions et persistance
Les API Excel peuvent être appelées dans l’un des deux modes :
- Session permanente : toutes les modifications apportées au classeur sont conservées (enregistrées). Il s’agit du mode de fonctionnement normal.
- Session non persistante : les modifications apportées par l’API ne sont pas enregistrées à l’emplacement source. À la place, le serveur principal Excel conserve une copie temporaire du fichier qui reflète les modifications apportées au cours de cette session API. Les modifications sont perdues à l’expiration de la session Excel. Ce mode est utile pour les applications qui doivent effectuer une analyse ou obtenir les résultats d’un calcul ou l’image d’un graphique, sans affecter l’état du document.
Pour représenter la session de l’API, utilisez l’en-tête workbook-session-id: {session-id}.
Remarque : l’en-tête de la session n’est pas nécessaire pour faire fonctionner une API Excel. Toutefois, nous vous recommandons d’utiliser l’en-tête de session pour obtenir de meilleures performances. Si vous n’utilisez pas un en-tête de session, les modifications apportées pendant l’appel de l’API sont conservées dans le fichier.
Obtention d’une session via l’appel d’une API
Demande
Transmettez un objet JSON en définissant la valeur persistchanges sur true ou false.
POST https://graph.microsoft.com/beta/me/drive/items/01CYZLFJGUJ7JHBSZDFZFL25KSZGQTVAUN/workbook/createSession
content-type: Application/Json
authorization: Bearer {access-token}
{ "persistChanges": true }
Lorsque la valeur de persistChanges est définie sur false, un ID de session non persistant est retourné.
Réponse
HTTP code: 201 Created
content-type: application/json;odata.metadata
{
"@odata.context": "https://graph.microsoft.com/beta/$metadata#microsoft.graph.sessionInfo",
"id": "{session-id}",
"persistChanges": true
}
Utilisation
L’ID de la session renvoyée par l’appel précédent est transmise sous forme d’en-tête aux demandes API suivantes dans
l’en-tête HTTP workbook-session-id.
GET https://graph.microsoft.com/beta/me/drive/items/01CYZLFJGUJ7JHBSZDFZFL25KSZGQTVAUN/workbook/worksheets
authorization: Bearer {access-token}
workbook-session-id: {session-id}
Remarque : si l’ID de session a expiré, un code d’erreur HTTP
404est renvoyé sur la session. Dans ce cas, vous pouvez choisir de créer une session et de poursuivre. Vous pouvez également actualiser la session régulièrement pour qu’elle reste active. En règle générale, une session permanente expire après environ 5 minutes d’inactivité. Une session non permanente expire après environ 7 minutes d’inactivité.
Scénarios Excel courants
Cette section fournit des exemples des opérations courantes que vous pouvez utiliser sur les objets Excel.
Opérations de feuille de calcul
Répertorier les feuilles de calcul du classeur
Demande
GET https://graph.microsoft.com/beta/me/drive/items/01CYZLFJGUJ7JHBSZDFZFL25KSZGQTVAUN/workbook/worksheets
accept: Application/Json
authorization: Bearer {access-token}
workbook-session-id: {session-id}
Réponse
HTTP code: 200 OK
content-type: application/json;odata.metadata
{
"@odata.context": "https://graph.microsoft.com/beta/$metadata#users('f6d92604-4b76-4b70-9a4c-93dfbcc054d5')/drive/items('01CYZLFJGUJ7JHBSZDFZFL25KSZGQTVAUN')/workbook/worksheets",
"value": [
{
"@odata.id": "/users('f6d92604-4b76-4b70-9a4c-93dfbcc054d5')/drive/items('01CYZLFJGUJ7JHBSZDFZFL25KSZGQTVAUN')/workbook/worksheets(%27%7B00000000-0001-0000-0000-000000000000%7D%27)",
"id": "{00000000-0001-0000-0000-000000000000}",
"name": "Sheet1",
"position": 0,
"visibility": "Visible"
},
{
"@odata.id": "/users('f6d92604-4b76-4b70-9a4c-93dfbcc054d5')/drive/items('01CYZLFJGUJ7JHBSZDFZFL25KSZGQTVAUN')/workbook/worksheets(%27%7B00000000-0001-0000-0100-000000000000%7D%27)",
"id": "{00000000-0001-0000-0100-000000000000}",
"name": "Sheet57664",
"position": 1,
"visibility": "Visible"
}
]
}
Ajouter une nouvelle feuille de calcul
POST /{version}/me/drive/root:/workbook/worksheets
content-type: Application/Json
authorization: Bearer {access-token}
workbook-session-id: {session-id}
{ "name": "Sheet32243" }
Réponse
HTTP code: 201 Created
content-type: application/json;odata.metadata
{
"@odata.context": "https://graph.microsoft.com/{version}/$metadata#users('f6d92604-4b76-4b70-9a4c-93dfbcc054d5')/drive/root/$entity",
"@odata.id": "/users('f6d92604-4b76-4b70-9a4c-93dfbcc054d5')/drive/items('01CYZLFJGUJ7JHBSZDFZFL25KSZGQTVAUN')/workbook/worksheets(%27%7B75A18F35-34AA-4F44-97CC-FDC3C05D9F40%7D%27)",
"id": "{75A18F35-34AA-4F44-97CC-FDC3C05D9F40}",
"name": "Sheet32243",
"position": 5,
"visibility": "Visible"
}
Obtenir une nouvelle feuille de calcul
GET https://graph.microsoft.com/beta/me/drive/items/01CYZLFJGUJ7JHBSZDFZFL25KSZGQTVAUN/workbook/worksheets/Sheet32243
content-type: Application/Json
authorization: Bearer {access-token}
workbook-session-id: {session-id}
Réponse
HTTP code: 200 OK
content-type: application/json;odata.metadata
{
"@odata.context": "https://graph.microsoft.com/beta/$metadata#users('f6d92604-4b76-4b70-9a4c-93dfbcc054d5')/drive/items('01CYZLFJGUJ7JHBSZDFZFL25KSZGQTVAUN')/workbook/worksheets/$entity",
"@odata.id": "/users('f6d92604-4b76-4b70-9a4c-93dfbcc054d5')/drive/items('01CYZLFJGUJ7JHBSZDFZFL25KSZGQTVAUN')/workbook/worksheets(%27%7B75A18F35-34AA-4F44-97CC-FDC3C05D9F40%7D%27)",
"id": "{75A18F35-34AA-4F44-97CC-FDC3C05D9F40}",
"name": "Sheet32243",
"position": 5,
"visibility": "Visible"
}
** Remarque : les feuilles de calcul peuvent également être récupérées à l’aide de l’ID. Toutefois, l’ID contient { actuellement des caractères et « } », qui doivent être codés dans l’URL pour que l’API fonctionne. Exemple : Pour obtenir une feuille de calcul avec l’ID , encodez l’ID {75A18F35-34AA-4F44-97CC-FDC3C05D9F40}dans le chemin d’accès en tant que /workbook/worksheets/%7B75A18F35-34AA-4F44-97CC-FDC3C05D9F40%7D.
Supprimer une feuille de calcul
Demande
DELETE https://graph.microsoft.com/beta/me/drive/items/01CYZLFJGUJ7JHBSZDFZFL25KSZGQTVAUN/workbook/worksheets('%7B75A18F35-34AA-4F44-97CC-FDC3C05D9F40%7D')
content-type: Application/Json
authorization: Bearer {access-token}
workbook-session-id: {session-id}
Réponse
HTTP code: 204 No Content
Mettre à jour les propriétés de la feuille de calcul
Demande
PATCH https://graph.microsoft.com/beta/me/drive/items/01CYZLFJGUJ7JHBSZDFZFL25KSZGQTVAUN/workbook/worksheets/SheetA
content-type: Application/Json
accept: application/Json
authorization: Bearer {access-token}
workbook-session-id: {session-id}
{ "name": "SheetA", "position": 3 }
Réponse
HTTP code: 200 OK
content-type: application/json;odata.metadata
{
"@odata.context": "https://graph.microsoft.com/beta/$metadata#users('f6d92604-4b76-4b70-9a4c-93dfbcc054d5')/drive/items('01CYZLFJGUJ7JHBSZDFZFL25KSZGQTVAUN')/workbook/worksheets/$entity",
"@odata.id": "/users('f6d92604-4b76-4b70-9a4c-93dfbcc054d5')/drive/items('01CYZLFJGUJ7JHBSZDFZFL25KSZGQTVAUN')/workbook/worksheets(%27%7B00000000-0001-0000-0100-000000000000%7D%27)",
"id": "{00000000-0001-0000-0100-000000000000}",
"name": "SheetA",
"position": 3,
"visibility": "Visible"
}
Opérations de graphique
Répertorier les graphiques qui font partie de la feuille de calcul
Demande
GET https://graph.microsoft.com/beta/me/drive/items/01CYZLFJB6K563VVUU2ZC2FJBAHLSZZQXL/workbook/worksheets('%7B00000000-0001-0000-0000-000000000000%7D')/charts
accept: Application/Json
authorization: Bearer {access-token}
workbook-session-id: {session-id}
Réponse
HTTP code: 200 OK
content-type: application/json;odata.metadata
{
"@odata.context": "https://graph.microsoft.com/beta/$metadata#users('f6d92604-4b76-4b70-9a4c-93dfbcc054d5')/drive/items('01CYZLFJB6K563VVUU2ZC2FJBAHLSZZQXL')/workbook/worksheets('%7B00000000-0001-0000-0000-000000000000%7D')/charts",
"value": [
{
"@odata.id": "/users('f6d92604-4b76-4b70-9a4c-93dfbcc054d5')/drive/items('01CYZLFJB6K563VVUU2ZC2FJBAHLSZZQXL')/workbook/worksheets(%27%7B00000000-0001-0000-0000-000000000000%7D%27)/charts(%27%7B00000000-0008-0000-0100-000003000000%7D%27)",
"height": 235.5,
"id": "{00000000-0008-0000-0100-000003000000}",
"left": 276.0,
"name": "Chart 2",
"top": 0.0,
"width": 401.25
}
]
}
** Remarque : L’ID de graphique contient { des caractères et } (exemple : {00000000-0008-0000-0100-000003000000}), qui doivent être codés dans une URL pour que l’API fonctionne. Exemple : pour obtenir un objet de graphique, l’URL encode l’ID dans le chemin d’accès en tant que /charts/%7B00000000-0008-0000-0100-000003000000%7D.
Obtenir une image de graphique
Demande
GET https://graph.microsoft.com/beta/me/drive/items/01CYZLFJB6K563VVUU2ZC2FJBAHLSZZQXL/workbook/worksheets('%7B00000000-0001-0000-0000-000000000000%7D')/charts('%7B00000000-0008-0000-0100-000003000000%7D')/Image(width=0,height=0,fittingMode='fit')
authorization: Bearer {access-token}
workbook-session-id: {session-id}
Réponse
HTTP code: 200 OK
content-type: application/json;odata.metadata
{
"@odata.context": "https://graph.microsoft.com/beta/$metadata#Edm.String",
"value": "{base-64-string}"
}
Ajouter un graphique
Demande
POST https://graph.microsoft.com/beta/me/drive/items/01CYZLFJB6K563VVUU2ZC2FJBAHLSZZQXL/workbook/worksheets('%7B00000000-0001-0000-0000-000000000000%7D')/charts/Add
content-type: Application/Json
accept: application/Json
authorization: Bearer {access-token}
{ "type": "ColumnClustered", "sourcedata": "A1:C4", "seriesby": "Auto" }
Réponse
HTTP code: 201 Created
content-type: application/json;odata.metadata
{
"@odata.context": "https://graph.microsoft.com/beta/$metadata#chart",
"@odata.type": "#microsoft.graph.workbookChart",
"@odata.id": "/users('f6d92604-4b76-4b70-9a4c-93dfbcc054d5')/drive/items('01CYZLFJB6K563VVUU2ZC2FJBAHLSZZQXL')/workbook/worksheets(%27%7B00000000-0001-0000-0000-000000000000%7D%27)/charts(%27%7B2D421098-FA19-41F7-8528-EE7B00E4BB42%7D%27)",
"height": 216.0,
"id": "{2D421098-FA19-41F7-8528-EE7B00E4BB42}",
"left": 0.0,
"name": "Chart 2",
"top": 0.0,
"width": 360.0
}
Mettre à jour un graphique
PATCH https://graph.microsoft.com/beta/me/drive/items/01CYZLFJB6K563VVUU2ZC2FJBAHLSZZQXL/workbook/worksheets('%7B00000000-0001-0000-0000-000000000000%7D')/charts('%7B2D421098-FA19-41F7-8528-EE7B00E4BB42%7D')
content-type: Application/Json
authorization: Bearer {access-token}
workbook-session-id: {session-id}
{ "height": 216.0, "left": 0, "name": "NewName", "top": 0, "width": 360.0 }
Réponse
HTTP code: 200 OK
content-type: application/json;odata.metadata
{
"@odata.context": "https://graph.microsoft.com/beta/$metadata#users('f6d92604-4b76-4b70-9a4c-93dfbcc054d5')/drive/items('01CYZLFJB6K563VVUU2ZC2FJBAHLSZZQXL')/workbook/worksheets('%7B00000000-0001-0000-0000-000000000000%7D')/charts/$entity",
"@odata.id": "/users('f6d92604-4b76-4b70-9a4c-93dfbcc054d5')/drive/items('01CYZLFJB6K563VVUU2ZC2FJBAHLSZZQXL')/workbook/worksheets(%27%7B00000000-0001-0000-0000-000000000000%7D%27)/charts(%27%7B2D421098-FA19-41F7-8528-EE7B00E4BB42%7D%27)",
"height": 216.0,
"id": "{2D421098-FA19-41F7-8528-EE7B00E4BB42}",
"left": 0.0,
"name": "NewName",
"top": 0.0,
"width": 360.0
}
Mettre à jour les données sources du graphique
Demande
POST https://graph.microsoft.com/beta/me/drive/items/01CYZLFJB6K563VVUU2ZC2FJBAHLSZZQXL/workbook/worksheets('%7B00000000-0001-0000-0000-000000000000%7D')/charts('%7B2D421098-FA19-41F7-8528-EE7B00E4BB42%7D')/setData
content-type: Application/Json
accept: application/Json
authorization: Bearer {access-token}
workbook-session-id: {session-id}
{ "sourceData": "A1:C4", "seriesBy": "Auto" }
Réponse
HTTP code: 204 No Content
Opérations de tableau
Obtenir la liste des tableaux
Demande
GET https://graph.microsoft.com/beta/me/drive/items/01CYZLFJB6K563VVUU2ZC2FJBAHLSZZQXL/workbook/worksheets('%7B00000000-0001-0000-0000-000000000000%7D')/tables
accept: Application/Json
authorization: Bearer {access-token}
workbook-session-id: {session-id}
Réponse
HTTP code: 200 OK
content-type: application/json;odata.metadata
Créer un tableau
Demande
POST https://graph.microsoft.com/beta/me/drive/items/01CYZLFJDYBLIGAE7G5FE3I4VO2XP7BLU4/workbook/tables/$/add
content-type: Application/Json
authorization: Bearer {access-token}
workbook-session-id: {session-id}
{ "name": "NewTableName", "hasHeaders": true, "showTotals": false, "style": "TableStyleMedium4" }
Réponse
HTTP code: 201 Created
content-type: application/json;odata.metadata
{
"@odata.context": "https://graph.microsoft.com/beta/$metadata#users('f6d92604-4b76-4b70-9a4c-93dfbcc054d5')/drive/items('01CYZLFJDYBLIGAE7G5FE3I4VO2XP7BLU4')/workbook/tables/$entity",
"@odata.id": "/users('f6d92604-4b76-4b70-9a4c-93dfbcc054d5')/drive/items('01CYZLFJDYBLIGAE7G5FE3I4VO2XP7BLU4')/workbook/tables(%272%27)",
"id": "2",
"name": "NewTableName",
"showHeaders": true,
"showTotals": false,
"style": "TableStyleMedium4"
}
Mettre à jour une table
Demande
PATCH https://graph.microsoft.com/beta/me/drive/items/01CYZLFJDYBLIGAE7G5FE3I4VO2XP7BLU4/workbook/tables('2')
content-type: Application/Json
authorization: Bearer {access-token}
workbook-session-id: {session-id}
{ "name": "NewTableName", "showHeaders": true, "showTotals": false, "style": "TableStyleMedium4" }
Réponse
HTTP code: 200 OK
content-type: application/json;odata.metadata
{
"@odata.context": "https://graph.microsoft.com/beta/$metadata#users('f6d92604-4b76-4b70-9a4c-93dfbcc054d5')/drive/items('01CYZLFJDYBLIGAE7G5FE3I4VO2XP7BLU4')/workbook/tables/$entity",
"@odata.id": "/users('f6d92604-4b76-4b70-9a4c-93dfbcc054d5')/drive/items('01CYZLFJDYBLIGAE7G5FE3I4VO2XP7BLU4')/workbook/tables(%272%27)",
"id": "2",
"name": "NewTableName",
"showHeaders": true,
"showTotals": false,
"style": "TableStyleMedium4"
}
Obtenir la liste des lignes de tableau
Demande
GET https://graph.microsoft.com/beta/me/drive/items/01CYZLFJDYBLIGAE7G5FE3I4VO2XP7BLU4/workbook/tables('4')/Rows
authorization: Bearer {access-token}
workbook-session-id: {session-id}
Réponse
HTTP code: 200 OK
content-type: application/json;odata.metadata
{
"@odata.context": "https://graph.microsoft.com/beta/$metadata#users('f6d92604-4b76-4b70-9a4c-93dfbcc054d5')/drive/items('01CYZLFJDYBLIGAE7G5FE3I4VO2XP7BLU4')/workbook/tables('4')/rows",
"value": [
{
"@odata.id": "/users('f6d92604-4b76-4b70-9a4c-93dfbcc054d5')/drive/items('01CYZLFJDYBLIGAE7G5FE3I4VO2XP7BLU4')/workbook/tables(%274%27)/rows/itemAt(0)",
"index": 0,
"values": [
[
42019,
53,
34
]
]
},
{
"@odata.id": "/users('f6d92604-4b76-4b70-9a4c-93dfbcc054d5')/drive/items('01CYZLFJDYBLIGAE7G5FE3I4VO2XP7BLU4')/workbook/tables(%274%27)/rows/itemAt(1)",
"index": 1,
"values": [
[
42020,
45,
39
]
]
},
{
"@odata.id": "/users('f6d92604-4b76-4b70-9a4c-93dfbcc054d5')/drive/items('01CYZLFJDYBLIGAE7G5FE3I4VO2XP7BLU4')/workbook/tables(%274%27)/rows/itemAt(2)",
"index": 2,
"values": [
[
42021,
50,
31
]
]
},
{
"@odata.id": "/users('f6d92604-4b76-4b70-9a4c-93dfbcc054d5')/drive/items('01CYZLFJDYBLIGAE7G5FE3I4VO2XP7BLU4')/workbook/tables(%274%27)/rows/itemAt(3)",
"index": 3,
"values": [
[
42022,
43,
39
]
]
},
{
"@odata.id": "/users('f6d92604-4b76-4b70-9a4c-93dfbcc054d5')/drive/items('01CYZLFJDYBLIGAE7G5FE3I4VO2XP7BLU4')/workbook/tables(%274%27)/rows/itemAt(4)",
"index": 4,
"values": [
[
42023,
45,
41
]
]
},
{
"@odata.id": "/users('f6d92604-4b76-4b70-9a4c-93dfbcc054d5')/drive/items('01CYZLFJDYBLIGAE7G5FE3I4VO2XP7BLU4')/workbook/tables(%274%27)/rows/itemAt(5)",
"index": 5,
"values": [
[
42024,
52,
40
]
]
}
]
}
Obtenir la liste des colonnes de tableau
Demande
GET https://graph.microsoft.com/beta/me/drive/items/01CYZLFJDYBLIGAE7G5FE3I4VO2XP7BLU4/workbook/tables('4')/Columns
authorization: Bearer {access-token}
workbook-session-id: {session-id}
Réponse
HTTP code: 200 OK
content-type: application/json;odata.metadata
{
"@odata.context": "https://graph.microsoft.com/beta/$metadata#users('f6d92604-4b76-4b70-9a4c-93dfbcc054d5')/drive/items('01CYZLFJDYBLIGAE7G5FE3I4VO2XP7BLU4')/workbook/tables('4')/columns",
"value": [
{
"@odata.id": "/users('f6d92604-4b76-4b70-9a4c-93dfbcc054d5')/drive/items('01CYZLFJDYBLIGAE7G5FE3I4VO2XP7BLU4')/workbook/tables(%274%27)/columns(%271%27)",
"id": "1",
"index": 0,
"name": "Date",
"values": [
[
"Date"
],
[
42019
],
[
42020
],
[
42021
],
[
42022
],
[
42023
],
[
42024
]
]
},
{
"@odata.id": "/users('f6d92604-4b76-4b70-9a4c-93dfbcc054d5')/drive/items('01CYZLFJDYBLIGAE7G5FE3I4VO2XP7BLU4')/workbook/tables(%274%27)/columns(%272%27)",
"id": "2",
"index": 1,
"name": "High (F)",
"values": [
[
"High (F)"
],
[
53
],
[
45
],
[
50
],
[
43
],
[
45
],
[
52
]
]
},
{
"@odata.id": "/users('f6d92604-4b76-4b70-9a4c-93dfbcc054d5')/drive/items('01CYZLFJDYBLIGAE7G5FE3I4VO2XP7BLU4')/workbook/tables(%274%27)/columns(%273%27)",
"id": "3",
"index": 2,
"name": "Low (F)",
"values": [
[
"Low (F)"
],
[
34
],
[
39
],
[
31
],
[
39
],
[
41
],
[
40
]
]
}
]
}
Ajouter une ligne de tableau
Demande
POST https://graph.microsoft.com/beta/me/drive/items/01CYZLFJDYBLIGAE7G5FE3I4VO2XP7BLU4/workbook/tables('4')/Rows
content-type: Application/Json
authorization: Bearer {access-token}
workbook-session-id: {session-id}
{ "values": [ [ "Jan-15-2016", "49", "37" ] ], "index": null }
Réponse
HTTP code: 201 Created
content-type: application/json;odata.metadata
{
"@odata.context": "https://graph.microsoft.com/beta/$metadata#users('f6d92604-4b76-4b70-9a4c-93dfbcc054d5')/drive/items('01CYZLFJDYBLIGAE7G5FE3I4VO2XP7BLU4')/workbook/tables('4')/rows/$entity",
"@odata.id": "/users('f6d92604-4b76-4b70-9a4c-93dfbcc054d5')/drive/items('01CYZLFJDYBLIGAE7G5FE3I4VO2XP7BLU4')/workbook/tables(%274%27)/rows(null)",
"index": 6,
"values": [
[
"Jan-15-2016",
49,
37
]
]
}
Ajouter une colonne de tableau
Demande
POST https://graph.microsoft.com/beta/me/drive/items/01CYZLFJDYBLIGAE7G5FE3I4VO2XP7BLU4/workbook/tables('2')/Columns
content-type: Application/Json
accept: application/Json
{ "values": [ [ "Status" ], [ "Open" ], [ "Closed" ] ], "index": 2 }
Réponse
HTTP code: 201 Created
content-type: application/json;odata.metadata
{
"@odata.context": "https://graph.microsoft.com/beta/$metadata#users('f6d92604-4b76-4b70-9a4c-93dfbcc054d5')/drive/items('01CYZLFJDYBLIGAE7G5FE3I4VO2XP7BLU4')/workbook/tables('2')/columns/$entity",
"@odata.id": "/users('f6d92604-4b76-4b70-9a4c-93dfbcc054d5')/drive/items('01CYZLFJDYBLIGAE7G5FE3I4VO2XP7BLU4')/workbook/tables(%272%27)/columns(%274%27)",
"id": "4",
"index": 2,
"name": "Status",
"values": [
[
"Status"
],
[
"Open"
],
[
"Closed"
]
]
}
Supprimer une ligne de tableau
Demande
DELETE https://graph.microsoft.com/beta/me/drive/items/01CYZLFJDYBLIGAE7G5FE3I4VO2XP7BLU4/workbook/tables('4')/Rows/$/ItemAt(index=6)
authorization: Bearer {access-token}
workbook-session-id: {session-id}
Réponse
HTTP code: 204 No Content
Supprimer une colonne de tableau
Demande
DELETE https://graph.microsoft.com/beta/me/drive/items/01CYZLFJDYBLIGAE7G5FE3I4VO2XP7BLU4/workbook/tables('4')/Columns('3')
authorization: Bearer {access-token}
workbook-session-id: {session-id}
Réponse
HTTP code: 204 No Content
Convertir le tableau en plage
Demande
POST https://graph.microsoft.com/beta/me/drive/items/01CYZLFJDYBLIGAE7G5FE3I4VO2XP7BLU4/workbook/tables('1')/convertToRange
authorization: Bearer {access-token}
workbook-session-id: {session-id}
Réponse
HTTP code: 200 OK
content-type: application/json;odata.metadata
Trier le tableau
Demande
POST https://graph.microsoft.com/beta/me/drive/items/01CYZLFJGUJ7JHBSZDFZFL25KSZGQTVAUN/workbook/worksheets('Sheet15799')/tables('table2')/sort/apply
authorization: Bearer {access-token}
workbook-session-id: {session-id}
{
"fields" : [
{ "key": 0,
"ascending": true
}
]
}
Réponse
HTTP code: 204 No Content
Filtrer le tableau
Demande
POST https://graph.microsoft.com/beta/me/drive/items/01CYZLFJGUJ7JHBSZDFZFL25KSZGQTVAUN/workbook/worksheets('Sheet15799')/tables('table2')/columns(id='2')/filter/apply
authorization: Bearer {access-token}
workbook-session-id: {session-id}
{
"criteria" :
{ "filterOn": "custom",
"criterion1": ">15",
"operator": "and",
"criterion2": "<50"
}
}
Réponse
HTTP code: 204 No Content
Effacer le filtre
Demande
POST https://graph.microsoft.com/beta/me/drive/items/01CYZLFJGUJ7JHBSZDFZFL25KSZGQTVAUN/workbook/worksheets('Sheet15799')/tables('table2')/columns(id='2')/filter/clear
authorization: Bearer {access-token}
workbook-session-id: {session-id}
Réponse
HTTP code: 204 No Content
Opérations de plage
Obtenir une plage
Demande
GET https://graph.microsoft.com/beta/me/drive/items/01CYZLFJDYBLIGAE7G5FE3I4VO2XP7BLU4/workbook/worksheets('test')/range(address='A1:B2')
authorization: Bearer {access-token}
workbook-session-id: {session-id}
Réponse
HTTP code: 200 OK
content-type: application/json;odata.metadata
{
"@odata.context": "https://graph.microsoft.com/beta/$metadata#range",
"@odata.type": "#microsoft.graph.workbookRange",
"@odata.id": "/users('f6d92604-4b76-4b70-9a4c-93dfbcc054d5')/drive/items('01CYZLFJDYBLIGAE7G5FE3I4VO2XP7BLU4')/workbook/worksheets(%27%7B00000000-0001-0000-0300-000000000000%7D%27)/range(address=%27A1:B2%27)",
"address": "test!A1:B2",
"addressLocal": "test!A1:B2",
"cellCount": 4,
"columnCount": 2,
"columnHidden": false,
"columnIndex": 0,
"formulas": [
[
"",
""
],
[
"",
""
]
],
"formulasLocal": [
[
"",
""
],
[
"",
""
]
],
"formulasR1C1": [
[
"",
""
],
[
"",
""
]
],
"hidden": false,
"numberFormat": [
[
"General",
"General"
],
[
"General",
"General"
]
],
"rowCount": 2,
"rowHidden": false,
"rowIndex": 0,
"text": [
[
"",
""
],
[
"",
""
]
],
"values": [
[
"",
""
],
[
"",
""
]
],
"valueTypes": [
[
"Empty",
"Empty"
],
[
"Empty",
"Empty"
]
]
}
Mettre à jour la plage
PATCH https://graph.microsoft.com/beta/me/drive/items/01CYZLFJDYBLIGAE7G5FE3I4VO2XP7BLU4/workbook/worksheets('test')/range(address='test!A1:B2')
authorization: Bearer {access-token}
workbook-session-id: {session-id}
{ "values": [ [ "Test", "Value" ], [ "For", "Update" ] ] }
HTTP code: 200 OK
content-type: application/json;odata.metadata
{
"@odata.context": "https://graph.microsoft.com/beta/$metadata#range",
"@odata.type": "#microsoft.graph.workbookRange",
"@odata.id": "/users('f6d92604-4b76-4b70-9a4c-93dfbcc054d5')/drive/items('01CYZLFJDYBLIGAE7G5FE3I4VO2XP7BLU4')/workbook/worksheets(%27%7B00000000-0001-0000-0300-000000000000%7D%27)/range(address=%27test!A1:B2%27)",
"address": "test!A1:B2",
"addressLocal": "test!A1:B2",
"cellCount": 4,
"columnCount": 2,
"columnHidden": false,
"columnIndex": 0,
"formulas": [
[
"Test",
"Value"
],
[
"For",
"Update"
]
],
"formulasLocal": [
[
"Test",
"Value"
],
[
"For",
"Update"
]
],
"formulasR1C1": [
[
"Test",
"Value"
],
[
"For",
"Update"
]
],
"hidden": false,
"numberFormat": [
[
"General",
"General"
],
[
"General",
"General"
]
],
"rowCount": 2,
"rowHidden": false,
"rowIndex": 0,
"text": [
[
"Test",
"Value"
],
[
"For",
"Update"
]
],
"values": [
[
"Test",
"Value"
],
[
"For",
"Update"
]
],
"valueTypes": [
[
"String",
"String"
],
[
"String",
"String"
]
]
}
Trier la plage
Demande
POST https://graph.microsoft.com/beta/me/drive/items/01CYZLFJGUJ7JHBSZDFZFL25KSZGQTVAUN/workbook/worksheets('Sheet15799')/usedRange/sort/apply
authorization: Bearer {access-token}
workbook-session-id: {session-id}
{
"fields" : [
{ "key": 0,
"ascending": true
}
]
}
Réponse
HTTP code: 204 No Content
Éléments nommés
Demande
GET https://graph.microsoft.com/beta/me/drive/items/01CYZLFJDYBLIGAE7G5FE3I4VO2XP7BLU4/workbook/names
authorization: Bearer {access-token}
workbook-session-id: {session-id}
Réponse
HTTP code: 200 OK
content-type: application/json
{
"@odata.context": "https://graph.microsoft.com/beta/$metadata#users('f6d92604-4b76-4b70-9a4c-93dfbcc054d5')/drive/items('01CYZLFJDYBLIGAE7G5FE3I4VO2XP7BLU4')/workbook/names",
"value": [
{
"@odata.id": "/users('f6d92604-4b76-4b70-9a4c-93dfbcc054d5')/drive/items('01CYZLFJDYBLIGAE7G5FE3I4VO2XP7BLU4')/workbook/names(%27data%27)",
"name": "data",
"type": "Range",
"value": "Range!$A$1:$D$3",
"visible": true
},
{
"@odata.id": "/users('f6d92604-4b76-4b70-9a4c-93dfbcc054d5')/drive/items('01CYZLFJDYBLIGAE7G5FE3I4VO2XP7BLU4')/workbook/names(%27myrange%27)",
"name": "myrange",
"type": "Range",
"value": "Range!$E$1:$F$7",
"visible": true
},
{
"@odata.id": "/users('f6d92604-4b76-4b70-9a4c-93dfbcc054d5')/drive/items('01CYZLFJDYBLIGAE7G5FE3I4VO2XP7BLU4')/workbook/names(%27range1%27)",
"name": "range1",
"type": "Range",
"value": "Range!$I$1:$M$11",
"visible": true
}
]
}
Utilisation de valeurs null
Entrée de valeurs null dans un tableau 2D
L’entrée de valeurs null dans un tableau à deux dimensions (pour des valeurs, des formats de nombre ou des formules) est ignorée dans les ressources Plage et Tableau. Aucune mise à jour n’a lieu vers la cible (cellule) prévue lorsque null l’entrée est envoyée dans des valeurs, un format de nombre ou une grille de formule de valeurs.
Par exemple, pour mettre à jour uniquement des parties spécifiques de la plage, par exemple le format de nombre d’une cellule, tout en conservant le format de nombre existant pour d’autres parties de la plage, indiquez le format de nombre là où un changement est nécessaire et envoyez null pour les autres cellules.
Dans la demande définie suivante, seules certaines parties du format de nombre de la plage sont définies et le format de nombre existant est conservé sur la partie restante (en indiquant des valeurs null).
{
"values" : [["Eurasia", "29.96", "0.25", "15-Feb" ]],
"numberFormat" : [[null, null, null, "m/d/yyyy;@"]]
}
Entrée null pour une propriété
null n’est pas une entrée unique valide pour la propriété entière. Par exemple, les éléments suivants ne sont pas valides, car les valeurs entières ne peuvent pas être définies sur null ou ignorées.
{
"values": null
}
Ce qui suit n’est pas valide non plus, car null n’est pas une valeur de couleur valide.
{
"color" : null
}
Réponse null
La représentation des propriétés de mise en forme qui se compose de valeurs non uniformes entraîne le retour d’une valeur Null dans la réponse.
Par exemple, une plage peut se composer d’une ou plusieurs cellules. Dans les cas où les cellules individuelles contenues dans la plage spécifiée n’ont pas de valeurs de mise en forme uniformes, la représentation au niveau de la plage n’est pas définie.
{
"size: : null,
"color" : null
}
Une valeur null est également renvoyée dans la réponse dans les cas suivants :
- Si une erreur se produit lorsque vous essayez d’obtenir une propriété spécifique d’un objet et que cette propriété peut être déterminée comme null, la propriété peut renvoyer la valeur null dans la réponse.
- Pour un objet de plage, lorsque vous obtenez une plage pour la totalité d’une ligne ou d’une colonne, certaines propriétés peuvent renvoyer la valeur null comme réponse. Si la taille de la plage dépasse la limite supérieure (5M de cellules), certaines propriétés retournent null comme valeur.
Entrées et sorties vides
Les valeurs vides dans les demandes de mise à jour sont traitées comme une instruction visant à effacer ou à restaurer la valeur de la propriété concernée. Une valeur vide est représentée par des guillemets droits non séparés par un espace : ""
Exemples :
pour
values, la valeur de plage est effacée. Cela revient à supprimer du contenu dans l’application.Pour
numberFormat, le format de nombre est défini surGeneral.Pour
formulaetformulaLocale, les valeurs de formule sont effacées.
Pour les opérations de lecture, il est normal d’obtenir des valeurs vides si les cellules le sont également. Si la cellule ne contient aucune donnée ou valeur, l’API renvoie une valeur vide. Une valeur vide est représentée par des guillemets droits non séparés par un espace : ""
{
"values" : [["", "some", "data", "in", "other", "cells", ""]]
}
{
"formula" : [["", "", "=Rand()"]]
}
Plage illimitée
Lecture
Une adresse de plage illimitée ne contient que des identificateurs de ligne ou de colonne, ainsi que des identificateurs de lignes ou de colonnes non spécifiées (respectivement), comme dans l’exemple ci-dessous :
C:C,A:F,A:XFD(contient des lignes non spécifiées)2:2,1:4,1:1048546(contient des colonnes non spécifiées)
Lorsque l’API effectue une demande pour récupérer une plage illimitée (getRange('C:C')), la réponse renvoyée contient null pour les propriétés définies au niveau des cellules, telles que values, text, numberFormat ou formula. D’autres propriétés de plage, telles que address ou cellCount refléteront la plage illimitée.
Écriture
Vous n’êtes pas autorisé à définir des propriétés de niveau cellule (par exemple, values, numberFormat, etc.) sur une plage illimitée, car la demande d’entrée risque d’être trop lourde à gérer.
Par exemple, ce qui suit n’est pas une demande de mise à jour valide, car la plage demandée est illimitée.
PATCH /me/drive/root/workbook/worksheets('Sheet1')/range(address="A:B")
{
"values" : "Due Date"
}
Lorsqu’une opération de mise à jour est tentée sur une plage de ce type, l’API retourne une erreur.
Plage de grande taille
Une plage de grande taille est une plage trop grande pour pouvoir être gérée par un seul appel à l’API. De nombreux facteurs tels que le nombre de cellules, les valeurs, le format de nombre et les formules contenues dans la plage peuvent entraîner une réponse trop lourde pour l’interaction avec l’API. L’API tente de renvoyer ou d’écrire les données requises en faisant au mieux de ses possibilités. Toutefois, la taille importante de la réponse peut provoquer une erreur de l’API à cause de la grande quantité de ressources mobilisées.
Pour éviter cela, nous vous recommandons de fractionner les plages de grande taille en plusieurs plages plus petites pour vos opérations de lecture et d’écriture.
Copie d’une seule entrée
Pour mettre à jour une plage contenant des formats de nombre ou des valeurs uniformes, ou pour appliquer une même formule à l’ensemble d’une plage, la convention suivante est utilisée dans l’API définie. Dans Excel, cela revient à attribuer des valeurs ou des formules à une plage en mode CTRL + ENTRÉE.
L’API recherche une seule valeur de cellule et, si la dimension de plage cible ne correspond pas à la dimension de plage d’entrée, elle applique la mise à jour à l’ensemble de la plage dans le modèle CTRL+Entrée avec la valeur ou la formule fournie dans la requête.
Exemples
La demande suivante met à jour la plage sélectionnée en y ajoutant le texte « Sample text ». Dans la requête, la plage comporte 200 cellules, tandis que l’entrée fournie n’a qu’une seule valeur de cellule.
PATCH /me/drive/root/workbook/worksheets('Sheet1')/range(address="A1:B100")
{
"values" : "Sample text"
}
Fonctions du classeur
Vous pouvez accéder aux fonctions du classeur via un ensemble de fonctions comprises dans la ressource /Functions.
Demande
https://graph.microsoft.com/beta/me/drive/root:/book1.xlsx:/workbook/functions/pmt
content-type: Application/Json
authorization: Bearer {access-token}
workbook-session-id: {session-id}
{
"rate": 4.5,
"nper": 12,
"pv": -1250
}
Réponse
HTTP code: 200 OK
content-type: application/json
{
"@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/pmt()",
"error": null,
"value": 5625.00000734125
}
Informations relatives aux erreurs
Les erreurs sont renvoyées avec un code d’erreur HTTP et un objet d’erreur. Les valeurs code et message d’une erreur en expliquent la nature.
Voici un exemple.
HTTP/1.1 400 Bad Request
Content-Type: application/json
{
"error": {
"code": "ItemAlreadyExists",
"message": "A resource with the same name or identifier already exists.",
"innerError": {
"request-id": "214ca7ea-9ea4-442e-9c67-71fdda0a559c",
"date": "2016-07-28T03:56:09"
}
}
}
Commentaires
Bientôt disponible : Tout au long de 2024, nous allons supprimer progressivement GitHub Issues comme mécanisme de commentaires pour le contenu et le remplacer par un nouveau système de commentaires. Pour plus d’informations, consultez https://aka.ms/ContentUserFeedback.
Envoyer et afficher des commentaires pour