사용 모델

서비스의 비동기 HTTP 인터페이스에 대해 작업할 때 다음과 같은 방법으로 작업 상태에 대해 알아보고 결과를 수신하도록 선택할 수 있습니다.

• 콜백 알림을 사용하여 다음을 수행하십시오.
  1. POST /v1/register_callback 메소드를 호출하여 콜백 URL을 서비스에 등록하십시오. URL에 전송된 콜백에 대한 인증 및 데이터 무결성을 사용하도록 선택적 사용자 지정 시크릿 문자열을 제공할 수 있습니다.
  2. 작업 상태가 변경될 때 서비스가 알림을 전송하는 이미 등록된 콜백 URL을 사용하여 POST /v1/recognitions 메소드를 호출하십시오. 알림을 받을 이벤트의 목록을 지정합니다. 기본적으로 서비스는 작업 시작 시, 작업 완료 시 및 오류 발생 시 알림을 전송합니다. 완료 알림에서 요청의 결과를 요청할 수도 있습니다. 그렇지 않으면 GET /v1/recognitions/{id} 메소드를 사용하여 결과를 검색해야 합니다.
• 서비스를 폴링하여 다음을 수행하십시오.
  1. 콜백 URL, 이벤트 또는 사용자 토큰 없이 POST /v1/recognitions 메소드를 호출하십시오.
  2. 주기적으로 GET /v1/recognitions 메소드를 호출하여 최신 작업의 상태를 확인하거나 GET /v1/recognitions/{id} 메소드를 사용하여 특정 작업의 상태를 확인하십시오.
  3. GET /v1/recognitions 메소드로 작업 상태를 확인하는 경우 작업이 완료된 후 GET /v1/recognitions/{id} 메소드를 사용하여 작업의 결과를 검색하십시오.

두 가지 접근 방식을 함께 사용할 수 있습니다. 여전히 서비스를 폴링하여 콜백 URL로 작성된 작업에 대한 최신 상태를 얻을 수 있습니다. 예를 들어, 알림이 도착하는 데 시간이 걸리는 경우 작업의 상태를 얻을 수 있습니다. 서비스 또는 네트워크 오류로 인해 하나 이상의 알림이 누락된 것으로 의심되는 경우에 상태를 확인할 수도 있습니다.

콜백 URL 등록

POST /v1/register_callback 메소드를 호출하여 콜백 URL을 등록할 수 있습니다. 콜백 URL을 등록하면 이 URL을 사용하여 무제한 수의 작업에 대한 알림을 받을 수 있습니다. 등록 프로세스는 다음 네 단계로 구성됩니다.

1. POST /v1/register_callback 메소드를 호출하고 콜백 URL을 전달합니다. 선택적으로 사용자 지정 시크릿을 지정할 수도 있습니다. 이 서비스는 시크릿을 사용하여 인증 및 데이터 무결성을 위한 키 해시 메시지 인증 코드(HMAC) SHA1(Secure Hash Algorithm 1) 서명을 계산합니다. 다음 예제에서는 URL http://{user_callback_path}/results에서 응답하는 사용자 콜백을 등록합니다. 호출에 ThisIsMySecret이라는 사용자 시크릿이 포함되어 있습니다.

   IBM Cloud

   curl -X POST -u "apikey:{apikey}" \
   "{url}/v1/register_callback?callback_url=http://{user_callback_path}/results&user_secret=ThisIsMySecret"
   

   IBM Cloud Pak for Data IBM Software Hub

   curl -X POST \
   --header "Authorization: Bearer {token}" \
   "{url}/v1/register_callback?callback_url=http://{user_callback_path}/results&user_secret=ThisIsMySecret"
   

2. 서비스는 콜백 URL로 GET 요청을 전송하여 아직 등록되지 않은 콜백 URL이 있는 경우 콜백 URL을 검증하거나 화이트리스트에 추가하려 합니다. 이 서비스는 요청의 challenge_string 조회 매개변수를 통해 랜덤 영숫자 인증 확인 문자열을 전달합니다. 요청에는 Accept을 필수 응답 유형으로 지정하는 text/plain 헤더가 포함되어 있습니다.

   register_callback 메소드에 대한 호출에 사용자 시크릿이 포함된 경우 서비스로부터의 GET 요청에도 인증 확인 문자열의 HMAC-SHA1 서명을 지정하는 X-Callback-Signature 헤더가 포함됩니다. 이 서비스는 사용자 시크릿을 키로 사용하여 서명을 계산합니다.

   GET http://{user_callback_path}/results?challenge_string=n9ArPGMQ36Hiu7QC
   header: X-Callback-Signature {HMAC-SHA1_signature}
   

