Translator w wersji 3.0

Artykuł
02/14/2024

Co nowego?

Wersja 3.0 usługi Translator udostępnia nowoczesny internetowy interfejs API oparty na formacie JSON. Zwiększa użyteczność i wydajność dzięki konsolidowaniu istniejących funkcji w mniejszej liczbie operacji i udostępnia nowe funkcje.

Transliteracja w celu przekonwertowania tekstu w jednym języku z jednego skryptu na inny skrypt.
Tłumaczenie na wiele języków w jednym żądaniu.
Wykrywanie języka, tłumaczenie i transliteracja w jednym żądaniu.
Słownik do wyszukiwania alternatywnych tłumaczeń terminu, aby znaleźć tłumaczenia wsteczne i przykłady przedstawiające terminy używane w kontekście.
Więcej informacji o wynikach wykrywania języka.

Podstawowe adresy URL

Żądania do usługi Translator są w większości przypadków obsługiwane przez centrum danych znajdujące się najbliżej miejsca, w którym pochodzi żądanie. Jeśli podczas korzystania z globalnego punktu końcowego wystąpi awaria centrum danych, żądanie może być kierowane poza lokalizacją geograficzną.

Aby wymusić obsługę żądania w określonej lokalizacji geograficznej, użyj żądanego punktu końcowego geograficznego. Wszystkie żądania są przetwarzane między centrami danych w lokalizacji geograficznej.

Lokalizacja geograficzna	Podstawowy adres URL (geograficzny punkt końcowy)	Centra danych
Globalny (`non-regional`)	api.cognitive.microsofttranslator.com	Najbliższe dostępne centrum danych
Azja i Pacyfik	api-apc.cognitive.microsofttranslator.com	Korea Południowa, Japonia Wschodnia, Azja Południowo-Wschodnia i Australia Wschodnia
Europa	api-eur.cognitive.microsofttranslator.com	Europa Północna, Europa Zachodnia
Stany Zjednoczone	api-nam.cognitive.microsofttranslator.com	Wschodnie stany USA, Południowo-środkowe stany USA, Zachodnio-środkowe stany USA i Zachodnie stany USA 2

¹ Klienci z zasobem znajdującym się w Szwajcarii Północnej lub Szwajcarii Zachodniej mogą upewnić się, że ich żądania interfejsu API tekstu są obsługiwane w Szwajcarii. Aby upewnić się, że żądania są obsługiwane w Szwajcarii, utwórz zasób translatora w Resource regionSwitzerland North obiekcie lub Switzerland West, a następnie użyj niestandardowego punktu końcowego zasobu w żądaniach interfejsu API.

Na przykład: Jeśli tworzysz zasób usługi Translator w witrynie Azure Portal Resource region jako i nazwa zasobu to my-swiss-n, niestandardowy punkt końcowy to https://my-swiss-n.cognitiveservices.azure.comSwitzerland North . A przykładowe żądanie tłumaczenia to:

// Pass secret key and region using headers to a custom endpoint
curl -X POST "https://my-swiss-n.cognitiveservices.azure.com/translator/text/v3.0/translate?to=fr" \
-H "Ocp-Apim-Subscription-Key: xxx" \
-H "Ocp-Apim-Subscription-Region: switzerlandnorth" \
-H "Content-Type: application/json" \
-d "[{'Text':'Hello'}]" -v

² Usługa Custom Translator nie jest obecnie dostępna w Szwajcarii.

Uwierzytelnianie

Zasubskrybuj usługę Translator lub wiele usług w usługach azure AI i użyj klucza (dostępnego w witrynie Azure Portal), aby się uwierzytelnić.

Istnieją trzy nagłówki, których można użyć do uwierzytelniania subskrypcji. W tej tabeli opisano sposób użycia poszczególnych elementów:

Nagłówki	opis
Ocp-Apim-Subscription-Key	Użyj z subskrypcją usług Azure AI, jeśli przekazujesz klucz tajny. Wartość to klucz tajny platformy Azure dla twojej subskrypcji w usłudze Translator.
Autoryzacja	Użyj z subskrypcją usług Azure AI, jeśli przekazujesz token uwierzytelniania. Wartość to token elementu nośnego: `Bearer <token>`.
Ocp-Apim-Subscription-Region	Używaj z wieloma usługami i regionalnymi zasobami translatora. Wartość jest regionem zasobu z wieloma usługami lub regionalnymi translatorami. Ta wartość jest opcjonalna w przypadku korzystania z globalnego zasobu translatora.

