Vertalen v3.0

Artikel
02/14/2024

Wat is er nieuw?

Versie 3.0 van de Vertalen biedt een moderne web-API op basis van JSON. Het verbetert de bruikbaarheid en prestaties door bestaande functies te consolideren in minder bewerkingen en nieuwe functies te bieden.

Transliteratie om tekst in één taal van het ene script naar een ander script te converteren.
Vertaling naar meerdere talen in één aanvraag.
Taaldetectie, vertaling en transliteratie in één aanvraag.
Woordenlijst om alternatieve vertalingen van een term op te zoeken, om terugvertalingen en voorbeelden te vinden met termen die in context worden gebruikt.
Meer informatieve resultaten voor taaldetectie.

Basis-URL's

Aanvragen voor Vertalen worden in de meeste gevallen verwerkt door het datacenter dat zich het dichtst bij de locatie bevindt waar de aanvraag vandaan komt. Als er een datacenterfout is opgetreden bij het gebruik van het globale eindpunt, kan de aanvraag buiten de geografie worden gerouteerd.

Als u wilt afdwingen dat de aanvraag binnen een specifieke geografie wordt verwerkt, gebruikt u het gewenste geografische eindpunt. Alle aanvragen worden verwerkt tussen de datacenters binnen de geografie.

Geografie	Basis-URL (geografisch eindpunt)	Datacenters
Globaal (`non-regional`)	api.cognitive.microsofttranslator.com	Dichtstbijzijnde beschikbare datacenter
Azië en Stille Oceaan	api-apc.cognitive.microsofttranslator.com	Korea - zuid, Japan - oost, Azië - zuidoost en Australië - oost
Europa	api-eur.cognitive.microsofttranslator.com	Europa - noord, Europa - west
Verenigde Staten	api-nam.cognitive.microsofttranslator.com	VS - oost, VS - zuid-centraal, VS - west-centraal en VS - west 2

¹ Klanten met een resource in Zwitserland - noord of Zwitserland - west kunnen ervoor zorgen dat hun Text-API-aanvragen binnen Zwitserland worden verwerkt. Als u ervoor wilt zorgen dat aanvragen worden verwerkt in Zwitserland, maakt u de Vertalen resource in het Resource regionSwitzerland North of Switzerland Westgebruikt u vervolgens het aangepaste eindpunt van de resource in uw API-aanvragen.

Bijvoorbeeld: Als u een Vertalen resource maakt in Azure Portal met Resource region de Switzerland North naam van uw resource en uw resourcenaam, is my-swiss-nhttps://my-swiss-n.cognitiveservices.azure.comuw aangepaste eindpunt. En een voorbeeldaanvraag om te vertalen is:

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

²Aangepaste Vertalen is momenteel niet beschikbaar in Zwitserland.

Verificatie

Abonneer u op Vertalen of meerdere services in Azure AI-services en gebruik uw sleutel (beschikbaar in Azure Portal) om te verifiëren.

Er zijn drie headers die u kunt gebruiken om uw abonnement te verifiëren. In deze tabel wordt beschreven hoe elk wordt gebruikt:

Headers	Beschrijving
Ocp-Apim-Subscription-Key	Gebruik het abonnement op Azure AI-services als u uw geheime sleutel doorgeeft. De waarde is de geheime Azure-sleutel voor uw abonnement voor Vertalen.
Autorisatie	Gebruik het abonnement op Azure AI-services als u een verificatietoken doorgeeft. De waarde is het Bearer-token: `Bearer <token>`.
Ocp-Apim-Subscription-Region	Gebruiken met een resource voor meerdere services en regionale vertalers. De waarde is de regio van de resource voor meerdere services of regionale vertalers. Deze waarde is optioneel wanneer u een globale translator-resource gebruikt.

Geheime sleutel

De eerste optie is om te verifiëren met behulp van de Ocp-Apim-Subscription-Key header. Voeg de Ocp-Apim-Subscription-Key: <YOUR_SECRET_KEY> header toe aan uw aanvraag.

Verifiëren met een globale resource

Wanneer u een globale translator-resource gebruikt, moet u één header opnemen om de Vertalen aan te roepen.

Headers	Beschrijving
Ocp-Apim-Subscription-Key	De waarde is de geheime Azure-sleutel voor uw abonnement voor Vertalen.

