從 Voice Gateway 報告 Watson Assistant 各回交談事件

IBM® Voice Gateway 可以產生 IBM Watson™ Assistant 各回交談事件，其中含有每次傳送要求給 Watson Assistant 之後，Voice Gateway 所收到的 JSON 回應。這些事件會以 HTTP POST 要求形式從 Voice Gateway 送出，且採用的格式輕易就能與 Splunk HTTP Event Collector (HEC) 整合，或與會儲存事件（例如，儲存在 noSQL 資料庫）的 REST 伺服器整合。在 1.0.06 版以及更新版本中，您也可以將 Voice Gateway 配置成直接發佈各回交談事件至 IBM Cloudant 或 CouchDB。

將 Voice Gateway 配置成發佈 Watson Assistant 各回交談事件
將 Voice Gateway 配置成發佈 Watson Assistant 各回交談事件至 IBM Cloudant
將 Voice Gateway 配置成發佈 Watson Assistant 各回交談事件至 CouchDB
Watson Assistant 各回交談事件格式

將 Voice Gateway 配置成發佈 Watson Assistant 各回交談事件

設置 Splunk HTTP Event Collector (HEC) 或可用來儲存事件（例如，儲存在 noSQL 資料庫中）的 REST 伺服器。
在 Voice Gateway 配置中，指定 REST 伺服器 URL 和授權認證，並設定 Watson Assistant 各回交談事件索引值，來啟用 Watson Assistant 各回交談事件。
- 單租戶環境：在您的配置中設定下列環境變數。
```
REPORTING_URL=http://myresteventserver.ibm.com/
REPORTING_USERNAME=myRestAdmin
REPORTING_PASSWORD=myRestTokenOrPassword
REPORTING_CONVERSATION_EVENT_INDEX=conv
REPORTING_CONVERSATION_REQUEST_EVENT_INDEX=convRequest
```
- 多租戶 JSON 配置：在多租戶 JSON 配置檔中，針對您想啟用 Watson Assistant 各回交談事件的每一個租戶，配置一個含有下列內容的 reporting 物件。您可以在相同物件內，針對其他類型的事件（例如：轉錄或通話詳細記錄事件）配置索引。
```
...
"reporting": {
 "url": "http://myresteventserver.ibm.com/",
 "username": "myRestAdmin",
 "password": "myRestTokenOrPassword",
 "convEventInd": "conv",
 "convRequestEventInd": "convRequest"
}
...
```
Watson Assistant 事件索引值會以 index 值形式，包含在所有 Watson Assistant 各回交談事件中，以便讓取用它們的 REST 伺服器能夠區分事件的類型。針對 Splunk HEC，索引欄位是必要的；不過，任何人只要想建置自己的 REST 伺服器來處理這些事件，則索引欄位也很有用。

將 Voice Gateway 配置成發佈 Watson Assistant 各回交談事件至 IBM Cloudant 資料庫

將 Voice Gateway 配置成發佈至 IBM Cloudant 之前，請先設置 IBM® Cloudant® for IBM Cloud。

在您的配置中設定下列環境變數，以便將 Watson Assistant 各回交談事件發佈到 IBM Cloudant 資料庫。您可以在配置中新增 IBM Cloudant 配置變數，以同步使用 IBM Cloudant 和另一項報告服務。

下列範例顯示發佈各回交談事件到 IBM Cloudant 的配置。您可以使用 API 金鑰，來配置 IBM Cloudant 的鑑別，作法是新增 REPORTING_CONVERSATION_CLOUDANT_APIKEY 變數，或是新增 REPORTING_CONVERSATION_CLOUDANT_USERNAME 和 REPORTING_CONVERSATION_CLOUDANT_PASSWORD，以使用使用者名稱和密碼。

