Udostępnij za pośrednictwem


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 Pacyfik
api-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.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

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.
  • Zobacz Przykł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

Zrzut ekranu: strona właściwości usługi Translator w witrynie 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.

  1. Przejdź do zasobu usługi Translator w witrynie Azure Portal.

  2. Wybierz pozycję Sieć w sekcji Zarządzanie zasobami.

  3. Na karcie Zapory i sieci wirtualne wybierz pozycję Wybrane sieci i prywatne punkty końcowe.

    Zrzut ekranu przedstawiający ustawienie sieci wirtualnej w witrynie Azure Portal.

  4. Wybierz pozycję Zapisz, aby zastosować zmiany.

  5. Wybierz pozycję Klucze i punkt końcowy w sekcji Zarządzanie zasobami.

  6. Wybierz kartę Sieć wirtualna.

  7. Na liście znajdują się punkty końcowe tłumaczenia tekstu i tłumaczenia dokumentów.

    Zrzut ekranu przedstawiający punkt końcowy sieci wirtualnej.

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.

Metryki usługi Translator

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.