Verwenden von Azure KI Übersetzer-APIs

  • Artikel

In dieser Schrittanleitung erfahren Sie, wie die REST-APIs des Übersetzerdiensts verwendet werden. Sie beginnen mit einfachen Beispielen und fahren dann mit einigen Konfigurationsoptionen für den Kern fort, die bei der Entwicklung häufig verwendet werden, darunter:

Voraussetzungen

  • Azure-Abonnement – Erstellen eines kostenlosen Kontos

  • Eine Azure KI-Ressource mit mehreren Diensten oder eine Translator-Ressource. Sobald Sie Ihr Azure-Abonnement haben, erstellen Sie im Azure-Portal eine Ressource für einen einzelnen Dienst oder für mehrere Dienste, um Ihren Schlüssel und Endpunkt zu erhalten. Wählen Sie nach Abschluss der Bereitstellung Zu Ressource wechseln aus.

  • Sie können den kostenlosen Tarif (F0) verwenden, um den Dienst zu testen, und später für die Produktion auf einen kostenpflichtigen Tarif upgraden.

  • Sie benötigen den Schlüssel und den Endpunkt der Ressource, um Ihre Anwendung mit dem Übersetzerdienst zu verbinden. Zu einem späteren Zeitpunkt fügen Sie Ihren Schlüssel und den Endpunkt in die Codebeispiele ein. Diese Werte sind im Azure-Portal auf der Seite Schlüssel und Endpunkt aufgeführt:

    Screenshot: Seite mit Schlüsseln und Endpunkt im Azure-Portal.

Wichtig

Denken Sie daran, den Schlüssel aus Ihrem Code zu entfernen, wenn Sie fertig sind, und ihn niemals zu veröffentlichen. Verwenden Sie für die Produktion eine sichere Art der Speicherung und des Zugriffs auf Ihre Anmeldeinformationen wie Azure Key Vault. Weitere Informationen finden Sie im Azure KI Services-Artikel Sicherheit.

Header

Beim Aufrufen des Übersetzerdiensts über die REST-API müssen Sie sicherstellen, dass jede Anforderung die folgenden Header enthält. Keine Sorge, wir fügen die Header in den folgenden Abschnitten in den Beispielcode ein.

Header Wert Bedingung
Ocp-Apim-Subscription-Key Ihr Übersetzerdienstschlüssel aus dem Azure-Portal.
  • Erforderlich
Ocp-Apim-Subscription-Region Die Region, in der Ihre Ressource erstellt wurde.
  • Erforderlich, wenn Sie eine Azure KI-Ressource für mehrere Dienste oder eine regionale (geografische) Ressource wie USA, Westen verwenden.
  • Optional beim Verwenden einer Übersetzerressource für einen einzelnen Dienst.
Content-Type Der Inhaltstyp der Nutzdaten. Die akzeptierten Werte sind application/json oder charset=UTF-8.
  • Erforderlich
Content-Length Die Länge des Anforderungstexts.
  • Optional
X-ClientTraceId Eine vom Client erstellte GUID zur eindeutigen Identifizierung der Anforderung. Sie können diesen Header weglassen, wenn Sie die Ablaufverfolgungs-ID mithilfe eines Abfrageparameters namens ClientTraceId in die Abfragezeichenfolge einschließen.
  • Optional

Einrichten der Anwendung

  1. Vergewissern Sie sich, dass Sie die neueste Version der Visual Studio-IDE installiert haben.

    Tipp

    Wenn Sie neu in Visual Studio einsteigen, sehen Sie sich das Learn-Modul Einführung in Visual Studio an.

  2. Öffnen Sie Visual Studio.

  3. Wählen Sie auf der Startseite Neues Projekt erstellen aus.

    Screenshot: Visual Studio-Startfenster

  4. Geben Sie auf der Seite Neues Projekt erstellen im Suchfeld den Suchbegriff Konsole ein. Wählen Sie die Vorlage Konsolenanwendung und dann Weiter aus.

    Screenshot: Visual Studio's Seite

  5. Geben Sie im Dialogfeld Neues Projekt konfigurieren im Feld für den Projektnamen den Namen translator_text_app ein. Lassen Sie das Kontrollkästchen „Projektmappe und Projekt im selben Verzeichnis platzieren“ deaktiviert, und wählen Sie Weiter aus.

    Screenshot: Das Dialogfenster von Visual Studio zum Konfigurieren eines neuen Projekts.

  6. Stellen Sie im Dialogfeld Zusätzliche Informationen sicher, dass .NET 6.0 (Langfristiger Support) ausgewählt ist. Lassen Sie das Kontrollkästchen „Anweisungen auf oberster Ebene nicht verwenden“ deaktiviert, und wählen Sie Erstellen aus.

    Screenshot: Das Dialogfenster für zusätzliche Informationen von Visual Studio.

Installieren des Newtonsoft.json-Pakets mit NuGet

  1. Klicken Sie mit der rechten Maustaste auf Ihr Projekt translator_quickstart, und wählen Sie NuGet-Pakete verwalten... aus.

    Screenshot des Suchfelds für NuGet-Pakete.

  2. Wählen Sie die Registerkarte „Durchsuchen“ aus, und geben Sie „Newtonsoft“ ein.

    Screenshot des Fensters für die Installation von NuGet-Paketen.

  3. Wählen Sie im rechten Paket-Manager-Fenster „Installieren“ aus, und fügen Sie das Paket Ihrem Projekt hinzu.

    Screenshot der Schaltfläche zur Installation von NuGet-Paketen.

