Zoho CRM用Node JS SDK - 概要
Node SDKはZoho CRM APIのラッパーです。したがって、NodeアプリケーションからZoho CRM APIを呼び出すと、最も適切なレスポンスを提供する関数が呼び出されます。
このSDKは、シングルユーザー認証とマルチユーザー認証の両方をサポートしています。
Zohoクライアントの登録
Zoho CRM APIはOAuth2標準で認証されているため、クライアントアプリをZohoで登録する必要があります。アプリを登録するには：
- こちらのページにアクセスしてください。https://accounts.zoho.com/developerconsole
- ［クライアントIDの追加］をクリックしてください。
- クライアント名、クライアントのドメイン、リダイレクトURIを入力してください。
- ［クライアントの種類］には、［Webベース］を選択してください。
- ［作成］をクリックしてください。
- これで、クライアントアプリが作成され、表示されるようになります。
- 新しく登録されたアプリのクライアントIDとクライアントシークレットは、［オプション］→［編集］をクリックして確認できます。
（オプションは、右隅にある3つの点のアイコンです）
Node CRM SDKのインストール
Node JS SDKがインストールされ、'zcrmsdk'という名前のパッケージがローカルマシンに作成されます。
パッケージは、次のコードを使用して追加できます。
var ZCRMRestClient = require('zcrmsdk')
SDKのインストール
Node JS SDKのインストール方法を次に示します。
- 次のコマンドを実行してください。
npm install zcrmsdk
SDKをインストールするもう1つの方法は、最新バージョン（推奨）でnodeサーバーのpackage.jsonに追加し、ディレクトリーでnpm installを実行し、package.json内のすべての依存関係をインストールすることです。
SDKのアップグレード
- 次のコマンドを実行して、Node JS SDKを最新バージョンにアップグレードしてください。
npm install --upgrade zcrmsdk
設定
OAuthクライアントの詳細は、SDKにプロパティーファイルとして提供する必要があります。SDKでは、oauth_configuration.propertiesという名前のファイルを設定する必要があります。そのファイルにそれぞれの値を入力してください。ファイルは、SDKが使用されているresourcesフォルダーの下に配置できます。
次のキーの値のみを入力してください。
ドメイン（EU、CN）に基づいて、crm.iamurlの値を変更してください。デフォルト値はUSドメインとして設定されています。
oauth_configuration.propertiesファイルの場合：
[zoho]
crm.iamurl=
crm.clientid=
crm.clientsecret=
crm.redirecturl=
- crm.clientid、crm.clientsecret、crm.redirecturlは、Zohoクライアントの登録後に取得するOAuthクライアントの設定です。
- crm.iamurlはアカウントのURLです。accounts.zoho.comやaccounts.zoho.euなどがあります。crm.iamurlが指定されていない場合、デフォルトでは、URLはaccounts.zoho.comになります。
configuration.propertiesファイルの場合：
[crm]
api.url=
api.user_identifier=
api.tokenmanagement=
[mysql]
username=
password=
- api.urlは、APIを呼び出すためのURLです。デフォルトのURLはwww.zohoapis.comです。
- api.user_identifierはデフォルトでは空です。シングルユーザー認証の場合、このキーにそれぞれのメールIDを入力すると、すべての呼び出しはこのユーザーの認証を使用して行われます。
- api.tokenmanagementは、トークンを管理、保守するための手段です。tokenmanagementが指定されていない場合は、SDKのデフォルト実装（mysql）に従います。
- すでにMySQL用に作成されている場合は、ここにusernameとpasswordを指定できます。
configuration.propertiesファイルで指定された上記のキーはすべてオプションです。
トークンストレージメカニズム
SDKが提供するデフォルトのトークンストレージを使用するには、次の操作を行います。
Mysqlはlocalhostのデフォルトポートで実行する必要があります。
zohooauthという名前のデータベースが作成され、以下の設定のテーブルがデータベースに存在する必要があります。「oauthtokens」という名前のテーブルには、「useridentifier」（varchar）、「accesstoken」（varchar）、「refreshtoken」（varchar）、「expirytime」（bigint）という列が必要です。
設定が設定されると、トークンの保存と取得がSDKによって処理されます。
独自のメカニズムを利用したい場合は、api.tokenmanagementでそれぞれのタブを指定することで、configuration.propertiesにそのメカニズムを記述できます。
このタブには、以下のメソッドが含まれている必要があります。
- saveOAuthTokens(token_obj)
- updateOAuthTokens(token_obj)
- レスポンスに関係なく、次の実行が行われます。そのため、取り扱いに注意する必要があります。
- getOAuthTokens()
- このメソッドで予想されるレスポンス：jsonレスポンスとexpirytime、refreshtoken、accesstoken項目を含むJSON配列。
注：
- すべてのメソッドがpromiseを返す必要があります。
saveOAuthtoken、updateOAuthTokensは、以下の項目を含むJSONパラメーターで呼び出されます。
access_token
refresh_token
expires_in
カスタムトークン管理のgetOAuthTokens()のサンプルコード
tokenmanagement.getOAuthTokens = function(user_identifier){ //有効期限：1527839622728
return new Promise(function(resolve,reject){
var result = {};
result.accesstoken = '1000.xxxxxxxxxxxxxxxx.xxxxxxxxxxxxxxxx';
result.expirytime = 15278396227289
result.refreshtoken = '1000.xxxxxxxxxxxxxxxx.xxxxxxxxxxxxxxxx';
var result_array =[];
result_array.push(result);
resolve(result_array);
});
}
初期化
アプリが起動されるたびに、以下のコードスニペットが初期化のために呼び出されます。
var ZCRMRestClient = require('zcrmsdk');
ZCRMRestClient.initialize().then(function()
{
//初期化後に必要な処理を実行
})
自己承認の認可トークンとリフレッシュトークンの作成
セルフクライアントアプリの場合、Zoho Developer Console（https://accounts.zoho.com/developerconsole）から自己承認認可トークンを作成する必要があります。
- https://accounts.zoho.com/developerconsoleにアクセスしてください。
- 権限を付与するクライアントの［オプション］→［セルフクライアント］をクリックしてください。
- 承認する有効なZoho CRMスコープを（複数の場合はカンマで区切って）［スコープ］項目に入力し、有効期限を選択してください。「aaaserver.profile.READ」スコープとZoho CRMスコープを指定してください。
- バックアップ用の認可トークンをコピーしてください。
- 以下のURLでPOSTリクエストを行うことによって、認可トークンからrefresh_tokenを作成できます。
https://accounts.zoho.com/oauth/v2/token?code={grant_token}&redirect_uri={redirect_uri}&client_id={client_id}&client_secret={client_secret}&grant_type=authorization_code
- バックアップ用のリフレッシュトークンをコピーしてください。
作成したた認可トークンは、作成時に選択した規定時間のみ有効です。したがって、その時間内にアクセストークンとリフレッシュトークンを作成する必要があります。
サーバーを再起動するたびに、この関数を呼び出す必要があります。この関数を呼び出す前に、両方の設定ファイルに適切な値を入力する必要があります。そうしないと、例外がスローされます。
すべての関数が、zcrmノードSDKでpromiseを返します。
メソッド呼び出しを通じてアクセストークン、リフレッシュトークンを認可トークンから取得する
ZCRMRestClient.generateAuthTokens(user_identifier,grant_token).then(function(auth_response){
console.log("access token :"+auth_response.access_token);
console.log("refresh token :"+auth_response.refresh_token);
console.log("expires in :"+auth_response.expires_in);
});
アクセストークンとリフレッシュトークンが作成されます。アクセストークンの有効期限が切れた場合は、SDKにより自動的にリフレッシュされます。
リフレッシュトークンを持っているユーザーがアクセストークンを作成する必要がある場合は、以下の関数を使用できます。
ZCRMRestClient.generateAuthTokenfromRefreshToken(user_identifier,refresh_token).then(function(auth_response){
console.log("access token :"+auth_response.access_token);
console.log("refresh token :"+auth_response.refresh_token);
console.log("expires in :"+auth_response.expires_in);
});
見込み客を取得するためのAPI呼び出しのサンプル：
var input ={};
input.module = "Leads";
var params = {};
params.page = 0;
params.per_page = 5;
input.params = params;
zcrmsdk.API.MODULES.get(input).then(function(response){
var result = "<html><body><b>Leads</b>";
var data = response.body;
data = JSON.parse(data);
data = data.data;
for (i in data){
var record = data[i];
var name = record.Full_Name;
result+="<span>"+name+"</span>";
}
result+="</body></html>";
})
階層
zcrmsdk
API
ORG
get
MODULES
get
post
put
delete
getAllDeletedRecords
getRecycleBinRecords
getPermanentlyDeletedRecords
search
SETTINGS
getFields
getLayouts
getCustomViews
updateCustomViews
getModules
getRoles
getProfiles
getRelatedLists
ACTIONS
convert
USERS
get
ATTACHMENTS
uploadFile
deleteFile
downloadFile
uploadLink
uploadPhoto
downloadPhoto
deletePhoto
FUNCTIONS
executeFunctionsInGet
executeFunctionsInPost
階層に表示されるように、zcrmsdkエンティティーには、様々なプロパティーを取得するための変数があります。
たとえば、タブのデータを取得するためにAPIを呼び出すには、リクエストはzcrmsdk.API.MODULES.{operation_type}にする必要があります。操作タイプには、GET、POST、PUT、DELETE、CREATEがあります。
レスポンス処理
すべてのAPI呼び出しにより、ファイルのダウンロードを除くZoho APIによって提供される実際のAPIレスポンスが提供されます。
ファイルをダウンロードする場合、レスポンスには追加の項目ファイル名が含まれます。
エラー処理：
すべてのエラーは明示的にスローされ、同じエラーを見つけるときには注意を払う必要があります。