單租戶環境：在您的配置中設定下列環境變數。
```
REPORTING_CONVERSATION_CLOUDANT_USERNAME=myIBM Cloudant Username
REPORTING_CONVERSATION_CLOUDANT_PASSWORD=myCloudantPassword
REPORTING_CONVERSATION_CLOUDANT_DB_NAME=myCloudantDB
REPORTING_CONVERSATION_CLOUDANT_EVENT_INDEX=conversation
```
如果您對 IBM Cloudant 使用非預設帳戶配置，您可能需要包含其他的環境變數。請參閱報告事件配置中的 REPORTING_CONVERSATION_CLOUDANT_URL 和 REPORTING_CONVERSATION_CLOUDANT_ACCOUNT。
多租戶 JSON 配置：在多租戶 JSON 配置檔中，針對您想啟用 Watson Assistant 各回交談事件的每一個租戶，配置一個含有下列內容的 reporting 物件。如果您對 IBM Cloudant 使用非預設帳戶配置，您可能需要包含其他的環境變數。請參閱 reporting 物件的內容中的 convCloudant。
```
...
"reporting": {
    "convCloudant": {
    "username": "myCloudantUsername",
    "password": "myCloudantPassword",
    "dbName": "myCloudantDB",
    "eventInd": "conversation"
  }
}
...
```

使用 API 金鑰來進行鑑別

除了使用您 IBM Cloudant 認證的使用者名稱與密碼組合，另一種替代作法是使用 API 金鑰來進行鑑別。您可以尋找或產生對 IBM Cloudant 的服務認證，然後將 URL 和 API 金鑰值複製到 Voice Gateway 報告事件配置中。如需 API 金鑰的相關資訊，請參閱 IBM Cloudant：API 金鑰。

單租戶環境：在您的配置中設定下列環境變數。

REPORTING_CONVERSATION_URL_CLOUDANT_URL=http://myconversationcloudant.ibm.com/
REPORTING_CONVERSATION_CLOUDANT_APIKEY=a1b2c3d3fgh1jk1mn0
REPORTING_CONVERSATION_CLOUDANT_DB_NAME=myCloudantDB
REPORTING_CONVERSATION_EVENT_INDEX_CLOUDANT_EVENT_INDEX=conversation

多租戶 JSON 配置：您必須配置 url 和 apikey 配置變數，而非配置 username 和 password。

...
"reporting": {
  "convCloudant": {
  "url": "http://myconversationcloudant.ibm.com/",
  "apikey": "a1b2c3d3fgh1jk1mn0",
  "dbName": "myCloudantDB",
  "eventInd": "conversation"
}
}
...

將 Voice Gateway 配置成發佈 Watson Assistant 各回交談事件至 CouchD

如果要設置 CouchDB，請複製儲存庫，並遵循 Github 上的指示。如果您使用 CouchDB，則無法使用 API 金鑰進行鑑別。

在您的配置中設定下列環境變數，以便將 Watson Assistant 各回交談事件發佈到 CouchDB 資料庫。您可以在配置中新增 CouchDB 配置變數，以同步使用 CouchDB 和另一項報告服務。

下列範例顯示的配置是將各回交談事件發佈到 CouchDB。

單租戶環境：在您的配置中設定下列環境變數。

REPORTING_CONVERSATION_CLOUDANT_URL="http://<svc-couchdb>:5984/"
REPORTING_CONVERSATION_CLOUDANT_USERNAME=myCouchDBUsername
REPORTING_CONVERSATION_CLOUDANT_PASSWORD=myCouchDBPassword
REPORTING_CONVERSATION_CLOUDANT_DB_NAME=myCouchDB
REPORTING_CONVERSATION_CLOUDANT_EVENT_INDEX=conversation

多租戶 JSON 配置：在多租戶 JSON 配置檔中，針對您想啟用 Watson Assistant 各回交談事件的每一個租戶，配置一個含有下列內容的 reporting 物件。如果您對 IBM Cloudant 使用非預設帳戶配置，您可能需要包含其他的環境變數。請參閱 reporting 物件的內容中的 convCloudant。
```
...
"reporting": {
    "convCloudant": {
    "url": "http://<svc-couchdb>:5984/",
    "username": "myCouchDBUsername",
    "password": "myCouchDBPassword",
    "dbName": "myCouchDB",
    "eventInd": "conversation"
  }
}
...
```

Watson Assistant 各回交談事件格式

Watson Assistant 各回交談事件是在每次 HTTP 交易之後，從 Watson Assistant 收回的完整 JSON 物件。事件還包含某些其他 meta 資料，可用來將所有的各回交談事件對映至特定的通話詳細記錄。事件格式是以 Splunk HTTP Event Controller JSON 格式為基礎。

重要事項： Watson Assistant 各回交談事件包含文字轉錄和其他資訊，且這些資訊可能含有「受保護的健康資訊 (PHI)」、個人識別資訊 (PII) 或「PCI 資料安全標準 (PCI DSS)」資料。因此，耗用端伺服器適當儲存這些事件以防個人資訊曝光，就很重要。

