Zoho APIで外部からZoho Projectsのタスクを作成

弊社では開発チームのタスク管理に「Zoho Projects」というプロジェクト管理ツールを採用しています。
「Zoho Projects」は各メンバの持ちタスクの優先度や期限の設定、
タスクをマイルストーン、タスクリストなどの粒度ごとで切り分けての工数管理、
ガントチャートでタスクの進捗率やアサイン状況が図式化…といった多種多様で
複雑なプロジェクト管理を比較的簡単な操作で行うことができるのが特徴です。

通常、「Zoho Projects」におけるタスク作成はブラウザ上の専用管理画面から手作業で行います。
今回はZohoが提供している「Zoho API」を使用し、タスク作成作業の自動化を行ってみます。
※Zohoアカウントの作成手順は今回省略します。
※「Zoho API」公式ドキュメント(英語)も併せてご覧ください。

1.Zohoアカウントに「クライアントID」とクライアントシークレットを作成する

「Zoho API」の使用には「クライアントID」とクライアントシークレットの2つの値が必要です。
これら2つの値はアカウントを作成しただけでは、自動生成されませんので手作業で作成します。

https://accounts.zoho.com/developerconsole
上記のページにアクセスし、「クライアントIDの追加」をクリックします。

クライアント名、クライアントのドメイン、認証済みのリダイレクトURI、Client Typeを求められます。
クライアント名は任意の名称、クライアントのドメインは自社サイトのURL、
認証済みのリダイレクトURIは自社サイト内の任意のページのURLなどで構いません。
Client Typeに関しては初期値の「Web Based」で特に問題ないかと思います。
「作成する」を押すことでクライアントIDとクライアントシークレットの作成が完了します。

完了画面にクライアントIDとクライアントシークレットが表示されますので、どこかにコピーしておきます。

2.認証リクエスト作業を行う

次に指定のURLから認証リクエストを行い、Zoho Apiへのアクセスを承認させます。

https://accounts.zoho.com/oauth/v2/auth?scope={スコープ}&client_id={クライアントID}&response_type=code&access_type={offlineまたはonline}&redirect_uri={認証済みのリダイレクトURI}&prompt=consent
上記の指定のURLへのアクセスには各種設定値の挿入が必要になります。
前項で使用した「クライアントID」、「認証済みのリダイレクトURI」の2つに加え、
「scope」「access_type」の2つが必要で、計4つの設定値の挿入が必要です。
「scope」はAPIアクセス時の公開を与える範囲の設定です。

https://www.zoho.com/projects/help/rest-api/tasks-api.html
上記のページ内で英語にて説明がありますが、該当プロジェクトの全てのタスクを読む場合は
「ZohoProjects.tasks.READ」という記述でAPIアクセス時の公開範囲を指定します。

今回はタスクの作成を行いたいので、「ZohoProjects.tasks.CREATE」と記述しましょう。
「access_type」に関しては「offline」に設定しておけば、特に問題はありません。
前述のURLの{スコープ}、{クライアントID}、{offlineまたはonline}、{認証済みのリダイレクトURI}、
計4カ所の値を書き換えた上でブラウザからアクセスを行います。

設定値に問題がなければ、承認ページが表示されます。
このまま先に進んでしまわずに、ここで一旦作業をとめてください。

3.POSTを行なって、アクセストークンの発行

「Zoho API」を使用するのに必要なアクセストークンを発行します。
(※この時点までに「Postman」などPOST・GETツールのご用意をおすすめします。)
今回は「Postman」を用いてPOSTを行い、アクセストークンを発行します。

https://accounts.zoho.com/oauth/v2/token?code={グラントトークン}&redirect_uri={認証済みのリダイレクトURI}&client_id={クライアントID}&client_secret={クライアントシークレット}&grant_type=authorization_code
前項で行なったのと同じように「クライアントID」、「認証済みのリダイレクトURI」、
「クライアントシークレット」の値をこれまでの過程で使用した取得値に置き換えます。
「グラントトークン」に関してはこれからの作業で取得した値を使用します。

「Postman」を起動しておき、前項の最後の工程で一旦とめてもらった作業を再開します。
承認ページ上で「承認する」をクリックしてみると、認証済みのリダイレクトURIにリダイレクトされます。

ブラウザのURL入力欄を見ると通常のURLではなく、色々な値が付与されているかと思います。
このURLのうち、code=●●●●●&location= の●●●●●にあたる値が「グラントトークン」です。
この「グラントトークン」は生成後2分間を越えると使用できなくなります。注意してください。
前述のURLの「グラントトークン」を差し替えた上でPostmanでPOSTを行います。

返ってきた値の中にアクセストークンやリフレッシュトークンが含まれています。
※このアクセストークンも1時間の使用期限付きです。

4.API経由でZohoのタスクを作成

それでは前項で取得したアクセストークンを使ってZoho Projects上でタスクを作成してみます。
今回は「Postman」上のPOST作業でタスクを作成してみます。

HeadersでkeyをAuthorization、Valueに前項で取得したtoken_typeとaccess_tokenを入力します。
token_typeとaccess_tokenに関しては「token_type(半角スペース)access_token」という形になります。