Adobe Sign SDK (JavaScript)の紹介 #AdobeIO

はじめに

2018年6月、Adobe Signの機能強化と機能改善が行われました。新たな機能の説明はAdobe Signリリースノートを参照してください。また機能強化に伴いAdobe Sign REST API Versionも5から6に更新されました。Version 5とVersion 6ではざっと見る限りwebhooks APIが追加され、各APIの整理、統合が行われました。この記事執筆時は、REST API Version 6のみ公開されました。SDKのV6対応スケジュールは公開され次第お知らせ致します。

この投稿について

前回はAdobe Sign APIを使うために必要な手続きについて説明しました。また簡単ではありましたがAdobe SignのREST APIの使い方を説明しました。

Adobe Sign にはREST API (HTTP) を利用する他に

JavaScript SDK for browser
JaveScript SDK for node.js
Java SDK

の開発キットが提供されます。この投稿ではサンプルソースコードを使いながらAdobe Sign SDKの使い方を説明します。

Adobe Sign SDKでできること

文書の送信
承認の作成と管理
署名済み文書の取り出し
署名済み文書の格納（アーカイブ）
アプリケーションへのサインUIの埋め込み
リマインダの送信
監査レポートのダウンロード
その他

のような機能を利用できます。

Adobe Sign JavaScript SDK

この投稿ではJavaScript SDKを説明します。JavaScript SDK はここからダウンロードします。

このSDKにはJavaScript SDK for browserとJavaScript SDK for node.jsの２つの開発環境が含まれます。

JavaScript SDK for browserはクライアント（ブラウザ）側で実行されるJavaScriptであり、JavaScript SDK for node.jsはサーバー側で実行されるJavaScriptになります。どちらの方式を採用するかは用途に応じて検討しなければなりません。どちらの方式でも提供される機能は同じです。

サンプルコードを使ってみる

SDKには機能を利用するためのAPIライブラリやリソースファイルと共にサンプルコードが提供されます。

Adobe Sign JavaScript SDK for browser

1) サンプルプログラムを動かすための環境を作ります。

Adobe Sign JavaScript SDK for browserはクライアント（ブラウザ）側で動作するJavaScriptからAPIを使用してAdobe Signの機能を操作します。一番オーソドックスなWebアプリケーション構成になります。まずパソコン上にWebサーバー環境を構築します。MacOSではhttpdを、WindowsではIISの標準搭載されるWeb環境を利用しましょう。またAPIはセキュアネットワークを必要とします。httpsが利用できる環境を構築してください。（各Webサーバーの有効化およびセキュアネットワークの構築方法につきましてはこの記事では省かせて頂きます。）

ダウンロードしたJavaScript SDKをWebサーバー上に配置(deploy)します。私はWindows 10にxamppというWebサービス環境を構築し、その環境下にAdobe SIgn JavaScript SDKを配置しました。(c:\\xampp\htdocs\sign\下SDKを展開）

ダウンロードした圧縮ファイルを解凍すると以下の階層（ディレクトリ）及びファイルを見ることができます。

https://blogs.adobe.com/japan-conversations/files/2018/07/WebRootDir.jpg

Adobe Sign JavaScript API for browserを構成するAPIはbrowser以下に集結します。

2）サンプルプログラムにアクセスします。

私の環境ではxampp webroot下にsignというディレクトリを作成して、その下にSDKを展開しました。

例）https://localhost:8443/sign/index.html

https://blogs.adobe.com/japan-conversations/files/2018/07/Sign_indexHTML.jpg

まずOAuth Sampleを動かしてみましょう。上記ページからOAuth sampleリンクをクリックするか、下記URLを指定します。

例）https://localhost:8443/sign/browser/rest-api-sample/api/oAuth/CreateGroupWithOAuthWorkFlow.html

このサンプルではOAuth認証コードの取得からOAuth アクセストークンの取得、グループ作成APIをコール、グループ作成までを行います。

https://blogs.adobe.com/japan-conversations/files/2018/07/SignOAuth.jpg

前回記事で説明しましたAdobe SignのAPIページから作成したAPIアプリケーションのアプリケーションID（クライアントID）をCLIENT_IDに指定します。また、今回使うAPIを利用するために必要な権限をSCOPEで指定します。

https://blogs.adobe.com/japan-conversations/files/2018/07/AdobeSign_API_Page.jpg

更にAdobe Signにて生成された承認コードを戻す先（REDIRECT_URI)を指定します。ここで指定するREDIRECT_URIは予め作成したAPIアプリケーションで登録されたredirect_uriに含まれたURIである必要があります。登録されたURIと違うURIが指定された場合はエラーになります。

