gRPC setup

Before developing and running client applications, you need to set up the gRPC environment for your programming language.

Basic steps

The basic steps in using the gRPC protocol for Dialog as a Service gRPC API are:

  1. Install gRPC for the programming language of your choice, including C++, Java, Python, Go, Ruby, C#, Node.js, and others. See gRPC Documentation  for a complete list and instructions on using gRPC with each language. Here and elsewhere in this document, Python will be used as an example.

    First, create a new directory for your sample apps, for example, dlg, and switch to that directory.

    mkdir dlg
cd dlg

    Then install Python gRPC libraries. Some details will depend on the platform and command shell you are using.

    For a POSIX or Mac OS using bash:

    pip install --upgrade pip
pip install grpcio
pip install grpcio-tools

    For Windows using cmd:

    python -m pip install --upgrade pip
pip install grpcio
pip install grpcio-tools

  2. Download the zip file containing the gRPC .proto files for the Dialog service. These files contain a generic version of the functions or classes that can interact with the dialog service. See Note about packaged proto files below.

  3. Unzip the file in a location that your applications can access, for example in the directory that contains or will contain your client apps.

    ├── Your client apps here
├── nuance_dialog_dialogservice_protos_v1.zip
└── nuance
    ├── dlg
    │   └── v1
    │       ├── common
    │       │   └── dlg_common_messages.proto
    │       ├── dlg_interface.proto
    │       └── dlg_messages.proto
    │
    ├── asr
    │   └── v1
    │       ├── recognizer.proto
    │       ├── resource.proto
    │       └── result.proto
    │
    ├── tts
    │   └── v1
    │       └── nuance_tts_v1.proto
    ├── nlu
    │   └── v1
    │       ├── interpretation-common.proto
    │       ├── multi-intent-interpretation.proto
    │       ├── result.proto
    │       ├── runtime.proto
    │       └── single-intent-interpretation.proto
    │
    ├── nrc
    │   └── v1
    │       └── nrc.proto
    └──rpc
        ├── error_details.proto
        ├── status.proto
        └── status_code.proto

  4. Generate client stub files in your programming language from the proto files.

    For Python:

    echo "Pulling support files"
mkdir -p google/api
curl https://raw.githubusercontent.com/googleapis/googleapis/master/google/api/annotations.proto > google/api/annotations.proto
curl https://raw.githubusercontent.com/googleapis/googleapis/master/google/api/http.proto > google/api/http.proto

echo "generate the stubs for support files"
python -m grpc_tools.protoc --proto_path=./ --python_out=./ google/api/http.proto
python -m grpc_tools.protoc --proto_path=./ --python_out=./ google/api/annotations.proto
echo "generate the stubs for the DLGaaS gRPC files"
python -m grpc_tools.protoc --proto_path=./ --python_out=./ --grpc_python_out=./ nuance/dlg/v1/dlg_interface.proto
python -m grpc_tools.protoc --proto_path=./ --python_out=./ nuance/dlg/v1/dlg_messages.proto
python -m grpc_tools.protoc --proto_path=./ --python_out=./ nuance/dlg/v1/common/dlg_common_messages.proto

echo "generate the stubs for the ASRaaS gRPC files"
python -m grpc_tools.protoc --proto_path=./ --python_out=./ --grpc_python_out=./ nuance/asr/v1/recognizer.proto
python -m grpc_tools.protoc --proto_path=./ --python_out=./  nuance/asr/v1/resource.proto
python -m grpc_tools.protoc --proto_path=./ --python_out=./ nuance/asr/v1/result.proto

echo "generate the stubs for the TTSaaS gRPC files"
python -m grpc_tools.protoc --proto_path=./ --python_out=./ --grpc_python_out=./ nuance/tts/v1/nuance_tts_v1.proto

echo "generate the stubs for the NLUaaS gRPC files"
python -m grpc_tools.protoc --proto_path=./ --python_out=./ --grpc_python_out=./ nuance/nlu/v1/runtime.proto
python -m grpc_tools.protoc --proto_path=./ --python_out=./ nuance/nlu/v1/result.proto
python -m grpc_tools.protoc --proto_path=./ --python_out=./ nuance/nlu/v1/interpretation-common.proto
python -m grpc_tools.protoc --proto_path=./ --python_out=./ nuance/nlu/v1/single-intent-interpretation.proto
python -m grpc_tools.protoc --proto_path=./ --python_out=./ nuance/nlu/v1/multi-intent-interpretation.proto

