Bewährte Methoden für das Arbeiten mit der Excel-API

  • Artikel

Dieser Artikel enthält Empfehlungen für die Arbeit mit den Excel-APIs in Microsoft Graph.

Verwalten von Sitzungen auf die effizienteste Weise

Wenn Innerhalb eines bestimmten Zeitraums mehrere Aufrufe ausgeführt werden müssen, empfiehlt es sich, eine Sitzung zu erstellen und die Sitzungs-ID bei jeder Anforderung zu übergeben. Um die Sitzung in der API darzustellen, verwenden Sie den workbook-session-id: {session-id}-Header. Auf diese Weise können Sie die Excel-APIs auf die effizienteste Weise verwenden.

Im folgenden Beispiel wird gezeigt, wie Sie mit diesem Ansatz einer Tabelle eine neue Zahl hinzufügen und dann einen Datensatz in einer Arbeitsmappe suchen.

Schritt 1: Erstellen einer Sitzung

Anforderung

POST https://graph.microsoft.com/v1.0/me/drive/items/{id}/workbook/createSession
Content-type: application/json

{
  "persistChanges": true
}

Antwort

Im Folgenden wird eine erfolgreiche Antwort angezeigt.

HTTP/1.1 201 Created
Content-type: application/json

{
  "id": "id-value",
  "persistChanges": true
}

Schritt 2: Hinzufügen einer neuen Zeile zur Tabelle

Anforderung

POST https://graph.microsoft.com/v1.0/me/drive/items/{id}/workbook/tables/{id|name}/rows/add
Content-type: application/json
workbook-session-id: {session-id}

{
  "values": [[“east”, “pear”, 4]]
}

Antwort

HTTP/1.1 200 OK
Content-type: application/json

{
  "index": 6,
  "values": [[“east”, “pear”, 4]]
}

Schritt 3: Suchen eines Werts in der aktualisierten Tabelle

Anforderung

POST https://graph.microsoft.com/v1.0/me/drive/items/{id}/workbook/functions/vlookup
Content-type: application/json
workbook-session-id: {session-id}

{
    "lookupValue":"pear",
    "tableArray":{"Address":"Sheet1!B2:C7"},
    "colIndexNum":2,
    "rangeLookup":false
}

Antwort

HTTP code: 200 OK
content-type: application/json

{
    "value": 5
}

Schritt 4: Schließen der Sitzung, nachdem alle Anforderungen abgeschlossen wurden

Anforderung

POST https://graph.microsoft.com/v1.0/me/drive/items/{id}/workbook/closeSession
Content-type: application/json
workbook-session-id: {session-id}

{
}

Antwort

HTTP/1.1 204 No Content

Weitere Informationen finden Sie unter Erstellen einer Sitzung und Schließen der Sitzung.

Arbeiten mit APIs, deren Ausführung sehr lange dauert

Möglicherweise stellen Sie fest, dass einige Vorgänge unbestimmte Zeit in Anspruch nehmen. z. B. das Öffnen einer großen Arbeitsmappe. Es ist einfach, ein Timeout zu erreichen, während auf die Antwort auf diese Anforderungen gewartet wird. Um dieses Problem zu beheben, stellen wir das Zeitintensive Vorgangsmuster bereit. Wenn Sie dieses Muster verwenden, müssen Sie sich keine Gedanken über das Timeout für die Anforderung machen.

Derzeit ist für die Excel-API für die Sitzungserstellung in Microsoft Graph das Zeitintensive Vorgangsmuster aktiviert. Dieses Muster umfasst die folgenden Schritte:

  1. Fügen Sie der Anforderung einen Prefer: respond-async Header hinzu, um anzugeben, dass es sich um einen Zeitintensiven Vorgang handelt, wenn Sie eine Sitzung erstellen.
  2. Ein zeitintensiver Vorgang gibt eine 202 Accepted Antwort zusammen mit einem Location-Header zurück, um den Vorgang status abzurufen. Wenn die Sitzungserstellung in einigen Sekunden abgeschlossen ist, wird eine reguläre Sitzungsantwort für die Erstellung zurückgegeben, anstatt das Muster für einen zeitintensiven Vorgang zu verwenden.
  3. Mit der 202 Accepted Antwort können Sie den Vorgang status an der angegebenen Position abrufen. Zu den status Werten gehören notStarted, running, succeededund failed.
  4. Nach Abschluss des Vorgangs können Sie das Sitzungserstellungsergebnis über die angegebene URL in der erfolgreichen Antwort abrufen.

