Code migreren van v2.0 naar v3.0 van de REST API

Vergeleken met v2 is de versie v3 van de Speech Services REST API voor spraak-naar-tekst betrouwbaarder, gemakkelijker te gebruiken en consistenter met API's voor vergelijkbare services. De meeste teams kunnen binnen een dag of twee migreren van v2 naar v3.

Compatibiliteit doorsturen

Alle entiteiten van v2 zijn ook te vinden in de v3-API onder dezelfde identiteit. Wanneer het schema van een resultaat is gewijzigd (bijvoorbeeld transcripties), maakt het resultaat van een GET in de v3-versie van de API gebruik van het v3-schema. Het resultaat van een GET in de versie v2 van de API maakt gebruik van hetzelfde v2-schema. Nieuw gemaakte entiteiten op v3 zijn niet beschikbaar in reacties   van v2 API's.

Migratiestappen

Dit is een overzichtslijst met items die u moet kennen wanneer u de migratie voorbereidt. Details vindt u in de afzonderlijke koppelingen. Afhankelijk van uw huidige gebruik van de API zijn mogelijk niet alle stappen die hier worden vermeld van toepassing. Voor slechts enkele wijzigingen zijn niet-triviale wijzigingen in de aanroepcode vereist. Voor de meeste wijzigingen is alleen een wijziging in itemnamen vereist.

Algemene wijzigingen:

1. De hostnaam wijzigen

2. Wijzig de naam van de eigenschaps-id in zelf in uw clientcode

3. Code wijzigen om te itereren over verzamelingen entiteiten

4. Wijzig de naam van de eigenschap in displayName in uw clientcode

5. Het ophalen van de metagegevens van entiteiten waarnaar wordt verwezen aanpassen

6. Als u Batch-transcriptie gebruikt:

   • Code aanpassen voor het maken van batchtranscripties

   • Code aanpassen aan het nieuwe transcriptieresultatenschema

   • Code aanpassen voor hoe resultaten worden opgehaald

7. Als u API's voor het trainen/testen van aangepaste modellen gebruikt:

   • Wijzigingen toepassen op de training van aangepaste modellen

   • Wijzigen hoe basis- en aangepaste modellen worden opgehaald

   • Wijzig de naam van de nauwkeurigheidstests van het padsegment in evaluaties in uw clientcode

8. Als u eindpunt-API's gebruikt:

   • Wijzigen hoe eindpuntlogboeken worden opgehaald

9. Andere kleine wijzigingen:

   • Geef alle aangepaste eigenschappen door als customProperties in plaats van eigenschappen in uw POST-aanvragen

   • Lees de locatie van de antwoordheader Locatie in plaats van Bewerkingslocatie

Wijzigingen die fouten veroorzaken

Wijzigingen in hostnaam

Hostnamen van eindpunten zijn gewijzigd van {region}.cris.ai in {region}.api.cognitive.microsoft.com . Paden naar de nieuwe eindpunten bevatten niet langer api/ omdat deze deel uitmaken van de hostnaam. In het Swagger-document worden geldige regio's en paden vermeld.

Identiteit van een entiteit

De eigenschap id is nu self . In v2 moest een API-gebruiker weten hoe onze paden op de API worden gemaakt. Dit was niet-uitvouwbaar en vereist onnodig werk van de gebruiker. De eigenschap id (uuid) wordt vervangen door self (tekenreeks), de locatie van de entiteit (URL). De waarde is nog steeds uniek tussen al uw entiteiten. Als id wordt opgeslagen als een tekenreeks in uw code, is een naams wijzigen voldoende om het nieuwe schema te ondersteunen. U kunt de inhoud nu self gebruiken als url voor de GET PATCH REST-aanroepen , en DELETE voor uw entiteit.

Als voor de entiteit aanvullende functionaliteit beschikbaar is via andere paden, worden deze weergegeven onder links . In het volgende voorbeeld voor transcriptie ziet u een afzonderlijke methode voor GET de inhoud van de transcriptie:

v2-transcriptie:

{
    "id": "9891c965-bb32-4880-b14b-6d44efb158f3",
    "createdDateTime": "2019-01-07T11:34:12Z",
    "lastActionDateTime": "2019-01-07T11:36:07Z",
    "status": "Succeeded",
    "locale": "en-US",
    "name": "Transcription using locale en-US"
}