在下列範例中，報告事件的起始部分含有 Voice Gateway 的索引鍵。事件 JSON 物件的索引鍵全由 Watson Assistant 服務來定義。如需詳細資料，請參閱 Watson Assistant 的 API 參照。

Voice Gateway 會以從 Watson Assistant 收到的確切形式，來遞送 Watson Assistant 各回交談事件。

  {
      "time": 1434567892.516,
      "host": "vgw1.ibm.com",
      "source": "a23de67h-f41b-47b4-a8dc-e1c32b925b79",
      "sourcetype": "conversationID",
      "index": "conv",
      "event": {
                "input": {
                    "text": "Turn on the lights"
                  },
                  "context": {
                    "conversation_id": "a23de67h-f41b-47b4-a8dc-e1c32b925b79",
                    "system": {
                      "dialog_stack": [
                        {
                          "dialog_node": "root"
                        }
                      ],
                      "dialog_turn_counter": 2,
                      "dialog_request_counter": 2
                    },
                    "defaultCounter": 0
                  },
                  "entities": [
                    {
                      "entity": "appliance",
                      "location": [12, 18],
                      "value": "light"
                    }
                  ],
                  "intents": [
                    {
                      "intent": "turn_on",
                      "confidence": 0.99
                    }
                  ],
                  "output": {
                   "log_messages": [],
                    "text": [
                      "Ok. Turning on the light."
                    ],
                    "nodes_visited": [
                      "node_1_1467221909631",
                      "node_2_1467232480480"
                    ]
                }
          }        
      }

如果將 Voice Gateway 配置成在傳送要求給 Watson Assistant 之前，先產生交談事件，則它在遞送 Watson Assistant 各回交談事件時，會使用將它們傳送給 Watson Assistant 時所採用的確切形式。

{
  "time": 1560524055.816,
  "host": "vgw1.ibm.com",
  "source": "sip:alice@example.com",
  "sourcetype": "sipURI",
  "index": "convRequest",
  "event": {
    "alternateIntents": false,
    "input": {
      "text": "1"
    },
                  "context": {
                    "vgwIsDTMF": "Yes",
      "global": {
        "vgwPostResponseTimeout": 1000
      },
      "vgwSIPCallID": "7DnGPA3SOw",
      "vgwTranscriptionSource": "sip:alice@example.com",
      "vgwSIPRequestURI": "sip:vgw@vgw1.ibm.com;transport=tcp",
      "system": {
        "initialized": true,
        "dialog_stack": [
          {
            "dialog_node": "root"
                        }
                      ],
        "dialog_turn_counter": 2,
        "dialog_request_counter": 2,
        "_node_output_map": {
          "Welcome": [
            0
          ],
          "Anything else": [
            0
          ]
        },
        "branch_exited": true,
        "branch_exited_reason": "fallback"
      },
      "vgwBargeInOccurred": "Yes",
      "conversation_id": "1eec7181-6424-4066-9f36-f6725574af5a",
      "vgwPostResponseTimeout": 1000,
      "vgwIsCaller": "Yes",
      "vgwCompletedActions": [
        {
          "command": "vgwActPlayText",
        "parameters": {
          "text": [
            "I didn't understand. You can try rephrasing."
            ]
          },
          "processed": true
        }
      ],
      "vgwSessionID": "7DnGPA3SOw",
      "vgwDTMFCollectionSucceeded": "Yes"
    }
  }
}

事件 meta 資料

所有報告事件都是以下列 meta 資料開頭：

表 1. 事件 meta 資料的索引鍵
索引鍵	說明
`time`	事件的時間。預設格式是 Epoch 時間，採用 <sec>.<ms> 格式。
`host`	指定產生事件之 Voice Gateway 實例的主機名稱。
`source`	代表產生事件的 Voice Gateway 租戶。一般而言，此值設為受話端的電話號碼。
`sourcetype`	來源類型，會定義成 `e164`（代表電話號碼）、`conversationID`（代表 Watson Assistant 工作區）或 `sipURI`（代表 SIP URI）。
`index`	報告事件索引配置環境變數中所定義的事件索引。
`event`	CDR 事件、Watson Assistant 各回交談事件或轉錄事件。