Erstellen Ihrer Anwendung

Hinweis

  • Ab .NET 6 erzeugen neue Projekte, die die Vorlage console verwenden, einen neuen Programmstil, der sich von früheren Versionen unterscheidet.
  • Die neue Ausgabe verwendet aktuelle C#-Funktionen, die den zu schreibenden Code vereinfachen.
  • Wenn Sie die neuere Version verwenden, müssen Sie nur den Text der Main-Methode schreiben. Sie müssen keine Top-Level-Anweisungen, globale Nutzungsanweisungen oder indirekte Nutzungsanweisungen einfügen.
  • Weitere Informationen finden Sie unter Neue C#-Vorlagen generieren übergeordnete Anweisungen.

  1. Öffnen Sie die Datei Program.cs.

  2. Löschen Sie den bereits vorhandenen Code, einschließlich der Zeile Console.WriteLine("Hello World!"). Kopieren Sie die Codebeispiele, und fügen Sie sie in die Datei „Program.cs“ Ihrer Anwendung ein. Vergewissern Sie sich für jedes Codebeispiel, dass Sie die Schlüssel- und Endpunktvariablen mit Werten aus Ihrer Übersetzerinstanz aus dem Azure-Portal aktualisieren.

  3. Nachdem Sie Ihrer Anwendung ein gewünschtes Codebeispiel hinzugefügt haben, wählen Sie die grüne Schaltfläche Start neben „formRecognizer_quickstart“ aus, um Ihr Programm zu erstellen und auszuführen, oder drücken Sie F5.

Screenshot der Schaltfläche Programm ausführen in Visual Studio.

Wichtig

Für die Beispiele in dieser Anleitung sind hartcodierte Schlüssel und Endpunkte erforderlich. Denken Sie daran, den Schlüssel aus Ihrem Code zu entfernen, wenn Sie fertig sind, und ihn niemals zu veröffentlichen. In der Produktionsumgebung sollten Sie eine sichere Methode zum Speichern Ihrer Anmeldeinformationen sowie zum Zugriff darauf verwenden. Für weitere Informationen lesen Sie Azure KI Services-Sicherheit.

Übersetzen von Text

Der Kernvorgang des Textübersetzungsdiensts besteht im Übersetzen von Text. In diesem Abschnitt erstellen Sie eine Anforderung, die eine einzelne Quelle (from) annimmt und zwei Ausgaben (to) zur Verfügung stellt. Anschließend überprüfen wir einige Parameter, die verwendet werden können, um sowohl die Anforderung als auch die Antwort anzupassen.

using System.Text;
using Newtonsoft.Json; // Install Newtonsoft.Json with NuGet

class Program
{
    private static readonly string key = "<YOUR-TRANSLATOR-KEY>";
    private static readonly string endpoint = "https://api.cognitive.microsofttranslator.com";

    // location, also known as region.
    // required if you're using a multi-service or regional (not global) resource. It can be found in the Azure portal on the Keys and Endpoint page.
    private static readonly string location = "<YOUR-RESOURCE-LOCATION>";

    static async Task Main(string[] args)
    {
        // Input and output languages are defined as parameters.
        string route = "/translate?api-version=3.0&from=en&to=sw&to=it";
        string textToTranslate = "Hello, friend! What did you do today?";
        object[] body = new object[] { new { Text = textToTranslate } };
        var requestBody = JsonConvert.SerializeObject(body);

        using (var client = new HttpClient())
        using (var request = new HttpRequestMessage())
        {
            // Build the request.
            request.Method = HttpMethod.Post;
            request.RequestUri = new Uri(endpoint + route);
            request.Content = new StringContent(requestBody, Encoding.UTF8, "application/json");
            request.Headers.Add("Ocp-Apim-Subscription-Key", key);
            // location required if you're using a multi-service or regional (not global) resource.
            request.Headers.Add("Ocp-Apim-Subscription-Region", location);

            // Send the request and get response.
            HttpResponseMessage response = await client.SendAsync(request).ConfigureAwait(false);
            // Read response as a string.
            string result = await response.Content.ReadAsStringAsync();
            Console.WriteLine(result);
        }
    }
}

Nach einem erfolgreichen Aufruf sollten Sie die folgende Antwort sehen:

[
   {
      "translations":[
         {
            "text":"Halo, rafiki! Ulifanya nini leo?",
            "to":"sw"
         },
         {
            "text":"Ciao, amico! Cosa hai fatto oggi?",
            "to":"it"
         }
      ]
   }
]

Sie können den Verbrauch (die Anzahl der in Rechnung gestellten Zeichen) für jede Anforderung im Feld response headers: x-metered-usage überprüfen.

Sprache erkennen