v3-transcriptie:

{
    "self": "https://westus.api.cognitive.microsoft.com/speechtotext/v3.0/transcriptions/9891c965-bb32-4880-b14b-6d44efb158f3",
    "createdDateTime": "2019-01-07T11:34:12Z",
    "lastActionDateTime": "2019-01-07T11:36:07Z",
    "status": "Succeeded",
    "locale": "en-US", 
    "displayName": "Transcription using locale en-US",
    "links": {
      "files": "https://westus.api.cognitive.microsoft.com/speechtotext/v3.0/transcriptions/9891c965-bb32-4880-b14b-6d44efb158f3/files"
    }
}

Afhankelijk van de implementatie van uw code is het mogelijk niet voldoende om de naam van de eigenschap te wijzigen. We raden u aan de geretourneerde self waarden en als doel-URL's van uw REST-aanroepen te gebruiken in plaats van links paden in uw client te genereren. Door de geretourneerde URL's te gebruiken, kunt u er zeker van zijn dat toekomstige wijzigingen in paden uw clientcode niet zullen breken.

Werken met verzamelingen entiteiten

Eerder heeft de v2-API alle beschikbare entiteiten in een resultaat geretourneerd. Om een fijner controle over de verwachte antwoordgrootte in v3 toe te staan, worden alle verzamelingsresultaten ge pagineerd. U hebt controle over het aantal geretourneerde entiteiten en de begin-offset van de pagina. Dit gedrag maakt het eenvoudig om de runtime van de antwoordprocessor te voorspellen.

De basisvorm van het antwoord is hetzelfde voor alle verzamelingen:

{
    "values": [
        {     
        }
    ],
    "@nextLink": "https://{region}.api.cognitive.microsoft.com/speechtotext/v3.0/{collection}?skip=100&top=100"
}

De values eigenschap bevat een subset van de beschikbare verzamelingsentiteiten. Het aantal en de offset kunnen worden beheerd met behulp van de skip top queryparameters en . Wanneer @nextLink niet null is, zijn er meer gegevens beschikbaar en kan de volgende batch met gegevens worden opgehaald door een GET uit te geven op $.@nextLink .

Voor deze wijziging moet de GET voor de verzameling in een lus worden aanroepen totdat alle elementen zijn geretourneerd.

Transcripties maken

Een gedetailleerde beschrijving van het maken van batches transcripties vindt u in Instructies voor Batchtranscriptie.

Met de v3-transcriptie-API kunt u expliciet specifieke transcriptieopties instellen. Alle (optionele) configuratie-eigenschappen kunnen nu worden ingesteld in de properties eigenschap . Versie v3 biedt ook ondersteuning voor meerdere invoerbestanden, dus hiervoor is een lijst met URL's in plaats van één URL vereist, zoals bij v2. De naam van de eigenschap v2 recordingsUrl is nu contentUrls in v3. De functionaliteit van het analyseren van sentiment in transcripties is verwijderd in v3. Zie Tekstanalyse van Microsoft Cognitive Service voor opties voor sentimentanalyse.

Met de nieuwe timeToLive eigenschap onder kunt u de bestaande properties voltooide entiteiten wegruimen. De timeToLive geeft een duur aan waarna een voltooide entiteit automatisch wordt verwijderd. Stel deze waarde in op een hoge waarde (bijvoorbeeld ) wanneer de entiteiten continu worden bijgespoord, verbruikt en verwijderd en daarom meestal worden verwerkt lang voordat PT12H 12 uur zijn verstreken.

Post-aanvraag voor v2-transcriptie:

{
  "locale": "en-US",
  "name": "Transcription using locale en-US",
  "recordingsUrl": "https://contoso.com/mystoragelocation",
  "properties": {
    "AddDiarization": "False",
    "AddWordLevelTimestamps": "False",
    "PunctuationMode": "DictatedAndAutomatic",
    "ProfanityFilterMode": "Masked"
  }
}

v3 transcriptie POST-aanvraag body:

{
  "locale": "en-US",
  "displayName": "Transcription using locale en-US",
  "contentUrls": [
    "https://contoso.com/mystoragelocation",
    "https://contoso.com/myotherstoragelocation"
  ],
  "properties": {
    "diarizationEnabled": false,
    "wordLevelTimestampsEnabled": false,
    "punctuationMode": "DictatedAndAutomatic",
    "profanityFilterMode": "Masked"
  }
}