https://blogs.adobe.com/japan-conversations/files/2018/07/AdobeSign_API_OAuth.jpg

OAuth認証ページにてSCOPEで指定した権限でアクセスを許可するか確認ページが表示されます。

例）https://secure.jp1.echosign.com/public/oauth?redirect_uri=https://localhost:8443/sign/browser/rest-api-sample/api/oAuth/redirectUri/&response_type=code&client_id=CBJCHBCAABAAXXXXXXXXXXXXrhcjlXPjtamLsFv4&
scope=user_login:self+user_write:self+user_read:self+workflow_read:self+workflow_write:self&state=

https://blogs.adobe.com/japan-conversations/files/2018/08/AdobeSing_AccessCheck2.png

アクセスを許可すると、REDIRECT_URI先にOAuth承認コードを持ってredirectされます。

例）https://localhost:8443/sign/browser/rest-api-sample/api/oAuth/redirectUri/?code=CBNCKBAAXXXXXXXXXArcrylh4wncayFMu9ls_XBUEmbeeuvFPW&api_access_point=https%3A%2F%2Fapi.jp1.echosign.com%2F&web_access_point=https%3A%2F%2Fsecure.jp1.echosign.com%2F

Redirect先ではアクセストークンを取得のために必要な情報を取得するWebページを用意します。

https://blogs.adobe.com/japan-conversations/files/2018/07/AccessToken.jpg

アクセストークン取得には上記のHTTP引数として渡された承認コード(code)とWebページから入力されたCLIENT_ID, CLIENT_SECRET, REDIRECT_URIをapi_access_pointで指定されたURIにPOSTリクエストします。api_access_pointはHTTP引数で渡されるURIです。

ここで得られたアクセストークンを使ってグループ作成APIをコールすることでグループが作成されます。

https://blogs.adobe.com/japan-conversations/files/2018/07/AdobeSing_CreatedGroup.jpg

Adobe Signのアカウントページからグループを選択すると、サンプルプログラムによって作成されたグループ”SampleGroupXXXXXX”を確認できます。

サンプルコードを理解する

では、Adobe Sign OAuth2.0認証の権限承認からアクセストークンの取得、グループの作成(APIコール）までの流れをプログラムを見ながら説明します。

Adobe Sign APIはこちらを参照ください。

1) Adobe Sign OAuth 2.0 認証から承認コードの取得

サンプルプログラムはこのWebページから始まります。

The Story Begins Here by Risfan Fardiansyah

このWebページでは承認コードを取得するために必要な情報（CLIENT_ID, REDIRECT_URI, SCOPE)を入手します。CLIENT_IDは予めAdobe Sing APIアプリケーションページで登録したアプリケーションに付与されたIDです。REDIRECT_URIはSCOPE(権限）が承認された後にリダイレクトする先のアドレスを指定します。SCOPEにはコールするAPIに必要な権限を指定します。

下のスクリプトはCreateGroupWithOAuthWorkFlow.htmlのJavaScript部の抜粋です。

<script>

var ApiUtils = AdobeSignSdk.ApiUtils;
    var OAuthUtils = AdobeSignSdk.OAuthUtils;

    function RedirectToAuthorizationUrl() {
      ApiUtils.configureProperty(RedirectToAuthorizationUrl.name);
      var clientId = document.getElementById("client_id").value;
      var redirectUri = document.getElementById("redirect_uri").value;
      var scopes = document.getElementById("scopes").value;

      OAuthUtils.getAuthorizationUrl(clientId, redirectUri, scopes)
      .then(function(authorizationUrl){
        window.location.replace(authorizationUrl);
      })
    }

  </script>

このHTMLコードではSCOPE (権限) を承認するための承認サイトのエンドポイントを取得します。

AdobeSignSDK/browser/rest-api-sample/api/oAuth/CreateGroupWithOAuthWorkFlow.html - OAuthUtils.getAuthorizationUrl()
  AdobeSignSDK/browser/rest-api-sample/utils/OAuthUtils.js - getAuthorizationUrl()    <--- APIに引き渡すためのユーティリティ関数
    AdobeSignSDK/rest-api-sdk/src/api/OAuthApi.js - getAuthenticationUrl()                <--- Adobe Sign SDK API

取得したURIの例）
https://secure.jp1.echosign.com/public/oauth?redirect_uri=redirectUri&response_type=code&client_id=clientId&scope=scopes&state=

https://secure.jp1.echosign.comでは指定されたSCOPE(権限) の承認確認が行われ、承認されるとREDIRECT_URIで指定したURIにリダイレクトされます。

例）https://localhost:8443/sign/browser/rest-api-sample/api/oAuth/redirectUri/?
code=CBNCKBAAXXXXXXXXXArcrylh4wncayFMu9ls_XBUEmbeeuvFPW&
api_access_point=https%3A%2F%2Fapi.jp1.echosign.com%2F&
web_access_point=https%3A%2F%2Fsecure.jp1.echosign.com%2F

この時に上記例でも示すように承認コード(code=)とAPIエンドポイント(api_access_point=)を取得することができます。

ここまでが承認コードを取得する手順です。

Tips) APIで指定するリダイレクトURIはAdobe Sign APIアプリケーションページで指定したREDIRECT_URIに含まれている必要があります。