Wenn Sie eine Übersetzung benötigen, aber die Sprache des Texts nicht kennen, können Sie den Vorgang zur Sprachenerkennung verwenden. Es gibt mehr als eine Möglichkeit, die Sprache des Ausgangstexts zu bestimmen. In diesem Abschnitt erfahren Sie, wie Sie die Sprachenerkennung mithilfe des translate-Endpunkts und des detect-Endpunkts verwenden.

Erkennen der Quellsprache während der Übersetzung

Wenn Sie den from-Parameter nicht in Ihre Übersetzungsanforderung aufnehmen, versucht der Übersetzerdienst, die Sprache des Ausgangstexts zu erkennen. In der Antwort erhalten Sie die erkannte Sprache (language) und eine Konfidenzbewertung (score). Je näher score an 1.0 liegt, mit desto größerer Zuverlässigkeit wurde die Sprache richtig erkannt.

using System;
using Newtonsoft.Json; // Install Newtonsoft.Json with NuGet

class Program
{
    private static readonly string key = "<YOUR-TRANSLATOR-KEY>";
    private static readonly string endpoint = "https://api.cognitive.microsofttranslator.com";

    // location, also known as region.
// required if you're using a multi-service or regional (not global) resource. It can be found in the Azure portal on the Keys and Endpoint page.
    private static readonly string location = "<YOUR-RESOURCE-LOCATION>";

    static async Task Main(string[] args)
    {
        // Output languages are defined as parameters, input language detected.
        string route = "/translate?api-version=3.0&to=en&to=it";
        string textToTranslate = "Halo, rafiki! Ulifanya nini leo?";
        object[] body = new object[] { new { Text = textToTranslate } };
        var requestBody = JsonConvert.SerializeObject(body);

        using (var client = new HttpClient())
        using (var request = new HttpRequestMessage())
        {
            // Build the request.
            request.Method = HttpMethod.Post;
            request.RequestUri = new Uri(endpoint + route);
            request.Content = new StringContent(requestBody, Encoding.UTF8, "application/json");
            // location required if you're using a multi-service or regional (not global) resource. 
            request.Headers.Add("Ocp-Apim-Subscription-Key", key);
            request.Headers.Add("Ocp-Apim-Subscription-Region", location);

            // Send the request and get response.
            HttpResponseMessage response = await client.SendAsync(request).ConfigureAwait(false);
            // Read response as a string.
            string result = await response.Content.ReadAsStringAsync();
            Console.WriteLine(result);
        }
    }
}

Nach einem erfolgreichen Aufruf sollten Sie die folgende Antwort sehen:

[
   {
      "detectedLanguage":{
         "language":"sw",
         "score":0.8
      },
      "translations":[
         {
            "text":"Hello friend! What did you do today?",
            "to":"en"
         },
         {
            "text":"Ciao amico! Cosa hai fatto oggi?",
            "to":"it"
         }
      ]
   }
]

Erkennen der Quellsprache ohne Übersetzung

Es ist möglich, den Textübersetzungsdienst zum Erkennen der Sprache von Quelltext zu verwenden, ohne eine Übersetzung durchzuführen. Zu diesem Zweck verwenden Sie den /detect-Endpunkt.

using System;
using Newtonsoft.Json; // Install Newtonsoft.Json with NuGet

class Program
{
    private static readonly string key = "<YOUR-TRANSLATOR-KEY>";
    private static readonly string endpoint = "https://api.cognitive.microsofttranslator.com";

    // location, also known as region.
// required if you're using a multi-service or regional (not global) resource. It can be found in the Azure portal on the Keys and Endpoint page.
    private static readonly string location = "<YOUR-RESOURCE-LOCATION>";

    static async Task Main(string[] args)
    {
        // Just detect language
        string route = "/detect?api-version=3.0";
        string textToLangDetect = "Hallo Freund! Was hast du heute gemacht?";
        object[] body = new object[] { new { Text = textToLangDetect } };
        var requestBody = JsonConvert.SerializeObject(body);

        using (var client = new HttpClient())
        using (var request = new HttpRequestMessage())
        {
            // Build the request.
            request.Method = HttpMethod.Post;
            request.RequestUri = new Uri(endpoint + route);
            request.Content = new StringContent(requestBody, Encoding.UTF8, "application/json");
            request.Headers.Add("Ocp-Apim-Subscription-Key", key);
            request.Headers.Add("Ocp-Apim-Subscription-Region", location);

            // Send the request and get response.
            HttpResponseMessage response = await client.SendAsync(request).ConfigureAwait(false);
            // Read response as a string.
            string result = await response.Content.ReadAsStringAsync();
            Console.WriteLine(result);
        }
    }
}

Die Antwort des /detect-Endpunkts enthält alternative erkannte Sprachen und gibt an, ob für alle der erkannten Sprachen Übersetzung und Transliteration unterstützt werden. Nach einem erfolgreichen Aufruf sollten Sie die folgende Antwort sehen:

[
   {
      "language":"de",

      "score":1.0,

      "isTranslationSupported":true,

      "isTransliterationSupported":false
   }
]

Transliteration von Text

