Configuración de puntos de conexión web

Artículo
01/22/2024

Importante

Comandos personalizados se retirará el 30 de abril de 2026. A partir del 30 de octubre de 2023 no puede crear nuevas aplicaciones de Comandos personalizados en Speech Studio. En relación con este cambio, LUIS se retirará el 1 de octubre de 2025. A partir del 1 de abril de 2023, no puede crear nuevos recursos de LUIS.

En este artículo, aprende a configurar los puntos de conexión web en una aplicación de los comandos personalizados que le permitirá realizar solicitudes HTTP desde una aplicación cliente. Debe realizar las siguientes tareas:

Configurar los puntos de conexión web en la aplicación de Comandos personalizados.
Llamar a puntos de conexión web en la aplicación de Comandos personalizados.
Recibir la respuesta de los puntos de conexión web.
Integrar la respuesta de los puntos de conexión web en una carga JSON personalizada, enviarla y visualizarla desde una aplicación cliente UWP en C# del SDK de Voz.

Requisitos previos

Visual Studio 2019
Una clave y región de recursos de Voz de Azure AI: creación de un recurso de Voz en Azure Portal. Para más información, consulte Crear un recurso multiservicio.
Una aplicación de Comandos personalizados (consulte Creación de un asistente para voz con Comandos personalizados)
Una aplicación cliente habilitada para el SDK de voz (consulte Integración con una aplicación cliente mediante el SDK de voz).

Implementación de un punto de conexión web externo mediante una aplicación de funciones de Azure

En este tutorial, se necesita un punto de conexión HTTP que mantenga los estados de todos los dispositivos configurados en el comando TurnOnOff de la aplicación de Comandos personalizados.

Si ya tiene un punto de conexión web al que quiera llamar, puede ir directamente a la sección siguiente. También, en la sección siguiente se proporcionan detalles sobre un punto de conexión web hospedado predeterminado que puede usar si quiere omitir esta sección.

Formato de entrada de la función de Azure

A continuación, implementa un punto de conexión mediante Azure Functions. Este es el formato de un evento de Comandos personalizados que se pasa a la función de Azure. Use esta información al escribir la aplicación de funciones de Azure.

{
  "conversationId": "string",
  "currentCommand": {
    "name": "string",
    "parameters": {
      "SomeParameterName": "string",
      "SomeOtherParameterName": "string"
    }
  },
  "currentGlobalParameters": {
      "SomeGlobalParameterName": "string",
      "SomeOtherGlobalParameterName": "string"
  }
}

En la tabla siguiente se describen los atributos clave de esta entrada:

Atributo	Explicación
conversationId	El identificador único de la conversación. Tenga en cuenta que este identificador se puede generar desde la aplicación cliente.
currentCommand	El comando que está activo actualmente en la conversación.
name	El nombre del comando. El atributo `parameters` es un mapa con los valores actuales de los parámetros.
currentGlobalParameters	Un mapa como `parameters`, pero se usa para los parámetros globales.

En el caso de la función de Azure DeviceState, un evento de Comandos personalizados de ejemplo tiene el siguiente aspecto. Esta función sirve como entrada a la aplicación de funciones.

{
  "conversationId": "someConversationId",
  "currentCommand": {
    "name": "TurnOnOff",
    "parameters": {
      "item": "tv",
      "value": "on"
    }
  }
}

Salida de la función de Azure en una aplicación de Comandos personalizados

Si una aplicación de Comandos personalizados usa la salida de la función de Azure, debería aparecer en el formato siguiente. Para más información, consulte Actualizar un comando desde un punto de conexión web.

{
  "updatedCommand": {
    "name": "SomeCommandName",
    "updatedParameters": {
      "SomeParameterName": "SomeParameterValue"
    },
    "cancel": false
  },
  "updatedGlobalParameters": {
    "SomeGlobalParameterName": "SomeGlobalParameterValue"
  }
}

Salida de la función de Azure en una aplicación cliente

Si una aplicación cliente consume la salida de la función de Azure, la salida puede tener el formato que requiera la aplicación cliente.

En el caso del punto de conexión DeviceState, una aplicación cliente, y no la aplicación de Comandos personalizados, consume la salida de la función de Azure. La salida de ejemplo de la función de Azure debe parecerse a esta:

{
  "TV": "on",
  "Fan": "off"
}

Esta salida debe escribirse en un almacenamiento externo para que se pueda mantener el estado de los dispositivos. El estado de almacenamiento externo se usa en la sección Integración con la aplicación cliente que viene a continuación.

Implementar la función de Azure

Se proporciona un ejemplo que puede configurar e implementar como una aplicación de Azure Functions. Para crear una cuenta de almacenamiento en nuestro ejemplo, siga estos pasos:

Cree el almacenamiento de tabla para guardar el estado del dispositivo. En Azure Portal, cree un recurso de tipo Cuenta de almacenamiento con el nombre devicestate.
Copie el valor de Cadena de conexión de devicestate -> Claves de acceso. Debe agregar este secreto de cadena al código de la aplicación de funciones de ejemplo descargado.
Descargue el código de la aplicación de funciones de ejemplo.
Abra la solución descargada en Visual Studio 2019. En Connections.jsen, reemplace STORAGE_ACCOUNT_SECRET_CONNECTION_STRING por el secreto del paso 2.
Descargue el código de DeviceStateAzureFunction.

Para implementar la aplicación de ejemplo en Azure Functions, siga estos pasos.

Implemente la aplicación de Azure Functions.
Espere a que la implementación se realice correctamente y vaya al recurso implementado en Azure Portal.
Seleccione Funciones en el panel izquierdo y, luego, elija DeviceState.
En la nueva ventana, seleccione Code + Test (Código y prueba) y, luego, elija Obtener la dirección URL de la función.

Configuración de puntos de conexión web en Comandos personalizados

Vamos a enlazar la función de Azure con la aplicación de Comandos personalizados existente. En esta sección, usa un punto de conexión DeviceState predeterminado ya existente. Si creó su propio punto de conexión web mediante Azure Functions o de otro modo, úselo en lugar del predeterminadohttps://webendpointexample.azurewebsites.net/api/DeviceState.

Abra la aplicación de Comandos personalizados que creó anteriormente.

Vaya a Puntos de conexión web y seleccione Nuevo punto de conexión web.

New web endpoint

Configuración	Valor sugerido	Description
Nombre	UpdateDeviceState	Nombre del punto de conexión web.
URL	`https://webendpointexample.azurewebsites.net/api/DeviceState`	Dirección URL del punto de conexión con el que quiere que se comunique la aplicación de comandos personalizados.
Método	POST	Interacciones permitidas (como GET, POST) con el punto de conexión.
Encabezados	Clave: app. Valor: tomar los primeros ocho dígitos de applicationId	Parámetros de encabezado que se incluirán en el encabezado de solicitud.

Nota

El punto de conexión web de ejemplo que se creó con Azure Functions, que establece un enlace con la base de datos que guarda el estado del dispositivo tanto del televisor como del ventilador.
El encabezado sugerido solo es necesario para el punto de conexión de ejemplo.
Para tener la seguridad de que el valor del encabezado es único en nuestro punto de conexión de ejemplo, tome los primeros 8 dígitos de su applicationId.
En realidad, el punto de conexión web puede ser el punto de conexión al centro de IoT que administra los dispositivos.

Seleccione Guardar.

Llamada a los puntos de conexión web

Diríjase al comando TurnOnOff, seleccione ConfirmationResponse en regla de finalización y, a continuación, seleccione Agregar una acción.
En Nuevo tipo de acción, seleccione Call web endpoint (llamar a un punto de conexión web).
En Editar acción: puntos de conexión, seleccione UpdateDeviceState, que es el punto de conexión web que hemos creado.

En Configuración, introduzca los siguientes valores:

Call web endpoints action parameters

Configuración	Valor sugerido	Descripción
Puntos de conexión	UpdateDeviceState	Punto de conexión web que quiere llamar en esta acción.
Parámetros de consulta	item={SubjectDevice}&&value={OnOff}	Parámetros de consulta que se anexarán a la dirección URL del punto de conexión web.
Contenido del cuerpo	N/D	Contenido del cuerpo de la solicitud.

Nota

Los parámetros de consulta sugeridos solo son necesarios para el punto de conexión de ejemplo.

Desde En caso de éxito: acción para ejecutar, seleccione Send speech response (enviar respuesta de voz).

En Simple editor (Editor sencillo), escriba {SubjectDevice} is {OnOff}.

Configuración Valor sugerido Descripción

Acción para ejecutar Enviar respuesta de voz Acción que se va a ejecutar si la solicitud al punto de conexión web se realiza correctamente.
Nota
- También puede acceder directamente a los campos de la respuesta HTTP mediante {YourWebEndpointName.FieldName}. Por ejemplo: {UpdateDeviceState.TV}
Desde En caso de error: acción para ejecutar, seleccione Send speech response (enviar respuesta de voz).

En Simple editor (Editor sencillo), escriba Sorry, {WebEndpointErrorMessage}.

Configuración Valor sugerido Descripción