Hier volgt een voorbeeldaanvraag voor het aanroepen van de Vertalen met behulp van de globale translator-resource

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

Verifiëren met een regionale resource

Wanneer u een regionale translator-resource gebruikt, zijn er twee headers die u de Vertalen moet aanroepen.

Headers	Beschrijving
Ocp-Apim-Subscription-Key	De waarde is de geheime Azure-sleutel voor uw abonnement voor Vertalen.
Ocp-Apim-Subscription-Region	De waarde is de regio van de translator-resource.

Hier volgt een voorbeeldaanvraag voor het aanroepen van de Vertalen met behulp van de regionale translator-resource

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

Verifiëren met een multiserviceresource

Met een resource voor meerdere services kunt u één API-sleutel gebruiken om aanvragen voor meerdere services te verifiëren.

Wanneer u een geheime sleutel voor meerdere services gebruikt, moet u twee verificatieheaders met uw aanvraag opnemen. Er zijn twee headers die u nodig hebt om de Vertalen aan te roepen.

Headers	Beschrijving
Ocp-Apim-Subscription-Key	De waarde is de geheime Azure-sleutel voor uw resource met meerdere services.
Ocp-Apim-Subscription-Region	De waarde is de regio van de resource met meerdere services.

Regio is vereist voor het text-API-abonnement voor meerdere services. De regio die u selecteert, is de enige regio die u voor tekstomzetting kunt gebruiken wanneer u de sleutel voor meerdere services gebruikt. Dit moet dezelfde regio zijn die u hebt geselecteerd toen u zich registreerde voor uw abonnement voor meerdere services via Azure Portal.

Als u de geheime sleutel in de queryreeks doorgeeft met de parameter Subscription-Key, moet u de regio met de queryparameter Subscription-Regionopgeven.

Verifiëren met een toegangstoken

U kunt uw geheime sleutel ook uitwisselen voor een toegangstoken. Dit token wordt bij elke aanvraag als header Authorization opgenomen. Als u een autorisatietoken wilt verkrijgen, dient u een POST aanvraag in bij de volgende URL:

Brontype	URL van verificatieservice
Globaal	`https://api.cognitive.microsoft.com/sts/v1.0/issueToken`
Regionale of multiservice	`https://<your-region>.api.cognitive.microsoft.com/sts/v1.0/issueToken`

Hier volgen voorbeeldaanvragen voor het verkrijgen van een token met een geheime sleutel voor een globale resource:

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

Hier volgen voorbeeldaanvragen voor het verkrijgen van een token met een geheime sleutel voor een regionale resource die zich in VS - centraal bevindt:

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

Een geslaagde aanvraag retourneert het gecodeerde toegangstoken als tekst zonder opmaak in de hoofdtekst van het antwoord. Het geldige token wordt doorgegeven aan de Vertalen-service als bearer-token in de autorisatie.

Authorization: Bearer <Base64-access_token>

Een verificatietoken is 10 minuten geldig. Het token moet opnieuw worden gebruikt bij het plaatsen van meerdere aanroepen naar de Vertalen. Als uw programma echter gedurende een langere periode aanvragen indient naar de Vertalen, moet uw programma regelmatig een nieuw toegangstoken aanvragen (bijvoorbeeld om de 8 minuten).

Verificatie met Microsoft Entra-id

Vertalen v3.0 ondersteunt Microsoft Entra-verificatie, de cloudoplossing voor identiteits- en toegangsbeheer van Microsoft. Met autorisatieheaders kan de Vertalen-service valideren dat de aanvragende client gemachtigd is om de resource te gebruiken en de aanvraag te voltooien.

Vereisten

Een kort begrip van hoe u zich verifieert met Microsoft Entra ID.
Een kort begrip van het autoriseren van toegang tot beheerde identiteiten.

Kopteksten