Transliteration ist der Vorgang der Umwandlung eines Worts oder Ausdrucks aus der Schrift (Alphabet) einer Sprache in eine andere, ausgehend von der phonetischen Ähnlichkeit. Beispielsweise können Sie Transliteration verwenden, um „สวัสดี“ (thai) in „sawatdi“ (latn) zu konvertieren. Es gibt mehrere Möglichkeiten zum Durchführen von Transliteration. In diesem Abschnitt erfahren Sie, wie Sie die Sprachenerkennung mithilfe des translate-Endpunkts und des transliterate-Endpunkts verwenden.

Transliteration während der Übersetzung

Wenn Sie in eine Sprache übersetzen, die ein anderes Alphabet (oder andere Phoneme) als ihre Quelle verwendet, benötigen Sie möglicherweise Transliteration. In diesem Beispiel wird „Hello“ von Englisch in Thailändisch übersetzt. Zusätzlich zur Übersetzung ins Thailändische erhalten Sie eine Transliteration des übersetzten Satzes, die das lateinische Alphabet verwendet.

Zum Abrufen einer Übersetzung vom translate-Endpunkt verwenden Sie den Parameter toScript.

Hinweis

Eine vollständige Liste der verfügbaren Sprachen und Transliterationen finden Sie unter Sprachunterstützung.

using System;
using Newtonsoft.Json; // Install Newtonsoft.Json with NuGet

class Program
{
    private static readonly string key = "<YOUR-TRANSLATOR-KEY>";
    private static readonly string endpoint = "https://api.cognitive.microsofttranslator.com";

    // location, also known as region.
   // required if you're using a multi-service or regional (not global) resource. It can be found in the Azure portal on the Keys and Endpoint page.
    private static readonly string location = "<YOUR-RESOURCE-LOCATION>";

    static async Task Main(string[] args)
    {
        // Output language defined as parameter, with toScript set to latn
        string route = "/translate?api-version=3.0&to=th&toScript=latn";
        string textToTransliterate = "Hello, friend! What did you do today?";
        object[] body = new object[] { new { Text = textToTransliterate } };
        var requestBody = JsonConvert.SerializeObject(body);

        using (var client = new HttpClient())
        using (var request = new HttpRequestMessage())
        {
            // Build the request.
            request.Method = HttpMethod.Post;
            request.RequestUri = new Uri(endpoint + route);
            request.Content = new StringContent(requestBody, Encoding.UTF8, "application/json");
            request.Headers.Add("Ocp-Apim-Subscription-Key", key);
            request.Headers.Add("Ocp-Apim-Subscription-Region", location);

            // Send the request and get response.
            HttpResponseMessage response = await client.SendAsync(request).ConfigureAwait(false);
            // Read response as a string.
            string result = await response.Content.ReadAsStringAsync();
            Console.WriteLine(result);
        }
    }
}

Nach einem erfolgreichen Aufruf sollten Sie die folgende Antwort sehen. Beachten Sie, dass die Antwort vom translate-Endpunkt die erkannte Ausgangssprache mit einer Vertrauensbewertung, eine Übersetzung im Alphabet der Zielsprache und eine Transliteration unter Verwendung des lateinischen Alphabets umfasst.

[
  {
    "detectedLanguage": {
      "language": "en",
      "score": 1
    },
    "translations": [
      {
        "text": "หวัดดีเพื่อน! วันนี้เธอทำอะไรไปบ้าง ",
        "to": "th",
        "transliteration": {
          "script": "Latn",
          "text": "watdiphuean! wannithoethamaraipaiang"
        }
      }
    ]
  }
]

Transliteration ohne Übersetzung

Sie können ferner den transliterate-Endpunkt verwenden, um eine Transliteration abzurufen. Beim Verwenden des Transliterationsendpunkts müssen Sie die Ausgangssprache (language), die Ausgangsschrift/das Ausgangsalphabet (fromScript) und die Zielschrift/das Zielalphabet (toScript) als Parameter angeben. In diesem Beispiel rufen wir die Transliteration für สวัสดีเพื่อน ab. วันนี้คุณทำอะไร.

Hinweis

Eine vollständige Liste der verfügbaren Sprachen und Transliterationen finden Sie unter Sprachunterstützung.

using System;
using Newtonsoft.Json; // Install Newtonsoft.Json with NuGet

class Program
{
    private static readonly string key = "<YOUR-TRANSLATOR-KEY>";
    private static readonly string endpoint = "https://api.cognitive.microsofttranslator.com";

    // location, also known as region.
   // required if you're using a multi-service or regional (not global) resource. It can be found in the Azure portal on the Keys and Endpoint page.
    private static readonly string location = "<YOUR-RESOURCE-LOCATION>";

    static async Task Main(string[] args)
    {
        // For a complete list of options, see API reference.
        // Input and output languages are defined as parameters.
        string route = "/transliterate?api-version=3.0&language=th&fromScript=thai&toScript=latn";
        string textToTransliterate = "สวัสดีเพื่อน! วันนี้คุณทำอะไร";
        object[] body = new object[] { new { Text = textToTransliterate } };
        var requestBody = JsonConvert.SerializeObject(body);

        using (var client = new HttpClient())
        using (var request = new HttpRequestMessage())
        {
            // Build the request.
            request.Method = HttpMethod.Post;
            request.RequestUri = new Uri(endpoint + route);
            request.Content = new StringContent(requestBody, Encoding.UTF8, "application/json");
            request.Headers.Add("Ocp-Apim-Subscription-Key", key);
            // location required if you're using a multi-service or regional (not global) resource.
            request.Headers.Add("Ocp-Apim-Subscription-Region", location);

            // Send the request and get response.
            HttpResponseMessage response = await client.SendAsync(request).ConfigureAwait(false);
            // Read response as a string.
            string result = await response.Content.ReadAsStringAsync();
            Console.WriteLine(result);
        }
    }
}

