Zoho CRM用Node JS SDK - 概要

目次

Node SDKはZoho CRM APIのラッパーです。したがって、NodeアプリケーションからZoho CRM APIを呼び出すと、最も適切なレスポンスを提供する関数が呼び出されます。

このSDKは、シングルユーザー認証とマルチユーザー認証の両方をサポートしています。

Zohoクライアントの登録

Zoho CRM APIはOAuth2標準で認証されているため、クライアントアプリをZohoで登録する必要があります。アプリを登録するには：

  1. こちらのページにアクセスしてください。https://accounts.zoho.com/developerconsole
  2. ［クライアントIDの追加］をクリックしてください。
  3. クライアント名、クライアントのドメイン、リダイレクトURIを入力してください。
  4. ［クライアントの種類］には、［Webベース］を選択してください。
  5. ［作成］をクリックしてください。
  6. これで、クライアントアプリが作成され、表示されるようになります。
  7. 新しく登録されたアプリのクライアント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にそのメカニズムを記述できます。

このタブには、以下のメソッドが含まれている必要があります。

  1. saveOAuthTokens(token_obj)
  2. updateOAuthTokens(token_obj)
    • レスポンスに関係なく、次の実行が行われます。そのため、取り扱いに注意する必要があります。
  3. 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）から自己承認認可トークンを作成する必要があります。

  1. https://accounts.zoho.com/developerconsoleにアクセスしてください。
  2. 権限を付与するクライアントの［オプション］→［セルフクライアント］をクリックしてください。
  3. 承認する有効なZoho CRMスコープを（複数の場合はカンマで区切って）［スコープ］項目に入力し、有効期限を選択してください。「aaaserver.profile.READ」スコープとZoho CRMスコープを指定してください。
  4. バックアップ用の認可トークンをコピーしてください。
  5. 以下の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

  6. バックアップ用のリフレッシュトークンをコピーしてください。

作成したた認可トークンは、作成時に選択した規定時間のみ有効です。したがって、その時間内にアクセストークンとリフレッシュトークンを作成する必要があります。

サーバーを再起動するたびに、この関数を呼び出す必要があります。この関数を呼び出す前に、両方の設定ファイルに適切な値を入力する必要があります。そうしないと、例外がスローされます。

すべての関数が、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レスポンスが提供されます。

ファイルをダウンロードする場合、レスポンスには追加の項目ファイル名が含まれます。

エラー処理：

すべてのエラーは明示的にスローされ、同じエラーを見つけるときには注意を払う必要があります。