echo "generate the stubs for the NRaaS gRPC files"
python -m grpc_tools.protoc --proto_path=./ --python_out=./ --grpc_python_out=./ nuance/nrc/v1/nrc.proto

echo "generate the stubs for supporting files"
python -m grpc_tools.protoc --proto_path=./ --python_out=./ nuance/rpc/error_details.proto
python -m grpc_tools.protoc --proto_path=./ --python_out=./ nuance/rpc/status.proto
python -m grpc_tools.protoc --proto_path=./ --python_out=./ nuance/rpc/status_code.proto

    Depending on your programming language, the stubs may consist of one file or multiple files per proto file. These stub files contain the methods and fields from the proto files as implemented in your programming language. You will consult the stubs in conjunction with the proto files. See Dialog service gRPC API.

  5. Write your client app, referencing the functions or classes in the client stub files. See Client app development for details and a scenario.

Final structure

The resulting files contain the information in the proto files and stubs in your programming language.

├── Your client apps here
├── nuance_dialog_dialogservice_protos_v1.zip
├── google (support files)
└── nuance
    ├── dlg
    │   └── v1
    │       ├── common
    │       │   ├── dlg_common_messages.proto
    │       │   └── dlg_common_messages_pb2.py
    │       ├── dlg_interface.proto
    │       ├── dlg_interface_pb2.py
    │       ├── dlg_interface_pb2_grpc.py
    │       ├── dlg_messages.proto
    │       └── dlg_messages_pb2.py
    │
    ├── asr
    │   └── v1
    │       ├── recognizer_pb2_grpc.py
    │       ├── recognizer_pb2.py
    │       ├── recognizer.proto
    │       ├── resource_pb2.py
    │       ├── resource.proto
    │       ├── result_pb2.py
    │       └── result.proto
    │
    ├── tts
    │   └── v1
    │       ├── nuance_tts_v1.proto
    │       ├── nuance_tts_v1_pb2.py
    │       └── nuance_tts_v1_pb2_grpc.py
    ├── nlu
    │   └── v1
    │       ├── interpretation-common.proto
    │       ├── multi_intent_interpretation_pb2.py
    │       ├── multi-intent-interpretation.proto
    │       ├── result.proto
    │       ├── result_pb2.py
    │       ├── runtime.proto
    │       ├── runtime_pb2.py
    │       ├── runtime_pb2_grpc.py
    │       ├── single_intent_interpretation_pb2.py
    │       └── single-intent-interpretation.proto
    │
    ├── nrc
    │   └── v1
    │       ├── nrc.proto
    │       ├── nrc_pb2.py
    │       └── nrc_pb2_grpc.py
    └──rpc
        ├── error_details.proto
        ├── error_details_pb2.py
        ├── status.proto
        ├── status_pb2.py
        ├── status_code.proto
        └── status_code_pb2.py

Note about packaged proto files

The DLGaaS API provides features that require that you install the ASR, TTS, and NLU proto files:

  • The StreamInput request performs recognition on streamed audio using ASRaaS and requests speech synthesis using TTSaaS.
  • The ExecuteRequest allows you to specify interpretation results in the NLUaaS format.

For your convenience, these files are packaged with the DLGaaS proto files available here, and this documentation provides instructions for generating the stub files.

As such, the following files are packaged with this documentation:

  • For DLGaaS:
    • nuance/dlg/v1/dlg_interface.proto
    • nuance/dlg/v1/dlg_messages.proto
    • nuance/dlg/v1/common/dlg_common_messages.proto
  • For ASRaaS audio streaming:
    • nuance/asr/v1/recognizer.proto
    • nuance/asr/v1/resource.proto
    • nuance/asr/v1/result.proto
  • For TTSaaS streaming:
    • nuance/tts/v1/nuance_tts_v1.proto
  • For NLUaaS interpretation:
    • nuance/nlu/v1/runtime.proto
    • nuance/nlu/v1/result.proto
    • nuance/nlu/v1/interpretation-common.proto
    • nuance/nlu/v1/single-intent-interpretation.proto
    • nuance/nlu/v1/multi-intent-interpretation.proto
  • For NRaaS:
    • nuance/nrc/v1/nrc.proto
  • Supporting files for other services:
    • nuance/rpc/error_details.proto
    • nuance/rpc/status.proto
    • nuance/rpc/status_code.proto

What’s next?

Once you have the proto files and optionally the client stubs, you are ready to develop and run client applications with the help of sample clients: