Pobieranie stanu dokumentów
Usługa referencyjna
: Wersja interfejsu API tłumaczenia
dokumentów sztucznej inteligencji platformy Azure: wersja 1.1
Jeśli liczba dokumentów w odpowiedzi przekracza limit stronicowania, używane jest stronicowanie po stronie serwera. Odpowiedzi podzielone na strony wskazują częściowy wynik i zawierają token kontynuacji w odpowiedzi. Brak tokenu kontynuacji oznacza, że żadne inne strony nie są dostępne.
$top
parametrów , $skip
i $maxpagesize
zapytania można użyć do określenia liczby wyników do zwrócenia i przesunięcia dla kolekcji.
$top
wskazuje łączną liczbę rekordów, które użytkownik chce zwrócić na wszystkich stronach. $skip
wskazuje liczbę rekordów do pominięcia z listy stanu dokumentu przechowywanego przez serwer na podstawie określonej metody sortowania. Domyślnie sortujemy według malejącego czasu rozpoczęcia. $maxpagesize
to maksymalna liczba elementów zwracanych na stronie. Jeśli więcej elementów zostanie żądanych za pośrednictwem $top
(lub $top
nie zostanie określonych i zostanie zwróconych więcej elementów), @nextLink będzie zawierać link do następnej strony.
$orderBy parametr zapytania może służyć do sortowania zwracanej listy (np. "$orderBy=createdDateTimeUtc asc" lub "$orderBy=createdDateTimeUtc desc"). Domyślne sortowanie jest malejące według wartości createdDateTimeUtc. Niektóre parametry zapytania mogą służyć do filtrowania zwracanej listy (np. "status=Succeeded,Cancelled") tylko zwraca zakończone powodzeniem i anulowane dokumenty. createdDateTimeUtcStart i createdDateTimeUtcEnd można używać łącznie lub oddzielnie, aby określić zakres daty/godziny filtrowania zwróconej listy według. Obsługiwane parametry zapytania filtrowania to (stan, identyfikatory, createdDateTimeUtcStart, createdDateTimeUtcEnd).
Po dołączeniu obu $top
elementów $skip
i serwer powinien najpierw mieć zastosowanie $skip
, a następnie $top
w kolekcji.
Uwaga
Jeśli serwer nie może honorować $top
i/lub $skip
, serwer musi zwrócić błąd do klienta informującego o nim zamiast ignorować opcje zapytania. Zmniejsza to ryzyko podejmowania przez klienta założeń dotyczących zwracanych danych.
Adres URL żądania
Wyślij żądanie GET
do:
GET https://<NAME-OF-YOUR-RESOURCE>.cognitiveservices.azure.com/translator/text/batch/v1.1/batches/{id}/documents
Dowiedz się, jak znaleźć niestandardową nazwę domeny.
Ważne
- Wszystkie żądania interfejsu API do usługi tłumaczenia dokumentów wymagają niestandardowego punktu końcowego domeny.
- Nie można użyć punktu końcowego znajdującego się na stronie kluczy zasobów i punktu końcowego witryny Azure Portal, ani globalnego punktu końcowego translatora —
api.cognitive.microsofttranslator.com
w celu wysłania żądań HTTP do tłumaczenia dokumentów.
Parametry żądania
Parametry żądania przekazane w ciągu zapytania to:
Parametr zapytania | W | Wymagania | Type | Opis |
---|---|---|---|---|
id |
path | Prawda | string | Identyfikator operacji. |
$maxpagesize |
zapytanie | Fałsz | liczba całkowita int32 | $maxpagesize to maksymalna liczba elementów zwracanych na stronie. Jeśli więcej elementów zostanie żądanych za pośrednictwem $top (lub $top nie zostanie określonych i zostanie zwróconych więcej elementów), @nextLink będzie zawierać link do następnej strony. Klienci mogą żądać stronicowania opartego na serwerze o określonym rozmiarze strony, określając preferencję $maxpagesize . Serwer powinien przestrzegać tej preferencji, jeśli określony rozmiar strony jest mniejszy niż domyślny rozmiar strony serwera. |
$orderby | zapytanie | Fałsz | tablica | Zapytanie sortowania dla kolekcji (np. CreatedDateTimeUtc asc , CreatedDateTimeUtc desc ). |
$skip |
zapytanie | Fałsz | liczba całkowita int32 | $skip wskazuje liczbę rekordów do pominięcia z listy rekordów przechowywanych przez serwer na podstawie określonej metody sortowania. Domyślnie sortujemy według malejącego czasu rozpoczęcia. Klienci MOGĄ używać $top i $skip parametrów zapytania, aby określić liczbę wyników do zwrócenia i przesunięcie do kolekcji. Gdy klient zwróci wartości i $top $skip , serwer POWINIEN najpierw zastosować $skip , a następnie $top w kolekcji. Jeśli serwer nie może honorować $top i/lub $skip , serwer MUSI zwrócić błąd do klienta informującego o nim zamiast ignorować opcje zapytania. |
$top |
zapytanie | Fałsz | liczba całkowita int32 | $top wskazuje łączną liczbę rekordów, które użytkownik chce zwrócić na wszystkich stronach. Klienci mogą używać $top parametrów i $skip wysyłać zapytania, aby określić liczbę wyników do zwrócenia i przesunięcie do kolekcji. Gdy klient zwróci wartości i $top $skip , serwer POWINIEN najpierw zastosować $skip , a następnie $top w kolekcji. Jeśli serwer nie może honorować $top i/lub $skip , serwer MUSI zwrócić błąd do klienta informującego o nim zamiast ignorować opcje zapytania. |
createdDateTimeUtcEnd | zapytanie | Fałsz | ciąg daty i godziny | Data/godzina zakończenia pobierania elementów przed. |
createdDateTimeUtcStart | zapytanie | Fałsz | ciąg daty i godziny | Data/godzina rozpoczęcia pobierania elementów po. |
ids |
zapytanie | Fałsz | tablica | Identyfikatory do użycia w filtrowaniu. |
Statusy | zapytanie | Fałsz | tablica | Stany do użycia w filtrowaniu. |
Nagłówki żądań
Nagłówki żądań to:
Nagłówki | opis |
---|---|
Ocp-Apim-Subscription-Key | Wymagany nagłówek żądania |
Kody stanu odpowiedzi
Poniżej przedstawiono możliwe kody stanu HTTP zwracane przez żądanie.
Kod stanu | opis |
---|---|
200 | OK. Pomyślne żądanie i zwraca stan dokumentów. HeadersRetry-After: integerETag: string |
400 | Nieprawidłowe żądanie. Sprawdź parametry wejściowe. |
401 | Brak autoryzacji. Sprawdź poświadczenia. |
404 | Nie można odnaleźć zasobu. |
500 | Wewnętrzny błąd serwera. |
Inne kody stanu | • Zbyt wiele żądań • Serwer jest tymczasowo niedostępny |
Uzyskiwanie odpowiedzi na stan dokumentów
Pomyślna odpowiedź na stan dokumentów
Następujące informacje są zwracane w pomyślnej odpowiedzi.
Nazwisko | Pisz | Opis |
---|---|---|
@nextLink | string | Adres URL następnej strony. Wartość null, jeśli nie ma więcej dostępnych stron. |
wartość | DocumentStatus [] | Szczegółowa lista stanów poszczególnych dokumentów. |
value.path | string | Lokalizacja dokumentu lub folderu. |
value.sourcePath | string | Lokalizacja dokumentu źródłowego. |
value.createdDateTimeUtc | string | Operacja utworzona data/godzina. |
value.lastActionDateTimeUtc | string | Data i godzina aktualizacji stanu operacji. |
value.status | status | Lista możliwych stanów zadania lub dokumentu. • Anulowana •Anulowanie •Nie powiodło się • Niestartowane •Uruchomiona •Zakończyła się pomyślnie • ValidationFailed |
value.to | string | Język. |
value.progress | Liczba | Postęp tłumaczenia, jeśli jest dostępny. |
value.id | string | Identyfikator dokumentu. |
value.characterCharged | integer | Znaki naliczane przez interfejs API. |
Odpowiedź błędna
Nazwisko | Pisz | Opis |
---|---|---|
code | string | Wyliczenia zawierające kody błędów wysokiego poziomu. Możliwe wartości: • InternalServerError • InvalidArgument • InvalidRequest • RequestRateTooHigh • ResourceNotFound • ServiceUnavailable •Nieautoryzowanych |
wiadomość | string | Pobiera komunikat o błędzie wysokiego poziomu. |
target | string | Pobiera źródło błędu. Na przykład byłoby documents to lub document id dla nieprawidłowego dokumentu. |
innerError | InnerTranslationError | Nowy format błędu wewnętrznego zgodny z wytycznymi interfejsu API usług AI platformy Azure. Ten komunikat o błędzie zawiera wymagane właściwości ErrorCode, message i optional properties target, details (key value pair), wewnętrzny błąd (można go zagnieżdżać). |
innerError.code | string | Pobiera ciąg błędu kodu. |
innerError.message | string | Pobiera komunikat o błędzie wysokiego poziomu. |
innerError.target | string | Pobiera źródło błędu. Na przykład byłoby documents to lub document id gdyby dokument był nieprawidłowy. |
Przykłady
Przykład pomyślnej odpowiedzi
Poniższy obiekt JSON jest przykładem pomyślnej odpowiedzi.
{
"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"
}
Przykładowa odpowiedź na błąd
Poniższy obiekt JSON jest przykładem odpowiedzi na błąd. Schemat innych kodów błędów jest taki sam.
Kod stanu: 500
{
"error": {
"code": "InternalServerError",
"message": "Internal Server Error",
"target": "Operation",
"innerError": {
"code": "InternalServerError",
"message": "Unexpected internal server error has occurred"
}
}
}
Następne kroki
Postępuj zgodnie z naszym przewodnikiem Szybki start, aby dowiedzieć się więcej na temat korzystania z tłumaczenia dokumentów i biblioteki klienta.