Migrera kod från v2.0 till v3.0 för REST API

Jämfört med v2 är v3-versionen av Speech Services REST API för tal till text mer tillförlitlig, enklare att använda och mer konsekvent med API:er för liknande tjänster. De flesta team kan migrera från v2 till v3 på en dag eller två.

Framåtkompatibilitet

Alla entiteter från v2 finns också i v3-API:et under samma identitet. Om schemat för ett resultat har ändrats (till exempel transkriptioner) använder resultatet av get i v3-versionen av API:et v3-schemat. Resultatet av get i v2-versionen av API:et använder samma v2-schema. Nyligen skapade entiteter i v3 är inte tillgängliga i svar   från v2 API:er.

Migreringsanvisningar

Det här är en sammanfattning av de objekt som du behöver känna till när du förbereder migreringen. Information finns i de enskilda länkarna. Beroende på din aktuella användning av API:et kanske inte alla steg som anges här gäller. Endast ett fåtal ändringar kräver icke-triviala ändringar i den anropande koden. De flesta ändringar kräver bara en ändring av objektnamnen.

Allmänna ändringar:

  1. Ändra värdnamnet

  2. Byt namn på egenskaps-ID:t till self i klientkoden

  3. Ändra kod för att iterera över entitetssamlingar

  4. Byt namn på egenskapsnamnet till displayName i klientkoden

  5. Justera hämtningen av metadata för refererade entiteter

  6. Om du använder Batch-transkription:

  7. Om du använder ANPASSADE API:er för modellträning/testning:

  8. Om du använder slutpunkts-API:er:

  9. Andra mindre ändringar:

Icke-bakåtkompatibla ändringar

Ändringar av värdnamn

Slutpunktens värdnamn har ändrats {region}.cris.ai från till {region}.api.cognitive.microsoft.com . Sökvägar till de nya slutpunkterna innehåller api/ inte längre eftersom det är en del av värdnamnet. Swagger-dokumentet innehåller en lista över giltiga regioner och sökvägar.

Viktigt

Ändra värdnamnet från {region}.cris.ai till den region där är regionen för din {region}.api.cognitive.microsoft.com talprenumeration. Ta även api/ bort från valfri sökväg i klientkoden.

Identitet för en entitet

Egenskapen är id nu self . I v2 var en API-användare tvungen att veta hur våra sökvägar i API:et skapas. Detta var icke-utökningsbart och krävde onödigt arbete från användaren. Egenskapen id (uuid) ersätts med self (sträng), som är platsen för entiteten (URL). Värdet är fortfarande unikt mellan alla dina entiteter. Om id lagras som en sträng i koden räcker det med ett namnbyte för att stödja det nya schemat. Nu kan du använda innehållet self som URL för GET REST-anropen PATCH , och för din DELETE entitet.

Om entiteten har ytterligare funktioner som är tillgängliga via andra sökvägar visas de under links . I följande exempel för transkription visas en separat metod GET för innehållet i transkriptionen:

Viktigt

Byt namn på id egenskapen self till i klientkoden. Ändra typen från till uuid om string det behövs.

v2-transkription:

{
    "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-transkription:

{
    "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"
    }
}

Beroende på kodens implementering kanske det inte räcker att byta namn på egenskapen. Vi rekommenderar att du använder de self returnerade links värdena och som mål-URL:er för dina REST-anrop i stället för att generera sökvägar i klienten. Genom att använda de returnerade URL:erna kan du vara säker på att framtida ändringar i sökvägar inte bryter klientkoden.

Arbeta med entitetssamlingar

Tidigare returnerade v2-API:et alla tillgängliga entiteter i ett resultat. För att ge en mer omfattande kontroll över den förväntade svarsstorleken i v3 är alla samlingsresultat sidnumrerade. Du har kontroll över antalet returnerade entiteter och sidans startförskjutning. Det här beteendet gör det enkelt att förutsäga körningen av svarsprocessorn.

Svarets grundläggande form är densamma för alla samlingar:

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

Egenskapen values innehåller en delmängd av de tillgängliga samlingsentiteterna. Antal och förskjutning kan styras med hjälp av skip top frågeparametrarna och . Om @nextLink inte finns det fler data tillgängliga och nästa null databatch kan hämtas genom att göra en GET på $.@nextLink .

Den här ändringen kräver GET anrop till för samlingen i en loop tills alla element har returnerats.

Viktigt

När svaret för en GET till innehåller ett värde i fortsätter utfärdandet tills inte har angetts för speechtotext/v3.0/{collection} att hämta alla element i $.@nextLink GETs $.@nextLink $.@nextLink samlingen.

Skapa transkriptioner

En detaljerad beskrivning av hur du skapar batchar med transkriptioner finns i Instruktioner för Batch-transkription.