Indeling van v3-transcriptieresultaten

Het schema van transcriptieresultaten is enigszins gewijzigd in overeenstemming met transcripties die zijn gemaakt door realtime-eindpunten. Zoek een gedetailleerde beschrijving van de nieuwe indeling in de Uitleg bij Batch-transcriptie. Het schema van het resultaat wordt gepubliceerd in onze GitHub voorbeeldopslagplaats onder samples/batch/transcriptionresult_v3.schema.json .

Eigenschapsnamen zijn nu camel-cased en de waarden voor channel en gebruiken nu gehele speaker getallen. Indeling voor duur maakt nu gebruik van de structuur die wordt beschreven in ISO 8601, wat overeenkomt met de duuropmaak die wordt gebruikt in andere Azure-API's.

Voorbeeld van een v3-transcriptieresultaat. De verschillen worden beschreven in de opmerkingen.

{
  "source": "...",                      // (new in v3) was AudioFileName / AudioFileUrl
  "timestamp": "2020-06-16T09:30:21Z",  // (new in v3)
  "durationInTicks": 41200000,          // (new in v3) was AudioLengthInSeconds
  "duration": "PT4.12S",                // (new in v3)
  "combinedRecognizedPhrases": [        // (new in v3) was CombinedResults
    {
      "channel": 0,                     // (new in v3) was ChannelNumber
      "lexical": "hello world",
      "itn": "hello world",
      "maskedITN": "hello world",
      "display": "Hello world."
    }
  ],
  "recognizedPhrases": [                // (new in v3) was SegmentResults
    {
      "recognitionStatus": "Success",   // 
      "channel": 0,                     // (new in v3) was ChannelNumber
      "offset": "PT0.07S",              // (new in v3) new format, was OffsetInSeconds
      "duration": "PT1.59S",            // (new in v3) new format, was DurationInSeconds
      "offsetInTicks": 700000.0,        // (new in v3) was Offset
      "durationInTicks": 15900000.0,    // (new in v3) was Duration

      // possible transcriptions of the current phrase with confidences
      "nBest": [
        {
          "confidence": 0.898652852,phrase
          "speaker": 1,
          "lexical": "hello world",
          "itn": "hello world",
          "maskedITN": "hello world",
          "display": "Hello world.",

          "words": [
            {
              "word": "hello",
              "offset": "PT0.09S",
              "duration": "PT0.48S",
              "offsetInTicks": 900000.0,
              "durationInTicks": 4800000.0,
              "confidence": 0.987572
            },
            {
              "word": "world",
              "offset": "PT0.59S",
              "duration": "PT0.16S",
              "offsetInTicks": 5900000.0,
              "durationInTicks": 1600000.0,
              "confidence": 0.906032
            }
          ]
        }
      ]
    }
  ]
}

De inhoud van entiteiten en de resultaten verkrijgen

In v2 zijn de koppelingen naar de invoer- of resultaatbestanden inline met de rest van de metagegevens van de entiteit. Als verbetering in v3 is er een duidelijke scheiding tussen entiteitsmetagegevens (die worden geretourneerd door een GET op ) en de details en referenties voor toegang tot de $.self resultaatbestanden. Deze scheiding helpt klantgegevens te beveiligen en biedt goede controle over de geldigheidsduur van de referenties.

Neem in v3 een sub-eigenschap op met de naam voor het geval de entiteit gegevens beschikbaar maakt links files (gegevenssets, transcripties, eindpunten of evaluaties). Met EEN $.links.files GET-aan wordt een lijst met bestanden en een SAS-URL voor toegang tot de inhoud van elk bestand weergegeven. Om de geldigheidsduur van de SAS-URL's te bepalen, kan de queryparameter sasValidityInSeconds worden gebruikt om de levensduur op te geven.

v2-transcriptie:

{
  "id": "9891c965-bb32-4880-b14b-6d44efb158f3",
  "status": "Succeeded",
  "reportFileUrl": "https://contoso.com/report.txt?st=2018-02-09T18%3A07%3A00Z&se=2018-02-10T18%3A07%3A00Z&sp=rl&sv=2017-04-17&sr=b&sig=6c044930-3926-4be4-be76-f728327c53b5",
  "resultsUrls": {
    "channel_0": "https://contoso.com/audiofile1.wav?st=2018-02-09T18%3A07%3A00Z&se=2018-02-10T18%3A07%3A00Z&sp=rl&sv=2017-04-17&sr=b&sig=6c044930-3926-4be4-be76-f72832e6600c",
    "channel_1": "https://contoso.com/audiofile2.wav?st=2018-02-09T18%3A07%3A00Z&se=2018-02-10T18%3A07%3A00Z&sp=rl&sv=2017-04-17&sr=b&sig=3e0163f1-0029-4d4a-988d-3fba7d7c53b5"
  }
}

v3-transcriptie:

{
    "self": "https://westus.api.cognitive.microsoft.com/speechtotext/v3.0/transcriptions/9891c965-bb32-4880-b14b-6d44efb158f3",
    "links": {
      "files": "https://westus.api.cognitive.microsoft.com/speechtotext/v3.0/transcriptions/9891c965-bb32-4880-b14b-6d44efb158f3/files"
    } 
}

Een GET-aan $.links.files zou resulteren in:

{
  "values": [
    {
      "self": "https://westus.api.cognitive.microsoft.com/speechtotext/v3.0/transcriptions/9891c965-bb32-4880-b14b-6d44efb158f3/files/f23e54f5-ed74-4c31-9730-2f1a3ef83ce8",
      "name": "Name",
      "kind": "Transcription",
      "properties": {
        "size": 200
      },
      "createdDateTime": "2020-01-13T08:00:00Z",
      "links": {
        "contentUrl": "https://customspeech-usw.blob.core.windows.net/artifacts/mywavefile1.wav.json?st=2018-02-09T18%3A07%3A00Z&se=2018-02-10T18%3A07%3A00Z&sp=rl&sv=2017-04-17&sr=b&sig=e05d8d56-9675-448b-820c-4318ae64c8d5"
      }
    },
    {
      "self": "https://westus.api.cognitive.microsoft.com/speechtotext/v3.0/transcriptions/9891c965-bb32-4880-b14b-6d44efb158f3/files/28bc946b-c251-4a86-84f6-ea0f0a2373ef",
      "name": "Name",
      "kind": "TranscriptionReport",
      "properties": {
        "size": 200
      },
      "createdDateTime": "2020-01-13T08:00:00Z",
      "links": {
        "contentUrl": "https://customspeech-usw.blob.core.windows.net/artifacts/report.json?st=2018-02-09T18%3A07%3A00Z&se=2018-02-10T18%3A07%3A00Z&sp=rl&sv=2017-04-17&sr=b&sig=e05d8d56-9675-448b-820c-4318ae64c8d5"
      }
    }
  ],
  "@nextLink": "https://westus.api.cognitive.microsoft.com/speechtotext/v3.0/transcriptions/9891c965-bb32-4880-b14b-6d44efb158f3/files?skip=2&top=2"
}

De kind eigenschap geeft de indeling van de inhoud van het bestand aan. Voor transcripties zijn de bestanden van het type de samenvatting van de taak en zijn bestanden van het soort het TranscriptionReport resultaat van de taak Transcription zelf.

Modellen aanpassen

Vóór v3 was er een onderscheid tussen een akoestisch model en een taalmodel toen een model werd getraind. Dit onderscheid heeft geleid tot de noodzaak om meerdere modellen op te geven bij het maken van eindpunten of transcripties. Om dit proces voor een aanroeper te vereenvoudigen, hebben we de verschillen verwijderd en is alles afhankelijk van de inhoud van de gegevenssets die worden gebruikt voor modeltraining. Met deze wijziging ondersteunt het maken van het model nu gemengde gegevenssets (taalgegevens en akoestische gegevens). Voor eindpunten en transcripties is nu slechts één model vereist.

Met deze wijziging is de noodzaak voor een in de bewerking verwijderd en kan de matrix nu meerdere gegevenssets van kind POST dezelfde of datasets[] gemengde soorten bevatten.

Om de resultaten van een getraind model te verbeteren, worden de akoestische gegevens automatisch intern gebruikt tijdens de taaltraining. Over het algemeen leveren modellen die zijn gemaakt via de v3-API nauwkeurigere resultaten dan modellen die zijn gemaakt met de v2-API.

Basis- en aangepaste modellen ophalen

Om het verkrijgen van de beschikbare modellen te vereenvoudigen, heeft v3 de verzamelingen 'basismodellen' gescheiden van de 'aangepaste modellen' die eigendom zijn van de klant. De twee routes zijn nu GET /speechtotext/v3.0/models/base en GET /speechtotext/v3.0/models/ .

In v2 werden alle modellen samen geretourneerd in één antwoord.

Naam van een entiteit

De name eigenschap is nu displayName . Dit is consistent met andere Azure-API's om identiteitseigenschappen niet aan te geven. De waarde van deze eigenschap mag niet uniek zijn en kan worden gewijzigd nadat de entiteit is gemaakt met een PATCH bewerking.

v2-transcriptie:

{
    "name": "Transcription using locale en-US"
}

v3-transcriptie:

{
    "displayName": "Transcription using locale en-US"
}

Toegang tot entiteiten waarnaar wordt verwezen

In v2 waren entiteiten waarnaar wordt verwezen altijd inline, bijvoorbeeld de gebruikte modellen van een eindpunt. Het nesten van entiteiten heeft geleid tot grote reacties en consumenten verbruikten zelden de geneste inhoud. Als u de antwoordgrootte wilt verkleinen en de prestaties wilt verbeteren, worden de entiteiten waarnaar wordt verwezen niet meer inline in het antwoord. In plaats daarvan wordt een verwijzing naar de andere entiteit weergegeven en kan deze rechtstreeks worden gebruikt voor een volgende entiteit (dit is ook een URL), volgens hetzelfde patroon als GET de self koppeling.

v2-transcriptie:

{
  "id": "9891c965-bb32-4880-b14b-6d44efb158f3",
  "models": [
    {
      "id": "827712a5-f942-4997-91c3-7c6cde35600b",
      "modelKind": "Language",
      "lastActionDateTime": "2019-01-07T11:36:07Z",
      "status": "Running",
      "createdDateTime": "2019-01-07T11:34:12Z",
      "locale": "en-US",
      "name": "Acoustic model",
      "description": "Example for an acoustic model",
      "datasets": [
        {
          "id": "702d913a-8ba6-4f66-ad5c-897400b081fb",
          "dataImportKind": "Language",
          "lastActionDateTime": "2019-01-07T11:36:07Z",
          "status": "Succeeded",
          "createdDateTime": "2019-01-07T11:34:12Z",
          "locale": "en-US",
          "name": "Language dataset",
        }
      ]
    },
  ]
}

v3-transcriptie:

{
  "self": "https://westus.api.cognitive.microsoft.com/speechtotext/v3.0/transcriptions/9891c965-bb32-4880-b14b-6d44efb158f3",
  "model": {
    "self": "https://westus.api.cognitive.microsoft.com/speechtotext/v3.0/models/021a72d0-54c4-43d3-8254-27336ead9037"
  }
}

Als u de details van een model waarnaar wordt verwezen wilt gebruiken, zoals wordt weergegeven in het bovenstaande voorbeeld, geeft u een GET uit op $.model.self .

Eindpuntlogboeken ophalen

Versie v2 van de service ondersteunde logboekregistratie eindpuntresultaten. Als u de resultaten van een eindpunt met v2 wilt ophalen, maakt u een 'gegevensexport', die een momentopname vertegenwoordigt van de resultaten die zijn gedefinieerd door een tijdsbereik. Het proces van het exporteren van batches met gegevens was niet flexibel. De v3-API biedt toegang tot elk afzonderlijk bestand en maakt iteratie via deze bestanden mogelijk.

Een met succes uitgevoerd v3-eindpunt:

{
  "self": "https://westus.api.cognitive.microsoft.com/speechtotext/v3.0/endpoints/afa0669c-a01e-4693-ae3a-93baf40f26d6",
  "links": {
    "logs": "https://westus.api.cognitive.microsoft.com/speechtotext/v3.0/endpoints/afa0669c-a01e-4693-ae3a-93baf40f26d6/files/logs" 
  }
}

Antwoord van $.links.logs GET:

{
  "values": [
    {
      "self": "https://westus.api.cognitive.microsoft.com/speechtotext/v3.0/endpoints/6d72ad7e-f286-4a6f-b81b-a0532ca6bcaa/files/logs/2019-09-20_080000_3b5f4628-e225-439d-bd27-8804f9eed13f.wav",
      "name": "2019-09-20_080000_3b5f4628-e225-439d-bd27-8804f9eed13f.wav",
      "kind": "Audio",
      "properties": {
        "size": 12345
      },
      "createdDateTime": "2020-01-13T08:00:00Z",
      "links": {
        "contentUrl": "https://customspeech-usw.blob.core.windows.net/artifacts/2019-09-20_080000_3b5f4628-e225-439d-bd27-8804f9eed13f.wav?st=2018-02-09T18%3A07%3A00Z&se=2018-02-10T18%3A07%3A00Z&sp=rl&sv=2017-04-17&sr=b&sig=e05d8d56-9675-448b-820c-4318ae64c8d5"
      }
    }    
  ],
  "@nextLink": "https://westus.api.cognitive.microsoft.com/speechtotext/v3.0/endpoints/afa0669c-a01e-4693-ae3a-93baf40f26d6/files/logs?top=2&SkipToken=2!188!MDAwMDk1ITZhMjhiMDllLTg0MDYtNDViMi1hMGRkLWFlNzRlOGRhZWJkNi8yMDIwLTA0LTAxLzEyNDY0M182MzI5NGRkMi1mZGYzLTRhZmEtOTA0NC1mODU5ZTcxOWJiYzYud2F2ITAwMDAyOCE5OTk5LTEyLTMxVDIzOjU5OjU5Ljk5OTk5OTlaIQ--"
}

Paginering voor eindpuntlogboeken werkt vergelijkbaar met alle andere verzamelingen, behalve dat er geen offset kan worden opgegeven. Vanwege de grote hoeveelheid beschikbare gegevens wordt paginering bepaald door de server.

In v3 kan elk eindpuntlogboek afzonderlijk worden verwijderd door een bewerking uit te voeren op de van een bestand of door DELETE self te gebruiken op DELETE $.links.logs . Als u een einddatum wilt opgeven, kan de endDate queryparameter worden toegevoegd aan de aanvraag.

Aangepaste eigenschappen gebruiken

Als u aangepaste eigenschappen wilt scheiden van de optionele configuratie-eigenschappen, bevinden alle expliciet benoemde eigenschappen zich nu in de eigenschap en bevinden alle eigenschappen die door de aanroepers zijn gedefinieerd zich properties in de customProperties eigenschap .

v2-transcriptie-entiteit:

{
  "properties": {
    "customerDefinedKey": "value",
    "diarizationEnabled": "False",
    "wordLevelTimestampsEnabled": "False"
  }
}

v3-transcriptie-entiteit:

{
  "properties": {
    "diarizationEnabled": false,
    "wordLevelTimestampsEnabled": false 
  },
  "customProperties": {
    "customerDefinedKey": "value"
  }
}

Met deze wijziging kunt u ook de juiste typen gebruiken voor alle expliciet benoemde eigenschappen onder properties (bijvoorbeeld booleaanse in plaats van tekenreeks).

Antwoordheaders

v3 retourneert niet langer de Operation-Location header naast de header bij Location POST aanvragen. De waarde van beide headers in v2 was hetzelfde. Nu wordt Location alleen geretourneerd.

Omdat de nieuwe API-versie nu wordt beheerd door Azure API Management (APIM), zijn de beperkingsgerelateerde headers , en niet opgenomen in de X-RateLimit-Limit X-RateLimit-Remaining X-RateLimit-Reset antwoordheaders.

Nauwkeurigheidstests

De naam van nauwkeurigheidstests is gewijzigd in evaluaties, omdat de nieuwe naam beter beschrijft wat ze vertegenwoordigen. De nieuwe paden zijn: https://{region}.api.cognitive.microsoft.com/speechtotext/v3.0/evaluations .

Volgende stappen

Bekijk alle functies van deze veelgebruikte REST API's die worden geleverd door Speech-services:

• REST API voor spraak-naar-tekst
• Swagger-document voor v3 van de REST API
• Als u voorbeeldcode wilt gebruiken om batchtranscripties uit te voeren, bekijkt u de GitHub voorbeeldopslagplaats in de samples/batch subdirectory.