Acción para ejecutar Enviar respuesta de voz Acción que se va a ejecutar si hay un error en la solicitud al punto de conexión web.
Nota
- {WebEndpointErrorMessage} es opcional. Puede quitarlo si no quiere exponer ningún mensaje de error.
- En nuestro punto de conexión de ejemplo, se devuelve una respuesta HTTP con mensajes de error detallados para los errores comunes, tales como los parámetros de encabezado faltantes.

Configuración	Valor sugerido	Descripción
Acción para ejecutar	Enviar respuesta de voz	Acción que se va a ejecutar si la solicitud al punto de conexión web se realiza correctamente.

Configuración	Valor sugerido	Descripción
Acción para ejecutar	Enviar respuesta de voz	Acción que se va a ejecutar si hay un error en la solicitud al punto de conexión web.

Prueba en el portal de pruebas

Si la respuesta es correcta, guarde, pruebe y entrene.
Si la respuesta es incorrecta, quite uno de los parámetros de consulta y guarde, vuelva a entrenar y pruebe.

Integración con la aplicación cliente

En Envío de una actividad de Comandos personalizados a la aplicación cliente, agregó una acción Send activity to client (Enviar actividad al cliente). La actividad se envía a la aplicación cliente, independientemente de si la acción Call web endpoint (llamar a un punto de conexión web) se realiza correctamente o no. Sin embargo, normalmente solo querrá enviar la actividad a la aplicación cliente cuando la llamada al punto de conexión web se realice correctamente. En este ejemplo, es cuando el estado del dispositivo se actualizó correctamente.

Elimine la acción Send activity to client (enviar una actividad al cliente) que agregó anteriormente.
Edite la acción de llamada a un punto de conexión web:
1. En Configuración, asegúrese de que Parámetros de consulta sea item={SubjectDevice}&&value={OnOff}
2. Desde En caso de éxito, cambie Acción para ejecutar por Send activity to client (enviar una actividad al cliente).
3. Copie el código JSON siguiente en el campo Activity content (contenido de la actividad).
```
{
   "type": "event",
   "name": "UpdateDeviceState",
   "value": {
     "state": "{OnOff}",
     "device": "{SubjectDevice}"
   }
 }
```

Ahora, solo envía la actividad al cliente cuando la solicitud al punto de conexión web se realiza correctamente.

Creación de objetos visuales para sincronizar el estado del dispositivo

Agregue el siguiente código XML a MainPage.xaml antes del bloque EnableMicrophoneButton.

<Button x:Name="SyncDeviceStateButton" Content="Sync Device State"
        Margin="0,10,10,0" Click="SyncDeviceState_ButtonClicked"
        Height="35"/>
<Button x:Name="EnableMicrophoneButton" ......
        .........../>

Sincronización del estado de dispositivo

En MainPage.xaml.cs, agregue la referencia using Windows.Web.Http;. Agregue el siguiente código a la clase MainPage . Este método enviará una solicitud GET al punto de conexión de ejemplo y extraerá el estado actual del dispositivo para la aplicación. Asegúrese de cambiar <your_app_name> por el valor que usó en el encabezado del punto de conexión web de Comandos personalizados.

private async void SyncDeviceState_ButtonClicked(object sender, RoutedEventArgs e)
{
    //Create an HTTP client object
    var httpClient = new HttpClient();

    //Add a user-agent header to the GET request.
    var your_app_name = "<your-app-name>";

    Uri endpoint = new Uri("https://webendpointexample.azurewebsites.net/api/DeviceState");
    var requestMessage = new HttpRequestMessage(HttpMethod.Get, endpoint);
    requestMessage.Headers.Add("app", $"{your_app_name}");

    try
    {
        //Send the GET request
        var httpResponse = await httpClient.SendRequestAsync(requestMessage);
        httpResponse.EnsureSuccessStatusCode();
        var httpResponseBody = await httpResponse.Content.ReadAsStringAsync();
        dynamic deviceState = JsonConvert.DeserializeObject(httpResponseBody);
        var TVState = deviceState.TV.ToString();
        var FanState = deviceState.Fan.ToString();
        await CoreApplication.MainView.CoreWindow.Dispatcher.RunAsync(
            CoreDispatcherPriority.Normal,
            () =>
            {
                State_TV.Text = TVState;
                State_Fan.Text = FanState;
            });
    }
    catch (Exception ex)
    {
        NotifyUser(
            $"Unable to sync device status: {ex.Message}");
    }
}

Prueba

Inicie la aplicación.
Seleccione Sincronizar estado del dispositivo.
Si probó la aplicación con turn on tv en la sección anterior, notará que el televisor aparece como encendido.
Seleccione Habilitar micrófono.
Seleccionar el botón Hablar.
Diga turn on the fan. El estado visual del ventilador debe cambiar a encendido.

Pasos siguientes

Actualización de un comando desde una aplicación cliente