Translator v3.0

Nyheter

Version 3 av Translator tillhandahåller ett modernt JSON-baserat webb-API. Det förbättrar användbarhet och prestanda genom att konsolidera befintliga funktioner i 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 bakåtöversättningar och exempel som visar termer som används i kontexten.
• Mer informativa språkidentifieringsresultat.

Bas-URL:er

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

Om du vill tvinga begäran att hanteras inom ett visst geografiskt område använder du önskad geografisk slutpunkt. Alla begäranden bearbetas mellan datacentren inom geografin.

¹ Kunder med en resurs i Schweiz, norra eller Schweiz, västra kan se till att deras API-begäranden via text betjänas i Schweiz. För att säkerställa att begäranden hanteras i Schweiz skapar du Translator-resursen i "Resursregion" "Schweiz, norra" eller "Schweiz, västra" och använder sedan resursens anpassade slutpunkt i dina API-begäranden. Exempel: Om du skapar en Translator-resurs i Azure Portal med "Resursregion" som "Schweiz, norra" och resursnamnet är "my-ch-n", är din anpassade slutpunkt " https://my-ch-n.cognitiveservices.azure.com ". Och en exempelbegäran för översättning är:

// Pass secret key and region using headers to a custom endpoint
curl -X POST " my-ch-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

² Anpassade Translator är för närvarande inte tillgängliga i Schweiz.

Autentisering

Prenumerera på Translator eller Cognitive Services flera tjänster i Azure Cognitive Services och använd din prenumerationsnyckel (finns i Azure Portal) för att autentisera.

Det finns tre huvuden som du kan använda för att autentisera din prenumeration. I den här tabellen beskrivs hur var och en används:

Hemlig nyckel

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

Autentisera med en global resurs

När du använder en global översättningsresursmåste du inkludera en rubrik för att anropa Translator.

Här är ett exempel på en begäran om att anropa Translator med hjälp av den globala översättningsresursen

// 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. Det finns två huvuden som du behöver för att anropa Translator.

Här är ett exempel på en begäran om att anropa Translator med hjälp av den regionala översättningsresursen

// 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 för flera tjänster

När du använder en Cognitive Service-resurs för flera tjänster. På så sätt kan du använda en enda hemlig nyckel för att autentisera begäranden för flera tjänster.

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

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

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

Autentisera med en åtkomsttoken

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

Här är exempel på begäranden om att hämta en token givet en hemlig nyckel:

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

En lyckad begäran returnerar den kodade åtkomsttoken som oformaterad text i svarstexten. Den giltiga token skickas till Translator tjänsten som en bearer-token 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 gör begäranden till Translator under en längre tidsperiod måste programmet begära en ny åtkomsttoken med jämna mellanrum (t.ex. var 8:e minut).

Autentisering med Azure Active Directory (Azure AD)

Translator v3.0 har stöd för Azure AD-autentisering, Microsofts molnbaserade lösning för identitets- och åtkomsthantering. Auktoriseringshuvuden gör att Translator kan verifiera att den begärande klienten har behörighet att använda resursen och att slutföra begäran.

Förutsättningar

• En kort förståelse för hur du autentiserar med Azure Active Directory.

• En kort förståelse för hur du auktoriserar åtkomst till hanterade identiteter.

Sidhuvuden

Translator egenskapssida – Azure Portal

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/translator/text/v3.0/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 har aktiverats för en översättningsresurs kan du skicka den bearer-token som genererats av en 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/translator/text/v3.0/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

Tjänsten Translator är nu tillgänglig med Virtual Network (VNET) i alla regioner i det offentliga Azure-molnet. Information om hur Virtual Network finns i Konfigurera Azure Cognitive Services virtuella nätverk.

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 översättningsslutpunkten ("api.cognitive.microsofttranslator.com") och du kan inte autentisera med en åtkomsttoken.

Du hittar den anpassade slutpunkten när du har skapat en översättningsresurs och tillåt åtkomst från valda nätverk och privata slutpunkter.

Här är ett exempel på en begä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-par 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 representation av felet.

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

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

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

Mått

Med mått kan du visa användnings- och tillgänglighetsinformationen för translator i Azure Portal under måttavsnittet som visas på skärmbilden nedan. Mer information finns i Data- och plattformsmått.

I den här tabellen visas tillgängliga mått med en beskrivning av hur de används för att övervaka API-anrop för översättning.