Adobe Document Services APIを使ってみよう

# はじめに
※以下の記事のアップデート版となります (2024年8月掲載)
[PDFを操作するなら「Adobe Document Services API」が便利！ (2022年2月掲載)](https://qiita.com/kurabaya/items/d8e6d0114ca5e5c7acfa)

Adobeでは、PDFの操作や編集をはじめとする便利なAPIサービス群を提供しています。用途に応じた様々な機能があり、必要とする機能を選んでアプリケーションに組み込む事が可能です。

![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/3812776/fcfc8428-cd5f-c3d8-c30e-9fd8f6bed31b.png)

Adobe Document Services APIの利用は、Adobeが所有するクラウド上のサービスにアクセスして処理を実行する為、ユーザ側のリソースを消費しないという利点があります。この記事では、それぞれの機能の紹介と、意外とシンプルなAPIの利用方法を紹介していきます。

# Adobe Document Services APIとは
Adobe Document Services APIは、次の6つのAPIで構成されています。(2024年8月時点)

### PDF Embed API
PDF Embed APIを使えば、WebアプリにPDFの閲覧機能を簡単に追加が出来ます。コメントや描画などをサポートするコラボレーション機能や、PDFイベントのトラッキングが可能なアナリティクス機能も提供しており、Webアプリのユーザ体験を拡張するのに役立ちます。

### PDF Services API
PDF Services APIを使えば、ドキュメントをプログラムから操作したり、様々なドキュメントワークフローを自動化する事が出来ます。Officeファイル等をPDFに変換する、PDFをパスワードで保護する、圧縮や最適化（リニアライズ）する、ページの挿入や並べ替えなどをする、OCRを実行する、といった豊富な操作が可能です。

### Document Generation API
Document Generation APIは、JSON形式のデータとWordテンプレートをマージして高品質なPDFやWordドキュメントを生成します。この機能により、契約書、インボイス、レポートなどの定型的なドキュメント作成を効率化します。ライセンス上は、Document Generation APIは、PDF Services APIの一部として提供されます。

### PDF Extract API
PDF Extract APIは、アドビのAIテクノロジーであるAdobe Senseiを利用してPDFを解析します。テキスト、図、表を認識し、読み順や書式の情報とともに構造化されたJSONデータを出力します。スキャンされたPDFの解析も可能です。ライセンス上は、PDF Extract APIは、PDF Services APIの一部として提供されます。

### Accessibility Auto-Tag API
Accessibility Auto-Tag APIは、PDFコンテンツの見出し、段落、リスト、テーブルなどの構造をタグ付けします。この機能により、スクリーンリーダーなどに適した読み上げ順序指示や見やすさなどアクセシビリティの向上を図る事が可能です。ライセンス上は、Accessibility Auto-Tag APIは、PDF Services APIの一部として提供されます。

### PDF Electronic Seal API
PDF Electronic Seal APIは、クラウドベースのサードパーティ製デジタル証明書を使用し、そのデータが改ざんされていない事を証明するeシールをPDFに適用します。ライセンス上は、PDF Electronic Seal APIは、PDF Services APIの一部として提供されます。

<br>

YouTubeにAdobe Document Services APIの活用事例が公開されていますので、よろしければこちらもご覧ください。

https://www.youtube.com/@AdobeDocumentCloudJP/search?query=API

# Adobe Developer
Adobe Document Services APIに関するリソースは、アドビのデベロッパ向けサイト[Adobe Developer](https://developer.adobe.com/)に集約されています。（API関連のページは、トップページ上部のタブから Products > Adobe PDF Services API または Adobe PDF Embed API で閲覧可能）

![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/3812776/af5c3571-74ea-9ab1-b828-1c35b6d1d3bc.png)

Adobe Developerでは、次の事が出来ます。
- APIリファレンスを含む各種ドキュメントの参照
- クレデンシャルの作成と管理
- サンプルコードを含むSDKのダウンロード（PDF Services APIのみ）
- ユースケースやナレッジの検索


PDF Services APIは、トライアル環境では一か月辺り500回のAPIコールが可能です。PDF Embed APIは無償であり、APIコール回数に制限はありません。その他の制限については、[こちらのページ](https://developer.adobe.com/document-services/docs/overview/limits/)をご参照下さい。

また、Adobe Developerを利用するには`Adobe ID`が必要です。まだ作成されていない場合は、[ヘルプページ](https://helpx.adobe.com/jp/manage-account/using/create-update-adobe-id.html)を参考に`Adobe ID`を作成してください。


# PDF Services APIを使ってみよう
PDF Services APIは、サンプルコードが多数含まれるSDKを利用して手軽に始められます。Adobe Developerサイトからトライアルを選択すると、クレデンシャルを作成するページに遷移し、作成が完了するとSDKが自動的にダウンロードされます。(このクレデンシャルでDocument Generation APIやPDF Extract API等も利用可能）。今回は、Python用のSDKを使って始めてみましょう。他にもJava用 、.NET用、Node.js用のSDKが提供されています。

### PDF Services APIのトライアル開始
[Adobe Developerサイト](https://developer.adobe.com/document-services/apis/pdf-services/)中央の`Start for free`をクリックし、トライアルを開始します。
※トライアルでは一か月辺り500回のAPIコールが利用可能

![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/3812776/01742763-0bb2-e2ab-328c-68d4faaab5b5.png)

### クレデンシャルの作成
クレデンシャルの作成画面に遷移する為、必須項目を全て入力します。developer terms (利用規約) を確認した後、規約の同意にチェックを入れ、`Create Credentials`をクリックします。

![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/3812776/ae3ddd17-f0e4-6295-4e3a-3d28d57a0177.png)

ここでは、以下の通りに入力しました。
|項目                             |入力値                 |説明                      |
|---                              |---                   |---                       |
|Credentials name                 |api-test-credentials  |任意のクレデンシャル名      |
|Create personalized code sample  |Yes                   |APIのサンプルコードを含める |
|Choose language                  |Python                |選択言語でPythonを指定      |

### クレデンシャルの表示とSDKのダウンロード
クレデンシャルが作成されると以下のような画面が表示されます。表示されている情報は、Adobe Developer Consoleからも確認可能です。画面遷移と同時に、SDKのZipファイル（`PDFServicesSDK-PythonSamples.zip`）が自動的にダウンロードされます。


![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/3812776/a678d01b-c822-dc82-c4b2-f3d7cf1bb495.png)


右の`Quick Start Guide`から導入手順が確認可能です。より詳細な情報は、[Documentaionページ](https://developer.adobe.com/document-services/docs/overview/pdf-services-api/)をご参照下さい。 (本記事では最小の導入手順を記載)

### Pythonのインストール
この記事の執筆時点では、Python 3.10 以降がサポートされています。まだインストールされていない場合は、[Pythonのサイト](https://www.python.org/downloads/)からダウンロードしインストールしてください。

### SDKの展開
クレデンシャル作成時にダウンロードしたSDKファイル (`PDFServicesSDK-PythonSamples.zip`) を、任意の場所に展開します。フォルダ階層としては、以下の通りとなっています。

```
PDFServicesSDK-PythonSamples/
 │  pdfservices-api-credentials.json
 │  README.txt
 └─ adobe-dc-pdf-services-sdk-python/
     │  .DS_Store
     │  CODE_OF_CONDUCT.md
     │  LICENSE.md
     │  README.md
     │  requirements.txt
     ├─ output/            　　　　　　　　　　　　　⇒ 初回API実行時に自動作成される
     └─ src/
         ├─ autotagpdf/                       　　 ⇒ 機能毎のサンプルコード用フォルダ
         │    autotag_pdf.py                  　　 ⇒ APIのサンプルコード
         │    autotag_pdf_parametrised.py
         │    autotag_pdf_with_options.py
         ├─ combinepdf/
         │    combine_pdf.py
         │    combine_pdf_with_page_ranges.py
         ├─ compresspdf/
         │    compress_pdf.py
         │    compress_pdf_with_options.py
         ├─ createpdf/
         │    (...)
         │      ・
         │      ・
         │      ・
         ├─ splitpdf/
         │    split_pdf_by_number_of_pages.py
         │    split_pdf_by_page_ranges.py
         │    split_pdf_into_number_of_files.py
         └─ resources/　　　　　　　　　　　　　　　   ⇒ APIテスト向けのドキュメント置き場
              (...)
```

srcフォルダ配下に、フォルダ分けされた各APIのサンプルコードの他、テスト用のpdfファイルやwordファイル等が保存されている`resources`フォルダがあります。なお、APIで出力したファイル類は、初回実行時にカレントフォルダ（通常は`src`と同じ階層）に`output`フォルダが作成され、そちらに保存されます。

### SDKのインストール
ターミナル（コマンドプロンプト）を開き、SDKのルートフォルダ（`PDFServicesSDK-PythonSamples/`）に移動し、`pip install`を実行します。

```
>cd .../Desktop/PDFServicesSDK-PythonSamples
>pip install pdfservices-sdk
```

### クレデンシャルの認証情報を環境変数として宣言
SDKのインストールが無事完了したら、クレデンシャルの認証情報を環境変数として宣言します。API呼び出し時のクレデンシャル認証手続きは、各APIサンプルコードの中に組み込まれている為、APIサンプルコード内で定義されている認証用の変数に対し、環境変数として宣言する事で認証情報を補完します。指定するクライアントIDとクライアントシークレットは、クレデンシャル情報から確認可能です。

**Windowsの場合（コマンドプロンプト用のコマンド、PowerShellだと実行されないので注意）**
```
>set PDF_SERVICES_CLIENT_ID=XXXXXXXXXXXXXXX（CLIENT ID）
>set PDF_SERVICES_CLIENT_SECRET=XXXXXXXXXXXXXXX（CLIENT SECRET）
```

**Macの場合**
```
% export PDF_SERVICES_CLIENT_ID=XXXXXXXXXXXXXXX（CLIENT ID）
% export PDF_SERVICES_CLIENT_SECRET=XXXXXXXXXXXXXXX（CLIENT SECRET）
```

### PDF Services APIでWordファイルをPDFに変換してみる
これで準備が整いましたので、SDKからAPIを実行してみましょう。OfficeファイルをPDFに変換する機会は多いと思いますので、今回は動作確認を兼ねて、テスト用のWordファイルをPDFファイルに変換するサンプルコードを実行してみます。

なお、今回実行するサンプルコード`creat_pdf_from_docx.py`は、テスト用のWordファイル（`src/resources/createPDFInput.docx`）をPDFに変換し、出力ファイル用のフォルダ（`output/createPDFFromDOCX/`）に保存する仕組みとなっています。

まず、サンプルコード内のパス指定の都合により、実行場所となるフォルダ（`PDFServicesSDK-PythonSamples/adobe-dc-pdf-services-sdk-python/`）へ移動します。それでは早速、サンプルコード（`src/resources/createpdf/creat_pdf_from_docx.py`）を実行してみましょう。

```
>cd ...\PDFServicesSDK-PythonSamples\adobe-dc-pdf-services-sdk-python
>python src\createpdf\create_pdf_from_docx.py
```

左が変換前のWordファイル、右が変換後のPDFファイルです。無事変換されました。
![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/3812776/3df370d9-dc77-008c-846d-a504bbf0cbcd.png)


`src`フォルダ配下には、他にも様々なサンプルプログラムが用意されています。例えば、上記のように作成したPDFを圧縮して、パスワード保護するといった処理も同様の流れで簡単に行えます。

# PDF Embed APIでWebアプリにPDFビューアを埋め込む
PDF Embed APIは、HTMLソースにAPIを組み込む事でWebアプリケーション上でのPDFの閲覧、埋め込みモードの指定、UIのカスタマイズ、アノテーションツールの使用、Adobe Analyticsやイベントハンドラを利用したアナリティクスが可能です。ソースコードは公開されている為、クレデンシャルを作成しソースコード内で指定する事により、誰でも簡単に利用する事が出来ます。

### PDF Embed APIの開始
[Adobe Developerサイト](https://developer.adobe.com/document-services/apis/pdf-embed/)下部の`Get free credentials`をクリックして開始します。
※PDF Embed APIは、無償で利用可能

![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/3812776/1de92218-3a52-acbd-803f-0b25b9ac1fb4.png)

### PDF Embed API用クレデンシャルの作成
クレデンシャルの作成画面に推移する為、必須項目を全て入力します。developer terms (利用規約) を確認した後、規約の同意にチェックを入れ、`Create Credentials`をクリックします。

![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/3812776/6fd41e68-f878-4c63-4440-ee70d1f7ba30.png)

ここでは、以下の通りに入力しました。
|項目                         |入力値                      |説明                      |
|---                          |---                        |---                       |
|Credentials name             |embedapi-test-credentials  |任意のクレデンシャル名      |
|Application Domain           |&#8203;www.example.com     |ドメイン名                 |

### クレデンシャルの表示
クレデンシャルが作成されると以下のような画面が表示されます。表示されている情報は、Adobe Developer Consoleからも確認可能です。

![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/3812776/34b0c215-9966-40b6-c37f-8310815e89f1.png)


右の`Quick Start Guide`から導入手順が確認可能です。より詳細な情報は、[Documentaionページ](https://developer.adobe.com/document-services/docs/overview/pdf-embed-api/gettingstarted/)をご参照下さい。

### PDF Embed APIをHTMLソースから呼び出す
PDF Embed APIはJavaScriptのAPIであり、HTMLに以下のようなごく短いコードを埋め込むだけで使用できます。以下のソースコードでは、PDFの閲覧機能を組み込んでおり、クレデンシャルで取得したクライアントID、指定したドメインでの対象PDFのパスと名前を指定し実装します。その他の機能等の詳細は、[Documentationページ](https://developer.adobe.com/document-services/docs/overview/pdf-embed-api/)をご参照下さい。

```diff_html
<body style="margin: 0px">
 <div id="adobe-dc-view"></div>
 <script src="https://acrobatservices.adobe.com/view-sdk/viewer.js"></script>
 <script type="text/javascript">
    document.addEventListener("adobe_dc_view_sdk.ready", function()
    {
        var adobeDCView = new AdobeDC.View({clientId: "XXXXX", divId: "adobe-dc-view"});
        adobeDCView.previewFile(
       {
          content:   {location: {url: "https://www.example.com/testpage/test.pdf"}},
          metaData: {fileName: "test.pdf"}
       });
    });
 </script>
 </body>
```

### PDF Embed APIの動作例
PDF Embed APIの動作は[オンラインデモ](https://acrobatservices.adobe.com/view-sdk-demo/index.html)からも確認が出来ます。このページでは、表示するPDFを変更したり、動作をカスタマイズしたりするだけでなく、それを反映したコードの生成もできます。コードをコピーしてクライアントIDなどを設定すればすぐに使えるので、非常に便利です。

![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/3812776/f6778b53-e650-4803-8a8f-c38212f7d3ce.png)

# まとめ
今回は、Adobe Document Services APIの概要と利用開始方法、実行手順について紹介しました。一からコードを書かずとも、用意されているサンプルコードを編集して手軽に実装する事が出来るので、自分好みの仕様に変えて活用の幅を広げてみて下さい。また、[Acrobat Services API Use Casesのページ](https://developer.adobe.com/document-services/use-cases/agreements-and-contracts/sales-proposals-and-contracts/)や、[Adobe Document Cloud 公式YouTube](https://www.youtube.com/@AdobeDocumentCloudJP)にも活用のヒントがたくさん含まれていますので、そちらも是非ともご活用下さい。

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

https://developer.adobe.com/document-services/pricing/contact/sales/?s_cid=7015Y0000048nxKQAQ&s_iid=7015Y000003pFaCQAU