Travailler avec Excel dans Microsoft Graph

Article
03/20/2024

Vous pouvez utiliser Microsoft Graph pour autoriser les applications web et mobiles à lire et à modifier des classeurs Excel stockés dans OneDrive Entreprise, un site SharePoint ou un lecteur de groupe. 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/v1.0/me/drive/items/{id}/workbook/
https://graph.microsoft.com/v1.0/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, GET https://graph.microsoft.com/v1.0/me/drive/items/{id}/workbook/worksheets
renvoie une collection d’objets de feuille de calcul qui font partie du classeur.

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.

Remarque : la prise en charge des classeurs stockés sur la plateforme client OneDrive n’est toujours pas disponible. À ce stade, seuls les fichiers stockés dans la plateforme métier sont pris en charge par les API REST Excel.

Autorisation et étendues

Vous pouvez utiliser la Plateforme d'identités Microsoft 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 (pour les actions de lecture)
Files.ReadWrite (pour les actions de lecture et d’écriture)

Sessions et persistance

Les API Excel peuvent être appelées dans l’un des trois modes suivants :

Session permanente : toutes les modifications apportées au classeur sont conservées (enregistrées). Il s’agit du mode de fonctionnement le plus efficace et le plus performant.
Session non persistante : les modifications apportées par l’API ne sont pas enregistrées dans 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.
Sans session : l’appel à l’API est effectué sans informations de session. Les serveurs Excel doivent localiser la copie du classeur du serveur à chaque fois pour effectuer l’opération. Par conséquent, il ne s’agit pas d’un moyen efficace d’appeler des API Excel. Il convient pour effectuer des demandes ponctuelles.

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/v1.0/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/v1.0/$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/v1.0/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 404 est 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/v1.0/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/v1.0/$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

Obtenez une feuille de calcul en fonction du nom.

GET https://graph.microsoft.com/v1.0/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/v1.0/$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/v1.0/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/v1.0/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/v1.0/$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/v1.0/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/v1.0/$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/v1.0/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/v1.0/$metadata#Edm.String",
  "value": "{base-64-string}"
}

Ajouter un graphique

Demande

POST https://graph.microsoft.com/v1.0/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/v1.0/$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/v1.0/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/v1.0/$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/v1.0/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/v1.0/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/v1.0/me/drive/items/01CYZLFJDYBLIGAE7G5FE3I4VO2XP7BLU4/workbook/tables/{table-id}/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/v1.0/$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/v1.0/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/v1.0/$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/v1.0/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/v1.0/$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/v1.0/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/v1.0/$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/v1.0/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/v1.0/$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/v1.0/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/v1.0/$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/v1.0/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/v1.0/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/v1.0/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/v1.0/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/v1.0/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/v1.0/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/v1.0/me/drive/items/{item-id}/workbook/worksheets/{worksheet-id}/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/v1.0/$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/v1.0/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/v1.0/$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/v1.0/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/v1.0/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/v1.0/$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
}

Ici n’est pas valide non plus, car null n’est pas une valeur de couleur valide.

{
"color" :  null
}

Réponse null

La représentation de propriétés de mise en forme composées de valeurs non uniformes renvoie une valeur null comme 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 sur General.
Pour formula et formulaLocale, 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/{id}/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 ». La plage a 200 cellules, tandis que l’entrée fournie n’a qu’une seule valeur de cellule.

PATCH /me/drive/root/workbook/worksheets/{id}/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/v1.0/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/v1.0/$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"
    }
  }
}

Partager via

Travailler avec Excel dans Microsoft Graph

Autorisation et étendues

Sessions et persistance

Obtention d’une session via l’appel d’une API

Demande

Réponse

Utilisation

Scénarios Excel courants

Opérations de feuille de calcul

Répertorier les feuilles de calcul du classeur

Ajouter une nouvelle feuille de calcul

Obtenir une nouvelle feuille de calcul

Supprimer une feuille de calcul

Mettre à jour les propriétés de la feuille de calcul

Opérations de graphique

Répertorier les graphiques qui font partie de la feuille de calcul

Obtenir une image de graphique

Ajouter un graphique

Mettre à jour un graphique

Mettre à jour les données sources du graphique

Opérations de tableau

Obtenir la liste des tableaux

Créer un tableau

Mettre à jour une table

Obtenir la liste des lignes de tableau

Obtenir la liste des colonnes de tableau

Ajouter une ligne de tableau

Ajouter une colonne de tableau

Supprimer une ligne de tableau

Supprimer une colonne de tableau

Convertir le tableau en plage

Trier le tableau

Filtrer le tableau

Effacer le filtre

Opérations de plage

Obtenir une plage

Mettre à jour la plage

Trier la plage

Éléments nommés

Utilisation de valeurs null

Entrée de valeurs null dans un tableau 2D

Entrée null pour une propriété

Réponse null

Entrées et sorties vides

Plage illimitée

Lecture

Écriture

Plage de grande taille

Copie d’une seule entrée

Exemples

Fonctions du classeur

Demande

Réponse

Informations relatives aux erreurs

Commentaires

Ressources supplémentaires