Freigeben über

Abrufen des Status für alle Dokumente

  • Artikel

Referenzfeature: Azure AI Translator → Version der Dokumentübersetzungs-API
: 2024-05-01
 HTTP-Methode: GET

Wichtig

Für alle API-Anforderungen an das Feature „Dokumentübersetzung“ ist ein benutzerdefinierter Domänenendpunkt erforderlich, der sich auf der Seite „Ressourcenübersicht“ im Azure-Portal befindet.

  • Verwenden Sie die get documents status Methode, um den Status für alle Dokumente in einem Übersetzungsauftrag anzufordern.

  • 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 werden Datensätze 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.
    • 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.

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.

  • $orderBy Der Abfrageparameter kann verwendet werden, um die zurückgegebene Liste (z $orderBy=createdDateTimeUtc asc . B. oder $orderBy=createdDateTimeUtc desc) zu sortieren.
  • Die Standardsortierung ist absteigend nach createdDateTimeUtc. Einige Abfrageparameter können verwendet werden, um die zurückgegebene Liste (z. B. status=Succeeded,Cancelled) nur erfolgreiche und abgebrochene Dokumente zurückzugeben.
  • Die createdDateTimeUtcStart Parameter und createdDateTimeUtcEnd Abfrageparameter können kombiniert oder separat verwendet werden, um einen Datumsbereich anzugeben, um die zurückgegebene Liste zu filtern.
  • Die unterstützten Filterabfrageparameter sind (status, id, und createdDateTimeUtcStartcreatedDateTimeUtcEnd).
  • Wenn sowohl $top als auch $skip enthalten sind, sollte der Server zuerst $skip und dann $top auf die Sammlung anwenden.

Anfrage-URL

Sendet eine GET-Anforderung an:

  curl -i -X GET "{document-translation-endpoint}/translator/document/batches/{id}/documents?api-version={date}"

Ermitteln des Werts für id

  • Sie finden die Auftrags-id im URL-Wert Operation-Location des Antwortheaders der POST-Methode start-batch-translation. Die alphanumerische Zeichenfolge nach dem /document/ Parameter ist die Auftrags-id des Vorgangs:
Antwortheader Antwort-URL
Operation-Location {document-translation-endpoint}/translator/document/9dce0aa9-78dc-41ba-8cae-2e2f3c2ff8ec?api-version=2024-05-01
  • Sie können auch eine get-translation-status-Anforderung verwenden, um eine Liste der Übersetzungsaufträge und deren ids abzurufen.

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 Abfrage 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 Abfrage 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 Abfrage 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 Abfrage False array IDs, die beim Filtern verwendet werden.
statuses Abfrage False array Statusangaben, die beim Filtern verwendet werden.

Anforderungsheader

Anforderungsheader:

Header Beschreibung Erkrankung
Ocp-Apim-Subscription-Key Ihr Übersetzerdienst-API-Schlüssel aus dem Azure-Portal. Erforderlich
Ocp-Apim-Subscription-Region Die Region, in der Ihre Ressource erstellt wurde. Erforderlich bei Verwendung einer regionalen (geografischen) Ressource wie west-US
Content-Type Der Inhaltstyp der Nutzdaten. Die akzeptierten Werte sind application/json oder charset=UTF-8. Erforderlich

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
•Abblasend
•Misslungen
• 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
•Unbefugt
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

Tipp

Verwenden Sie diese Methode, um den documentId Parameter für die Abfragezeichenfolge "get-document-status " abzurufen.

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.

Erste Schritte bei der Dokumentübersetzung