REST API's programmatisch gebruiken
Documentomzetting is een cloudfunctie van de Azure AI Translator-service . U kunt de Documentomzettings-API gebruiken om hele documenten asynchroon te vertalen in ondersteunde talen en verschillende bestandsindelingen , terwijl de brondocumentstructuur en tekstopmaak behouden blijven. In deze handleiding leert u hoe u API's voor documentomzetting gebruikt met een programmeertaal van uw keuze en de HTTP REST API.
Vereisten
Notitie
Documentomzetting wordt ondersteund in het S1 Standard-serviceplan (betalen per gebruik) en C2, C3, C4 en D3 Volumekortingsplannen. Zie prijzen voor Azure AI-services: Translator.
Om aan de slag te gaan, hebt u het volgende nodig:
Een actief Azure-account. Als u nog geen account hebt, kunt u een gratis account maken
Een Azure Blob Storage-account. U moet ook containers maken in uw Azure Blob Storage-account voor uw bron- en doelbestanden:
- Broncontainer. In deze container uploadt u uw bestanden voor vertaling (vereist).
- Doelcontainer. In deze container worden uw vertaalde bestanden opgeslagen (vereist).
-
Voltooi de velden translator-project- en exemplaardetails als volgt:
Abonnement. Selecteer een van uw beschikbare Azure-abonnementen.
Resourcegroep. U kunt een nieuwe resourcegroep maken of uw resource toevoegen aan een bestaande resourcegroep die dezelfde levenscyclus, machtigingen en beleidsregels deelt.
Resourceregio. Kies Globaal , tenzij uw bedrijf of toepassing een specifieke regio vereist. Als u van plan bent om een door het systeem toegewezen beheerde identiteit te gebruiken voor verificatie, kiest u een geografische regio, zoals VS - west.
Name. Voer de naam in die u voor uw resource hebt gekozen. De naam die u kiest, moet uniek zijn binnen Azure.
Notitie
Documentomzetting vereist een aangepast domeineindpunt. De waarde die u invoert in het veld Naam, is de parameter voor de aangepaste domeinnaam voor uw eindpunt.
Prijscategorie. Documentomzetting wordt niet ondersteund in de gratis laag. Als u de service wilt proberen, selecteert u Standard S1.
Selecteer Controleren + maken.
Controleer de servicevoorwaarden en selecteer Maken om uw resource te implementeren.
Nadat uw resource is geïmplementeerd, selecteert u Ga naar de resource om uw sleutel en eindpunt op te halen.
Uw sleutel en aangepast domeineindpunt ophalen
- Aanvragen voor de Translator-service vereisen een alleen-lezen sleutel en een aangepast eindpunt om toegang te verifiëren. Het eindpunt van het aangepaste domein is een URL die is opgemaakt met uw resourcenaam, hostnaam en Translator-submappen en is beschikbaar in Azure Portal.
Als u een nieuwe resource hebt gemaakt nadat deze is geïmplementeerd, selecteert u Ga naar de resource. Als u een bestaande documentomzettingsresource hebt, gaat u rechtstreeks naar de resourcepagina.
Selecteer sleutels en eindpunt in de linkerrail onder Resourcebeheer.
Kopieer en plak uw
keyendocument translation endpointop een handige locatie, zoals Microsoft Kladblok. Er is slechts één sleutel nodig om een API-aanroep te maken.U
keyendocument translation endpointin de codevoorbeelden om uw aanvraag te verifiëren bij de service Documentvertaling.
Uw sleutel ophalen
Aanvragen voor de Translator-service vereisen een alleen-lezen sleutel voor het verifiëren van toegang.
- Als u een nieuwe resource hebt gemaakt nadat deze is geïmplementeerd, selecteert u Ga naar de resource. Als u een bestaande documentomzettingsresource hebt, gaat u rechtstreeks naar de resourcepagina.
- Selecteer sleutels en eindpunt in de linkerrail onder Resourcebeheer.
- Kopieer en plak uw sleutel op een handige locatie, zoals Microsoft Kladblok.
- U plakt deze in het codevoorbeeld om uw aanvraag te verifiëren bij de documentomzettingsservice.
Azure Blob Storage-containers maken
U moet containers maken in uw Azure Blob Storage-account voor bron- en doelbestanden.
- Broncontainer. In deze container uploadt u uw bestanden voor vertaling (vereist).
- Doelcontainer. In deze container worden uw vertaalde bestanden opgeslagen (vereist).
Notitie
Documentomzetting ondersteunt woordenlijsten als blobs in doelcontainers (geen afzonderlijke woordenlijstcontainers). Als u een aangepaste woordenlijst wilt opnemen, voegt u deze toe aan de doelcontainer en neemt u deze glossaryUrl op met de aanvraag. Als het vertaaltaalpaar niet aanwezig is in de woordenlijst, wordt deze niet toegepast. Zie Documenten vertalen met behulp van een aangepaste woordenlijst
SAS-toegangstokens maken voor documentomzetting
Het sourceUrl , targetUrl en optioneel glossaryUrl moet een SAS-token (Shared Access Signature) bevatten, toegevoegd als een querytekenreeks. Het token kan worden toegewezen aan uw container of specifieke blobs. Zie SAS-tokens maken voor documentomzettingsproces.
- Uw broncontainer of -blob moet lees- en lijsttoegang aanwijzen.
- Uw doelcontainer of blob moet schrijf- en lijsttoegang aanwijzen.
- De woordenlijst-blob moet lees- en lijsttoegang aanwijzen.
Tip
- Als u meerdere bestanden (blobs) in een bewerking vertaalt, delegeert u SAS-toegang op containerniveau.
- Als u één bestand (blob) in een bewerking vertaalt, delegeert u SAS-toegang op blobniveau.
- Als alternatief voor SAS-tokens kunt u een door het systeem toegewezen beheerde identiteit gebruiken voor verificatie.
HTTP-aanvragen
Een asynchrone batchomzettingsaanvraag wordt via een POST-aanvraag verzonden naar uw Translator-service-eindpunt. Als dit lukt, retourneert de POST-methode een 202 Accepted antwoordcode en maakt de service een batchaanvraag. De vertaalde documenten worden weergegeven in uw doelcontainer.
Zie Aanvraaglimieten voor documentomzetting voor gedetailleerde informatie over aanvraaglimieten voor Azure AI Translator Service.
HTTP-kopteksten
De volgende headers zijn opgenomen in elke api-aanvraag voor documentomzetting:
| HTTP-header | Beschrijving |
|---|---|
| Ocp-Apim-Subscription-Key | Vereist: De waarde is de Azure-sleutel voor uw Translator- of Azure AI-servicesresource. |
| Inhoudstype | Vereist: Hiermee geeft u het inhoudstype van de nettolading op. Geaccepteerde waarden zijn application/json of charset=UTF-8. |
Eigenschappen van post-aanvraagbody
- De URL van de POST-aanvraag is POST
https://<NAME-OF-YOUR-RESOURCE>.cognitiveservices.azure.com/translator/text/batch/v1.1/batches. - De hoofdtekst van de POST-aanvraag is een JSON-object met de naam
inputs. - Het
inputsobject bevat zowel containeradressensourceURLvoor de bron- alstargetURLdoeltaalparen. - De
prefixensuffixzijn hoofdlettergevoelige tekenreeksen voor het filteren van documenten in het bronpad voor vertaling. Hetprefixveld wordt vaak gebruikt om submappen voor vertaling af te bakenen. Hetsuffixveld wordt meestal gebruikt voor bestandsextensies. - Er wordt een waarde voor het
glossariesveld (optioneel) toegepast wanneer het document wordt vertaald. - De
targetUrlvoor elke doeltaal moet uniek zijn.
Notitie
Als er al een bestand met dezelfde naam in de bestemming bestaat, mislukt de taak.
Alle documenten in een container vertalen
{
"inputs": [
{
"source": {
"sourceUrl": "{sourceSASUrl}"
},
"targets": [
{
"targetUrl": "{targetSASUrl}",
"language": "fr"
}
]
}
]
}
Een specifiek document vertalen in een container
- Geef
"storageType": "File"op. - Als u geen door het systeem toegewezen beheerde identiteit gebruikt voor verificatie, moet u ervoor zorgen dat u bron-URL en SAS-tokens hebt gemaakt voor de specifieke blob/het document (niet voor de container).
- Zorg ervoor dat u de bestandsnaam van het doel hebt opgegeven als onderdeel van de doel-URL, hoewel het SAS-token nog steeds voor de container is.
- Met deze voorbeeldaanvraag wordt één document geretourneerd dat in twee doeltalen is vertaald.
{
"inputs": [
{
"storageType": "File",
"source": {
"sourceUrl": "{sourceSASUrl}"
},
"targets": [
{
"targetUrl": "{targetSASUrl}",
"language": "es"
},
{
"targetUrl": "{targetSASUrl}",
"language": "de"
}
]
}
]
}
Documenten vertalen met behulp van een aangepaste woordenlijst
{
"inputs": [
{
"source": {
"sourceUrl": "{sourceSASUrl}"
},
"targets": [
{
"targetUrl": "{targetSASUrl}",
"language": "es",
"glossaries": [
{
"glossaryUrl": "{glossaryUrl/en-es.xlf}",
"format": "xliff"
}
]
}
]
}
]
}
🆕 Tekst vertalen die is ingesloten in afbeeldingen in documenten
Notitie
- Deze functie is optioneel en moet zijn ingeschakeld voor elke vertaalaanvraag.
- Als u deze functie inschakelt, worden extra kosten in rekening gebracht op basis van het gebruik. Zie Prijzen voor Azure AI Vision voor meer informatie
- Deze functie is momenteel alleen beschikbaar met de Batch Document Translation-API.
- De ondersteunde bestandsindeling is
.docxalleen beschikbaar. - Er is een Azure AI Services-resource (niet de zelfstandige Translator-resource) vereist om deze functie te kunnen gebruiken.
Aanvraagconfiguratie
De optionele
translateTextWithinImageparameter in hetoptionsveld gebruiken- Gegevenstype: Booleaanse waarde (
trueoffalse) - De standaard booleaanse instelling is
false. Stel de optie in omtruetekstomzetting van afbeeldingen in te schakelen.
- Gegevenstype: Booleaanse waarde (
Antwoorddetails. Wanneer de functie is ingeschakeld, worden toegevoegde informatie over afbeeldingsverwerking opgenomen in het antwoord:
totalImageScansSucceeded. Het aantal geslaagde scans van afbeeldingen.totalImageScansFailed. Het aantal scans van afbeeldingen dat de verwerking is mislukt.
Code gebruiken om aanvragen voor documentomzetting in te dienen
Uw coderingsplatform instellen
- Een nieuw project maken.
- Vervang Program.cs door het C#-codevoorbeeld.
- Stel uw eindpunt-, sleutel- en container-URL-waarden in Program.cs in.
- Voeg het Newtonsoft.Json-pakket toe met behulp van .NET CLI voor het verwerken van JSON-gegevens.
- Voer het programma uit vanuit de projectmap.
Belangrijk
Voor de codevoorbeelden code codet u de SAS-URL (Shared Access Signature) waar aangegeven. Vergeet niet om de SAS-URL uit uw code te verwijderen wanneer u klaar bent en deze nooit openbaar te plaatsen. Gebruik voor productie een veilige manier om uw referenties op te slaan en te openen, zoals Azure Managed Identity. Zie Azure Storage-beveiliging voor meer informatie.
Mogelijk moet u de volgende velden bijwerken, afhankelijk van de bewerking:
endpointbasePathkeysourceURLtargetURLglossaryURLid(taak-id)
id De waarde zoeken
- U vindt de taak
idin de URL-waarde van de POST-methode-antwoordheaderstart-batch-translationOperation-Location. De alfanumerieke tekenreeks na de/document/parameter is de taakidvan de bewerking:
| Antwoordheader | Antwoord-URL |
|---|---|
| Operation-Location | {document-translation-endpoint}/translator/document/9dce0aa9-78dc-41ba-8cae-2e2f3c2ff8ec?api-version={date} |
- U kunt ook een get-translation-statusaanvraag gebruiken om een lijst met vertaaltaken en hun
idtaken op te halen.
Asynchrone batchomzetting starten
using System;
using System.Net.Http;
using System.Threading.Tasks;
using System.Text;
class Program
{
static readonly string route = "?api-version={date}";
private static readonly string basePath = "{your-document-translation-endpoint}/translator/document/batches";
private static readonly string key = "{your-api-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(basePath + 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");
}
}
}
De ondersteunde documentindelingen ophalen
Een lijst met ondersteunde bestandsindelingen ophalen. Als dit lukt, retourneert deze methode een 200 OK antwoordcode.
using System;
using System.Net.Http;
using System.Threading.Tasks;
class Program
{
private static readonly string basePath = "{your-document-translation-endpoint}/translator/document/formats";
static readonly string route = "?api-version={date}&type=document";
private static readonly string key = "{your-api-key}";
static async Task Main(string[] args)
{
HttpClient client = new HttpClient();
using HttpRequestMessage request = new HttpRequestMessage();
{
request.Method = HttpMethod.Get;
request.RequestUri = new Uri(basePath + 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);
}
}
Status ophalen voor een vertaaltaak
De huidige status voor één taak en een overzicht van alle taken in een aanvraag voor documentomzetting ophalen. Als dit lukt, retourneert deze methode een 200 OK antwoordcode.
using System;
using System.Net.Http;
using System.Threading.Tasks;
class Program
{
private static readonly string basePath = "{your-document-translation-endpoint}/translator/document/batches/{id}";
static readonly string route = "?api-version={date}";
private static readonly string key = "{your-api-key}";
static async Task Main(string[] args)
{
HttpClient client = new HttpClient();
using HttpRequestMessage request = new HttpRequestMessage();
{
request.Method = HttpMethod.Get;
request.RequestUri = new Uri(basePath + 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);
}
}
}
Status ophalen voor een specifiek document
Kort overzicht
Haal de status voor een specifiek document op in een aanvraag voor documentomzetting. Als dit lukt, retourneert deze methode een 200 OK antwoordcode.
using System;
using System.Net.Http;
using System.Threading.Tasks;
class Program
{
private static readonly string basePath = "{document-translation-endpoint}/translator/document/batches/{id}/documents/{documentId}";
static readonly string route = "?api-version={date}";
private static readonly string key = "{your-api-key}";
static async Task Main(string[] args)
{
HttpClient client = new HttpClient();
using HttpRequestMessage request = new HttpRequestMessage();
{
request.Method = HttpMethod.Get;
request.RequestUri = new Uri(basePath + 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);
}
}
Taak verwijderen
Kort overzicht
Annuleer momenteel de verwerking of wachtrijtaak. Alleen documenten waarvoor de vertaling niet is gestart, worden geannuleerd.
using System;
using System.Net.Http;
using System.Threading.Tasks;
class Program
{
private static readonly string basePath = "{your-document-translation-endpoint}/translator/document/batches/{id}";
static readonly string route = "?api-version={date}";
private static readonly string key = "{your-api-key}";
static async Task Main(string[] args)
{
HttpClient client = new HttpClient();
using HttpRequestMessage request = new HttpRequestMessage();
{
request.Method = HttpMethod.Delete;
request.RequestUri = new Uri(basePath + 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);
}
}
Algemene HTTP-statuscodes
| HTTP-statuscode | Beschrijving | Mogelijke reden |
|---|---|---|
| 200 | OK | De aanvraag is geslaagd. |
| 400 | Onjuiste aanvraag | Een vereiste parameter ontbreekt, leeg of null. Of de waarde die is doorgegeven aan een vereiste of optionele parameter, is ongeldig. Een veelvoorkomend probleem is een header die te lang is. |
| 401 | Niet geautoriseerd | De aanvraag is niet geautoriseerd. Controleer of uw sleutel of token geldig is en zich in de juiste regio bevindt. |
| 429 | Te veel aanvragen | U hebt het quotum of de frequentie van aanvragen overschreden die zijn toegestaan voor uw abonnement. |
| 502 | Ongeldige gateway | Probleem aan de netwerk- of serverzijde. Kan ook ongeldige headers aangeven. |