Klucz tajny

Pierwszą opcją jest uwierzytelnienie przy użyciu nagłówka Ocp-Apim-Subscription-Key . Ocp-Apim-Subscription-Key: <YOUR_SECRET_KEY> Dodaj nagłówek do żądania.

Uwierzytelnianie za pomocą zasobu globalnego

Jeśli używasz globalnego zasobu translatora, musisz dołączyć jeden nagłówek, aby wywołać usługę Translator.

Nagłówki	opis
Ocp-Apim-Subscription-Key	Wartość to klucz tajny platformy Azure dla twojej subskrypcji w usłudze Translator.

Oto przykładowe żądanie wywołania usługi Translator przy użyciu globalnego zasobu translatora

// Pass secret key using headers
curl -X POST "https://api.cognitive.microsofttranslator.com/translate?api-version=3.0&to=es" \
     -H "Ocp-Apim-Subscription-Key:<your-key>" \
     -H "Content-Type: application/json" \
     -d "[{'Text':'Hello, what is your name?'}]"

Uwierzytelnianie przy użyciu zasobu regionalnego

Jeśli używasz zasobu regionalnego translatora, istnieją dwa nagłówki, które należy wywołać w usłudze Translator.

Nagłówki	opis
Ocp-Apim-Subscription-Key	Wartość to klucz tajny platformy Azure dla twojej subskrypcji w usłudze Translator.
Ocp-Apim-Subscription-Region	Wartość jest regionem zasobu translatora.

Oto przykładowe żądanie wywołania usługi Translator przy użyciu regionalnego zasobu translatora

// Pass secret key and region using headers
curl -X POST "https://api.cognitive.microsofttranslator.com/translate?api-version=3.0&to=es" \
     -H "Ocp-Apim-Subscription-Key:<your-key>" \
     -H "Ocp-Apim-Subscription-Region:<your-region>" \
     -H "Content-Type: application/json" \
     -d "[{'Text':'Hello, what is your name?'}]"

Uwierzytelnianie za pomocą zasobu z wieloma usługami

Zasób z wieloma usługami umożliwia użycie pojedynczego klucza interfejsu API do uwierzytelniania żądań dla wielu usług.

W przypadku korzystania z klucza tajnego z wieloma usługami należy dołączyć dwa nagłówki uwierzytelniania do żądania. Istnieją dwa nagłówki, które należy wywołać w usłudze Translator.

Nagłówki	opis
Ocp-Apim-Subscription-Key	Wartość to klucz tajny platformy Azure dla zasobu z wieloma usługami.
Ocp-Apim-Subscription-Region	Wartość jest regionem zasobu z wieloma usługami.

Region jest wymagany dla subskrypcji interfejsu API tekstu wielu usług. Wybrany region jest jedynym regionem, którego można użyć do tłumaczenia tekstu podczas korzystania z klucza wielosłużowego. Musi to być ten sam region, który został wybrany podczas tworzenia konta subskrypcji z wieloma usługami za pośrednictwem witryny Azure Portal.

Jeśli przekażesz klucz tajny w ciągu zapytania przy użyciu parametru Subscription-Key, musisz określić region z parametrem Subscription-Regionzapytania .

Uwierzytelnianie przy użyciu tokenu dostępu

Alternatywnie możesz wymienić klucz tajny dla tokenu dostępu. Ten token jest dołączany do każdego żądania jako nagłówka Authorization . Aby uzyskać token autoryzacji, prześlij POST żądanie do następującego adresu URL:

Typ zasobu	Adres URL usługi uwierzytelniania
Globalnie	`https://api.cognitive.microsoft.com/sts/v1.0/issueToken`
Regionalne lub wieloasłużowe	`https://<your-region>.api.cognitive.microsoft.com/sts/v1.0/issueToken`

Oto przykładowe żądania uzyskania tokenu podanego klucza tajnego dla zasobu globalnego:

// Pass secret key using header
curl --header 'Ocp-Apim-Subscription-Key: <your-key>' --data "" 'https://api.cognitive.microsoft.com/sts/v1.0/issueToken'

// Pass secret key using query string parameter
curl --data "" 'https://api.cognitive.microsoft.com/sts/v1.0/issueToken?Subscription-Key=<your-key>'

Oto przykładowe żądania uzyskania tokenu podanego klucza tajnego dla zasobu regionalnego znajdującego się w regionie Środkowe stany USA:

// Pass secret key using header
curl --header "Ocp-Apim-Subscription-Key: <your-key>" --data "" "https://centralus.api.cognitive.microsoft.com/sts/v1.0/issueToken"

// Pass secret key using query string parameter
curl --data "" "https://centralus.api.cognitive.microsoft.com/sts/v1.0/issueToken?Subscription-Key=<your-key>"

Pomyślne żądanie zwraca zakodowany token dostępu jako zwykły tekst w treści odpowiedzi. Prawidłowy token jest przekazywany do usługi Translator jako token elementu nośnego w autoryzacji.

Authorization: Bearer <Base64-access_token>

Token uwierzytelniania jest ważny przez 10 minut. Token powinien być ponownie używany podczas wykonywania wielu wywołań do usługi Translator. Jeśli jednak program wysyła żądania do usługi Translator przez dłuższy czas, program musi zażądać nowego tokenu dostępu w regularnych odstępach czasu (na przykład co 8 minut).

Uwierzytelnianie przy użyciu identyfikatora Entra firmy Microsoft

Usługa Translator w wersji 3.0 obsługuje uwierzytelnianie firmy Microsoft, oparte na chmurze rozwiązanie do zarządzania tożsamościami i dostępem firmy Microsoft. Nagłówki autoryzacji umożliwiają usłudze Translator sprawdzenie, czy klient żądający ma autoryzację do korzystania z zasobu i do ukończenia żądania.

Wymagania wstępne

Krótka wiedza na temat uwierzytelniania za pomocą identyfikatora Entra firmy Microsoft.
Krótka wiedza na temat autoryzowania dostępu do tożsamości zarządzanych.

Nagłówki

Nagłówek	Wartość
Autoryzacja	Wartość to token elementu nośnego dostępu generowany przez usługę Azure AD. Token elementu nośnego zapewnia dowód uwierzytelniania i weryfikuje autoryzację klienta do korzystania z zasobu. Token uwierzytelniania jest ważny przez 10 minut i powinien być ponownie używany podczas wykonywania wielu wywołań w usłudze Translator. ZobaczPrzykładowe żądanie: 2. Uzyskiwanie tokenu
Ocp-Apim-Subscription-Region	Wartość jest regionem zasobu translatora. Ta wartość jest opcjonalna, jeśli zasób jest globalny.
Ocp-Apim-ResourceId	Wartość to identyfikator zasobu dla wystąpienia zasobu usługi Translator. Identyfikator zasobu można znaleźć w witrynie Azure Portal na stronie Właściwości zasobu usługi Translator →. Format identyfikatora zasobu: /subscriptions/subscriptionId>/<resourceGroups/<resourceGroupName>/providers/Microsoft.CognitiveServices/accounts/<resourceName/>

Strona właściwości usługi Translator — Witryna Azure Portal

Screenshot:Translator properties page in the Azure portal.

Przykłady

Korzystanie z globalnego punktu końcowego

 // Using headers, pass a bearer token generated by Azure AD, resource ID, and the region.

curl -X POST "https://api.cognitive.microsofttranslator.com/translate?api-version=3.0&to=es" \
     -H "Authorization: Bearer <Base64-access_token>"\
     -H "Ocp-Apim-ResourceId: <Resource ID>" \
     -H "Ocp-Apim-Subscription-Region: <your-region>" \
     -H "Content-Type: application/json" \
     -data-raw "[{'Text':'Hello, friend.'}]"

Korzystanie z niestandardowego punktu końcowego

// Using headers, pass a bearer token generated by Azure AD.

curl -X POST https://<your-custom-domain>.cognitiveservices.azure.com/translator/text/v3.0/translate?api-version=3.0&to=es \
     -H "Authorization: Bearer <Base64-access_token>"\
     -H "Content-Type: application/json" \
     -data-raw "[{'Text':'Hello, friend.'}]"

Przykłady użycia tożsamości zarządzanych

Usługa Translator w wersji 3.0 obsługuje również autoryzowanie dostępu do tożsamości zarządzanych. Jeśli tożsamość zarządzana jest włączona dla zasobu translatora, możesz przekazać token elementu nośnego wygenerowany przez tożsamość zarządzaną w nagłówku żądania.

Za pomocą globalnego punktu końcowego

// Using headers, pass a bearer token generated either by Azure AD or Managed Identities, resource ID, and the region.

