Använda REST-API:er programmatiskt
Dokumentöversättning är en molnbaserad funktion i Azure AI Translator-tjänsten . Du kan använda API:et för dokumentöversättning för att asynkront översätta hela dokument på språk som stöds och olika filformat samtidigt som källdokumentets struktur och textformatering bevaras . I den här instruktionsguiden lär du dig att använda API:er för dokumentöversättning med valfritt programmeringsspråk och HTTP REST API.
Förutsättningar
Kommentar
När du skapar en Azure AI-resurs i Azure-portalen kan du vanligtvis skapa en nyckel för flera tjänster eller en enskild tjänstnyckel. Dokumentöversättning stöds dock för närvarande endast i Translator-resursen (enskild tjänst) och ingår inte i Azure AI-tjänsternas resurs (flera tjänster).
Dokumentöversättning stöds endast i S1 Standard Service Plan (Betala per användning) eller I D3-volymrabattplanen. SePrissättning för Azure AI-tjänster – Translator.
Du behöver följande för att komma igång:
Ett aktivt Azure-konto. Om du inte har ett konto kan du skapa ett kostnadsfritt konto
Ett Azure Blob Storage-konto. Du måste också skapa containrar i ditt Azure Blob Storage-konto för dina käll- och målfiler:
- Källcontainer. I den här containern laddar du upp dina filer för översättning (krävs).
- Målcontainer. I den här containern lagras dina översatta filer (krävs).
En Translator-resurs med en enda tjänst (inte en Azure AI-tjänstresurs med flera tjänster):
Fyll i fälten Translator-projekt- och instansinformation på följande sätt:
Prenumeration. Välj en av dina tillgängliga Azure-prenumerationer.
Resursgrupp. Du kan skapa en ny resursgrupp eller lägga till resursen i en befintlig resursgrupp som delar samma livscykel, behörigheter och principer.
Resursregion. Välj Global om inte ditt företag eller program kräver en viss region. Om du planerar att använda en systemtilldelad hanterad identitet för autentisering väljer du en geografisk region som USA, västra.
Namn. Ange det namn som du valde för resursen. Namnet du väljer måste vara unikt i Azure.
Kommentar
Dokumentöversättning kräver en anpassad domänslutpunkt. Värdet som du anger i fältet Namn är den anpassade domännamnsparametern för slutpunkten.
Prisnivå. Dokumentöversättning stöds inte på den kostnadsfria nivån. Om du vill prova tjänsten väljer du Standard S1.
Välj Granska + skapa.
Granska tjänstvillkoren och välj Skapa för att distribuera resursen.
När resursen har distribuerats väljer du Gå till resurs för att hämta nyckeln och slutpunkten.
Hämta din nyckel och din anpassade domänslutpunkt
- Begäranden till Translator-tjänsten kräver en skrivskyddad nyckel och en anpassad slutpunkt för att autentisera åtkomsten. Den anpassade domänslutpunkten är en URL som är formaterad med resursnamnet, värdnamnet och Translator-underkatalogerna och är tillgänglig i Azure-portalen.
Om du har skapat en ny resurs väljer du Gå till resurs när den har distribuerats. Om du har en befintlig dokumentöversättningsresurs går du direkt till resurssidan.
Välj Nycklar och slutpunkt under Resurshantering i det vänstra spåret.
Kopiera och klistra in och
keydocument translation endpointpå en lämplig plats, till exempel Microsoft Anteckningar. Endast en nyckel krävs för att göra ett API-anrop.Du
keyochdocument translation endpointi kodexemplen för att autentisera din begäran till dokumentöversättningstjänsten.
Hämta din nyckel
Begäranden till Translator-tjänsten kräver en skrivskyddad nyckel för autentisering av åtkomst.
- Om du har skapat en ny resurs väljer du Gå till resurs när den har distribuerats. Om du har en befintlig dokumentöversättningsresurs går du direkt till resurssidan.
- Välj Nycklar och slutpunkt under Resurshantering i det vänstra spåret.
- Kopiera och klistra in din nyckel på en lämplig plats, till exempel Microsoft Anteckningar.
- Du klistrar in den i kodexemplet för att autentisera din begäran till dokumentöversättningstjänsten.
Skapa Azure Blob Storage-containrar
Du måste skapa containrar i ditt Azure Blob Storage-konto för käll- och målfiler.
- Källcontainer. I den här containern laddar du upp dina filer för översättning (krävs).
- Målcontainer. I den här containern lagras dina översatta filer (krävs).
Kommentar
Dokumentöversättning stöder ordlistor som blobar i målcontainrar (inte separata ordlistecontainrar). Om du vill inkludera en anpassad ordlista lägger du till den i målcontainern och inkluderar glossaryUrl med begäran. Om översättningsspråkparet inte finns i ordlistan tillämpas det inte. SeÖversätta dokument med hjälp av en anpassad ordlista
Skapa SAS-åtkomsttoken för dokumentöversättning
Den sourceUrl valfria glossaryUrl , targetUrl och måste innehålla en SAS-token (Signatur för delad åtkomst), som läggs till som en frågesträng. Token kan tilldelas till din container eller specifika blobar. SeSkapa SAS-token för dokumentöversättningsprocessen.
- Källcontainern eller bloben måste ange läs- och liståtkomst.
- Målcontainern eller bloben måste ange skriv- och liståtkomst.
- Ordlistebloben måste ange läs- och liståtkomst.
Dricks
- Om du översätter flera filer (blobar) i en åtgärd delegerar du SAS-åtkomst på containernivå.
- Om du översätter en enskild fil (blob) i en åtgärd delegerar du SAS-åtkomst på blobnivå.
- Som ett alternativ till SAS-token kan du använda en systemtilldelad hanterad identitet för autentisering.
HTTP-begäranden
En asynkron batchöversättningsbegäran skickas till translator-tjänstslutpunkten via en POST-begäran. Om det lyckas returnerar POST-metoden en 202 Accepted svarskod och tjänsten skapar en batchbegäran. De översatta dokumenten visas i målcontainern.
Detaljerad information om begränsningar för Azure AI Translator Service-begäranden finns iBegränsningar för begäran om dokumentöversättning.
HTTP-rubriker
Följande rubriker ingår i varje BEGÄRAN om API för dokumentöversättning:
| HTTP-huvud | beskrivning |
|---|---|
| Ocp-Apim-Subscription-Key | Obligatoriskt: Värdet är Azure-nyckeln för din Translator- eller Azure AI-tjänstresurs. |
| Innehållstyp | Obligatoriskt: Anger innehållstypen för nyttolasten. Godkända värden är application/json eller charset=UTF-8. |
Egenskaper för POST-begärandetext
- URL:en för POST-begäran är POST
https://<NAME-OF-YOUR-RESOURCE>.cognitiveservices.azure.com/translator/text/batch/v1.1/batches. - POST-begärandetexten är ett JSON-objekt med namnet
inputs. - Objektet
inputsinnehåller bådesourceURLochtargetURLcontaineradresser för dina käll- och målspråkpar. - Och
prefixsuffixär skiftlägeskänsliga strängar för att filtrera dokument i källsökvägen för översättning. Fältetprefixanvänds ofta för att definiera undermappar för översättning. Fältetsuffixanvänds oftast för filnamnstillägg. - Ett värde för fältet
glossaries(valfritt) tillämpas när dokumentet översätts. - För
targetUrlvarje målspråk måste vara unikt.
Kommentar
Om det redan finns en fil med samma namn i målet misslyckas jobbet.
Översätta alla dokument i en container
{
"inputs": [
{
"source": {
"sourceUrl": "{sourceSASUrl}"
},
"targets": [
{
"targetUrl": "{targetSASUrl}",
"language": "fr"
}
]
}
]
}
Översätta ett visst dokument i en container
- Ange
"storageType": "File". - Om du inte använder en systemtilldelad hanterad identitet för autentisering kontrollerar du att du har skapat käll-URL:en och SAS-token för den specifika bloben/dokumentet (inte för containern).
- Se till att du har angett målfilnamnet som en del av mål-URL:en, även om SAS-token fortfarande är för containern.
- Den här exempelbegäran returnerar ett enda dokument som översätts till två målspråk.
{
"inputs": [
{
"storageType": "File",
"source": {
"sourceUrl": "{sourceSASUrl}"
},
"targets": [
{
"targetUrl": "{targetSASUrl}",
"language": "es"
},
{
"targetUrl": "{targetSASUrl}",
"language": "de"
}
]
}
]
}
Översätta dokument med hjälp av en anpassad ordlista
{
"inputs": [
{
"source": {
"sourceUrl": "{sourceSASUrl}"
},
"targets": [
{
"targetUrl": "{targetSASUrl}",
"language": "es",
"glossaries": [
{
"glossaryUrl": "{glossaryUrl/en-es.xlf}",
"format": "xliff"
}
]
}
]
}
]
}
Använda kod för att skicka begäranden om dokumentöversättning
Konfigurera din kodningsplattform
- Skapa ett nytt projekt.
- Ersätt Program.cs med C#-kodexemplet.
- Ange värdena för slutpunkt, nyckel och container-URL i Program.cs.
- Lägg till Newtonsoft.Json-paketet med .NET CLI för bearbetning av JSON-data.
- Kör programmet från projektkatalogen.
Viktigt!
För kodexemplen hårdkodar du din SAS-URL (Signatur för delad åtkomst) där det anges. Kom ihåg att ta bort SAS-URL:en från koden när du är klar och publicera den aldrig offentligt. För produktion använder du ett säkert sätt att lagra och komma åt dina autentiseringsuppgifter som Azure Managed Identity. Mer information finns i Azure Storage-säkerhet.
Du kan behöva uppdatera följande fält beroende på åtgärden:
endpointkeysourceURLtargetURLglossaryURLid(jobb-ID)
Hitta värdet id
- Du hittar jobbet
idi POST-metodensstart-batch-translationsvarshuvud-URL-värdeOperation-Location. Den alfanumeriska strängen som följer parametern/document/är åtgärdens jobbid:
| Svarsrubrik | Svars-URL |
|---|---|
| Åtgärdsplats | {document-translation-endpoint}/translator/document/9dce0aa9-78dc-41ba-8cae-2e2f3c2ff8ec?api-version=2024-05-01 |
- Du kan också använda en begäran om get-translations-status för att hämta en lista över översättningsjobboch deras.
id
Översätta dokument
using System;
using System.Net.Http;
using System.Threading.Tasks;
using System.Text;
class Program
{
static readonly string route = "/batches";
private static readonly string endpoint = "https://<NAME-OF-YOUR-RESOURCE>.cognitiveservices.azure.com/translator/text/batch/v1.1";
private static readonly string key = "<YOUR-KEY>";
static readonly string json = ("{\"inputs\": [{\"source\": {\"sourceUrl\": \"https://YOUR-SOURCE-URL-WITH-READ-LIST-ACCESS-SAS\",\"storageSource\": \"AzureBlob\",\"language\": \"en\"}, \"targets\": [{\"targetUrl\": \"https://YOUR-TARGET-URL-WITH-WRITE-LIST-ACCESS-SAS\",\"storageSource\": \"AzureBlob\",\"category\": \"general\",\"language\": \"es\"}]}]}");
static async Task Main(string[] args)
{
using HttpClient client = new HttpClient();
using HttpRequestMessage request = new HttpRequestMessage();
{
StringContent content = new StringContent(json, Encoding.UTF8, "application/json");
request.Method = HttpMethod.Post;
request.RequestUri = new Uri(endpoint + route);
request.Headers.Add("Ocp-Apim-Subscription-Key", key);
request.Content = content;
HttpResponseMessage response = await client.SendAsync(request);
string result = response.Content.ReadAsStringAsync().Result;
if (response.IsSuccessStatusCode)
{
Console.WriteLine($"Status code: {response.StatusCode}");
Console.WriteLine();
Console.WriteLine($"Response Headers:");
Console.WriteLine(response.Headers);
}
else
Console.Write("Error");
}
}
}
Hämta filformat
Hämta en lista över filformat som stöds. Om det lyckas returnerar den här metoden en 200 OK svarskod.
using System;
using System.Net.Http;
using System.Threading.Tasks;
class Program
{
private static readonly string endpoint = "https://<NAME-OF-YOUR-RESOURCE>.cognitiveservices.azure.com/translator/text/batch/v1.1";
static readonly string route = "/documents/formats";
private static readonly string key = "<YOUR-KEY>";
static async Task Main(string[] args)
{
HttpClient client = new HttpClient();
using HttpRequestMessage request = new HttpRequestMessage();
{
request.Method = HttpMethod.Get;
request.RequestUri = new Uri(endpoint + route);
request.Headers.Add("Ocp-Apim-Subscription-Key", key);
HttpResponseMessage response = await client.SendAsync(request);
string result = response.Content.ReadAsStringAsync().Result;
Console.WriteLine($"Status code: {response.StatusCode}");
Console.WriteLine($"Response Headers: {response.Headers}");
Console.WriteLine();
Console.WriteLine(result);
}
}
Hämta jobbstatus
Hämta aktuell status för ett enskilt jobb och en sammanfattning av alla jobb i en begäran om dokumentöversättning. Om det lyckas returnerar den här metoden en 200 OK svarskod.
using System;
using System.Net.Http;
using System.Threading.Tasks;
class Program
{
private static readonly string endpoint = "https://<NAME-OF-YOUR-RESOURCE>.cognitiveservices.azure.com/translator/text/batch/v1.1";
static readonly string route = "/batches/{id}";
private static readonly string key = "<YOUR-KEY>";
static async Task Main(string[] args)
{
HttpClient client = new HttpClient();
using HttpRequestMessage request = new HttpRequestMessage();
{
request.Method = HttpMethod.Get;
request.RequestUri = new Uri(endpoint + route);
request.Headers.Add("Ocp-Apim-Subscription-Key", key);
HttpResponseMessage response = await client.SendAsync(request);
string result = response.Content.ReadAsStringAsync().Result;
Console.WriteLine($"Status code: {response.StatusCode}");
Console.WriteLine($"Response Headers: {response.Headers}");
Console.WriteLine();
Console.WriteLine(result);
}
}
}
Hämta dokumentstatus
Kort översikt
Hämta status för ett visst dokument i en begäran om dokumentöversättning. Om det lyckas returnerar den här metoden en 200 OK svarskod.
using System;
using System.Net.Http;
using System.Threading.Tasks;
class Program
{
private static readonly string endpoint = "https://<NAME-OF-YOUR-RESOURCE>.cognitiveservices.azure.com/translator/text/batch/v1.1";
static readonly string route = "/{id}/document/{documentId}";
private static readonly string key = "<YOUR-KEY>";
static async Task Main(string[] args)
{
HttpClient client = new HttpClient();
using HttpRequestMessage request = new HttpRequestMessage();
{
request.Method = HttpMethod.Get;
request.RequestUri = new Uri(endpoint + route);
request.Headers.Add("Ocp-Apim-Subscription-Key", key);
HttpResponseMessage response = await client.SendAsync(request);
string result = response.Content.ReadAsStringAsync().Result;
Console.WriteLine($"Status code: {response.StatusCode}");
Console.WriteLine($"Response Headers: {response.Headers}");
Console.WriteLine();
Console.WriteLine(result);
}
}
Ta bort jobb
Kort översikt
Avbryt bearbetningen eller det köade jobbet. Endast dokument för vilka översättningen inte startas avbryts.
using System;
using System.Net.Http;
using System.Threading.Tasks;
class Program
{
private static readonly string endpoint = "https://<NAME-OF-YOUR-RESOURCE>.cognitiveservices.azure.com/translator/text/batch/v1.1";
static readonly string route = "/batches/{id}";
private static readonly string key = "<YOUR-KEY>";
static async Task Main(string[] args)
{
HttpClient client = new HttpClient();
using HttpRequestMessage request = new HttpRequestMessage();
{
request.Method = HttpMethod.Delete;
request.RequestUri = new Uri(endpoint + route);
request.Headers.Add("Ocp-Apim-Subscription-Key", key);
HttpResponseMessage response = await client.SendAsync(request);
string result = response.Content.ReadAsStringAsync().Result;
Console.WriteLine($"Status code: {response.StatusCode}");
Console.WriteLine($"Response Headers: {response.Headers}");
Console.WriteLine();
Console.WriteLine(result);
}
}
Vanliga HTTP-statuskoder
| HTTP-statuskod | beskrivning | Möjlig orsak |
|---|---|---|
| 200 | OK | Begäran lyckades. |
| 400 | Felaktig förfrågan | En obligatorisk parameter saknas, är tom eller null. Eller så är värdet som skickas till en obligatorisk eller valfri parameter ogiltigt. Ett vanligt problem är en rubrik som är för lång. |
| 401 | Behörighet saknas | Begäran är inte auktoriserad. Kontrollera att din nyckel eller token är giltig och i rätt region. När du hanterar din prenumeration på Azure-portalen kontrollerar du att du använder translator-resursen för en enda tjänst, inte Azure AI-tjänsternas multitjänstresurs. |
| 429 | För många begäranden | Du har överskridit kvoten eller antalet begäranden som tillåts för din prenumeration. |
| 502 | Felaktig gateway | Problem på nätverks- eller serversidan. Kan också ange ogiltiga rubriker. |
Läs mer
Nästa steg
Feedback
Kommer snart: Under hela 2024 kommer vi att fasa ut GitHub-problem som feedbackmekanism för innehåll och ersätta det med ett nytt feedbacksystem. Mer information finns i: https://aka.ms/ContentUserFeedback.
Skicka och visa feedback för