Nach einem erfolgreichen Aufruf sollten Sie die folgende Antwort sehen. Im Gegensatz zu einem Aufruf des translate-Endpunkts gibt transliterate nur die text und den Ausgabe-script zurück.

[
   {
      "text":"sawatdiphuean! wannikhunthamarai",

      "script":"latn"
   }
]

Abrufen der Satzlänge

Mit dem Textübersetzungsdienst können Sie die Zeichenanzahl für einen Satz oder eine Reihe von Sätzen bestimmen. Die Antwort wird als Array zurückgegeben, das die Zeichenanzahl für jeden erkannten Satz enthält. Sie können Satzlängen mit den Endpunkten translate und breaksentence abrufen.

Abrufen der Satzlänge während der Übersetzung

Sie können die Zeichenanzahl sowohl für den Ausgangstext als auch für die übersetzte Ausgabe mithilfe des translate-Endpunkts abrufen. Um die Satzlänge (srcSenLen und transSenLen) zurückzugeben, müssen Sie den includeSentenceLength-Parameter auf True festlegen.

using System;
using Newtonsoft.Json; // Install Newtonsoft.Json with NuGet

class Program
{
    private static readonly string key = "<YOUR-TRANSLATOR-KEY>";
    private static readonly string endpoint = "https://api.cognitive.microsofttranslator.com";

    // location, also known as region.
   // required if you're using a multi-service or regional (not global) resource. It can be found in the Azure portal on the Keys and Endpoint page.
    private static readonly string location = "<YOUR-RESOURCE-LOCATION>";

    static async Task Main(string[] args)
    {
        // Include sentence length details.
        string route = "/translate?api-version=3.0&to=es&includeSentenceLength=true";
        string sentencesToCount =
                "Can you tell me how to get to Penn Station? Oh, you aren't sure? That's fine.";
        object[] body = new object[] { new { Text = sentencesToCount } };
        var requestBody = JsonConvert.SerializeObject(body);

        using (var client = new HttpClient())
        using (var request = new HttpRequestMessage())
        {
            // Build the request.
            request.Method = HttpMethod.Post;
            request.RequestUri = new Uri(endpoint + route);
            request.Content = new StringContent(requestBody, Encoding.UTF8, "application/json");
            request.Headers.Add("Ocp-Apim-Subscription-Key", key);
            // location required if you're using a multi-service or regional (not global) resource.
            request.Headers.Add("Ocp-Apim-Subscription-Region", location);

            // Send the request and get response.
            HttpResponseMessage response = await client.SendAsync(request).ConfigureAwait(false);
            // Read response as a string.
            string result = await response.Content.ReadAsStringAsync();
            Console.WriteLine(result);
        }
    }
}

Nach einem erfolgreichen Aufruf sollten Sie die folgende Antwort sehen. Über die erkannte Ausgangssprache und die Übersetzung hinaus erhalten Sie die Zeichenanzahl für jeden erkannten Satz, und zwar sowohl für die Quelle (srcSentLen) als auch für die Übersetzung (transSentLen).

[
   {
      "detectedLanguage":{
         "language":"en",
         "score":1.0
      },
      "translations":[
         {
            "text":"¿Puedes decirme cómo llegar a Penn Station? Oh, ¿no estás seguro? Está bien.",
            "to":"es",
            "sentLen":{
               "srcSentLen":[
                  44,
                  21,
                  12
               ],
               "transSentLen":[
                  44,
                  22,
                  10
               ]
            }
         }
      ]
   }
]

Abrufen der Satzlänge ohne Übersetzung

Der Textübersetzungsdienst lässt Sie die Satzlänge auch ohne Übersetzung abrufen, wenn Sie den breaksentence-Endpunkt verwenden.

using System;
using Newtonsoft.Json; // Install Newtonsoft.Json with NuGet

class Program
{
    private static readonly string key = "<YOUR-TRANSLATOR-KEY>";
    private static readonly string endpoint = "https://api.cognitive.microsofttranslator.com";

    // location, also known as region.
   // required if you're using a multi-service or regional (not global) resource. It can be found in the Azure portal on the Keys and Endpoint page.
    private static readonly string location = "<YOUR-RESOURCE-LOCATION>";