Im folgenden Beispiel wird eine Sitzung mit dem Zeitintensiven Vorgangsmuster erstellt.

Anfängliche Anforderung zum Erstellen einer Sitzung

Anforderung

POST https://graph.microsoft.com/v1.0/me/drive/items/{drive-item-id}/workbook/createSession
Prefer: respond-async
Content-type: application/json
{
    "persistChanges": true
}

Antwort

Das Muster für zeitintensive Vorgänge gibt eine 202 Accepted Antwort zurück, die der folgenden ähnelt.

HTTP/1.1 202 Accepted
Location: https://graph.microsoft.com/v1.0/me/drive/items/{drive-item-id}/workbook/operations/{operation-id}
Content-type: application/json

{
}

In einigen Fällen wird die Erstellung, wenn die Erstellung innerhalb von Sekunden erfolgreich ist, nicht in das Muster für zeitintensive Vorgänge übergehen. stattdessen wird als reguläre Erstellungssitzung zurückgegeben, und die erfolgreiche Anforderung gibt eine 201 Created Antwort zurück.

HTTP/1.1 201 Created
Content-type: application/json

{
  "id": "id-value",
  "persistChanges": true
}

Das folgende Beispiel zeigt die Antwort, wenn die Anforderung fehlschlägt.

Hinweis: Das hier gezeigte Antwortobjekt kann zur besseren Lesbarkeit gekürzt werden.

HTTP/1.1 500 Internal Server Error
Content-type: application/json

{
  "error":{
    "code": "internalServerError",
    "message": "An internal server error occurred while processing the request.",
    "innerError": {
      "code": "internalServerErrorUncategorized",
      "message": "An unspecified error has occurred.",
      "innerError": {
        "code": "GenericFileOpenError",
        "message": "The workbook cannot be opened."
      }
    }
  }
}

Abfragen status der Erstellungssitzung mit langer Ausführungszeit

Mit dem Zeitintensiven Vorgangsmuster können Sie die Erstellung status am angegebenen Speicherort mithilfe der folgenden Anforderung abrufen. Das empfohlene Intervall zum Abfragen status beträgt etwa 30 Sekunden. Das maximale Intervall sollte nicht mehr als 4 Minuten betragen.

Anforderung

GET https://graph.microsoft.com/v1.0/me/drive/items/{drive-item-id}/workbook/operations/{operation-id}
{
}

Antwort

Im Folgenden wird die Antwort angezeigt, wenn der Vorgang über den status verfügtrunning.

HTTP/1.1 200 OK
Content-type: application/json

{
    "id": {operation-id},
    "status": "running"
}

Im Folgenden wird die Antwort angezeigt, wenn der Vorgang status istsucceeded.

HTTP/1.1 200 OK
Content-type: application/json

{
    "id": {operation-id},
    "status": "succeeded",
    "resourceLocation": "https://graph.microsoft.com/v1.0/me/drive/items/{drive-item-id}/workbook/sessionInfoResource(key='{key}')
}

Im Folgenden wird die Antwort angezeigt, wenn der Vorgang status istfailed.

HTTP/1.1 200 OK
Content-type: application/json

{
  "id": {operation-id},
  "status": "failed",
  "error":{
    "code": "internalServerError",
    "message": "An internal server error occurred while processing the request.",
    "innerError": {
      "code": ""internalServerErrorUncategorized",
      "message": "An unspecified error has occurred.",
      "innerError": {
        "code": "GenericFileOpenError",
        "message": "The workbook cannot be opened."
      }
    }
  }
}

