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.
👉 Github repo: dinhanhthi/google-api-playground
This note is mainly for Dialogflow APIs. However, I mention also the other services of Google.
- Dialogflow: SDK (other official site) | REST API
- Manage projects: Resource Manager SDK (other official site) | REST API
- Note: From version
2.0.0,resource-managerchange the package to@google-cloud/resource-manager. And from version3.0,0, the "folder" was introduced!
- 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.👉 Link of all (dialogflow nodejs) samples on github.
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 that1const 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>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.👉 REST API.
👉 Node.js SDK.
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
- REST (different with the general case): this link.
- SDK (the same as the general case), in this, we just need to add "location" into the
agentproperty, like
1const parent = (location) => "projects/-" + "/locations/" + location;- Normally, it's easier if we use Node.js SDK.
- First, you need to create a Service Account, then create a key and download the JSON file. Follow these steps.
- Check an example code.
- Remark: the code above use
requestwhich has been already deprecated! You can choose any alternative.
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).👉 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 that1const parent = (location) => "projects/-" + "/locations/" + location;💡They are the same (for endpoints):
1dialogflow.googleapis.com
2us-dialogflow.googleapis.com
3global-dialogflow.googleapis.com👉 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):
👉 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).
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;🎯 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
parentsomething likeprojects/<projectId>/agentand then click Execute. Don't forget to choose theintentViewasINTENT_VIEW_FULL(without this one, you cannot see the examples or "trainingPhrases") 👈 Copy and remember the output of typeIntent.
- Create a new entities using this API. Again, put in
parentasprojects/<projectId>/agnetand 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.