Translator v3.0

Artikel
04/29/2024

Nyheter

Version 3.0 av Translator tillhandahåller ett modernt JSON-baserat webb-API. Det förbättrar användbarheten och prestandan genom att konsolidera befintliga funktioner till färre åtgärder och ger nya funktioner.

Transkribering för att konvertera text på ett språk från ett skript till ett annat skript.
Översättning till flera språk i en begäran.
Språkidentifiering, översättning och transkribering i en begäran.
Ordlista för att söka efter alternativa översättningar av en term för att hitta back-translations och exempel som visar termer som används i kontext.
Mer informativa språkidentifieringsresultat.

Grundläggande URL:er

Begäranden till Translator hanteras i de flesta fall av det datacenter som ligger närmast platsen där begäran kommer. Om det uppstår ett datacenterfel vid användning av den globala slutpunkten kan begäran dirigeras utanför geografin.

Använd önskad geografisk slutpunkt för att framtvinga att begäran hanteras inom ett visst geografiskt område. Alla begäranden bearbetas mellan datacenter inom geografin.

✔️ Funktion: Translator Text

Tjänstslutpunkt	Begära bearbetning av datacenter
Global (rekommenderas): `api.cognitive.microsofttranslator.com`	Närmaste tillgängliga datacenter.
Americas: `api-nam.cognitive.microsofttranslator.com`	USA, östra 2 • USA, västra 2
Asien och stillahavsområdet `api-apc.cognitive.microsofttranslator.com`:	Japan, östra • Sydostasien
Europa (utom Schweiz): `api-eur.cognitive.microsofttranslator.com`	Frankrike, centrala • Europa, västra
Schweiz: Mer information finns iTjänstslutpunkter för Schweiz.	Schweiz, norra • Schweiz, västra

Tjänstslutpunkter i Schweiz

Kunder med en resurs i Schweiz, norra eller Schweiz, västra, kan se till att deras text-API-begäranden hanteras i Schweiz. För att säkerställa att begäranden hanteras i Schweiz skapar du Translator-resursen Resource regionSwitzerland North i eller Switzerland Westoch använder sedan resursens anpassade slutpunkt i dina API-begäranden.

Exempel: Om du skapar en Translator-resurs i Azure-portalen med Resource region som Switzerland North och resursnamnet är my-swiss-n, är https://my-swiss-n.cognitiveservices.azure.comdin anpassade slutpunkt . Och en exempelbegäran om att översätta är:

// 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

Custom Translator är för närvarande inte tillgängligt i Schweiz.

Autentisering

Prenumerera på Translator eller flera tjänster i Azure AI-tjänster och använd din nyckel (tillgänglig i Azure-portalen) för att autentisera.

Det finns tre rubriker som du kan använda för att autentisera din prenumeration. Den här tabellen beskriver hur var och en används:

Sidhuvuden	beskrivning
Ocp-Apim-Subscription-Key	Använd med Azure AI-tjänstprenumeration om du skickar din hemliga nyckel. Värdet är Azure-hemlighetsnyckeln för din prenumeration på Translator.
Auktorisering	Använd med Azure AI-tjänstprenumeration om du skickar en autentiseringstoken. Värdet är ägartoken: `Bearer <token>`.
Ocp-Apim-Subscription-Region	Använd med flera tjänster och regionala translator-resurser. Värdet är regionen för multitjänstresursen eller den regionala translator-resursen. Det här värdet är valfritt när du använder en global translator-resurs.

Hemlig nyckel

Det första alternativet är att autentisera Ocp-Apim-Subscription-Key med huvudet. Lägg till huvudet i Ocp-Apim-Subscription-Key: <YOUR_SECRET_KEY> din begäran.

Autentisera med en global resurs

När du använder en global translator-resurs måste du inkludera en rubrik för att anropa Translator.

Sidhuvuden	beskrivning
Ocp-Apim-Subscription-Key	Värdet är Azure-hemlighetsnyckeln för din prenumeration på Translator.

Här är ett exempel på en begäran om att anropa Translator med hjälp av den globala translator-resursen

// 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?'}]"

Autentisera med en regional resurs

När du använder en regional translator-resurs finns det två rubriker som du behöver anropa Translator.

Sidhuvuden	beskrivning
Ocp-Apim-Subscription-Key	Värdet är Azure-hemlighetsnyckeln för din prenumeration på Translator.
Ocp-Apim-Subscription-Region	Värdet är regionen för translator-resursen.

Här är en exempelbegäran om att anropa Translator med hjälp av den regionala translatorresursen

// 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?'}]"

Autentisera med en resurs med flera tjänster

Med en resurs med flera tjänster kan du använda en enda API-nyckel för att autentisera begäranden för flera tjänster.

När du använder en hemlighetsnyckel för flera tjänster måste du inkludera två autentiseringshuvuden med din begäran. Det finns två rubriker som du behöver anropa Translator.

Sidhuvuden	beskrivning
Ocp-Apim-Subscription-Key	Värdet är Azure-hemlighetsnyckeln för din resurs med flera tjänster.
Ocp-Apim-Subscription-Region	Värdet är regionen för resursen för flera tjänster.

Region krävs för text-API-prenumerationen med flera tjänster. Den region du väljer är den enda region som du kan använda för textöversättning när du använder multitjänstnyckeln. Det måste vara samma region som du valde när du registrerade dig för din prenumeration med flera tjänster via Azure-portalen.

Om du skickar den hemliga nyckeln i frågesträngen med parametern Subscription-Keymåste du ange regionen med frågeparametern Subscription-Region.

Autentisera med en åtkomsttoken

Du kan också byta ut din hemliga nyckel mot en åtkomsttoken. Den här token ingår i varje begäran som Authorization rubrik. Om du vill hämta en auktoriseringstoken gör du en POST begäran till följande URL:

Resurstyp	URL för autentiseringstjänst
Global	`https://api.cognitive.microsoft.com/sts/v1.0/issueToken`
Regional eller flera tjänster	`https://<your-region>.api.cognitive.microsoft.com/sts/v1.0/issueToken`

Här är exempel på begäranden om att hämta en token med en hemlig nyckel för en global resurs:

// 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>'

Här är exempel på begäranden om att hämta en token med en hemlig nyckel för en regional resurs som finns i USA, centrala:

// 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>"

En lyckad begäran returnerar den kodade åtkomsttoken som oformaterad text i svarstexten. Den giltiga token skickas till Translator-tjänsten som en ägartoken i auktoriseringen.

Authorization: Bearer <Base64-access_token>

En autentiseringstoken är giltig i 10 minuter. Token ska återanvändas när du gör flera anrop till Translator. Men om programmet skickar begäranden till Translator under en längre tid måste programmet begära en ny åtkomsttoken med jämna mellanrum (till exempel var 8:e minut).

Autentisering med Microsoft Entra-ID

Translator v3.0 stöder Microsoft Entra-autentisering, Microsofts molnbaserade lösning för identitets- och åtkomsthantering. Med auktoriseringshuvuden kan Translator-tjänsten verifiera att den begärande klienten har behörighet att använda resursen och slutföra begäran.

Krav

En kort förståelse för hur du autentiserar med Microsoft Entra-ID.
En kort förståelse för hur du auktoriserar åtkomst till hanterade identiteter.

Rubriker

Header	Värde
Auktorisering	Värdet är en åtkomstbäraretoken som genereras av Azure AD. Ägartoken tillhandahåller autentiseringsbevis och validerar klientens auktorisering för att använda resursen. En autentiseringstoken är giltig i 10 minuter och bör återanvändas när du gör flera anrop till Translator. SeExempelbegäran: 2. Hämta en token
Ocp-Apim-Subscription-Region	Värdet är regionen för translator-resursen. Det här värdet är valfritt om resursen är global.
Ocp-Apim-ResourceId	Värdet är resurs-ID:t för din Translator-resursinstans. Du hittar resurs-ID:t i Azure-portalen på Translator Resource → Properties. Resurs-ID-format: /subscriptions/<subscriptionId>/resourceGroups/<resourceGroupName>/providers/Microsoft.CognitiveServices/accounts/<resourceName/>

Translator-egenskapssida – Azure-portalen

Skärmbild: Sidan Translator-egenskaper i Azure-portalen.

Exempel

Använda den globala slutpunkten

 // 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.'}]"

Använda din anpassade slutpunkt

// 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.'}]"

Exempel med hanterade identiteter

Translator v3.0 stöder också auktorisering av åtkomst till hanterade identiteter. Om en hanterad identitet är aktiverad för en translator-resurs kan du skicka ägartoken som genereras av hanterad identitet i begärandehuvudet.

Med den globala slutpunkten

// 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.'}]"

Med din anpassade slutpunkt

//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.'}]"

Stöd för virtuellt nätverk

Translator-tjänsten är nu tillgänglig med VNET-funktioner (Virtual Network) i alla regioner i det offentliga Azure-molnet. Information om hur du aktiverar virtuellt nätverk finns i Konfigurera virtuella Nätverk för Azure AI-tjänster.

När du aktiverar den här funktionen måste du använda den anpassade slutpunkten för att anropa Translator. Du kan inte använda den globala translator-slutpunkten ("api.cognitive.microsofttranslator.com") och du kan inte autentisera med en åtkomsttoken.

Du hittar den anpassade slutpunkten när du har skapat en translator-resurs och tillåter åtkomst från valda nätverk och privata slutpunkter.

Gå till din Translator-resurs i Azure-portalen.
Välj Nätverk i avsnittet Resurshantering .
Under fliken Brandväggar och virtuella nätverk väljer du Valda nätverk och privata slutpunkter.
Välj Spara för att tillämpa ändringarna.
Välj Nycklar och slutpunkt i avsnittet Resurshantering .
Välj fliken Virtuellt nätverk .
I listan finns slutpunkterna för textöversättning och dokumentöversättning.

Sidhuvuden	beskrivning
Ocp-Apim-Subscription-Key	Värdet är Azure-hemlighetsnyckeln för din prenumeration på Translator.
Ocp-Apim-Subscription-Region	Värdet är regionen för translator-resursen. Det här värdet är valfritt om resursen är `global`

