Acrobat Services APIをREST APIで実行してみよう

Last updated at 2024-12-23Posted at 2024-12-23

はじめに

前回の記事にて、Acrobat Services APIの始め方を紹介しましたが、今回はREST APIでの実行方法について紹介していこうと思います。Acrobat Services APIにおけるREST APIのメリットの一つとしては、ファイルに対する柔軟な操作が可能な点にあります。Acrobat Services APIでは、通常Adobe Cloud上にファイルをアップロード⇒API処理⇒ダウンロードというのが一回の処理の流れになりますが、REST APIの場合、アップロードされたファイルに対して、後から自由にリクエストを実行する事が出来ます。

下記はAdobe Document Services APIの機能の概要です。これらのPDFに関する様々なオペレーションを自動化及び効率化する事が出来ます。こちらも詳しくは前回の記事に記載しておりますので、よろしければ併せてご覧下さい。

また、Acrobat Services APIにおけるREST APIの利用方法に関するリファレンスは、以下のページから確認可能です。

事前準備について

今回は、PostmanというGUIツールを使ってREST APIを実行していきます。なお、この記事の執筆時点では、Postman v11.22.0 を利用しています。もし同様に実行される方は、Postmanのサイトからダウンロードしインストールしてください。

今回の作業の流れ

今回の作業の流れとしては、以下の通りです。出来る限り細かく流れを確認しつつ進めたいので、最小のリクエスト単位で実行処理を進めていきます。項目毎に簡単な説明を入れてありますので、ここでは大まかな流れだけ把握出来れば問題ありません。

事前準備
- Postmanの作業環境作成
- クレデンシャルの取得
  　
本番作業
- アクセストークンの作成
- アップロード用のURLを発行
- Wordファイルをアップロード
- APIによる処理を実行 (Word⇒PDF変換)
- ダウンロード用のURLを発行
- 変換したPDFファイルをダウンロード
- APIによる処理を実行 (PDFを圧縮)
- ダウンロード用のURLを発行
- 圧縮したPDFファイルをダウンロード
- アップロードしたファイルを削除

PostmanによるREST API実行環境を作成

Postmanの実行環境の説明

Postmanの実行環境としては、以下の層形式になっています。
ワークスペース＞コレクション＞リクエスト

それぞれの機能としては以下の通りとなります。

ワークスペース ・・・複数のコレクションを束ねたプロジェクト管理用のコンテナ
コレクション ・・・複数のリクエストを束ねたモジュール管理用のコンテナ
リクエスト ・・・ REST APIのリクエストを行う最小の単位

今回は、個人用の実行環境として新規にワークスペース作成から始めていきます。

Postmanでワークスペースを作成

Postmanを起動し、ホーム内の左メニューからワークスペースを選択します。

右上にCreate Workspaceが表示されるので、これを選択します。

左のメニューから、空のワークスペースを選択し次に進みます。

今回は、Acrobat REST API Testという名前でワークスペースを作成します。

コレクションの作成

ワークスペースが出来たので、次にコレクションを作成します。

リクエストの作成

コレクションが出来たので、次にリクエストを追加します。

REST APIの実行場所となる新規のリクエストが追加されました。

クレデンシャルを取得

クレデンシャルの説明

クレデンシャルは、API接続時に必要な認証情報を指します。今回は、既にクレデンシャルが作成されている事を前提に進めていきますが、まだ作成されていない方は、以下の記事で作成方法を紹介しておりますのでこちらをご確認下さい。
Adobe Document Services APIを使ってみよう

クレデンシャルの確認

Adobe Developer右上のConsoleを選択します。

クレデンシャルを複数作成している場合は、利用するクレデンシャルを一つ選択します。

Client IDが表示されるので、こちらの情報をテキストにメモします。メモ出来たら、Generate access tokenを選択し、Client Secretの確認画面に移動します。

Retrieve client secretを選択します。

Client Secretが表示されるので、こちらの情報をテキストにメモします。メモ出来たら、こちらのページはこれ以降は利用しませんので閉じて問題ありません。

種別	値	説明
Client ID	XXXXXXXXXXXXXXX	クライアントID
Client Secret	XXXXXXXXXXXXXXX	クライアントキー

アクセストークンの取得

アクセストークンの説明