3. 상태 코드 200으로 서비스의 GET 요청에 응답합니다. 서비스에서 전송된 인증 확인 문자열을 응답에 포함하십시오. 일반 텍스트의 문자열을 응답 본문에 포함하고 Content-Type 응답 헤더를 text/plain으로 설정하십시오.

   초기 POST 요청에 사용자 시크릿이 포함된 경우 이 시크릿을 키로 사용하여 인증 확인 문자열의 HMAC-SHA1 서명을 계산할 수 있습니다. 서비스에서 GET 요청이 전송된 경우 서명이 X-Callback-Signature 헤더에 지정된 값과 일치합니다.

   response code: 200 OK
   body: n9ArPGMQ36Hiu7QC
   

4. 이 서비스는 해당 GET 요청에 대한 응답의 본문에 인증 확인 문자열이 리턴되는지 여부를 확인합니다. 리턴된 경우 서비스는 콜백 URL을 화이트리스트에 추가하고 상태 코드 201로 원래의 POST 요청에 응답합니다. 요청의 본문에 status 필드의 값이 created이고 url 필드의 값이 해당 콜백 URL인 JSON 오브젝트가 포함됩니다.

   response code: 201 Created
   body: {
     "status": "created",
     "url": "http://{user_callback_path}/results"
   }
   

이 서비스는 등록 프로세스 중에 콜백 URL에 대한 단일 GET 요청만 전송합니다. 서비스가 5초 이내에 본문에 인증 코드 문자열이 포함된 응답을 응답 코드 200으로 수신해야 합니다. 그렇지 않으면 URL을 화이트리스트에 추가하지 않습니다. 대신, POST /v1/register_callback 요청에 대한 응답으로 상태 코드 400을 전송합니다. 콜백 URL이 이미 화이트리스트에 있는 경우 서비스는 초기 POST 요청에 대한 응답으로 상태 코드 200을 전송합니다.

curl -X POST -u "apikey:{apikey}" \
"{url}/v1/unregister_callback?callback_url=http://{user_callback_path}/results"

curl -X POST \
--header "Authorization: Bearer {token}" \
"{url}/v1/unregister_callback?callback_url=http://{user_callback_path}/results"

작업 작성

POST /v1/recognitions 메소드를 호출하여 인식 작업을 작성할 수 있습니다. 작업의 상태 및 결과를 알아보는 방법은 사용하는 접근 방식과 전달하는 매개변수에 따라 달라집니다.

• 콜백 알림을 사용하려면 작업 상태가 변경될 때 서비스가 콜백 알림을 전송하는 URL을 지정하는 callback_url 조회 매개변수를 포함하십시오. 다음과 같은 선택적 조회 매개변수를 지정할 수도 있습니다.
  • 알림 이벤트 목록에 등록하기 위한 events. 기본적으로 서비스는 작업 시작 시(recognitions.started 이벤트), 작업 완료 시(recognitions.completed 이벤트) 및 오류 발생 시(recognitions.failed 이벤트) 콜백 알림을 전송합니다. 이벤트의 서브세트를 지정하거나 recognitions.completed_with_results 이벤트 대신 recognitions.completed 이벤트를 사용하여 작업 완료 알림에 결과를 포함시킬 수 있습니다.
  • 작업에 대한 각 알림에 포함될 문자열을 지정하기 위한 user_token. 무제한 수의 작업에 동일한 콜백 URL을 사용할 수 있으므로 사용자 토큰을 사용하여 여러 작업에 대한 알림을 구별할 수 있습니다.
• 폴링을 사용하려면 callback_url, events 및 user_token 조회 매개변수를 생략하십시오. 그런 다음 GET /v1/recognitions 또는 GET /v1/recognitions/{id} 메소드를 사용하여 작업의 상태를 확인해야 합니다. 작업이 완료되면 후자를 사용하여 결과를 검색합니다.

두 경우 모두에 results_ttl 조회 매개변수를 포함하여 작업이 완료된 후 결과가 사용 가능한 상태로 유지되는 시간(분)을 지정할 수 있습니다. 새 작업은 해당 인증 정보를 사용하여 이를 작성한 서비스의 인스턴스가 소유합니다.