Weitere Informationen zu Fehlern finden Sie unter Fehlercodes und -meldungen.

Abrufen von Sitzungsinformationen

Anforderung

Mit dem status können succeededSie die erstellten Sitzungsinformationen resourceLocation mit einer Anforderung wie der folgenden abrufen.

GET https://graph.microsoft.com/v1.0/me/drive/items/{drive-item-id}/workbook/sessionInfoResource(key='{key}')
{
}

Antwort

Im Folgenden finden Sie die Antwort.

HTTP/1.1 200 OK
Content-type: application/json

{
    "id": "id-value",
    "persistChanges": true
}

Hinweis

Das Abrufen von Sitzungsinformationen hängt von der ursprünglichen Anforderung ab. Sie müssen das Ergebnis nicht abrufen, wenn die ursprüngliche Anforderung keinen Antworttext zurückgibt.

Reduzieren von Drosselungsfehlern

Excel-APIs in Microsoft Graph wirken sich auf die Ressourcennutzung mehrerer Abhängigkeitsdienste aus. Die Auswirkungen können zwischen verschiedenen Anforderungen variieren: Sie können beispielsweise erwarten, dass das Aktualisieren einer kurzen Zeichenfolge in einer einzelnen Zelle einer kleinen Arbeitsmappe weniger Ressourcen beansprucht als das Hinzufügen einer großen Tabelle mit komplexen Formeln zu einer großen Arbeitsmappe.

Selbst mit der gleichen API können Parameter und Zielarbeitsmappen erhebliche Unterschiede mit sich bringen. Daher ist die Drosselung der Excel-API nicht mit einfachen und universellen Grenzwertnummern definiert, da sie zu restriktiveren Grenzwerten führen würden. Die folgenden bewährten Methoden helfen Ihnen, Aufgaben schneller mit weniger Drosselungsfehlern abzuschließen.

Retry-After-Header

In vielen Fällen enthält eine Drosselungsantwort einen Retry-After -Header. Das Respektieren des Werts des Headers und das Verzögern ähnlicher Anforderungen würde dem Client helfen, die Drosselung wiederherzustellen. Ausführliche Informationen zur Behandlung von Fehlerantworten von Excel-APIs in Microsoft Graph finden Sie unter Fehlerbehandlung für Excel-APIs in Microsoft Graph.

Drosselung und Parallelität

Ein weiterer Faktor im Zusammenhang mit der Drosselung ist die Anforderungsparallelität. Es wird nicht empfohlen, die Parallelität zu erhöhen, wenn Sie Excel-APIs verwenden (z. B. die Parallelisierung der Anforderungen mit derselben Arbeitsmappe), insbesondere für Schreibanforderungen. Es sei denn, es besteht ein spezifisches Problem, z. B. ein erheblicher Netzwerkaufwand im Vergleich zur sehr kurzen Anforderungsausführungszeit, wird im häufigsten Fall die sequenzielle Verwendung empfohlen: Senden Sie für jede Arbeitsmappe nur die nächste Anforderung, nachdem sie eine erfolgreiche Antwort auf die aktuelle Anforderung erhalten hat.

Gleichzeitige Schreibanforderungen an dieselbe Arbeitsmappe werden in der Regel nicht parallel ausgeführt (in einigen Fällen auch). Stattdessen sind sie häufig die Ursache für Drosselung, Timeout (wenn Anforderungen auf Servern in die Warteschlange gestellt werden), Mergekonflikte (wenn gleichzeitige Sitzungen beteiligt sind) und andere Arten von Fehlern. Außerdem erschweren sie die Fehlerbehandlung. Wenn Sie beispielsweise eine Fehlerantwort erhalten, gibt es keine Möglichkeit, die status anderer ausstehender Anforderungen zu bestätigen, sodass es schwierig ist, den Zustand der Arbeitsmappe zu bestimmen oder wiederherzustellen.

Verwandte Inhalte