    static async Task Main(string[] args)
    {
        // Only include sentence length details.
        string route = "/breaksentence?api-version=3.0";
        string sentencesToCount =
                "Can you tell me how to get to Penn Station? Oh, you aren't sure? That's fine.";
        object[] body = new object[] { new { Text = sentencesToCount } };
        var requestBody = JsonConvert.SerializeObject(body);

        using (var client = new HttpClient())
        using (var request = new HttpRequestMessage())
        {
            // Build the request.
            request.Method = HttpMethod.Post;
            request.RequestUri = new Uri(endpoint + route);
            request.Content = new StringContent(requestBody, Encoding.UTF8, "application/json");
            request.Headers.Add("Ocp-Apim-Subscription-Key", key);
            // location required if you're using a multi-service or regional (not global) resource.
            request.Headers.Add("Ocp-Apim-Subscription-Region", location);

            // Send the request and get response.
            HttpResponseMessage response = await client.SendAsync(request).ConfigureAwait(false);
            // Read response as a string.
            string result = await response.Content.ReadAsStringAsync();
            Console.WriteLine(result);
        }
    }
}

Nach einem erfolgreichen Aufruf sollten Sie die folgende Antwort sehen. Anders als ein Aufruf des translate-Endpunkts gibt breaksentence nur die Zeichenanzahl für den Ausgangstext in einem Array mit dem Namen sentLen zurück.

[
   {
      "detectedLanguage":{
         "language":"en",
         "score":1.0
      },
      "sentLen":[
         44,
         21,
         12
      ]
   }
]

Wörterbuchsuche (Alternative Übersetzungen)

Mit dem Endpunkt können Sie alternative Übersetzungen für ein Wort oder einen Satz abrufen. Wenn Sie beispielsweise das Wort „sunshine“ aus en in es übersetzen, gibt dieser Endpunkt „luz solar“, „rayos solares“ sowie „soleamiento“, „sol“ und „insolación“ zurück.

using System;
using Newtonsoft.Json; // Install Newtonsoft.Json with NuGet

class Program
{
    private static readonly string key = "<YOUR-TRANSLATOR-KEY>";
    private static readonly string endpoint = "https://api.cognitive.microsofttranslator.com";

    // location, also known as region.
   // required if you're using a multi-service or regional (not global) resource. It can be found in the Azure portal on the Keys and Endpoint page.
    private static readonly string location = "<YOUR-RESOURCE-LOCATION>";

    static async Task Main(string[] args)
    {
        // See many translation options
        string route = "/dictionary/lookup?api-version=3.0&from=en&to=es";
        string wordToTranslate = "sunlight";
        object[] body = new object[] { new { Text = wordToTranslate } };
        var requestBody = JsonConvert.SerializeObject(body);

        using (var client = new HttpClient())
        using (var request = new HttpRequestMessage())
        {
            // Build the request.
            request.Method = HttpMethod.Post;
            request.RequestUri = new Uri(endpoint + route);
            request.Content = new StringContent(requestBody, Encoding.UTF8, "application/json");
            request.Headers.Add("Ocp-Apim-Subscription-Key", key);
            // location required if you're using a multi-service or regional (not global) resource.
            request.Headers.Add("Ocp-Apim-Subscription-Region", location);

            // Send the request and get response.
            HttpResponseMessage response = await client.SendAsync(request).ConfigureAwait(false);
            // Read response as a string.
            string result = await response.Content.ReadAsStringAsync();
            Console.WriteLine(result);
        }
    }
}

Nach einem erfolgreichen Aufruf sollten Sie die folgende Antwort sehen. Untersuchen wir die Antwort genauer, da der JSON-Code komplexer als viele der anderen Beispiele in diesem Artikel ist. Das Array translations enthält eine Liste mit Übersetzungen. Jedes Objekt in diesem Array umfasst eine Vertrauensbewertung (confidence), den für die Anzeige auf dem Endbenutzerdisplay optimierten Text (displayTarget), den normalisierten Text (normalizedText), den Teil der Sprache (posTag) und Informationen über frühere Übersetzungen (backTranslations). Weitere Informationen über die Antwort finden Sie unter Wörterbuchsuche