비동기 인터페이스에 특정한 이전 매개변수 이외에 POST /v1/recognitions 메소드는 WebSocket 및 동기 HTTP 인터페이스와 동일한 매개변수 중 대부분을 지원됩니다. 자세한 정보는 매개변수 요약을 참조하십시오.

{
  "id": "{job_id}",
  "event": "{recognitions_status}",
  "user_token": "{user_token}"
}

from hashlib import sha1
import hmac
hashed = hmac.new(user_secret, notification_payload, sha1)
signature = hashed.digest().encode("base64").rstrip('\n')

curl -X POST -u "apikey:{apikey}" \
--header "Content-Type: audio/flac" \
--data-binary @{path}audio-file.flac \
"{url}/v1/recognitions?callback_url=http://{user_callback_path}/results&user_token=job25&timestamps=true"

curl -X POST \
--header "Authorization: Bearer {token}" \
--header "Content-Type: audio/flac" \
--data-binary @{path}audio-file.flac \
"{url}/v1/recognitions?callback_url=http://{user_callback_path}/results&user_token=job25&timestamps=true"

{
  "created": "2016-08-17T19:15:17.926Z",
  "id": "4bd734c0-e575-21f3-de03-f932aa0468a0",
  "url": "{url}/v1/recognitions/4bd734c0-e575-21f3-de03-f932aa0468a0",
  "status": "waiting"
}

curl -X POST -u "apikey:{apikey}" \
--header "Content-Type: audio/wav" \
--data-binary @{path}audio-file.wav \
"{url}/v1/recognitions?timestamps=true"

curl -X POST \
--header "Authorization: Bearer {token}" \
--header "Content-Type: audio/wav" \
--data-binary @{path}audio-file.wav \
"{url}/v1/recognitions?timestamps=true"

{
  "created": "2016-08-17T19:13:23.622Z",
  "id": "4bb1dca0-f6b1-11e5-80bc-71fb7b058b20",
  "url": "{url}/v1/recognitions/4bb1dca0-f6b1-11e5-80bc-71fb7b058b20",
  "status": "processing"
}

상태 확인 및 작업의 결과 검색

GET /v1/recognitions/{id} 메소드를 호출하여 id 경로 매개변수로 지정된 작업의 상태를 확인할 수 있습니다. 응답에는 항상 작업의 ID 및 상태와 작업 작성 및 업데이트 시간이 포함됩니다. 상태가 completed이면 인식 요청의 결과도 응답에 포함됩니다.

다음과 같은 경우 GET /v1/recognitions/{id} 메소드가 작업 결과를 검색하는 유일한 방법입니다.

• 작업이 콜백 URL 없이 제출되었습니다.
• 작업이 콜백 URL과 함께 제출되었지만 recognitions.completed_with_results 이벤트를 지정하지 않았습니다.
• 작업이 100개의 최신 미해결 작업 중 하나가 아닙니다. id 경로 매개변수를 생략하면 100개의 최신 작업만 리턴됩니다.

그러나 여전히 이 메소드를 사용하여 콜백 URL 및 recognitions.completed_with_results 이벤트를 지정한 작업의 결과를 검색할 수 있습니다. 사용 가능한 상태로 유지되는 동안 원하는 횟수만큼 작업의 결과를 검색할 수 있습니다. DELETE /v1/recognitions/{id} 메소드를 사용하여 삭제하거나 작업의 TTL(Time To Live)이 만료될 때까지 작업 및 해당 결과가 사용 가능한 상태로 유지됩니다. 기본적으로 results_ttl 메소드의 POST /v1/recognitions 매개변수를 사용하여 다른 TTL(Time To Live)을 지정하지 않는 한 1주일 후에 결과가 만료됩니다.

curl -X GET -u "apikey:{apikey}" \
"{url}/v1/recognitions/{job_id}"

curl -X GET \
--header "Authorization: Bearer {token}" \
"{url}/v1/recognitions/{job_id}"

{
  "id": "4bb1dca0-f6b1-11e5-80bc-71fb7b058b20",
  "created": "2016-08-17T19:13:23.622Z",
  "updated": "2016-08-17T19:13:24.434Z",
  "status": "processing"
}

curl -X GET -u "apikey:{apikey}" \
"{url}/v1/recognitions/{job_id}"

curl -X GET \
--header "Authorization: Bearer {token}" \
"{url}/v1/recognitions/{job_id}"

