Vertalen v3.0

Wat is er nieuw?

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

• Transliteratie om tekst in één taal te converteren van het ene script naar het andere.
• 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 back-vertalingen en voorbeelden te vinden met termen die in context worden gebruikt.
• Meer informatieve taaldetectieresultaten.

Basis-URL's

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

Gebruik het gewenste geografische eindpunt om af te dwingen dat de aanvraag binnen een specifieke geografie wordt verwerkt. Alle aanvragen worden verwerkt tussen de datacenters binnen de geografie.

¹ Klanten met een resource in Zwitserland - noord of Zwitserland - west kunnen ervoor zorgen dat hun Text-API-aanvragen worden ingediend in Zwitserland. Om ervoor te zorgen dat aanvragen worden verwerkt in Zwitserland, maakt u de Vertalen-resource in de resourceregio 'Zwitserland - noord' of 'Zwitserland - west' en gebruikt u vervolgens het aangepaste eindpunt van de resource in uw API-aanvragen. Bijvoorbeeld: als u een Vertalen-resource maakt in Azure Portal met 'Resourceregio' als 'Zwitserland - noord' en uw resourcenaam 'my-ch-n' is, is uw aangepaste eindpunt ' https://my-ch-n.cognitiveservices.azure.com ''. En een voorbeeldaanvraag om te vertalen is:

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

² Aangepaste Vertalen is momenteel niet beschikbaar in Zwitserland.

Verificatie

Abonneer u op Vertalen of Cognitive Services-service in Azure Cognitive Services en gebruik uw abonnementssleutel (beschikbaar in de 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 elke wordt 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.

Authenticeren met een globale resource

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

Hier is een voorbeeldaanvraag voor het aanroepen van de Vertalen met behulp van de global 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?'}]"

Authenticeren met een regionale resource

Wanneer u een regionale translator-resource gebruikt. Er zijn twee headers die u nodig hebt om de Vertalen.

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

Authenticeren met een resource voor meerdere service

Wanneer u de multiserviceresource van een Cognitive Service gebruikt. Hiermee kunt u één geheime sleutel gebruiken om aanvragen voor meerdere services te verifiëren.

Wanneer u een geheime sleutel met meerdere service gebruikt, moet u twee verificatieheaders toevoegen aan uw aanvraag. Er zijn twee headers die u nodig hebt om de Vertalen.

Regio is vereist voor het text-API-abonnement met meerdere service. De regio die u selecteert, is de enige regio die u kunt gebruiken voor tekstvertaling wanneer u de abonnementssleutel voor meerdere service gebruikt en moet dezelfde regio zijn die u hebt geselecteerd toen u zich hebt aangemeld voor uw abonnement met meerdere Azure Portal.

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

Authenticeren met een toegangsteken

U kunt uw geheime sleutel ook inruilen voor een toegang token. Dit token is opgenomen in elke aanvraag als de Authorization header. Als u een autorisatie-token wilt verkrijgen, moet u een POST aanvraag indienen bij de volgende URL:

Hier volgen voorbeeldaanvragen voor het verkrijgen van een token op basis van een geheime sleutel:

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

Een geslaagde aanvraag retourneert het gecodeerde toegangsteken als tekst zonder tekst in de antwoordtekst. Het geldige token wordt doorgegeven aan de Vertalen service als bearer-token in de autorisatie.

Authorization: Bearer <Base64-access_token>

Een verificatie-token is tien minuten geldig. Het token moet opnieuw worden gebruikt bij het maken van meerdere aanroepen naar Vertalen. Als uw programma echter gedurende een langere periode aanvragen indient bij de Vertalen, moet uw programma met regelmatige tussenpozen een nieuw toegang token aanvragen (bijvoorbeeld om de 8 minuten).

Verificatie met Azure Active Directory (Azure AD)

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

Vereisten

• Een kort begrip van het verifiëren met Azure Active Directory.

• Een kort begrip van het machtigen van toegang tot beheerde identiteiten.

Kopteksten

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

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 van het gebruik van 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 de 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/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.'}]"

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 Virtual Network -mogelijkheden (VNET) in alle regio's van de openbare Azure-cloud. Zie Configuring Azure Cognitive Services virtual networks (Virtuele netwerken configureren) Virtual Network inschakelen.

Zodra u deze mogelijkheid hebt in gebruik, moet u het aangepaste eindpunt gebruiken om de functie aan te Vertalen. U kunt het global translator-eindpunt ('api.cognitive.microsofttranslator.com') niet gebruiken en u kunt zich niet verifiëren met een toegangs token.

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

Hier is 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/waarde-paar 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 ontvangt bijvoorbeeld de volgende foutmelding zodra het gratis quotum is verbruikt:

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

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

Metrische gegevens

Met metrische gegevens kunt u de informatie over het gebruik en de beschikbaarheid van translators weergeven in Azure Portal sectie Metrische gegevens, zoals wordt weergegeven in de onderstaande schermopname. Zie Metrische gegevens voor gegevens en platform voor meer informatie.

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