Translator w wersji 3.0
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.
✔️ Funkcja: tłumaczenie tekstu w usłudze Translator
Punkt końcowy usługi | Żądanie przetwarzania centrum danych |
---|---|
Globalny (zalecane):api.cognitive.microsofttranslator.com |
Najbliższe dostępne centrum danych. |
Ameryka:api-nam.cognitive.microsofttranslator.com |
Wschodnie stany USA 2 • Zachodnie stany USA 2 |
Azja i Pacyfikapi-apc.cognitive.microsofttranslator.com : |
Japonia Wschodnia • Azja Południowo-Wschodnia |
Europa (z wyjątkiem Szwajcarii):api-eur.cognitive.microsofttranslator.com |
Francja Środkowa • Europa Zachodnia |
Szwajcaria: Aby uzyskać więcej informacji, zobacz Punkty końcowe usługi Szwajcarii. |
Szwajcaria Północna • Szwajcaria Zachodnia |
Punkty końcowe usługi Szwajcarii
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 region
Switzerland 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.com
Switzerland 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-Region
zapytania .
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.
|
Ocp-Apim-Subscription-Region | Wartość jest regionem zasobu translatora.
|
Ocp-Apim-ResourceId | Wartość to identyfikator zasobu dla wystąpienia zasobu usługi Translator.
|
Strona właściwości usługi Translator — Witryna Azure Portal
Ważne
Przypisz rolę użytkownika usług Cognitive Services do jednostki usługi. Przypisując tę rolę, udzielasz jednostce usługi dostępu do zasobu usługi Translator.
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ą, zobacz Konfigurowanie 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.
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. |