{
  "id": "398fcd80-330a-22ba-93ce-1a73f454dd98",
  "results": [
    {
      "result_index": 0,
      "results": [
        {
          "final": true,
          "alternatives": [
            {
              "transcript": "several tornadoes touch down as a line of severe thunderstorms swept through Colorado on Sunday ",
              "timestamps": [
                [
                  "several",
                  1,
                  1.52
                ],
                [
                  "tornadoes",
                  1.52,
                  2.15
                ],
                . . .
                [
                  "Sunday",
                  5.74,
                  6.33
                ]
              ],
              "confidence": 0.96
            }
          ]
        }
      ]
    }
  ],
  "created": "2016-08-17T19:11:04.298Z",
  "updated": "2016-08-17T19:11:16.003Z",
  "status": "completed"
}

최신 작업의 상태 확인

GET /v1/recognitions 메소드를 호출하여 최신 작업의 상태를 확인할 수 있습니다. 이 메소드는 호출 시 사용된 인증 정보와 연관된 100개의 최신 미해결 작업의 상태를 리턴합니다. 이 메소드는 각 작업의 ID 및 상태를 작성 및 업데이트 시간과 함께 리턴합니다. 작업이 콜백 URL 및 사용자 토큰으로 작성된 경우 이 메소드가 작업에 대한 사용자 토큰도 리턴합니다.

응답에는 다음 상태 중 하나가 포함됩니다.

• waiting: 서비스가 처리를 위해 작업을 준비하는 중입니다. 이 상태는 모든 작업의 초기 상태입니다. 서비스에 처리를 시작할 수 있는 용량이 있을 때까지 작업이 이 상태로 남아 있습니다.
• processing: 서비스가 활발하게 작업을 처리 중입니다.
• completed: 서비스가 작업 처리를 완료했습니다. 작업이 콜백 URL 및 recognitions.completed_with_results 이벤트를 지정한 경우 서비스가 결과를 콜백 알림과 함께 전송했습니다. 그렇지 않으면 GET /v1/recognitions/{id} 메소드를 사용하여 결과를 얻으십시오.
• failed: 어떤 이유로든 작업이 실패했습니다.

DELETE /v1/recognitions/{id} 메소드를 사용하여 삭제하거나 작업의 TTL(Time To Live)이 만료될 때까지 작업 및 해당 결과가 사용 가능한 상태로 유지됩니다.

curl -X GET -u "apikey:{apikey}" \
"{url}/v1/recognitions"

curl -X GET \
--header "Authorization: Bearer {token}" \
"{url}/v1/recognitions"

{
  "recognitions": [
    {
      "id": "4bd734c0-e575-21f3-de03-f932aa0468a0",
      "created": "2016-08-17T19:15:17.926Z",
      "updated": "2016-08-17T19:15:17.926Z",
      "status": "waiting",
      "user_token": "job25"
    },
    {
      "id": "4bb1dca0-f6b1-11e5-80bc-71fb7b058b20",
      "created": "2016-08-17T19:13:23.622Z",
      "updated": "2016-08-17T19:13:24.434Z",
      "status": "processing"
    },
    {
      "id": "398fcd80-330a-22ba-93ce-1a73f454dd98",
      "created": "2016-08-17T19:11:04.298Z",
      "updated": "2016-08-17T19:11:16.003Z",
      "status": "completed"
    }
  ]
}

작업 삭제

DELETE /v1/recognitions/{id} 메소드를 사용하면 id 경로 매개변수로 지정된 작업을 삭제할 수 있습니다. 일반적으로 서비스에서 해당 결과를 얻은 후 작업을 삭제합니다. 작업을 삭제하면 해당 결과를 더 이상 사용할 수 없습니다. 서비스가 활발히 처리 중인 작업은 삭제할 수 없습니다.

기본적으로 이 서비스는 작업의 TTL(Time to Live)이 만료될 때까지 각 작업의 결과를 유지보수합니다. 기본 TTL(Time to Live)은 1주이지만 results_ttl 메소드의 POST /v1/recognitions 매개변수를 사용하여 서비스가 결과를 유지보수하는 기간(분)을 지정할 수 있습니다.

curl -X DELETE -u "apikey:{apikey}" \
"{url}/v1/recognitions/{job_id}"

curl -X DELETE \
--header "Authorization: Bearer {token}" \
"{url}/v1/recognitions/{job_id}"