Koptekst	Waarde
Autorisatie	De waarde is een bearer-token voor toegang dat wordt gegenereerd door Azure AD. Het Bearer-token biedt bewijs van verificatie en valideert de autorisatie van de client voor het gebruik van de resource. Een verificatietoken is 10 minuten geldig en moet opnieuw worden gebruikt bij het plaatsen van meerdere aanroepen naar Vertalen. ZieVoorbeeldaanvraag: 2. Een token ophalen
Ocp-Apim-Subscription-Region	De waarde is de regio van de translator-resource. Deze waarde is optioneel als de resource globaal is.
Ocp-Apim-ResourceId	De waarde is de resource-id voor uw Vertalen resource-exemplaar. U vindt de resource-id in Azure Portal op Vertalen Resource → Eigenschappen. Resource-id-indeling: /subscriptions/<subscriptionId>/resourceGroups/<resourceGroupName>/providers/Microsoft.CognitiveServices/accounts/<resourceName/>

Vertalen eigenschappenpagina: Azure Portal

Screenshot:Translator properties page in the Azure portal.

Voorbeelden

Het globale eindpunt gebruiken

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

Uw aangepaste eindpunt gebruiken

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

Voorbeelden met beheerde identiteiten

Vertalen v3.0 ondersteunt ook het autoriseren van toegang tot beheerde identiteiten. Als een beheerde identiteit is ingeschakeld voor een translator-resource, kunt u het Bearer-token doorgeven dat is gegenereerd door een beheerde identiteit in de aanvraagheader.

Met het globale eindpunt

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

Met uw aangepaste eindpunt

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

Ondersteuning voor virtuele netwerken

De Vertalen-service is nu beschikbaar met VNET-mogelijkheden (Virtual Network) in alle regio's van de openbare Azure-cloud. ZieVirtuele netwerken van Azure AI-services configureren om virtueel netwerk in te schakelen.

Nadat u deze mogelijkheid hebt ingeschakeld, moet u het aangepaste eindpunt gebruiken om de Vertalen aan te roepen. U kunt het globale translator-eindpunt ('api.cognitive.microsofttranslator.com') niet gebruiken en u kunt zich niet verifiëren met een toegangstoken.

U kunt het aangepaste eindpunt vinden nadat u een translator-resource hebt gemaakt en toegang vanuit geselecteerde netwerken en privé-eindpunten hebt toegestaan.

Navigeer naar uw Vertalen resource in Azure Portal.
Selecteer Netwerken in de sectie Resourcebeheer .
Kies op het tabblad Firewalls en virtuele netwerken de optie Geselecteerde netwerken en privé-eindpunten.
Selecteer Opslaan om uw wijzigingen toe te passen.
Selecteer Sleutels en eindpunt in de sectie Resourcebeheer .
Selecteer het tabblad Virtueel netwerk .
Er worden de eindpunten weergegeven voor tekstomzetting en documentomzetting.

Headers	Beschrijving
Ocp-Apim-Subscription-Key	De waarde is de geheime Azure-sleutel voor uw abonnement voor Vertalen.
Ocp-Apim-Subscription-Region	De waarde is de regio van de translator-resource. Deze waarde is optioneel als de resource `global`

Hier volgt een voorbeeldaanvraag voor het aanroepen van de Vertalen met behulp van het aangepaste eindpunt

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

Fouten

Een standaardfoutreactie is een JSON-object met een naam/waardepaar met de naam error. De waarde is ook een JSON-object met eigenschappen:

code: Een door de server gedefinieerde foutcode.
message: Een tekenreeks die een door mensen leesbare weergave van de fout geeft.

Een klant met een gratis proefabonnement krijgt bijvoorbeeld de volgende foutmelding zodra het gratis quotum is uitgeput:

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

De foutcode is een getal van 6 cijfers dat de HTTP-statuscode van 3 cijfers combineert, gevolgd door een 3-cijferig getal om de fout verder te categoriseren. Veelvoorkomende foutcodes zijn:

Code	Beschrijving
400000	Een deel van de aanvraaginvoer is niet geldig.
400001	De parameter "bereik" is ongeldig.
400002	De parameter "categorie" is ongeldig.
400003	Een taalaanduiding ontbreekt of is niet geldig.
400004	Er ontbreekt een doelscriptaanduiding ('Aan script') of deze is ongeldig.
400005	Een invoertekst ontbreekt of is niet geldig.
400006	Combinatie van taal en script is niet geldig.
400018	Er ontbreekt een bronscriptaanduiding ('Van script') of deze is ongeldig.
400019	Een van deze opgegeven talen wordt niet ondersteund.
400020	Een van deze elementen in de matrix met invoertekst is niet geldig.
400021	De parameter API-versie ontbreekt of is niet geldig.
400023	Een van de opgegeven taalparen is niet geldig.
400035	Brontaal ('Van'-veld) is niet geldig.
400036	Het doeltaal ('Aan'-veld) ontbreekt of is niet geldig.
400042	Een van opgegeven opties ('Opties'-veld) is niet geldig.
400043	De clienttracerings-id (het veld ClientTraceId of de X-ClientTranceId-header) ontbreekt of is niet geldig.
400050	Invoertekst is te lang. Aanvraaglimieten bekijken.
400064	De parameter "vertaling" ontbreekt of is niet geldig.
400070	Het aantal van de doelscripts (ToScript-parameter) komt niet overeen met het aantal doeltalen (to-parameter).
400071	Waarde is niet geldig voor TextType.
400072	Matrix met invoertekst bevat te veel elementen.
400073	Scriptparameter is niet geldig.
400074	Hoofdtekst van de aanvraag is geen geldige JSON.
400075	Combinatie van taalpaar en categorie is niet geldig.
400077	Maximale aanvraaggrootte is overschreden. Aanvraaglimieten bekijken.
400079	Aangepaste systeem dat is aangevraagd voor vertaling tussen en naar taal, bestaat niet.
400080	De transliteratie wordt niet ondersteund voor de taal of het script.
401000	De aanvraag is niet geautoriseerd omdat referenties ontbreken of ongeldig zijn.
401015	"De opgegeven referenties zijn voor de Speech-API. Voor deze aanvraag zijn referenties vereist voor de Text-API. Gebruik een abonnement om te Vertalen.".
403000	De bewerking is niet toegestaan.
403001	De bewerking is niet toegestaan omdat het abonnement het gratis quotum heeft overschreden.
405000	De aanvraagmethode wordt niet ondersteund voor de aangevraagde resource.
408001	Aangevraagde vertaalsysteem wordt voorbereid. Wacht een paar minuten en probeer het opnieuw.
408002	Er is een time-out opgetreden voor de aanvragen die wachten op binnenkomende stream. De client heeft geen aanvraag geproduceerd binnen de tijd die door de server was ingesteld om te wachten. De client kan de aanvraag op elk moment herhalen zonder wijzigingen.
415000	De header Inhoudstype ontbreekt of is ongeldig.
429000, 429001, 429002	De server heeft de aanvraag geweigerd omdat de client de aanvraaglimieten heeft overschreden.
500.000	Er is een onverwachte fout opgetreden. Als de fout zich blijft voordoen, meldt u deze met de datum/tijd van de fout, de aanvraag-id van de antwoordheader X-RequestId en de client-id van de aanvraagheader X-ClientTraceId.
503000	De service is tijdelijk niet beschikbaar. Probeer het opnieuw. Als de fout zich blijft voordoen, meldt u deze met de datum/tijd van de fout, de aanvraag-id van de antwoordheader X-RequestId en de client-id van de aanvraagheader X-ClientTraceId.

Metrische gegevens voor

Metrische gegevens bieden u de mogelijkheid om de translator-gebruiks- en beschikbaarheidsgegevens weer te geven in azure Portal, onder de sectie met metrische gegevens, zoals wordt weergegeven in de onderstaande schermopname. Zie metrische gegevens en platformgegevens voor meer informatie.

Translator Metrics

Deze tabel bevat beschikbare metrische gegevens met een beschrijving van hoe deze worden gebruikt voor het bewaken van API-aanroepen voor vertaling.

Metrische gegevens voor	Beschrijving
TotalCalls	Totaal aantal API-aanroepen.
TotalTokenCalls	Totaal aantal API-aanroepen via tokenservice met behulp van verificatietoken.
SuccessfulCalls	Aantal geslaagde oproepen.
TotalErrors	Aantal aanroepen met een foutbericht.
BlockedCalls	Aantal aanroepen dat de frequentie of quotumlimiet heeft overschreden.
ServerErrors	Aantal aanroepen met interne serverfout (5XX).
ClientErrors	Aantal aanroepen met fout aan de clientzijde (4XX).
Latentie	Duur voor het voltooien van de aanvraag in milliseconden.
CharactersTranslated	Totaal aantal tekens in binnenkomende tekstaanvraag.