Här är en exempelbegäran om att anropa Translator med hjälp av den anpassade slutpunkten

// 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?'}]"

Fel

Ett standardfelsvar är ett JSON-objekt med namn/värde-paret med namnet error. Värdet är också ett JSON-objekt med egenskaper:

code: En serverdefinierad felkod.
message: En sträng som ger en läsbar återgivning av felet.

En kund med en kostnadsfri utvärderingsprenumeration får till exempel följande fel när den kostnadsfria kvoten är slut:

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

Felkoden är ett 6-siffrigt tal som kombinerar den tresiffriga HTTP-statuskoden följt av ett tresiffrigt tal för att ytterligare kategorisera felet. Vanliga felkoder är:

Kod	beskrivning
400000	En av inmatningarna i begäran är ogiltig.
400001	Parametern "omfång" är ogiltig.
400002	Parametern "kategori" är ogiltig.
400003	En språkspecificerare saknas eller är ogiltig.
400004	En målskriptsspecificerare ("Till skript") saknas eller är ogiltig.
400005	En indatatext saknas eller är ogiltig.
400006	Kombinationen av språk och skript är ogiltig.
400018	En källskriptspecificerare ("Från skript") saknas eller är ogiltig.
400019	Ett av de angivna språken stöds inte.
400020	Ett av elementen i matrisen med indatatext är ogiltigt.
400021	API-versionsparametern saknas eller är ogiltig.
400023	Ett av de angivna språkparen är ogiltigt.
400035	Källspråket (fältet "Från") är ogiltigt.
400036	Målspråket (fältet "Till") saknas eller är ogiltigt.
400042	Ett av de angivna alternativen (fältet "Alternativ") är ogiltigt.
400043	Klientspårnings-ID (fältet ClientTraceId eller X-ClientTranceId-huvudet) saknas eller är ogiltigt.
400050	Indatatexten är för lång. Visa begärandebegränsningar.
400064	Parametern "översättning" saknas eller är ogiltig.
400070	Antalet målskript (parametern ToScript) matchar inte antalet målspråk (parametern Till).
400071	Värdet är inte giltigt för TextType.
400072	Matrisen med indatatext har för många element.
400073	Skriptparametern är ogiltig.
400074	Brödtexten i begäran är inte giltig JSON.
400075	Språkparet och kategorikombinationen är ogiltiga.
400077	Den maximala begärandestorleken har överskridits. Visa begärandebegränsningar.
400079	Det anpassade system som begärs för översättning mellan från-språket och till-språket finns inte.
400080	Transkribering stöds inte för språket eller skriptet.
401000	Begäran är inte auktoriserad eftersom autentiseringsuppgifter saknas eller är ogiltiga.
401015	"De angivna autentiseringsuppgifterna gäller för Speech-API:et. Den här begäran kräver autentiseringsuppgifter för text-API:et. Använd en prenumeration på Translator."
403000	Åtgärden är inte tillåten.
403001	Åtgärden tillåts inte eftersom prenumerationen har överskridit sin kostnadsfria kvot.
405000	Begärandemetoden stöds inte för den begärda resursen.
408001	Det begärda översättningssystemet förbereds. Försök igen om några minuter.
408002	Tidsgränsen för begäran uppnåddes i väntan på inkommande ström. Klienten har inte skapat en begäran inom den tid som servern var beredd att vänta. Klienten kan upprepa begäran utan ändringar vid ett senare tillfälle.
415000	Rubriken Innehållstyp saknas eller är ogiltig.
429000, 429001, 429002	Servern avvisade begäran eftersom klienten har överskridit begärandegränserna.
500000	Det uppstod ett oväntat fel. Om felet kvarstår rapporterar du det med datum/tid för fel, begärandeidentifierare från svarshuvudet X-RequestId och klientidentifierare från begärandehuvudet X-ClientTraceId.
503 000	Tjänsten är inte tillgänglig för tillfället. Försök igen. Om felet kvarstår rapporterar du det med datum/tid för fel, begärandeidentifierare från svarshuvudet X-RequestId och klientidentifierare från begärandehuvudet X-ClientTraceId.

Mått

Med mått kan du visa information om translator-användning och tillgänglighet i Azure-portalen under måttavsnittet som du ser i skärmbilden nedan. Mer information finns i Data- och plattformsmått.

Translator Metrics

Den här tabellen visar tillgängliga mått med en beskrivning av hur de används för att övervaka översättnings-API-anrop.

Metrics	beskrivning
TotalCalls	Totalt antal API-anrop.
TotalTokenCalls	Totalt antal API-anrop via tokentjänsten med hjälp av autentiseringstoken.
SuccessfulCalls	Antal lyckade anrop.
TotalErrors	Antal anrop med felsvar.
BlockedCalls	Antal anrop som överskred hastighets- eller kvotgränsen.
ServerErrors	Antal anrop med internt serverfel(5XX).
ClientErrors	Antal anrop med fel på klientsidan(4XX).
Svarstid	Varaktighet för att slutföra begäran i millisekunder.
TeckenÖversatt	Totalt antal tecken i inkommande textbegäran.