2）次にリダイレクトされた先で新規グループを作成するためにAPIを発行します。

サンプルプログラムではリダイレクトURIとして

The Story Begins Here by Risfan Fardiansyah

を指定しました。

このページではアクセストークンを取得して新しいグループを作成するためのAPIを発行します。index.htmlでOAuthUtils.createGroupWithAuthCode()関数をコールします。

AdobeSignSDK_root/browser/rest-api-samples/utils/OAuthUtils.js

OAuthUtils.createGroupWithAuthCode()ではOAuthAPIを使ってアクセストークン、リフレッシュトークンを取得、その後グループ作成ユーティリティー関数をコールします。

OAuthUtils.createGroupWithAuthCode = function (code, apiAccessPoint, clientId, clientSecret, redirectUri) {
    var context = ApiUtils.getContext();
    context.setBaseUri(apiAccessPoint);
    var oAuthApi = new AdobeSignSdk.OAuthApi(context);
    var groupId = null;
    var accessToken = null;

    //Fetch the access token.
    var accessTokenRequest = new oAuthModel.AccessTokenRequest();
    var token = new oAuthModel.Token();
    accessTokenRequest.setClientId(clientId);          // APIアプリケーション登録で取得したクライアントID
    accessTokenRequest.setClientSecret(clientSecret);  // APIアプリケーション登録で取得したクライアントシークレット
    accessTokenRequest.setRedirectUri(redirectUri);    // リダイレクトURI
    accessTokenRequest.setCode(code);                  // 承認コード
    accessTokenRequest.setGrantType(Constants.ACCESS_TOKEN_GRANT_TYPE);

    //Access Token should be stored in the encrypted format
    return oAuthApi.getAccessToken(accessTokenRequest).then(function (accessTokenResponse) {

OAuthAPI getAccessToken()でアクセストークンを取得し、refreshAccessToken()でリフレッシュトークンを取得します。

トークンが取得できましたらサンプルプログラムのユーティリティ関数 createGroupWithOAuthWorkflow() を介してグループ作成API createGroup()をコールします。

createGroupWithOAuthWorkflow() – AdobeSingSDK_Root/browser/rest-api-samples/utils/GroupUtils.js

GroupUtils.createGroupWithOAuthWorkflow = function(groupName,accessToken) {
   var groupCreationInfo = new groupsModel.GroupCreationInfo();
   groupCreationInfo.setGroupName(groupName);
   var headers = {};
   headers[ACCESS_TOKEN_KEY] = accessToken;
   return groupsApi.createGroup(headers,groupCreationInfo).then(function(groupCreationResponse) {
       return groupCreationResponse.getGroupId();
   }).catch(function(apiError) {
       ApiUtils.logAndThrowError(Errors.CREATE_USER, apiError);
   });
};

これで新しいグループが作成されました。

次回は、その他のサンプルプログラムとAPIの説明をします。

ありがとうございました。

投稿者

Yoshiaki Nagayasu