curl -X POST https://api.cognitive.microsofttranslator.com/translate?api-version=3.0&to=es \
     -H "Authorization: Bearer <Base64-access_token>"\
     -H "Ocp-Apim-ResourceId: <Resource ID>" \
     -H "Ocp-Apim-Subscription-Region: <your-region>" \
     -H "Content-Type: application/json" \
     -data-raw "[{'Text':'Hello, friend.'}]"

Za pomocą niestandardowego punktu końcowego

//Using headers, pass a bearer token generated by Managed Identities.

curl -X POST https://<your-custom-domain>.cognitiveservices.azure.com/translator/text/v3.0/translate?api-version=3.0&to=es \
     -H "Authorization: Bearer <Base64-access_token>"\
     -H "Content-Type: application/json" \
     -data-raw "[{'Text':'Hello, friend.'}]"

Obsługa sieci wirtualnej

Usługa Translator jest teraz dostępna z funkcjami usługi Virtual Network (VNET) we wszystkich regionach chmury publicznej platformy Azure. Aby włączyć sieć wirtualną, zobaczKonfigurowanie sieci wirtualnych usług Azure AI.

Po włączeniu tej funkcji należy wywołać usługę Translator przy użyciu niestandardowego punktu końcowego. Nie można użyć globalnego punktu końcowego translatora ("api.cognitive.microsofttranslator.com") i nie można uwierzytelnić się przy użyciu tokenu dostępu.

Niestandardowy punkt końcowy można znaleźć po utworzeniu zasobu translatora i umożliwieniu dostępu z wybranych sieci i prywatnych punktów końcowych.

Przejdź do zasobu usługi Translator w witrynie Azure Portal.
Wybierz pozycję Sieć w sekcji Zarządzanie zasobami.
Na karcie Zapory i sieci wirtualne wybierz pozycję Wybrane sieci i prywatne punkty końcowe.
Wybierz pozycję Zapisz, aby zastosować zmiany.
Wybierz pozycję Klucze i punkt końcowy w sekcji Zarządzanie zasobami.
Wybierz kartę Sieć wirtualna.
Na liście znajdują się punkty końcowe tłumaczenia tekstu i tłumaczenia dokumentów.

Nagłówki	opis
Ocp-Apim-Subscription-Key	Wartość to klucz tajny platformy Azure dla twojej subskrypcji w usłudze Translator.
Ocp-Apim-Subscription-Region	Wartość jest regionem zasobu translatora. Ta wartość jest opcjonalna, jeśli zasób jest `global`

Oto przykładowe żądanie wywołania usługi Translator przy użyciu niestandardowego punktu końcowego

// Pass secret key and region using headers
curl -X POST "https://<your-custom-domain>.cognitiveservices.azure.com/translator/text/v3.0/translate?api-version=3.0&to=es" \
     -H "Ocp-Apim-Subscription-Key:<your-key>" \
     -H "Ocp-Apim-Subscription-Region:<your-region>" \
     -H "Content-Type: application/json" \
     -d "[{'Text':'Hello, what is your name?'}]"

Błędy

Standardowa odpowiedź o błędzie to obiekt JSON z parą nazwa/wartość o nazwie error. Wartość jest również obiektem JSON z właściwościami:

code: kod błędu zdefiniowany przez serwer.
message: ciąg dający czytelną dla człowieka reprezentację błędu.

Na przykład klient z subskrypcją bezpłatnej wersji próbnej otrzyma następujący błąd po wyczerpaniu bezpłatnego limitu przydziału:

{
  "error": {
    "code":403001,
    "message":"The operation isn't allowed because the subscription has exceeded its free quota."
    }
}

Kod błędu to 6-cyfrowy numer łączący 3-cyfrowy kod stanu HTTP, po którym następuje 3-cyfrowy numer w celu dalszego kategoryzowania błędu. Typowe kody błędów:

Kod	Opis
400000	Jedna z wartości wejściowych żądania jest niepoprawna.
400001	Parametr „scope” jest niepoprawny.
400002	Parametr „category” jest niepoprawny.
400003	Brakuje specyfikatora języka lub jest on niepoprawny.
400004	Brakuje specyfikatora skryptu docelowego („ToScript”) lub jest on niepoprawny.
400005	Brakuje tekstu wejściowego lub jest on niepoprawny.
400006	Kombinacja języka i skryptu jest niepoprawna.
400018	Brakuje specyfikatora skryptu źródłowego („FromScript”) lub jest on niepoprawny.
400019	Jeden z określonych języków nie jest obsługiwany.
400020	Jeden z elementów tablicy tekstu wejściowego jest niepoprawny.
400021	Brakuje parametru wersji interfejsu API lub jest on niepoprawny.
400023	Jedna z określonych par języków jest niepoprawna.
400035	Język źródłowy (pole „From”) jest niepoprawny.
400036	Brakuje języka docelowego (pole „To”) lub jest on niepoprawny.
400042	Jedna z określonych opcji (pole „Options”) jest niepoprawna.
400043	Brakuje identyfikatora śledzenia klienta (pole ClientTraceId lub nagłówek X-ClientTranceId) lub jest on niepoprawny.
400050	Tekst wejściowy jest za długi. Zobacz Limity żądań.
400064	Brakuje parametru „translation” lub jest on niepoprawny.
400070	Liczba skryptów docelowych (parametr ToScript) nie jest zgodna z liczbą języków docelowych (parametr To).
400071	Wartość jest niepoprawna dla parametru TextType.
400072	Tablica tekstu wejściowego zawiera zbyt wiele elementów.
400073	Parametr dotyczący skryptu jest niepoprawny.
400074	Treść żądania nie jest poprawnym kodem JSON.
400075	Kombinacja pary języków i kategorii jest niepoprawna.
400077	Przekroczono maksymalny rozmiar żądania. Zobacz Limity żądań.
400079	System niestandardowy zażądany do tłumaczenia między językiem źródłowym i docelowym nie istnieje.
400080	Transliteracja nie jest obsługiwana dla danego języka lub skryptu.
401000	Żądanie nie jest autoryzowane, ponieważ brakuje poświadczeń lub są one nieprawidłowe.
401015	"Podane poświadczenia są przeznaczone dla interfejsu API rozpoznawania mowy. To żądanie wymaga poświadczeń interfejsu API tekstu. Używanie subskrypcji do tłumaczenia w usłudze Translator.
403000	Operacja nie jest dozwolona.
403001	Operacja nie jest dozwolona, ponieważ subskrypcja przekroczyła limit przydziału bezpłatnego.
405000	Metoda żądania nie jest obsługiwana dla żądanego zasobu.
408001	Żądany system tłumaczeń jest przygotowywany. Ponów próbę za kilka minut.
408002	Upłynął limit czasu żądania podczas oczekiwania na strumień przychodzący. Klient nie wygenerował żądania w okresie, w którym oczekiwał serwer. Klient może powtórzyć żądanie bez modyfikacji w dowolnym późniejszym czasie.
415000	Brak nagłówka Content-Type lub jest on nieprawidłowy.
429000, 429001, 429002	Serwer odrzucił żądanie, ponieważ klient przekroczył limity żądań.
500000	Wystąpił nieoczekiwany błąd. Jeśli błąd będzie się powtarzać, zgłoś go z datą/godziną błędu, identyfikatorem żądania z nagłówka odpowiedzi X-RequestId i identyfikatorem klienta z nagłówka żądania X-ClientTraceId.
503000	Usługa jest tymczasowo niedostępna. Ponów próbę. Jeśli błąd będzie się powtarzać, zgłoś go z datą/godziną błędu, identyfikatorem żądania z nagłówka odpowiedzi X-RequestId i identyfikatorem klienta z nagłówka żądania X-ClientTraceId.

Metryki

Metryki umożliwiają wyświetlanie informacji o użyciu i dostępności tłumacza w witrynie Azure Portal w sekcji metryk, jak pokazano na poniższym zrzucie ekranu. Aby uzyskać więcej informacji, zobacz Metryki danych i platformy.

Translator Metrics

W tej tabeli wymieniono dostępne metryki z opisem sposobu ich użycia do monitorowania wywołań interfejsu API tłumaczenia.

Mierniki	opis
TotalCalls	Łączna liczba wywołań interfejsu API.
TotalTokenCalls	Łączna liczba wywołań interfejsu API za pośrednictwem usługi tokenu przy użyciu tokenu uwierzytelniania.
Pomyślnie zakończone niepowodzeniem	Liczba pomyślnych wywołań.
TotalErrors	Liczba wywołań z odpowiedzią na błąd.
BlockedCalls	Liczba wywołań, które przekroczyły limit szybkości lub limitu przydziału.
Błędy serwera	Liczba wywołań z błędem wewnętrznym serwera (5XX).
Błędy klienta	Liczba wywołań z błędem po stronie klienta (4XX).
Opóźnienie	Czas trwania żądania w milisekundach.
Znakiprzetłumaczone	Łączna liczba znaków w przychodzącym żądaniu tekstowym.