Arbeiten mit APIs, deren Abschluss eine lange Zeit dauern können
Einige Szenarien wie Kopieren oder Hochladen von URL können nicht immer innerhalb eines begrenzten Zeitraums abgeschlossen werden. Um diese Szenarien zu verarbeiten und die API-Antwortwartezeit niedrig zu halten, werden diese Aktionen mit einem Muster für lange ausgeführte Aktionen implementiert.
- Die App fordert eine lange ausgeführte Aktion über die API an. Die API akzeptiert die Aktion und gibt eine
202 Accepted-Antwort zusammen mit einem Speicherortheader für die API-URL zum Abrufen von Statusberichten zur Aktion zurück. - Die App fordert die Statusberichts-URL zur Aktion an und empfängt eine AsyncJobStatus-Antwort mit dem Fortschritt der lange ausgeführten Aktion.
- Die lange ausgeführte Aktion wird abgeschlossen. Beim nächsten Mal fordert die App die Statusberichts-URL zur Aktion an und empfängt eine AsyncJobStatus-Antwort über den Abschluss der lange ausgeführten Aktion.
Anfängliche Aktionsanforderung
Lassen Sie uns die einzelnen Schritte für ein Beispiel eines Kopieren-Szenarios durchgehen. In diesem Szenario fordert eine App das Kopieren eines Ordners mit einer großen Menge enthaltener Daten an. Das Abschließen dieser Anforderung wird wahrscheinlich einige Sekunden dauern, da die Datenmenge groß ist.
POST /drive/items/{folder-item-id}/copy
Content-Type: application/json
Prefer: respond-async
{
"parentReference": {
"path": "/drive/root:/Documents"
},
"name": "Copy of LargeFolder1"
}
Die API antwortet, dass die Aktion akzeptiert wurde, und gibt die URL zum Abrufen des Status der lange ausgeführten Aktion zurück.
HTTP/1.1 202 Accepted
Location: https://api.onedrive.com/monitor/4A3407B5-88FC-4504-8B21-0AABD3412717
In vielen Fällen ist dies das Ende der Anforderung, da der Kopiervorgang abgeschlossen wird, ohne dass die App weitere Aufgaben ausführt. Wenn die App jedoch den Status des Kopiervorgangs anzeigen oder sicherstellen möchte, dass diese ohne Fehler abgeschlossen wird, kann sie dazu die Überwachungs-URL verwenden.
Abrufen eines Statusberichts von der Überwachungs-URL
Um den Status des Kopiervorgang zu überprüfen, stellt die App eine Anforderung an die URL, die in der vorherigen Antwort bereitgestellt wurde. Hinweis: Diese Anforderung erfordert keine Authentifizierung, da die URL kurzlebig und einzigartig für den ursprünglichen Aufrufer ist.
GET https://api.onedrive.com/monitor/4A3407B5-88FC-4504-8B21-0AABD3412717
Der Dienst gibt eine Antwort mit der Information zurück, dass die lang ausgeführte Aktion noch nicht abgeschlossen ist:
HTTP/1.1 202 Accepted
Content-type: application/json
{
"operation": "ItemCopy",
"percentageComplete": 27.8,
"status": "inProgress"
}
Diese Information kann verwendet werden, um den Benutzer über den Fortschritt des Kopiervorgangs zu informieren. Die App kann die Überwachungs-URL weiterhin abfragen, um Statusupdates anzufordern und den Fortschritt der Aktion nachzuverfolgen.
Abrufen eines Statusberichts zum Abschluss von der Überwachungs-URL
Nach einigen Sekunden ist der Kopiervorgang abgeschlossen. Wenn die App nun die Überwachungs-URL abfragt, ist die Antwort eine Weiterleitung zum Endergebnis der Aktion.
GET https://api.onedrive.com/monitor/4A3407B5-88FC-4504-8B21-0AABD3412717
Wenn die Aktion ausgeführt wurde, gibt die Antwort des Überwachungsdienstes die resourceId für die Ergebnisse zurück.
HTTP/1.1 303 See Other
Content-type: application/json
{
"percentageComplete": 100.0,
"resourceId": "01MOWKYVJML57KN2ANMBA3JZJS2MBGC7KM",
"status": "completed"
}