Med v3-transkriptions-API:et kan du uttryckligen ange specifika transkriptionsalternativ. Alla (valfria) konfigurationsegenskaper kan nu anges i properties egenskapen . Version v3 stöder också flera indatafiler, så det krävs en lista över URL:er i stället för en enda URL som v2 gjorde. V2-egenskapsnamnet recordingsUrl finns contentUrls nu i v3. Funktionen för att analysera sentiment i transkriptioner har tagits bort i v3. Se Textanalys i Microsoft Cognitive Service för alternativ för attitydanalys.

Den nya egenskapen timeToLive under kan hjälpa dig att rensa befintliga properties slutförda entiteter. timeToLiveanger efter hur lång tid en slutförd entitet tas bort automatiskt. Ange det till ett högt värde (till exempel ) när entiteterna kontinuerligt spåras, används och tas bort och därför vanligtvis bearbetas långt innan PT12H 12 timmar har passerat.

v2 transkription POST-begärandetext:

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

v3: postbegärandetext för transkription:

{
  "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"
  }
}

Viktigt

Byt namn på recordingsUrl egenskapen till och skicka en matris med contentUrls URL:er i stället för en enda URL. Skicka inställningar för diarizationEnabled eller som i stället för wordLevelTimestampsEnabled bool string .

Format för v3-transkriptionsresultat

Schemat för transkriptionsresultat har ändrats något så att det överensstämmer med transkriptioner som skapats av realtidsslutpunkter. Hitta en detaljerad beskrivning av det nya formatet i batchtranskriberingsbeskrivningen. Schemat för resultatet publiceras i vår GitHub exempeldatabas under samples/batch/transcriptionresult_v3.schema.json .

Egenskapsnamn är nu kamelskalade och värdena för och channel speaker använder nu heltalstyper. Formatet för varaktigheter använder nu den struktur som beskrivs i ISO 8601, som matchar varaktighetsformatet som används i andra Azure-API:er.

Exempel på ett v3-transkriptionsresultat. Skillnaderna beskrivs i kommentarerna.

{
  "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
            }
          ]
        }
      ]
    }
  ]
}

Viktigt

Deserialisera transkriptionsresultatet till den nya typen enligt ovan. I stället för en enda fil per ljudkanal kan du särskilja kanaler genom att kontrollera egenskapsvärdet channel för för varje element i recognizedPhrases . Det finns nu en enda resultatfil för varje indatafil.

Hämta innehållet i entiteter och resultaten

I v2 har länkarna till indata- eller resultatfilerna försedts med resten av entitetsmetadata. Som en förbättring i v3 finns det en tydlig uppdelning mellan entitetsmetadata (som returneras av en GET på ) och information och autentiseringsuppgifter för att $.self komma åt resultatfilerna. Den här separationen hjälper till att skydda kunddata och ger bra kontroll över giltigheten för autentiseringsuppgifterna.

I v3 inkluderar du en underegenskap med namnet om entiteten exponerar links files data (datauppsättningar, transkriptioner, slutpunkter eller utvärderingar). En GET på $.links.files returnerar en lista över filer och en SAS-URL för att komma åt innehållet i varje fil. Frågeparametern kan användas för att ange livslängden för att styra giltigheten för sasValidityInSeconds SAS-URL:erna.

v2-transkription:

{
  "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-transkription:

{
    "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"
    } 
}

En GET på $.links.files skulle resultera i:

{
  "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"
}

Egenskapen kind anger formatet på filens innehåll. För transkriptioner är filerna av typen sammanfattningen av jobbet och filer av typen TranscriptionReport är resultatet av själva Transcription jobbet.

Viktigt

Om du vill få resultatet av åtgärderna använder GET du på , de finns inte längre i svaren för på eller /speechtotext/v3.0/{collection}/{id}/files GET /speechtotext/v3.0/{collection}/{id} /speechtotext/v3.0/{collection} .

Anpassa modeller

Före v3 fanns det en skillnad mellan en akustisk modell och en språkmodell när en modell tränades. Den här skillnaden gjorde att du behövde ange flera modeller när du skapade slutpunkter eller transkriptioner. För att förenkla den här processen för en anropare har vi tagit bort skillnaderna och gjort allt beroende av innehållet i de datauppsättningar som används för modellträning. Med den här ändringen har modellskapandet nu stöd för blandade datauppsättningar (språkdata och akustiska data). Slutpunkter och transkriptioner kräver nu bara en modell.

Med den här ändringen har behovet av en i åtgärden tagits bort och matrisen kan nu innehålla flera kind POST datasets[] datauppsättningar av samma eller blandade typer.

För att förbättra resultatet av en tränad modell används akustiska data automatiskt internt under språkträningen. I allmänhet levererar modeller som skapats via v3-API:et mer exakta resultat än modeller som skapats med v2-API:et.

Viktigt

Om du vill anpassa både den akustiska modelldelen och språkmodelldelen skickar du alla nödvändiga språk- och akustiska datauppsättningar datasets[] i för POST till /speechtotext/v3.0/models . Detta skapar en enda modell med båda delarna anpassade.