[
   {
      "normalizedSource":"sunlight",
      "displaySource":"sunlight",
      "translations":[
         {
            "normalizedTarget":"luz solar",
            "displayTarget":"luz solar",
            "posTag":"NOUN",
            "confidence":0.5313,
            "prefixWord":"",
            "backTranslations":[
               {
                  "normalizedText":"sunlight",
                  "displayText":"sunlight",
                  "numExamples":15,
                  "frequencyCount":702
               },
               {
                  "normalizedText":"sunshine",
                  "displayText":"sunshine",
                  "numExamples":7,
                  "frequencyCount":27
               },
               {
                  "normalizedText":"daylight",
                  "displayText":"daylight",
                  "numExamples":4,
                  "frequencyCount":17
               }
            ]
         },
         {
            "normalizedTarget":"rayos solares",
            "displayTarget":"rayos solares",
            "posTag":"NOUN",
            "confidence":0.1544,
            "prefixWord":"",
            "backTranslations":[
               {
                  "normalizedText":"sunlight",
                  "displayText":"sunlight",
                  "numExamples":4,
                  "frequencyCount":38
               },
               {
                  "normalizedText":"rays",
                  "displayText":"rays",
                  "numExamples":11,
                  "frequencyCount":30
               },
               {
                  "normalizedText":"sunrays",
                  "displayText":"sunrays",
                  "numExamples":0,
                  "frequencyCount":6
               },
               {
                  "normalizedText":"sunbeams",
                  "displayText":"sunbeams",
                  "numExamples":0,
                  "frequencyCount":4
               }
            ]
         },
         {
            "normalizedTarget":"soleamiento",
            "displayTarget":"soleamiento",
            "posTag":"NOUN",
            "confidence":0.1264,
            "prefixWord":"",
            "backTranslations":[
               {
                  "normalizedText":"sunlight",
                  "displayText":"sunlight",
                  "numExamples":0,
                  "frequencyCount":7
               }
            ]
         },
         {
            "normalizedTarget":"sol",
            "displayTarget":"sol",
            "posTag":"NOUN",
            "confidence":0.1239,
            "prefixWord":"",
            "backTranslations":[
               {
                  "normalizedText":"sun",
                  "displayText":"sun",
                  "numExamples":15,
                  "frequencyCount":20387
               },
               {
                  "normalizedText":"sunshine",
                  "displayText":"sunshine",
                  "numExamples":15,
                  "frequencyCount":1439
               },
               {
                  "normalizedText":"sunny",
                  "displayText":"sunny",
                  "numExamples":15,
                  "frequencyCount":265
               },
               {
                  "normalizedText":"sunlight",
                  "displayText":"sunlight",
                  "numExamples":15,
                  "frequencyCount":242
               }
            ]
         },
         {
            "normalizedTarget":"insolación",
            "displayTarget":"insolación",
            "posTag":"NOUN",
            "confidence":0.064,
            "prefixWord":"",
            "backTranslations":[
               {
                  "normalizedText":"heat stroke",
                  "displayText":"heat stroke",
                  "numExamples":3,
                  "frequencyCount":67
               },
               {
                  "normalizedText":"insolation",
                  "displayText":"insolation",
                  "numExamples":1,
                  "frequencyCount":55
               },
               {
                  "normalizedText":"sunstroke",
                  "displayText":"sunstroke",
                  "numExamples":2,
                  "frequencyCount":31
               },
               {
                  "normalizedText":"sunlight",
                  "displayText":"sunlight",
                  "numExamples":0,
                  "frequencyCount":12
               },
               {
                  "normalizedText":"solarization",
                  "displayText":"solarization",
                  "numExamples":0,
                  "frequencyCount":7
               },
               {
                  "normalizedText":"sunning",
                  "displayText":"sunning",
                  "numExamples":1,
                  "frequencyCount":7
               }
            ]
         }
      ]
   }
]

Wörterbuchbeispiele (Übersetzungen im Kontext)

Nachdem Sie eine Wörterbuchsuche durchgeführt haben, können Sie den Ausgangstext und die Übersetzung an den dictionary/examples-Endpunkt übergeben, um eine Liste mit Beispielen zu erhalten, in denen beide Begriffe im Kontext eines Satzes oder Ausdrucks gezeigt werden. Ausgehend vom vorherigen Beispiel verwenden Sie normalizedText und normalizedTarget aus der Antwort der Wörterbuchsuche als text bzw. translation. Die Parameter für die Ausgangssprache (from) und das Ausgabeziel (to) sind erforderlich.

using System;
using Newtonsoft.Json; // Install Newtonsoft.Json with NuGet

class Program
{
    private static readonly string key = "<YOUR-TRANSLATOR-KEY>";
    private static readonly string endpoint = "https://api.cognitive.microsofttranslator.com";

    // location, also known as region.
   // required if you're using a multi-service or regional (not global) resource. It can be found in the Azure portal on the Keys and Endpoint page.
    private static readonly string location = "<YOUR-RESOURCE-LOCATION>";

    static async Task Main(string[] args)
    {
        // See examples of terms in context
        string route = "/dictionary/examples?api-version=3.0&from=en&to=es";
        object[] body = new object[] { new { Text = "sunlight",  Translation = "luz solar" } } ;
        var requestBody = JsonConvert.SerializeObject(body);

        using (var client = new HttpClient())
        using (var request = new HttpRequestMessage())
        {
            // Build the request.
            request.Method = HttpMethod.Post;
            request.RequestUri = new Uri(endpoint + route);
            request.Content = new StringContent(requestBody, Encoding.UTF8, "application/json");
            request.Headers.Add("Ocp-Apim-Subscription-Key", key);
            // location required if you're using a multi-service or regional (not global) resource.
            request.Headers.Add("Ocp-Apim-Subscription-Region", location);

            // Send the request and get response.
            HttpResponseMessage response = await client.SendAsync(request).ConfigureAwait(false);
            // Read response as a string.
            string result = await response.Content.ReadAsStringAsync();
            Console.WriteLine(result);
        }
    }
}

Nach einem erfolgreichen Aufruf sollten Sie die folgende Antwort sehen. Weitere Informationen über die Antwort finden Sie unter Wörterbuchsuche

[
   {
      "normalizedSource":"sunlight",
      "normalizedTarget":"luz solar",
      "examples":[
         {
            "sourcePrefix":"You use a stake, silver, or ",
            "sourceTerm":"sunlight",
            "sourceSuffix":".",
            "targetPrefix":"Se usa una estaca, plata, o ",
            "targetTerm":"luz solar",
            "targetSuffix":"."
         },
         {
            "sourcePrefix":"A pocket of ",
            "sourceTerm":"sunlight",
            "sourceSuffix":".",
            "targetPrefix":"Una bolsa de ",
            "targetTerm":"luz solar",
            "targetSuffix":"."
         },
         {
            "sourcePrefix":"There must also be ",
            "sourceTerm":"sunlight",
            "sourceSuffix":".",
            "targetPrefix":"También debe haber ",
            "targetTerm":"luz solar",
            "targetSuffix":"."
         },
         {
            "sourcePrefix":"We were living off of current ",
            "sourceTerm":"sunlight",
            "sourceSuffix":".",
            "targetPrefix":"Estábamos viviendo de la ",
            "targetTerm":"luz solar",
            "targetSuffix":" actual."
         },
         {
            "sourcePrefix":"And they don't need unbroken ",
            "sourceTerm":"sunlight",
            "sourceSuffix":".",
            "targetPrefix":"Y ellos no necesitan ",
            "targetTerm":"luz solar",
            "targetSuffix":" ininterrumpida."
         },
         {
            "sourcePrefix":"We have lamps that give the exact equivalent of ",
            "sourceTerm":"sunlight",
            "sourceSuffix":".",
            "targetPrefix":"Disponemos de lámparas que dan el equivalente exacto de ",
            "targetTerm":"luz solar",
            "targetSuffix":"."
         },
         {
            "sourcePrefix":"Plants need water and ",
            "sourceTerm":"sunlight",
            "sourceSuffix":".",
            "targetPrefix":"Las plantas necesitan agua y ",
            "targetTerm":"luz solar",
            "targetSuffix":"."
         },
         {
            "sourcePrefix":"So this requires ",
            "sourceTerm":"sunlight",
            "sourceSuffix":".",
            "targetPrefix":"Así que esto requiere ",
            "targetTerm":"luz solar",
            "targetSuffix":"."
         },
         {
            "sourcePrefix":"And this pocket of ",
            "sourceTerm":"sunlight",
            "sourceSuffix":" freed humans from their ...",
            "targetPrefix":"Y esta bolsa de ",
            "targetTerm":"luz solar",
            "targetSuffix":", liberó a los humanos de ..."
         },
         {
            "sourcePrefix":"Since there is no ",
            "sourceTerm":"sunlight",
            "sourceSuffix":", the air within ...",
            "targetPrefix":"Como no hay ",
            "targetTerm":"luz solar",
            "targetSuffix":", el aire atrapado en ..."
         },
         {
            "sourcePrefix":"The ",
            "sourceTerm":"sunlight",
            "sourceSuffix":" shining through the glass creates a ...",
            "targetPrefix":"La ",
            "targetTerm":"luz solar",
            "targetSuffix":" a través de la vidriera crea una ..."
         },
         {
            "sourcePrefix":"Less ice reflects less ",
            "sourceTerm":"sunlight",
            "sourceSuffix":", and more open ocean ...",
            "targetPrefix":"Menos hielo refleja menos ",
            "targetTerm":"luz solar",
            "targetSuffix":", y más mar abierto ..."
         },
         {
            "sourcePrefix":"",
            "sourceTerm":"Sunlight",
            "sourceSuffix":" is most intense at midday, so ...",
            "targetPrefix":"La ",
            "targetTerm":"luz solar",
            "targetSuffix":" es más intensa al mediodía, por lo que ..."
         },
         {
            "sourcePrefix":"... capture huge amounts of ",
            "sourceTerm":"sunlight",
            "sourceSuffix":", so fueling their growth.",
            "targetPrefix":"... capturan enormes cantidades de ",
            "targetTerm":"luz solar",
            "targetSuffix":" que favorecen su crecimiento."
         },
         {
            "sourcePrefix":"... full height, giving more direct ",
            "sourceTerm":"sunlight",
            "sourceSuffix":" in the winter.",
            "targetPrefix":"... altura completa, dando más ",
            "targetTerm":"luz solar",
            "targetSuffix":" directa durante el invierno."
         }
      ]
   }
]

Problembehandlung

Allgemeine HTTP-Statuscodes

HTTP-Statuscode BESCHREIBUNG Mögliche Ursache
200 OK Die Anforderung wurde erfolgreich gesendet.
400 Ungültige Anforderung Ein erforderlicher Parameter fehlt, ist leer oder Null. Oder der an einen erforderlichen oder optionalen Parameter übergebene Wert ist ungültig. Ein häufiges Problem sind zu lange Kopfzeilen.
401 Nicht autorisiert Die Anforderung ist nicht autorisiert. Stellen Sie sicher, dass Ihr Schlüssel oder Token gültig ist und sich in der richtigen Region befindet. Siehe auch Authentifizierung.
429 Zu viele Anforderungen Sie haben das Kontingent oder die zulässige Anforderungsrate für das Abonnement überschritten.
502 Ungültiges Gateway Netzwerk- oder serverseitiges Problem. Kann auch auf ungültige Header hinweisen.

Java-Benutzer

Wenn Verbindungsprobleme auftreten, ist möglicherweise das TLS/SSL-Zertifikat abgelaufen. Installieren Sie zum Beheben dieses Problems DigiCertGlobalRootG2.crt im privaten Speicher.

Nächste Schritte

Anpassen und Verbessern der Übersetzung