Abrufen des Dokumentstatus
Referenz
Dienst: Azure KI-Dokumentübersetzung
API-Version: v1.1
Wenn die Anzahl der Dokumente in der Antwort das Paging-Limit überschreitet, wird serverseitiges Paging verwendet. Paging-Antworten geben ein Teilergebnis an und enthalten ein Fortsetzungstoken in der Antwort. Das Fehlen eines Fortsetzungstokens bedeutet, dass keine weiteren Seiten verfügbar sind.
Die Abfrageparameter $top, $skip und $maxpagesize können verwendet werden, um die Ergebnisse, die zurückgegeben werden sollen, und einen Offset für die Sammlung anzugeben.
Mit $top wird die Gesamtzahl der Datensätze angegeben, die auf Wunsch der Benutzer*innen auf allen Seiten zurückgegeben werden sollen. Mit $skip wird die Anzahl der Datensätze angegeben, die in der Liste der Dokumentstatusangaben übersprungen werden sollen, die vom Server basierend auf der angegebenen Sortiermethode bereitgestellt wird. Standardmäßig wird nach absteigender Startzeit sortiert. Mit $maxpagesize wird die maximale Anzahl der Elemente angegeben, die auf einer Seite zurückgegeben werden. Wenn über $top weitere Elemente angefordert werden oder $top nicht angegeben ist und weitere Elemente zurückgegeben werden sollen, enthält @nextLink den Link zur nächsten Seite.
Der Abfrageparameter $orderBy kann verwendet werden, um die zurückgegebene Liste zu sortieren (Beispiel: „$orderBy=createdDateTimeUtc asc“ oder „$orderBy=createdDateTimeUtc desc“). Die Standardsortierung ist absteigend nach „createdDateTimeUtc“. Einige Abfrageparameter können verwendet werden, um die zurückgegebene Liste zu filtern. Z. B. gibt „status=Succeeded,Cancelled“ nur die erfolgreich zurückgegebenen und abgebrochenen Dokumente zurück. „createdDateTimeUtcStart“ und „createdDateTimeUtcEnd“ können kombiniert oder separat verwendet werden, um einen Datumsbereich anzugeben, nach dem die zurückgegebene Liste gefiltert wird. Die unterstützten Filterabfrageparameter sind (status, IDs, createdDateTimeUtcStart, createdDateTimeUtcEnd).
Wenn sowohl $top als auch $skip enthalten sind, sollte der Server zuerst $skip und dann $top auf die Sammlung anwenden.
Hinweis
Wenn der Server $top und/oder $skip nicht berücksichtigt, muss er einen Fehler an den Client zurückgeben, der darüber informiert, anstatt nur die Abfrageoptionen zu ignorieren. Dadurch wird das Risiko verringert, dass der Client Annahmen über die zurückgegebenen Daten vornimmt.
Anfrage-URL
Sendet eine GET-Anforderung an:
GET https://<NAME-OF-YOUR-RESOURCE>.cognitiveservices.azure.com/translator/text/batch/v1.1/batches/{id}/documents
Erfahren Sie, wie Sie Ihren benutzerdefinierten Domänennamenfinden.
Wichtig
- Für alle API-Anforderungen an den Dienst für die Dokumentübersetzung muss ein Endpunkt einer benutzerdefinierten Domäne verwendet werden.
- Zum Senden von HTTP-Anforderungen für die Dokumentübersetzung verwenden Sie nicht den Endpunkt, der im Azure-Portal auf der Ressourcenseite Schlüssel und Endpunkt angegeben ist, und auch nicht den globalen Übersetzungsendpunkt
api.cognitive.microsofttranslator.com.
Anforderungsparameter
Die folgenden Anforderungsparameter werden in der Abfragezeichenfolge übergeben:
| Query parameter (Abfrageparameter) | Geben Sie in | Erforderlich | Type | Beschreibung |
|---|---|---|---|---|
id |
path | True | Zeichenfolge | Vorgangs-ID. |
$maxpagesize |
query | False | integer int32 | Mit $maxpagesize wird die maximale Anzahl der Elemente angegeben, die auf einer Seite zurückgegeben werden. Wenn über $top weitere Elemente angefordert werden oder $top nicht angegeben ist und weitere Elemente zurückgegeben werden sollen, enthält @nextLink den Link zur nächsten Seite. Clients können servergesteuertes Paging mit einer bestimmten Seitengröße anfordern, indem sie eine $maxpagesize Einstellung angeben. Der Server SOLLTE diese Einstellung berücksichtigen, wenn die angegebene Seitengröße kleiner als die Standardseitengröße des Servers ist. |
| $orderBy | Abfrage | False | array | Die Sortierungsabfrage für die Sammlung, z. B. CreatedDateTimeUtc asc, CreatedDateTimeUtc desc |
$skip |
query | False | integer int32 | Mit $skip wird die Anzahl der Datensätze angegeben, die aus der Liste der Datensätze übersprungen werden sollen, die vom Server basierend auf der angegebenen Sortiermethode bereitgestellt wird. Standardmäßig wird nach absteigender Startzeit sortiert. Clients KÖNNEN die Abfrageparameter $top und $skip verwenden, um Ergebnisse, die zurückgegeben werden sollen, und einen Offset für die Sammlung anzugeben. Wenn der Client sowohl $top als auch $skip zurückgibt, SOLLTE der Server zuerst $skip und dann $top auf die Sammlung anwenden. Wenn der Server nicht berücksichtigt $top werden kann und/oder $skip, muss der Server einen Fehler an den Client zurückgeben, der darüber informiert wird, anstatt nur die Abfrageoptionen zu ignorieren. |
$top |
query | False | integer int32 | Mit $top wird die Gesamtzahl der Datensätze angegeben, die auf Wunsch der Benutzer*innen auf allen Seiten zurückgegeben werden sollen. Clients können Parameter verwenden $top und $skip abfragen, um die Anzahl der zurückzugebenden Ergebnisse und einen Offset in der Auflistung anzugeben. Wenn der Client sowohl $top als auch $skip zurückgibt, SOLLTE der Server zuerst $skip und dann $top auf die Sammlung anwenden. Wenn der Server nicht berücksichtigt $top werden kann und/oder $skip, muss der Server einen Fehler an den Client zurückgeben, der darüber informiert wird, anstatt nur die Abfrageoptionen zu ignorieren. |
| createdDateTimeUtcEnd | Abfrage | False | string Datum/Uhrzeit | Der Endzeitpunkt (Datum/Uhrzeit), vor dem Elemente abgerufen werden sollen. |
| createdDateTimeUtcStart | Abfrage | False | string Datum/Uhrzeit | Der Startzeitpunkt (Datum/Uhrzeit), nach dem Elemente abgerufen werden sollen. |
ids |
query | False | array | IDs, die beim Filtern verwendet werden. |
| statuses | Abfrage | False | array | Statusangaben, die beim Filtern verwendet werden. |
Anforderungsheader
Anforderungsheader:
| Header | BESCHREIBUNG |
|---|---|
| Ocp-Apim-Subscription-Key | Erforderlicher Anforderungsheader |
Antwortstatuscodes
Im Folgenden finden Sie die möglichen HTTP-Statuscodes, die eine Anforderung zurückgeben kann.
| Statuscode | BESCHREIBUNG |
|---|---|
| 200 | OK. Die Anforderung wurde erfolgreich ausgeführt, und der Status aller Dokumente wird zurückgegeben. HeadersRetry-After: integerETag: Zeichenfolge |
| 400 | Ungültige Anforderung. Eingabeparameter prüfen. |
| 401 | Nicht autorisiert. Anmeldeinformationen prüfen. |
| 404 | Die Ressource wurde nicht gefunden. |
| 500 | Interner Serverfehler. |
| Andere Statuscodes | • Zu viele Anforderungen • Der Server ist vorübergehend nicht verfügbar. |
„Abrufen des Dokumentstatus“-Antwort
Erfolgreiche „Abrufen des Dokumentstatus“-Antwort
Die folgenden Informationen werden bei erfolgreicher Antwort zurückgegeben.
| Name | Typ | Beschreibung |
|---|---|---|
| @nextLink | Zeichenfolge | Die URL für die nächste Seite. Null, wenn keine weiteren Seiten verfügbar sind. |
| Wert | DocumentStatus [] | Die Detailstatusliste der einzelnen Dokumente |
| value.path | Zeichenfolge | Speicherort des Dokuments oder des Ordners. |
| value.sourcePath | Zeichenfolge | Speicherort des Quelldokuments. |
| value.createdDateTimeUtc | Zeichenfolge | Das Datum und die Uhrzeit des Vorgangs. |
| value.lastActionDateTimeUtc | Zeichenfolge | Datumszeit, zu der der Status des Vorgangs aktualisiert wird. |
| value.status | status | Liste möglicher Status für Auftrag oder Dokument: • Canceled •Stornieren •Fehlgeschlagen • NotStarted •Ausgeführte •Gelungen • ValidationFailed |
| value.to | Zeichenfolge | In Sprache. |
| value.progress | number | Der Fortschritt der Übersetzung, falls verfügbar. |
| value.id | Zeichenfolge | Dokument-ID |
| value.characterCharged | integer | Zeichen, die von der API abgerechnet werden. |
Fehlerantwort
| Name | Typ | BESCHREIBUNG |
|---|---|---|
| code | Zeichenfolge | Enumerationen, die High-Level-Fehlercodes enthalten. Mögliche Werte: • InternalServerError • InvalidArgument • InvalidRequest • RequestRateTooHigh • ResourceNotFound • ServiceUnavailable •Unbefugte |
| message | Zeichenfolge | Ruft High-Level-Fehlermeldung ab. |
| target | Zeichenfolge | Ruft die Ursache des Fehlers ab. Dies wäre z. B. documents oder document id im Falle eines ungültigen Dokuments. |
| innerError | InnerTranslationError | Neues Format für innere Fehler, das den Richtlinien der Azure KI Services-API entspricht. Diese Fehlermeldung enthält die erforderlichen Eigenschaften „ErrorCode“ und „message“ sowie die optionalen Eigenschaften „target“, „details“ (Schlüssel-Wert-Paar) und „inner error“ (kann geschachtelt werden). |
| innerError.code | Zeichenfolge | Ruft Code der Fehlerzeichenfolge ab. |
| innerError.message | Zeichenfolge | Ruft High-Level-Fehlermeldung ab. |
| innerError.target | Zeichenfolge | Ruft die Ursache des Fehlers ab. Würde im Fall eines ungültigen Dokuments z. B. documents oder document id lauten. |
Beispiele
Beispiel für erfolgreiche Antwort
Das folgende JSON-Objekt ist ein Beispiel für eine erfolgreiche Antwort.
{
"value": [
{
"path": "https://myblob.blob.core.windows.net/destinationContainer/fr/mydoc.txt",
"sourcePath": "https://myblob.blob.core.windows.net/sourceContainer/fr/mydoc.txt",
"createdDateTimeUtc": "2020-03-26T00:00:00Z",
"lastActionDateTimeUtc": "2020-03-26T01:00:00Z",
"status": "Running",
"to": "fr",
"progress": 0.1,
"id": "273622bd-835c-4946-9798-fd8f19f6bbf2",
"characterCharged": 0
}
],
"@nextLink": "https://westus.cognitiveservices.azure.com/translator/text/batch/v1.1/operation/0FA2822F-4C2A-4317-9C20-658C801E0E55/documents?$top=5&$skip=15"
}
Beispiel für Fehlerantwort
Das folgende JSON-Objekt ist ein Beispiel für eine Fehlerantwort. Das Schema für andere Fehlercodes ist identisch.
Statuscode: 500
{
"error": {
"code": "InternalServerError",
"message": "Internal Server Error",
"target": "Operation",
"innerError": {
"code": "InternalServerError",
"message": "Unexpected internal server error has occurred"
}
}
}
Nächste Schritte
Befolgen Sie unsere Schnellstartanleitung, um mehr über die Verwendung der Dokumentübersetzung und der Clientbibliothek zu erfahren.