Delen via

Translator v3.0

  • Artikel

Wat is er nieuw?

Versie 3.0 van translator 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 Translator 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.

✔️ Functie: Translator Text

Service-eindpunt Gegevensverwerkingscentrum aanvragen
Algemeen (aanbevolen):
api.cognitive.microsofttranslator.com		 Dichtstbijzijnde beschikbare datacentrum.
Amerika:
api-nam.cognitive.microsofttranslator.com		 VS - oost 2 • VS - west 2
Azië en Stille Oceaan
api-apc.cognitive.microsofttranslator.com:		 Japan - oost • Azië - zuidoost
Europa (behalve Zwitserland):
api-eur.cognitive.microsofttranslator.com		 Frankrijk - centraal • Europa - west
Zwitserland: Zie De service-eindpunten van Zwitserland voor meer informatie .
 Zwitserland - noord • Zwitserland - west

Service-eindpunten van Zwitserland

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 Translator-resource in het Resource region Switzerland North of Switzerland Westgebruikt u vervolgens het aangepaste eindpunt van de resource in uw API-aanvragen.

Bijvoorbeeld: Als u een Translator-resource maakt in Azure Portal met Resource region de Switzerland North naam van uw resource, 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

Custom Translator is momenteel niet beschikbaar in Zwitserland.

Verificatie

Abonneer u op Translator 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:

Kopteksten 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 op Translator.
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 Translator aan te roepen.

Kopteksten Beschrijving
Ocp-Apim-Subscription-Key De waarde is de Geheime Azure-sleutel voor uw abonnement op Translator.

Hier volgt een voorbeeldaanvraag voor het aanroepen van de Translator 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 translator moet aanroepen.

Kopteksten Beschrijving
Ocp-Apim-Subscription-Key De waarde is de Geheime Azure-sleutel voor uw abonnement op Translator.
Ocp-Apim-Subscription-Region De waarde is de regio van de translator-resource.

Hier volgt een voorbeeldaanvraag voor het aanroepen van de Translator 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 de Translator moet aanroepen.

Kopteksten 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 als bearer-token doorgegeven aan de Translator-service 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 Translator. Als uw programma echter gedurende langere tijd aanvragen indient bij Translator, moet uw programma regelmatig een nieuw toegangstoken aanvragen (bijvoorbeeld om de 8 minuten).

Verificatie met Microsoft Entra-id

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

Vereisten

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 Translator.
    • Zie Voorbeeldaanvraag: 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 Translator-resource-exemplaar.
  • U vindt de resource-id in Azure Portal bij Translator Resource → Properties.
  • Resource-id-indeling:
    /subscriptions/<subscriptionId>/resourceGroups/<resourceGroupName>/providers/Microsoft.CognitiveServices/accounts/<resourceName/>
Translator-eigenschappenpagina: Azure Portal

Schermopname: pagina Eigenschappen van Translator in Azure Portal.

Belangrijk

Wijs de rol Cognitive Services-gebruiker toe aan de service-principal. Door deze rol toe te wijzen, verleent u service-principal toegang tot de Translator-resource.

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

Translator v3.0 biedt ook ondersteuning voor 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 Translator-service is nu beschikbaar met VNET-mogelijkheden (Virtual Network) in alle regio's van de openbare Azure-cloud. Zie Virtuele 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 translator 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.

  1. Navigeer naar uw Translator-resource in Azure Portal.

  2. Selecteer Netwerken in de sectie Resourcebeheer .

  3. Kies op het tabblad Firewalls en virtuele netwerken de optie Geselecteerde netwerken en privé-eindpunten.

    Schermopname van de instelling voor het virtuele netwerk in Azure Portal.

  4. Selecteer Opslaan om uw wijzigingen toe te passen.

  5. Selecteer Sleutels en eindpunt in de sectie Resourcebeheer .

  6. Selecteer het tabblad Virtueel netwerk .

  7. Er worden de eindpunten weergegeven voor tekstomzetting en documentomzetting.

    Schermopname van het eindpunt van het virtuele netwerk.

Kopteksten Beschrijving
Ocp-Apim-Subscription-Key De waarde is de Geheime Azure-sleutel voor uw abonnement op Translator.
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 om de Translator aan te roepen 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-ClientTraceId-header) ontbreekt of is ongeldig.
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 op Translator.
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.