アクセストークンは、クレデンシャルを使用して作成されるAcrobat Services API接続用の資格情報です。このトークンは一時的に有効なもので、発行から24時間(84,000秒)経過すると失効します。日を空けて実行する際等は、再度アクセストークンの取得から開始する必要があります。

アクセストークンの発行

先ほどメモしたクレデンシャルを使って、アクセストークンを発行します。作成したPostmanのリクエスト画面を表示し、パラメーターをボディに変更、application/x-www-form-urlencodedスキーマを選択した後、下の表に従ってキーと値を入力します。

キー	値	説明
client_id	XXXXXXXXXXXXXXX	クライアントID
client_secret	XXXXXXXXXXXXXXX	クライアントキー

POSTを選択して以下のどちらかのリージョンのURLを指定し、送信します。これ以降に発生するPOST処理については、ここで選択したリージョンと同一のURLを選択して下さい。

リクエスト	URL	説明
POST	https://pdf-services-ue1.adobe.io/token	USリージョン
POST	https://pdf-services-ew1.adobe.io/token	EUリージョン

アクセストークンが発行されるので、トークン本体の長い文字列をテキストにメモします。

種別	値	説明
access_token	XXXXXXXXXXXXXXX（英数字の長い文字列）	トークン本体
token_type	bearer	トークンのタイプ
expires_in	86399	トークンの有効期限

ファイルアップロード用URLの取得

先ほどメモしたアクセストークンを使って、ファイルアップロード用のURLを発行します。POSTを選択して、アクセストークン作成時に指定したリージョンと同一リージョンのURLを以下から指定します。次にヘッダーを選択し、下の表に従ってキーと値を入力します。

リクエスト	URL	説明
POST	https://pdf-services-ue1.adobe.io/assets	USリージョン
POST	https://pdf-services-ew1.adobe.io/assets	EUリージョン

キー	値	説明
Authorization	Bearer XXXXXXXXXXXXXXX	Bearer + トークン本体
x-api-key	XXXXXXXXXXXXXXX	Client ID

今回は、wordファイルをアップロードする為、Media Typeをwordの形式で指定します。パラメーターをボディに変更し、RAWスキーマ(JSON形式)を選択、下のスクリプトを入力し送信します。

{
"mediaType": "application/vnd.openxmlformats-officedocument.wordprocessingml.document"
}

以下は、よく使うmediaTypeを記載しています。 (Microsoft Officeとpdf)
mediaTypeは、ファイル形式に応じて変更して下さい。 (検索すると色々出てきます)

ファイルの種類	拡張子	Media Type (MIME Type)
Portable Document Format	.pdf	application/pdf
Microsoft Word	.docx	application/vnd.openxmlformats-officedocument.wordprocessingml.document
Microsoft Excel	.xlsx	application/vnd.openxmlformats-officedocument.spreadsheetml.sheet
Microsoft PowerPoint	.pptx	application/vnd.openxmlformats-officedocument.presentationml.presentation

ファイルアップロード用のURLとファイルのIDが発行されるので、これらをテキストにメモします。

種別	値	説明
uploadUri	https://XXXXXXXXXXXXXXX	ファイルアップロード用のURL
assetID	XXXXXXXXXXXXXXX	アップロードファイルのID

ファイルのアップロード

URLが発行されたので、次にファイルのアップロードを行います。まずは、入力済みのヘッダ情報の二つの項目のチェックを外します。なお、ヘッダ情報が入力されていると、ファイルのアップロードに失敗します。(ファイルのアップロードは認証不要の為)

パラメーターをボディに変更し、+ New file from local machineを選択してローカルにあるwordファイルを指定します。

PUTを選択して、ファイルアップロード用URLを指定し送信します。

リクエスト	URL	説明
PUT	https://XXXXXXXXXXXXXXX	ファイルアップロード用のURL

200 OKの結果が出力され、アップロードに成功しました。

念の為、ファイルが問題無くアップロードされているか確認してみます。GETを選択してアクセストークン作成時に指定したリージョンと同一リージョンのURLを以下から指定し、URL内の[アセットID]をファイルアップロード用のURL取得時に併せてメモしたファイルのIDに置き換えます。次に先ほどチェックを外したヘッダ情報の二つの項目にチェックを入れ、送信します。

リクエスト	URL	説明
GET	https://pdf-services-ue1.adobe.io/assets/[アセットID]/metadata	USリージョン
GET	https://pdf-services-ew1.adobe.io/assets/[アセットID]/metadata	EUリージョン

200 OKの結果が出力され、ファイルが存在している事が確認出来ました。

ファイルが存在しない場合は、以下の通り404 Not Foundの結果が出力されます。

アップロードしたWordファイルをPDFファイルに変換

アップロードしたWordファイルに対して、APIによるPDF変換処理を行います。POSTを選択して、アクセストークン作成時に指定したリージョンと同一リージョンのURLを以下から指定します。次にヘッダ情報は有効化したままでパラメーターをボディに変更し、RAWスキーマ(JSON形式)を選択、下のスクリプト内の[アセットID]をファイルアップロード用のURL取得時に併せてメモしたファイルのIDに置き換えて入力し、送信します。

※スクリプト内のnotifiersの項目は、有効にする事でWebhookを用いて指定したURLに通知を行う事が可能となりますが、今回は利用せずにdummyを指定しています

リクエスト	URL	説明
POST	https://pdf-services-ue1.adobe.io/operation/createpdf	USリージョン
POST	https://pdf-services-ew1.adobe.io/operation/createpdf	EUリージョン

{
  "assetID": "[アセットID]",
  "documentLanguage": "en-US",
  "notifiers": [
    {
      "type": "CALLBACK",
      "data": {
        "url": "https://dummy.callback.org/",
        "headers": {
          "x-api-key": "dummykey",
          "access-token": "dummytoken"
        }
      }
    }
  ]
}

201 Createdの結果が出力され、ファイル変換のAPI処理に成功しました。

PDF変換したファイルのダウンロード

先ほどのPDF変換処理後の出力結果のヘッダーからlocationを確認し、URLの値をメモします。

※補足ですが、このURLの中にはx-request-idという文字列が埋め込まれており、このIDはジョブIDとも呼ばれ、問題発生時の問い合わせに利用する事が出来ます。以下の記事にジョブID、ログに関連した情報が記載されていますので、良ければご参照下さい。
Acrobat Services APIのログ取得とリクエストIDの確認方法

リクエスト	URL	説明
GET	https://XXXXXXXXXXXXXXX	Acrobat Services API上の保存場所

GETを選択し、locationのURLを入力後、パラメーターをボディに変更しスキーマは指定せずに送信します。

リクエスト	URL	説明
GET	https://XXXXXXXXXXXXXXX	Acrobat Services API上の保存場所

ファイルダウンロード用のURLとファイルのIDが発行されるので、これらをテキストにメモします。

種別	値	説明
uploadUri	https://XXXXXXXXXXXXXXX	ファイルダウンロード用のURL
assetID	XXXXXXXXXXXXXXX	ダウンロードファイルのID

URLが発行されたので、ファイルのダウンロードを行います。GETを選択し、ファイルダウンロード用のURLを指定します。次にヘッダ情報の二つの項目のチェックを外して送信します。(ファイルのダウンロードは認証不要)

リクエスト	URL	説明
GET	https://XXXXXXXXXXXXXXX	ファイルダウンロード用のURL

Wordファイルから変換したPDFファイルが出力結果として表示されました。

変換したPDFファイルを圧縮処理

Wordファイルから変換したPDFファイルに対して、今度はAPIによる圧縮処理を行う事で容量を削減します。まずは、先ほどチェックを外したヘッダ情報の二つの項目にチェックを入れます。

POSTを選択して、アクセストークン作成時に指定したリージョンと同一リージョンのURLを以下から指定します。次にパラメーターをボディに変更し、RAWスキーマ(JSON形式)を選択、下のスクリプト内の[アセットID]を先ほどのPDF変換後に発行したファイルダウンロード用のURL取得時に、併せてメモしたファイルのIDに置き換えて入力し送信します。

リクエスト	URL	説明
POST	https://pdf-services-ue1.adobe.io/operation/compresspdf	USリージョン
POST	https://pdf-services-ew1.adobe.io/operation/compresspdf	EUリージョン

{
  "assetID": "[アセットID]",
  "compressionLevel": "LOW",
  "notifiers": [
    {
      "type": "CALLBACK",
      "data": {
        "url": "https://dummy.callback.org/",
        "headers": {
          "x-api-key": "dummykey",
          "access-token": "dummytoken"
        }
      }
    }
  ]
}

201 Createdの結果が出力され、ファイル圧縮のAPI処理に成功しました。

圧縮処理したPDFファイルのダウンロード

先ほどのPDF圧縮処理後の出力結果のヘッダーからlocationを確認し、URLの値をメモします。

キー	値	説明
locatoin	https://XXXXXXXXXXXXXXX	Acrobat Services API上の保存場所

GETを選択し、locationのURLを入力後、パラメーターをボディに変更しスキーマは指定せずに送信します。

リクエスト	URL	説明
GET	https://XXXXXXXXXXXXXXX	Acrobat Services API上の保存場所

ファイルダウンロード用のURLとファイルのIDが発行されるので、これらをテキストにメモします。

種別	値	説明
uploadUri	https://XXXXXXXXXXXXXXX	ファイルダウンロード用のURL
assetID	XXXXXXXXXXXXXXX	ダウンロードファイルのID

リクエスト	URL	説明
GET	https://XXXXXXXXXXXXXXX	ファイルダウンロード用のURL

圧縮処理したPDFファイルが出力結果として表示されました。

左が圧縮前、右が圧縮後のPDFです。右の方がわずかに容量が小さくなっています。

アップロードしたファイルの削除

今回は、以下の三つのファイルがAcrobat Services API上に存在しており、それぞれで削除を実行します。手順はいずれも同様の為、今回は1回分のみ記載しています。なお、アップロードされたファイルの保持期間は24時間の為、意図的に削除を行わずとも24時間後には自動的に削除される仕組みとなります。

種別	値	説明
assetID	XXXXXXXXXXXXXXX	処理前のWordファイル
assetID	XXXXXXXXXXXXXXX	変換後のPDFファイル
assetID	XXXXXXXXXXXXXXX	圧縮後のPDFファイル

まずは、ファイルが存在しているか確認してみます。GETを選択してアクセストークン作成時に指定したリージョンと同一リージョンのURLを以下から指定し、URL内の[アセットID]を上記のいずれかのファイルのIDに置き換えます。次に先ほどチェックを外したヘッダ情報の二つの項目にチェックを入れ、送信します。

リクエスト	URL	説明
GET	https://pdf-services-ue1.adobe.io/assets/[アセットID]/metadata	USリージョン
GET	https://pdf-services-ew1.adobe.io/assets/[アセットID]/metadata	EUリージョン

200 OKの結果が出力され、ファイルが存在している事が確認出来ました。

それでは、ファイルの削除を行います。DELETEを選択してアクセストークン作成時に指定したリージョンと同一リージョンのURLを以下から指定し、URL内の[アセットID]を先ほど選択したファイルのIDに置き換え、送信します。

リクエスト	URL	説明
DELETE	https://pdf-services-ue1.adobe.io/assets/[アセットID]	USリージョン
DELETE	https://pdf-services-ew1.adobe.io/assets/[アセットID]	EUリージョン

204 No Contentの結果が出力されれば、ファイルの削除に成功しています。

最後に、ファイルが削除されているか確認してみます。GETを選択してアクセストークン作成時に指定したリージョンと同一リージョンのURLを以下から指定し、URL内の[アセットID]を先ほど選択したファイルのIDに置き換え、送信します。

リクエスト	URL	説明
GET	https://pdf-services-ue1.adobe.io/assets/[アセットID]/metadata	USリージョン
GET	https://pdf-services-ew1.adobe.io/assets/[アセットID]/metadata	EUリージョン

404 Not Foundの結果が出力され、ファイルが存在していない事が確認出来ました。

まとめ

今回の記事では、REST APIの利用方法と流れについて紹介しました。今回利用したPostmanは、コレクションやリクエストを多数作成する事は勿論、履歴の確認、まとめて実行やフローを作成する事も出来、効率的なシステム開発を行う事が出来ます。また、Adobe developerでもPostman向けのサンプルコードが多数用意されており、今回の一連の流れを1スクリプトで実行する事も可能です。以下のREST APIのページの上部にPostmanのサンプルコードがありますので、ご確認下さい。

また、Acrobat Services API Use Casesのページや、Adobe Document Cloud 公式YouTubeにも活用のヒントがたくさん含まれていますので、そちらも是非ともご活用下さい。

もし本格的に導入を検討したい方がおられましたら、以下のページからご相談頂く事が可能なので、是非ともお気軽にお問合せ下さい。

You get articles that match your needs
You can efficiently read back useful information
You can use dark theme

What you can do with signing up