Google Dialogflow APIs and other services of Google

Anh-Thi Dinh
Google's documentation is like an ocean. It's not easy to find a right one to start. This note contains only basic things that I've already worked with. Try your own hand at Google's APIs will help you understand more.
☝️
This note is mainly for Dialogflow APIs. However, I mention also the other services of Google.

Official documentation

Some services

  • Active API on some projects: Service Usage SDK | REST API
    • Note: APIs can only be activated for Projects, neither folder nor organization!
⚠️
When you use any NodeJS service, for example,
1const client = new library.SampleClient(opts?: ClientOptions);
The opts is described here.

Wanna run the Node.js samples?{:#run-samples}

⚠️
The old version uses dialogflow and @type/dialogflow. The new version uses only one @google-cloud/dialogflow!
⚠️
On SDK documentation, they don't mention about the location in the parent property. For example, they say "parent can be projects/<Project ID or '-'>", but you can add the location information inside it like that
1const parent = (location) => "projects/-" + "/locations/" + location;
☝️
You have to enable the Dialogflow API in the current project. Other wise, we meet below problem.
17 PERMISSION_DENIED: Dialogflow API has not been used in project 284022294153 before or it is disabled. Enable it by visiting <https://console.developers.google.com/apis/api/dialogflow.googleapis.com/overview?project=284022294153> then retry. If you enabled this API recently, wait a few minutes for the action to propagate to our systems and retry.
You can use Service Usage to enable a service on some project programmatically or go to beflow url to active it visually,
1<https://console.developers.google.com/apis/api/cloudresourcemanager.googleapis.com/overview?project=><projectId>

Wanna try gapi (JS client)?

⚠️
Google has announced that they will be discontinuing the Google Sign-In JavaScript Platform Library for web. You will have to switch to using Google Identity Services (or Sign In With Google or gsi). The old service will be completely discontinued on March 31, 2023.
1<!-- OLD -->
2<script src="<https://apis.google.com/js/platform.js>" async defer></script>
3
4<!-- NEW -->
5<script src="<https://accounts.google.com/gsi/client>" async defer></script>
What's this gapi? You can use it completely inside an HTML file without using any backend.
👉 List of samples (google apis javascript client).
👉 You have to use REST API in this case.
☝️
Tip: If you are using VSCode, you can install the Live Server extension to quickly create a server (port 5500 by default). Just click the button at the bottom right of the file and a website will appear.

The corresponding between REST API and Node.js clients

👉 REST API.
⚠️
Sometimes, the location infotmation is mentionned in the REST API but not in the SDK. For example, load the list of agents w.r.t. some location
  • SDK (the same as the general case), in this, we just need to add "location" into the agent property, like
    • 1const parent = (location) => "projects/-" + "/locations/" + location;

Using REST API in Node.js

  • First, you need to create a Service Account, then create a key and download the JSON file. Follow these steps.
⚠️
Remark: With keys generated from a service account (stored in JSON), we can only get 1 agent for methods like projects.agent.search although it says that we can get a list of agents. In this case, try to get access token via OAuth 2.0. With this, we can access to all projects instead of only 1 (which is used to generate the json file).

Dialogflow REST APIs with Postman

Location problem

👉 List of endpoints (containing location inside).
👉 LIst of location information you can use with Dialogflow.
You have to use the same endpoint and location information in the API/SDK. If you use them differently, for example,
1<https://global-dialogflow.googleapis.com/v2/projects/-/locations/europe-west1/agent:search>
You will meet an error like below,
1"Please switch to 'europe-west1-dialogflow.googleapis.com' to access resources located in 'europe-west1'."
In the SDK documention, they don't mention about the location you need to use in the agent property. For example, they say "parent can be projects/<Project ID or '-'>", but you can add the location information inside it like that
1const parent = (location) => "projects/-" + "/locations/" + location;
💡They are the same (for endpoints):
1dialogflow.googleapis.com
2us-dialogflow.googleapis.com
3global-dialogflow.googleapis.com

Custom roles

👉 Create here (then you need to choose a project / a folder / an organization)
  • If you choose a project, there are some roles cannot be added because they belongs to folders/organization (eg. resourcemanager.projects.list)
  • (ref) You have to pay (using Google Workspace or Google Identity) to create an organization or a folder.
☝️
If you already have a domain, you can try to create a Google Workspace and use it in 1 month of trial. After that, you can deactivate the Google Workspace account but the things on the Google Cloud Platform are still there and the organization you have created in Google Workspace is still working!
In case you wanna some tasks + don't wanna create a custom role (don't forget to check this list):

Service Account w.r.t Organization / Folder

👉 Create a service account. (and also the key for it > then download the JSON file)
  • By default, a service account can only access to the current project (even if you choose the roles which created in the organization/folder).
  • If you want that service account can perform tasks in the organization/folder, you have to go to IAM & Admin > IAM > choose the organization / folder (yes, IAM is different for different project/organization/folder) > ADD > add the email of the service account to New principals and choose a role for it.
☝️
If you use SDK listProjectsAsync to list all projects in the organization, you can only list the projects in that organization, not the ones inside a folder even if that folder belongs to the organization.
☝️
Quota: For each Service Account, the limit of number of projects you can create is 22. You can ask more but the better idea is to create another service account (and don't forget to remove the old one with its credentials).

Types for TypeScript

⚠️
The old version uses dialogflow and @type/dialogflow. The new version uses only one @google-cloud/dialogflow!
For example, the returned type for getAgent() method can be defined as,
1export type Agent = dialogflow.protos.google.cloud.dialogflow.v2.Agent;

Play with Intents, Examples and Entities

🎯 Aim: Suppose that we want to create a new entities via API (including the system entities).
  • List all intents from some agent: just put in the parent something like projects/<projectId>/agent and then click Execute. Don't forget to choose the intentView as INTENT_VIEW_FULL (without this one, you cannot see the examples or "trainingPhrases") 👈 Copy and remember the output of type Intent.
  • Create a new entities using this API. Again, put in parent as projects/<projectId>/agnet and then in the Request body, paste an object which looks like the output in the previous step (remember to remove "name" sections, this section will be created by DF), then Execute.