Hämta basmodeller och anpassade modeller

V3 har gjort det enklare att hämta tillgängliga modeller genom att separera samlingarna med "basmodeller" från de kundägda "anpassade modellerna". De två vägarna är nu GET /speechtotext/v3.0/models/base och GET /speechtotext/v3.0/models/ .

I v2 returnerades alla modeller tillsammans i ett enda svar.

Viktigt

Om du vill hämta en lista över tillhandahållna basmodeller för anpassning använder GET du på /speechtotext/v3.0/models/base . Du hittar dina egna anpassade modeller med på GET /speechtotext/v3.0/models .

Namnet på en entitet

Egenskapen name är nu displayName . Detta stämmer överens med andra Azure-API:er för att inte ange identitetsegenskaper. Värdet för den här egenskapen får inte vara unikt och kan ändras när entiteten har skapats med en PATCH åtgärd.

v2-transkription:

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

v3-transkription:

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

Viktigt

Byt namn på name egenskapen displayName till i klientkoden.

Åtkomst till refererade entiteter

I v2 var refererade entiteter alltid inlinade, till exempel de använda modellerna för en slutpunkt. Kapsling av entiteter resulterade i stora svar och konsumenter förbrukade sällan det kapslade innehållet. För att minska svarsstorleken och förbättra prestandan, kommer de refererade entiteterna inte längre att gå in i svaret. I stället visas en referens till den andra entiteten och kan användas direkt för en efterföljande (det är även en URL), enligt GET samma mönster som self länken.

v2-transkription:

{
  "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-transkription:

{
  "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"
  }
}

Om du behöver använda informationen för en refererad modell som visas i exemplet ovan kan du bara utfärda en GET på $.model.self .

Viktigt

Om du vill hämta metadata för refererade entiteter utfärdar du en GET på , till exempel för att hämta modellen för $.{referencedEntity}.self en transkription, gör en GET$.model.self .

Hämta slutpunktsloggar

Version v2 av tjänsten har stöd för loggning av slutpunktsresultat. Om du vill hämta resultatet av en slutpunkt med v2 skapar du en "dataexport", som representerar en ögonblicksbild av resultaten som definieras av ett tidsperiod. Processen att exportera batchar med data var oflexibel. V3-API:et ger åtkomst till varje enskild fil och tillåter iteration genom dem.

En v3-slutpunkt som körs:

{
  "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" 
  }
}

Svar från GET $.links.logs :

{
  "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--"
}

Sidnumrering för slutpunktsloggar fungerar ungefär som alla andra samlingar, förutom att ingen offset kan anges. På grund av den stora mängden tillgängliga data bestäms sidnumreringen av servern.

I v3 kan varje slutpunktslogg tas bort individuellt genom att utfärda en åtgärd för en fil DELETE eller genom att använda på self DELETE $.links.logs . Om du vill ange ett slutdatum kan endDate frågeparametern läggas till i begäran.

Viktigt

I stället för att skapa loggexporter /api/speechtotext/v2.0/endpoints/{id}/data använder du för att komma åt /v3.0/endpoints/{id}/files/logs/ loggfiler individuellt.

Använda anpassade egenskaper

Om du vill separera anpassade egenskaper från de valfria konfigurationsegenskaperna finns nu alla explicit namngivna egenskaper i egenskapen och alla egenskaper som definieras av anroparna finns properties nu i customProperties egenskapen .

v2-transkriptionsentitet:

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

v3-transkriptionsentitet:

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

Med den här ändringen kan du också använda rätt typer för alla explicit namngivna egenskaper under properties (till exempel booleska i stället för sträng).

Viktigt

Skicka alla anpassade egenskaper som customProperties i stället för i dina properties POST begäranden.

Svarshuvuden

v3 returnerar inte Operation-Location längre rubriken utöver rubriken för Location POST begäranden. Värdet för båda rubrikerna i v2 var detsamma. Nu Location returneras endast.

Eftersom den nya API-versionen nu hanteras av Azure API Management (APIM) finns inte de begränsningsrelaterade huvudena , och i X-RateLimit-Limit X-RateLimit-Remaining X-RateLimit-Reset svarshuvudena.

Viktigt

Läs platsen från svarshuvudet Location i stället för Operation-Location . Om det finns en 429-svarskod läser du Retry-After rubrikvärdet i stället för X-RateLimit-Limit , X-RateLimit-Remaining eller X-RateLimit-Reset .

Noggrannhetstester

Noggrannhetstester har bytt namn till utvärderingar eftersom det nya namnet beskriver bättre vad de representerar. De nya sökvägarna är: https://{region}.api.cognitive.microsoft.com/speechtotext/v3.0/evaluations .

Viktigt

Byt namn på accuracytests evaluations sökvägssegmentet till i klientkoden.

Nästa steg

Granska alla funktioner i dessa vanliga REST-API:er som tillhandahålls av Speech Services: