Adobe Sign APIの紹介 #AdobeIO

Adobe Signはアドビが提供する電子サインソリューションです。面倒な書類や契約書の電子サインプロセスを一括管理することで最適化、最短化することができきます。

Adobe Sign APIsは、Signソリューションが提供する機能をアプリケーションから利用、統合します。

Adobe Sign APIでできること

https://blog.adobe.com/media_d2608ac7bd852e4bde5e05fc6bd4f2ca092ff872.gif

青のブロックで示した機能をAPIで操作することができます。

Adobe Sign APIを前編、後編でまとめます。

前編では、Adobe Sign APIを利用するための諸手続きやHTTP (REST API）を使ってAPIでできることについて学びます。
後編では、Java, JavaScript with Node.js, JavaScriptを使って簡単なプログラムを作ります。

Adobe Sign APIのドキュメントは充実しています。

Overview（Adobe I/Oポータルより）
https://www.adobe.io/apis/documentcloud/sign/docs/overview.html

Adobe Sign REST API Version 5 Methods（Adobe Signダッシュボードより）
https://secure.jp1.echosign.com/public/docs/restapi/v5

これらのドキュメントは現在英語のみです。このブログでは原文を要約して日本語で説明していきます。

プログラムの前準備としてAPIを使うアプリケーションを登録し、アプリケーションキーを取得しなければなりません。Adobe製品の開発キットはAdobe I/O Consoleに統合されますが、Adobe Sign APIはまだAdobe I/Oポータルに完全には統合されていないため、Adobe Sign Consoleへのリンクが張られます。

アプリケーションを開発するまでの手順

Adobe Sign開発者アカウントの取得
アプリケーションの登録とクライアントIDの取得
アプリケーションの認証（OAuth)を構成
アクセストークンの取得

アプリケーションを開発するまでの工程を考えると上のようなリストになります。

Adobe Sign開発者ライセンスの取得

Adobe Signとインテグレーションを行うアプリケーションを開発するためにはアプリケーションのClient IDを取得したり、認証システムと繋げたりしますので、まずはAdobe Signの開発者ライセンスを取得します。
すでにAdobe Signの開発者ライセンスを取得されている方は改めて開発者ライセンスを取得する必要はありません。
また、既に、Adobe Sign に登録したメールアドレス（無料試用版含む）は開発者ライセンス（Developer Edition）のアカウントとして利用できませんので、新しくメールアドレスをご準備ください。

開発者向けアカウントの取得はこちら(https://acrobat.adobe.com/us/en/sign/developer-form.html) から行います。
開発者アカウントの取得、APIの利用は無料です。
しかし開発者アカウントで登録できるユーザー数は10名まで、また電子サインを依頼するドキュメントには商用利用はできない旨の透かしが入ります。

それでは、登録サイトを簡単に解説します。
https://blogs.adobe.com/japan-conversations/files/2018/04/SignDevAcct.jpg

まず、名前や会社名などを入力します。会社所在地（国）を選択すると都市選択フィールドが表示されますので、これを入力してContinueボタンを押します。

https://blogs.adobe.com/japan-conversations/files/2018/04/SignUpSign.jpg

パスワード指定画面が表示されますので、任意のパスワードを指定して更に国と誕生日を入力の上、Sign Upボタンを押して開発者アカウントの登録を行います。

重要）
アカウントを登録する時に選択した”国”によって利用するAdobe Signのインスタンス（na1, eu1, jp1 など）が変わります。これによりAdobe Sign APIのエンドポイント（URL)が変わります。

Adobe SignインスタンスIDを参考に、どのインスタンスを利用するか確認してください。

アプリケーションの登録とクライアントIDの取得

Adobe SignはOAuth認証を使用してSign APIエンドポイントのリクエストを承認します。そのため予めAdobe Sign Web UIからクライアントIDとクライアントシークレットを取得します。

https://blogs.adobe.com/japan-conversations/files/2018/04/SignLogin.jpg

登録したアカウントでAdobe Sign Web UIにログインします。

https://blogs.adobe.com/japan-conversations/files/2018/04/SignWebUI.jpg

Adobe Sign Web UIのAPIタブをクリックすると下図のようなAPI情報ページが表示されます。APIアプリケーションサイドメニューを選んでアプリケーションを作成（登録）します。

https://blogs.adobe.com/japan-conversations/files/2018/04/SignWebUI2.jpg

顧客：テストや内部のみで使用する場合はこちらを指定します。あなたのアカウントに登録されたデータのみアクセスできます。
パートナー：プロダクションや一般向けのアプリケーションではこちらを指定します。すべてのAdobe Signのデータにアクセスできます。

アプリケーションIDとクライアントシークレットはAdobe Sign APIでアクセストークンを取得するために使用されます。

アプリケーションの認証（OAuth)を構成

