- Erste Schritte
- Über OData und Referenzen
- Aufgezählte Typen
- Authentifizierung
- Erstellen von API-Anfragen
- Berechtigungen pro Endpunkt
- Antwortcodes
- Ratenbegrenzungen und Nutzungsoptimierung für große Datenfelder
- Swagger-Definition
- Orchestrator-APIs
- Warnungsanforderungen
- Anfragen zu Assets
- Kalenderanforderungen
- Umgebungsabfragen
- Ordneranforderungen
- Generische Aufgabenanforderungen
- Jobanfragen
- Bibliotheksabfragen
- Lizenzabfragen
- Paketanfragen
- Berechtigungsabfragen
- Anfragen für persönliche Arbeitsbereiche
- Prozessabfragen
- Bearbeitung von Anforderungen an die Datenaufbewahrung
- Anforderungen von Warteschlangenelementen
- Anforderungen an Warteschlangenaufbewahrungsrichtlinien
- Roboteranfragen
- Rollenanfragen
- Zeitplanabfragen
- Anfragen zu Einstellungen
- Anforderungen für Speicher-Buckets
- Aufgabenanforderungen
- Aufgabenkataloganforderungen
- Aufgabenformularanforderungen
- Mandantenabfragen
- Transaktionsanfragen
- Benutzerabfragen
- Webhook-Abfragen
Ratenbegrenzungen und Nutzungsoptimierung für große Datenfelder
- Sie gewährleisten ein vorhersagbares System: Wenn Sie das API-Aufruflimit kennen, können Sie Ihre Anwendungen besser entwerfen und warten. Es bietet eine vorhersehbare Umgebung und minimiert Überraschungen aufgrund unerwarteter Grenzwertüberschreitungen.
- Sie verbessern die Leistung: Durch die Kontrolle des Datenverkehrs auf unseren Servern sorgen wir für optimale Leistung und schnellere Antworten, wodurch Ihr Produkterlebnis erheblich verbessert wird.
- Sie verbessern die Sicherheit: Die unten beschriebenen Grenzwerte dienen als zusätzliche Sicherheitsebene und schützen Ihr System vor potenziellen Cyber-Bedrohungen.
- Sie stellen eine gerechte Nutzung sicher: Unsere Ratenlimits gewährleisten eine gerechte Ressourcenverteilung an alle Nutzer und einen reibungslosen Betrieb auch während der Spitzenzeiten.
Die unten beschriebenen Grenzwerte und Optimierungen für große Datenfelder erfordern einige Anpassungen Ihrerseits. Wir sind jedoch zuversichtlich, dass sie langfristige Vorteile bringen werden.
Diese Grenzwerte werden durchgesetzt:
Endpoint |
Limits |
Gültig seit | Beispiele |
---|---|---|---|
|
|
Community-, Canary- und Enterprise-Mandanten: Juli 2024 |
|
|
|
Community-, Canary- und Enterprise-Mandanten: Juli 2024 |
|
|
100 API-Anforderungen/Tag/Mandant |
Community-, Canary- und Enterprise-Mandanten: Oktober 2024 |
Keine Angabe |
| 100 API-Anforderungen/Tag/Mandant |
Community-, Canary- und Enterprise-Mandanten: Oktober 2024 |
Keine Angabe |
|
100 API-Anforderungen/Tag/Mandant |
Community-, Canary- und Enterprise-Mandanten: Oktober 2024 |
Keine Angabe |
|
100 API-Anforderungen/Tag/Mandant |
Community-, Canary- und Enterprise-Mandanten: Oktober 2024 |
Keine Angabe |
1 Die Nutzung ohne Automatisierung bezieht sich auf API-Aufrufe, die von API-Integrationen außerhalb von Prozessen stammen, z. B. PowerShell-Skripte und Überwachungstools von Drittanbietern.
2 Automatisierungsnutzung bezieht sich auf API-Aufrufe, die von den Aktivitäten Get Queue Items, Get Jobs und Orchestrator Http Request stammen.
GET/odata/Jobs(<job_id>)
gibt es keine Ratenbegrenzung.
Diese Einschränkungen gelten nicht für das Hinzufügen von Warteschlangenelementen und das Verarbeiten von Aufträgen. Daher gibt es keine Auswirkungen auf das Hinzufügen eines Warteschlangenelements, das Entfernen eines Elements aus einer Warteschlange, das Festlegen seines Status oder das Starten und Verarbeiten einer beliebigen Anzahl von Aufträgen.
Sie können Ihre API-Nutzung pro Monat oder Tag auf der Registerkarte API-Prüfung auf Mandantenebene im Fenster Überwachung überprüfen.
Kopfzeile |
Beschreibung |
Beispiel |
---|---|---|
|
Allen Anforderungen, die über die vorgenannten Grenzen hinausgehen, wird die HTTP-Antwort 429 zurückgegeben, die diesen Header enthält. Zeigt die Anzahl der Sekunden an, die Sie warten müssen, bis der Endpunkt wieder für Sie verfügbar ist. |
Retry-After: 10 bedeutet, dass das Ratenlimit am Endpunkt in 10 Sekunden abläuft. Alle Wiederholungen innerhalb dieser 10 Sekunden führen zur Antwort 429.
|
|
Die Anzahl der verbleibenden Aufrufe |
X-RateLimit-Remaining: 30 bedeutet, dass Sie im aktuellen Zeitbereich 30 verbleibende Aufrufe haben
|
Wenn die Anzahl der Anforderungen pro Minute unter 10 ist, wird sie als 0 gerendert.
Die folgenden Aktivitäten sind von diesen Einschränkungen betroffen:
- Get Job
- Warteschlangenobjekte erhalten (Get Queue Items)
- Orchestrator Http Request (bei Verwendung zum Aufrufen der
GET /odata/Jobs
- oderGET /odata/QueueItems
-Endpunkte)
Retry-after
-Antwortheader, d. h. sie führen automatische Wiederholungen von Orchestrator-Vorgängen durch. Stellen Sie sicher, dass Sie immer die aktuelle Version der Systemaktivitäten verwenden, um davon zu profitieren.
Dies empfehlen wir Ihnen, um sicherzustellen, dass Sie unsere Grenzwerte einhalten und in vollem Umfang nutzen können:
- Überprüfen Sie Ihre API-Nutzungsmuster und die Informationen, die Sie von unseren zuvor erwähnten Endpunkten vom Typ
GetAll
abrufen. - Passen Sie Ihre API-Aufrufhäufigkeit und Datenextraktionsverfahren ggf. an diese Grenzwerte an.
- Verwenden Sie die Option Insights-Datenexport in Echtzeit für Echtzeitexporte.
- In den Abschnitten Exportieren von Aufträgen und Exportieren von Warteschlangenelementen finden Sie Beispiele zum Abrufen von Aufträgen und Warteschlangenelementdaten nur zu Berichts- und Archivierungszwecken.
Wichtig:
- Diese Endpunkte sind auf 100 API-Anforderungen/Tag/Mandant begrenzt.
Sobald dieser Grenzwert überschritten wird, wird ein Fehler #4502 angezeigt, der angibt, dass das Tageslimit pro Mandant erreicht wurde. Der Grenzwert wird um 00:00 UTC zurückgesetzt.
- Verwenden Sie diese Endpunkte nicht für den Echtzeit-Datenabruf.
- Diese Endpunkte sind auf 100 API-Anforderungen/Tag/Mandant begrenzt.
- Stellen Sie sicher, dass Sie immer die neueste Version der Systemaktivitäten verwenden.
- Wenden Sie sich an Ihren Kontomanager oder unser Support-Team, wenn Sie Fragen haben oder weitere Erläuterungen benötigen.
Diese Warnungen, die im Abschnitt API-Ratenlimits Ihrer Warnungseinstellungen verfügbar sind, informieren Sie, wenn die Grenzwerte überschritten werden, und liefern wertvolle Informationen über den betroffenen Endpunkt.
- Die Anforderungsrate hat den Grenzwert am vergangenen Tag überschritten – Schweregrad Warnung:
- Sie wird täglich in der Anwendung und per E-Mail gesendet.
- Sie haben sie standardmäßig abonniert.
- Sie enthält den Namen des Endpunkts, für den die Anzahl der Anforderungen überschritten wurde.
- Es enthält einen Link zum Überwachungsfenster der API-Prüfung auf Mandantenebene, das sich auf die tägliche Ansicht konzentriert. Details …
- Dafür ist die Berechtigung Prüfung – Anzeigen erforderlich.
- Die Anforderungsrate hat den Grenzwert überschritten – Schweregrad Fehler:
- Er wird alle zehn Minuten in der Anwendung und per E-Mail gesendet.
- Sie sind davon standardmäßig abgemeldet.
- Sie enthält den Namen des Endpunkts, für den die Anzahl der Anforderungen überschritten wurde.
- Es enthält einen Link zum Überwachungsfenster der API-Prüfung auf Mandantenebene, das sich auf die detaillierte 10-Minuten-Ansicht konzentriert. Details …Hinweis: Es kann eine 10-minütige Verzögerung zwischen dem Überschreiten des Grenzwerts und dem Versand der Warnung geben.
- Dafür ist die Berechtigung Prüfung – Anzeigen erforderlich.
Warnungsszenarien
Sie werden in den folgenden Szenarien gewarnt:
- Wenn Sie 100 API-Anforderungen/Minute/Mandant durch Nicht-Automatisierungsnutzung überschreiten.
- Wenn Sie 1.000 API-Anforderungen/Minute/Mandant durch Automatisierungsnutzung überschreiten.
Die API-Endpunkte, die zum Abrufen von Auftragslisten und Warteschlangenelementen verwendet werden, können sich als problematisch erweisen, wenn sie für die Echtzeitüberwachung und den Datenexport verwendet werden. Zum Beispiel:
-
Wenn bis zu 1.000 Elemente angefordert werden und jedes Element bis zu 1 MB an großen Daten umfasst, kann die Antwort auf einen einzigen API-Aufruf 1 GB groß sein. Da es zwischengeschaltete Stellen gibt, die keine Antworten dieser Größe zulassen, schlagen die Anforderungen fehl.
-
Wenn Sie komplexe Filter verwenden und dann eine Warteschlange mit mehreren Millionen Warteschlangenelementen paginieren, kann nach einigen Dutzend Seiten eine Zeitüberschreitung bei den Anforderungen auftreten. Das ist auf die Datenmenge zurückzuführen, die aus der Datenbank abgerufen werden muss.
Jobs - GetAll
-Endpunktantworten weggelassen. Das sind die betroffenen Felder:
Endpoint |
Ausgelassene Felder |
Was Sie stattdessen verwenden können |
Gültig seit |
---|---|---|---|
|
|
|
Community- und Canary-Mandanten: März 2024 Enterprise-Mandanten: Juli 2024 |
GET /odata/Jobs
-Endpunkt über die API oder über die Aktivitäten Get Jobs, Get Queue Items oder Orchestrator HTTP Request verwenden, müssen Sie ermitteln, ob Sie eines der aufgelisteten Felder verwenden. Wenn das der Fall ist, beachten Sie bitte, dass der Inhalt dieser Felder als „null“ zurückgegeben wird.
Wir empfehlen Ihnen, Prozesse in Ihren Canary-Mandanten zu testen, um die Auswirkungen zu bewerten.
GET/odata/QueueItems
-Endpunkts wird optimiert, indem diese Größenbeschränkungen auf seine Felder angewendet werden:
Feld |
Grenzwert | Gültig seit |
So stellen Sie fest, ob Sie betroffen sind |
So beheben Sie das Problem |
---|---|---|---|---|
Fortschritt |
1.048.576 Zeichen |
> Community- und Canary-Mandanten: April 2024 > Enterprise-Mandanten: Mai 2024 |
Eine bestimmte Fehlermeldung wird zurückgegeben, wenn die Daten, die Sie hochladen möchten, diese Grenzen überschreiten. |
Wir empfehlen die Verwendung von Speicher-Buckets und/oder Data Service Blob-Speicher, wenn Sie weitere Daten speichern müssen. |
104.857 Zeichen |
Alle Mandanten: September 2024 | |||
AnalyticsData/Analytics |
5.120 Zeichen |
> Community- und Canary-Mandanten: Juni 2024 > Enterprise-Mandanten: September 2024 | ||
OutputData/Output |
51.200 Zeichen | |||
SpecificContent/SpecificData |
256.000 Zeichen | |||
ProcessingException – Reason |
102.400 Zeichen | |||
ProcessingException – Details |
102.400 Zeichen |
Diese Grenzwerte basieren auf dem Codierungsstil UTF-16, der hauptsächlich vom SQL Server zum Speichern von Daten verwendet wird.
Informationen werden im SQL Server über Datentypen wie NVARCHAR gespeichert. In diesen Datentypen wird jedes Zeichen, einschließlich weit verbreiteter Zeichen aus Sprachen wie Chinesisch, Japanisch und Koreanisch, mit 2 Bytes gespeichert. Dies kann irreführend sein, wenn Sie die Datennutzlast mit Notepad oder in UTF-8 überprüfen, da diese 1 Byte pro Zeichen anzeigen (hauptsächlich ASCII 0-127 abc123 usw.).
Wenn Sie beispielsweise ein chinesisches Zeichen wie 文 in einer Textdatei mit UTF-8-Codierung speichern würden, würde es als 3-Byte-Sequence (E6 96 87) gespeichert und mehr Speicherplatz verbrauchen. Aufgrund der unterschiedlichen Codierungsstile ist die Anzahl der Zeichen als Begrenzung unzuverlässig.
Der folgende Filter ist auch aus Leistungsgründen eingeschränkt:
Filter |
Grenzwert |
Gültig seit |
So stellen Sie fest, ob Sie betroffen sind |
So beheben Sie das Problem |
---|---|---|---|---|
|
> Wenn Sie den Filter
$top nicht verwenden, erhalten Sie standardmäßig 100 Datensätze.
> Wenn Sie den Filter
$top verwenden, erhalten Sie maximal 100 Datensätze. Alles, was über 100 hinausgeht, löst die Fehlermeldung 400 Bad Request aus.
|
> Community- und Canary-Mandant: Juni 2024 > Enterprise-Mandanten: September 2024 |
Enterprise: Wir möchten eine E-Mail-Benachrichtigung an Administratoren senden, wenn wir die Verwendung dieses Filters in API-Aufrufen erkennen. Wir bitten Sie jedoch, auch Ihre Seite im Auge zu behalten. |
Wir empfehlen Ihnen, Ihren Prozess oder Ihre API-Nutzungslogik entsprechend zu ändern, wenn Sie erwarten, dass dieser Grenzwert überschritten wird. |
Jobs
und QueueItems
abzurufen:
- In den Abschnitten Exportieren von Aufträgen und Exportieren von Warteschlangenelementen finden Sie Beispiele zum Abrufen von Aufträgen und Warteschlangenelementdaten.
- Verwenden Sie die Option Insights-Datenexport in Echtzeit.
- Wenden Sie sich an Ihren Account Manager oder unser Supportteam, wenn die genannten Methoden nicht für Sie funktionieren.
Änderungen an Ratenlimits und großen Datenfeldern werden in lokalen Umgebungen nicht implementiert.
Wenn Sie einen eigenständigen Orchestrator verwenden und erwägen, in die Cloud zu migrieren, können Sie die IIS-Anforderungsprotokolle verwenden, um die Anforderungsrate für die betroffenen Endpunkte zu bestimmen. Die Analyse hängt davon ab, wie Sie die Protokolle aggregieren, wofür Sie z. B. Microsoft Log Parser verwenden können.
Um die Auswirkungen auf große Datenfelder zu bewerten, empfehlen wir, Ihre Prozesse in Canary-Mandanten zu testen.