作成するアプリケーションがAdobe Sign APIを呼び出せるようにOAuthを構成します。

https://blogs.adobe.com/japan-conversations/files/2018/04/SignAPIApplicationPanel.jpg

”アプリケーション向けにOAuthを設定”をクリックすると下の『OAuthを設定』ウインドウが表示されます。

ここで得られるクライアントID,クライアントシークレットを使ってアクセストークンを取得するプログラムを併記しました。プログラムの詳細は以降で説明します。

https://blogs.adobe.com/japan-conversations/files/2018/04/AuthConfig1.jpg

＊）Web UIに同じ値を Client IDまたはApplication IDと記載している箇所がありますが同じものです。

『OAuthを設定』ウインドウでは、アプリケーションがアクセスできるリソースとアクションを指定します。
アプリケーションはAdobe Signの機能を利用するためにAdobe Sign APIを呼び出します。呼び出されるAPIは実行に必要な “範囲” が定義されています。例えばsendDocument APIにはagreement_sendが有効である必要があります。
API ReferenceドキュメントにはAPIにどの ”範囲” を指定する必要があるか説明があります。利用するAPIに応じて ”範囲” を有効化してください。

アクセストークンの取得 (REST API)

ここまでは手続きの説明でしたが、ここから少しだけ技術系ブログになります。
これまでの手続きはクライアント個別の認証を行うためのもので、ここで取得したクライアントIDを元にアクセストークンを取得します。

参考文書として Using OAuth to Access Adobe Sign APIs を紹介します。英語のページになりますが、アクセストークン取得までの手続きを説明しています。

内容は重複しますがアクセストークン取得までの手順を日本語で説明します。

Adobe Signのアクセストークンの取得はOAuth2.0のAuthorization Code Grantで定義された認可フローになるのでしょうか。response_type に token を指定してみましたが、access_tokenではなくcodeが返ってきます。
この方法では、まず認可コードを取得し、認可コードをAccess Tokenに交換します。

Authorization Code Grant (認可コードフロー）

認可コードの取得

https://secure.jp1.echosign.com/public/oauth?                                           // Adobe Signの認可エンドポイント
    redirect_uri=https%3A%2F%2Flocalhost%3A8443%2FoauthDemo%2Fcallback.php&             // リダイレクトURL 　*1)
    response_type=code&                                                                 // 返信のタイプを指定
    client_id=CBJCXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXhg9-09t&                             // クライアントID　*2) 
    scope=widget_read                                                                   // アクセスするリソースを宣言します *3)

*1) 今回はテスト用に自分のマシン上にxamppをインストールしてリダイレクトを受け取ります。
*2) Adobe Sign UIパネルでAPIアプリケーションを登録した際に取得できるクライアントID
*3) scopeに指定する”範囲”はSign UIパネルでAPIアプリケーションを登録する際に指定するOAuthを設定ダイアログボックスの”有効？”チェックボックスにチェックしておかないとaccess deniedでエラーになります。

認可コードの取得をPHPでサンプルプログラムを書いてみます。

index.php – 認可コードの取得要求をAdobe Sign OAuthエンドポイントに送信します。

<?php
    $redirect = 'https://localhost:8443/oauthDemo/callback.php';
    $endpoint = 'https://secure.jp1.echosign.com/public/oauth';

    $params = array(
        'redirect_uri' => $redirect,
        'response_type' => 'code',
        'client_id' => 'CBJCXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXhg9-09t',
        'scope' => 'user_login agreement_send'
    );
 
    header("Location: " . $endpoint . '?' . http_build_query($params));
?>

callback.php – リダイレクトされた先で認可コード、トークンエンドポイントを受け取ります。

<?php
    echo $_GET['code'];
    echo $_GET['api_access_point'];
    echo $_GET['web_access_point'];
?>

アクセストークンと交換

次に、認可コードの取得で得た “code とAdobe Sign UIでAPIアプリケーションの作成で取得したClient ID, Client Sercretを用いてアクセストークンと交換します。トークンの交換にはトークンエンドポイントにPOSTリクエストを発行します。

サンプルリクエスト

POST oauth/token HTTP/1.1
Host: api.jp1.echosign.com

Content-Type: application/x-www-form-urlencoded

code=CBNCKBAAHBCAABAANSwUl8rZhXSnOWyoMPAHPpfngzdXXxwt&
client_id=CBJCXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXhg9-09t&
client_secret=QDXXXXXXXXXXXXXXXXXXXXXXXXXXXl6i1&
redirect_uri=https%3A%2F%2Flocalhost%3A8443%2FoauthDemo%2Fcallback.php&
grant_type=authorization_code

このサンプルリクエストをPHPで書いてみます。（先ほど作成した認可コードを取得する callback.php を書き換えます。）

<?php
    $clientId = 'CBJCXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXhg9-09t';      // Sign UI - APIアプリケーション作成時に発行されるID
    $clientSecret = 'QDXXXXXXXXXXXXXXXXXXXXXXXXXXXl6i1';              // Sign UI - APIアプリケーション作成時に発行されるSecret
    $redirect = 'https://localhost:8443/oauthDemo/callback.php';     // Sign UI - APIアプリケーション作成時に指定したRedirect URL

    $data = array(
        'code' => $_GET['code'],                                     // 認可コードの取得で得られる code
        'client_id' => $clientId,
        'client_secret' => $clientSecret,
        'redirect_uri' => $redirect,
        'grant_type' => 'authorization_code'
    );

    $headers = array('Content-Type: application/x-www-form-urlencoded');
    $options = array('http' => array(
        'method' => 'POST',
        'content'=> http_build_query($data),
        'header' => implode("\r\n", $headers)
    ));

    // リクエストエンドポイントは認可コードの取得で得られる api_access_point パスに oauth/token を足した
    $res = file_get_contents($_GET['api_access_point'] . 'oauth/token', false, stream_context_create($options));
    $response = json_decode($res, true);

    echo 'access_token: ' . $response['access_token'] . '<br>';
    echo 'refresh_token: ' . $response['refresh_token'] . '<br>';
    echo 'token_type: ' . $response['token_type'] . '<br>';
    echo 'expire: ' . $response['expires_in'] . '<br>';

?>

アクセストークンが取れました。

これでAdobe Signに対して書類のアップロードや、承認リクエストの送信、承認状況の確認等、用意されたAPIを利用できるようになりました。この記事ではREST APIを使った各機能を説明します。

記事の最初に説明しましたが、Adobe Sign APIsにはREST APIの他にJava SDK, JavaScript SDK, JavaScript SDK for Node.jsがあります。この記事ではREST APIを説明、他プログラム言語SDKは後編で扱います。

Adobe Sign REST APIs

Adobe SignのREST APIを理解するのにこのページ Adobe SIgn REST API Version 5 Methods が便利です。
またREST APIを使ったサンプルプログラム集 (Java)を下図のリンク「REST APIのサンプル」からダウンロードできます。

https://blogs.adobe.com/japan-conversations/files/2018/04/SignAPISample.jpg

更にAPI USAGEも役に立ちます。

Adobe Sign REST API Version 5 Methodsは英語ページなので、ここで使い方を簡単に説明します。サンプルプログラムのコンパイル方法や使い方についてはAdobe Sign APIs 後編にて説明します。

Adobe Sign REST API Version 5 Methods

このページではAccess Tokenの取得から各REST APIの動作検証（試用）まで行えます。実際にAdobe SignにREST APIを発行して、返信を確認することができます。

ページ前半 **“How to get started“**はAccess tokenの取得についての説明で、これは、この記事でも説明したことなので読み飛ばしてください。

ページ中盤 “Using the “Try it out” functionality” はページ下のResources and Operationsを説明します。Resouces and OperationsはREST APIを試すためのUIでAPIに必要なパラメータをセットしてTry it out (試用）することができます。APIの動作やレスポンスが正しいかをこのページで試すことができます。

**Developer Implementation Notes**ではREST APIを使って実装する場合の注意点を説明しています。目を通しておいてください。
ノートを要約すると

APIでは識別子やURLの長さを指定することができません。開発者はURLの長さは2083文字まで、識別子は512文字まで扱えるように設定する必要があります。
enum値や返り値が追加される場合があります。このような拡張に対してAPIクライアントは適切な方法で処理できる方法を意識してAPIを呼び出す必要があります。

Resources and Operationsの使い方を説明します。これは対話型のUIでREST APIを発行する際に必要な情報をセットしてAPIを発行し、返信を受け取り、その結果を表示します。

まず簡単なところでbase_urisをテストします。

https://blogs.adobe.com/japan-conversations/files/2018/04/SingRestAPI1.jpg

赤丸で囲ったbase_urisをクリックします。

https://blogs.adobe.com/japan-conversations/files/2018/04/SignRestAPI_BaseURL1.jpg

base_urisのREST UI操作パネルが表示されます。右上のOAuth access tokenボタンをクリックしてAccess Tokenを取得します。赤下線のところにアクセストークンが表示されます。
ここで Try it outボタンをクリックすると base_uris REST APIが発行されます。

https://blogs.adobe.com/japan-conversations/files/2018/04/SignRestAPI_BaseURL2.jpg

REST APIが実行された結果が表示されます。

このようにAdobe Sign REST API Version 5 MethodsページではREST APIを試用することができます。

このブログはAdobe Sign UIを使ってAPIアプリケーションの登録からAccess Tokenの取得、REST APIを試用して動作を確認するところまで説明しました。

次回はJava, Node.jsでAdobe SIgnの機能を利用するアプリケーションを作ってみたいと思います。

投稿者
Yoshiaki Nagayasu