Cloudinary の Search API でアセットを検索してみた

Cloudinaryとは画像や動画、他あらゆるアセットを保管・一元管理でき、変換や最適化を即座に行え、CDNで高速配信できるサービスです。

通常ビジネスで Cloudinary でアセット管理を行う場合、大量のアセットを格納することになります。

画面コンソールでも、デザイナーやクリエイター等の技術者以外も直感的に DAM として使える機能が揃っていますが、今回は Search API を使ってアセット検索する方法をご紹介します。

Search API メソッド

Admin API の一つである Search メソッドでは、Lucene クエリ構文のような表記でさまざまなフィルタ指定をしてアセットを検索することができます。

result = cloudinary.Search().expression("resource_type:image").execute()

基本構文

構文に含められるパラメータは次のとおりです。

すべて任意のため、何も指定しない場合は作成日が直近のもの50件が作成時間の降順で表示されます。ですが、少なくとも expression で検索条件は指定したほうが良いでしょう。

• expression: 検索条件
• sort_by: 検索結果の表示順序
• max_results: 表示する検索結果の最大件数（デフォルトは10件）
• next_cursor: ページングID（該当結果が指定した最大件数を超える場合、レスポンスにこの値が返されるので、次回実行時にその値をこれで指定することで続きの値が取得できる）
• fields: レスポンスに含める項目
• with_field: デフォルトで返される項目に加えて、追加でレスポンスに含める項目

基本構文についての詳細はAPI ドキュメントを確認してください。

検索条件の指定

expression(”フィールド名1:条件 AND フィールド名2:条件”) のように全体をクォーテーションで囲って指定します。

検索条件にできるフィールドの一覧は、指定例とともに Expression Fields からすべて確認できます。以下では、よく使いそうなものをピックアップしてみました。

• public_id: パブリック ID
• folder: フォルダーパス
• filename: ファイル名（パブリックIDで最後のスラッシュ以降、拡張子部分を除く）
• tags: タグ
• resource_type: リソースタイプ（image、video、または raw）
• type: 公開タイプ（upload、authenticated 等）
• created_at、last_updated: アセットの作成日、更新日
• その他アセットのプロパティ（拡張子、ファイルサイズ、アスペクト比等々）

◾️ フィールド演算子 (Field Operators)

ワイルドカード（*）を使って前方一致も可能ですが、部分・後方一致の検索には使えません。

また数字やアルファベットでの範囲指定も可能です。

文字列の検索では基本的にイコール演算子（=）を使った完全 or 前方一致で、値の大文字・小文字も区別されます（例: public_id=path1/path2/*）が、ファイル名やタグなどフィールドによってはダブルコロン演算子（:）を使ったトークン検索も可能です。
トークン検索では、大文字・小文字を区別せず、単語検索ができるなど、より柔軟な検索が可能になります。

◾️ ブール演算子 (Boolean Operators)

条件は AND/OR を使って複数指定したり、NOT で例外条件とすることもできます。

これらの演算子に関しては、Search expressions のドキュメントを確認してください。

特定のアセットを検索してみた

以下、いずれも Python を使った場合の実行例です。

まずは、ファイル名に sample と名の付く画像をリストしてみます。

res = cloudinary.Search()\
    .expression("resource_type:image AND filename:sample*")\
    .sort_by("public_id","desc")\
    .max_results("30")\
    .execute()
for r in res["resources"]:
    print(r["public_id"])

環境内で次のファイルがありました：

sample
ito-test/dir1/sample02
ito-test/dir1/dir2/sample1
ito-test/Sample03
ito-test/Sample02
ito-test/Sample01
hands-on/Sample03
cld-sample-5
cld-sample-4
cld-sample-3
cld-sample-2
cld-sample

トークン検索のためファイル名の途中に文字列を含む cld-sample などもヒットしてますね。なおトークン（単語）の後方一致はできないので、これが例えば filename:mple ではいずれもヒットしません。（filename:*mple はそもそもエラーに）

---

今度はフォルダとファイル名で指定してみます。

res = cloudinary.Search()\
    .expression("filename:sample* && folder:ito-test/dir1")\
    .sort_by("uploaded_at","desc")\
    .execute()
print(res)

この検索結果はito-test/dir1/sample02の1件のみでした。

生のレスポンスはこんな感じ。

{'total_count': 1, 'time': 53, 'resources': [{'asset_id': 'deb30adefaf3fe9c1d9e1b1f5432ab9a', 'public_id': 'ito-test/dir1/sample02', 'asset_folder': 'ito-test/dir1', 'filename': 'sample02', 'display_name': 'sample02', 'format': 'jpg', 'version': 1705497403, 'resource_type': 'image', 'type': 'upload', 'created_at': '2024-01-17T13:16:43+00:00', 'uploaded_at': '2024-01-17T13:16:43+00:00', 'bytes': 115661, 'backup_bytes': 115661, 'width': 1500, 'height': 1000, 'aspect_ratio': 1.5, 'pixels': 1500000, 'pages': 1, 'url': 'http://{CLOUD_NAME}-ressh.cloudinary.com/image/upload/v1705497403/ito-test/dir1/sample02.jpg', 'secure_url': 'https://{CLOUD_NAME}-ressh.cloudinary.com/image/upload/v1705497403/ito-test/dir1/sample02.jpg', 'status': 'active', 'access_mode': 'public', 'access_control': None, 'etag': '6779a1fa4f302f35e53d18170e60b526', 'created_by': {'access_key': 'XXXXXXXXXXXXXXX', 'custom_id': '{USER EMAIL ADDRESS}', 'external_id': '931cdb623a57b6e0c59c03d116f61c'}, 'uploaded_by': {'access_key': 'XXXXXXXXXXXXXXX', 'custom_id': '{USER EMAIL ADDRESS}', 'external_id': '931cdb623a57b6e0c59c03d116f61c'}, 'last_updated': {'updated_at': '2024-01-17T13:17:57+00:00', 'public_id_updated_at': '2024-01-17T13:17:57+00:00'}}]}

ただし、フォルダ名にもfolder:ito-test/dir1*とワイルドカードを付けた場合は、ito-test/dir1/dir2/sample1も該当することになります。

---

最後に、タグとパブリックIDで指定してみます。

res = cloudinary.Search()\
    .expression("public_id=ito-test/* && tags=temp*")\
    .sort_by("uploaded_at","asc")\
    .execute()

for r in res["resources"]:
    print(r["public_id"])

結果、”temp-asset” というタグを付与していた以下の2件がヒットしました：

ito-test/dir1/dir2/sample1
ito-test/dir1/sample02

注意

• こちらのブログで説明している通り、本メソッドは Admin API のため1時間あたりのレートリミットがあります。
• 本機能はすべての製品環境で利用可能ですが、1,000万以上のアセットがある場合は、サポートへお問い合わせください。
• Search API メソッドの Tier 2 では、さらに画像分析や埋め込みメタデータ、集計情報に基づいた検索が可能で、こちらはプレミアム機能です。

参考

• Search API Method | Cloudinary
• Search for resources - Admin API Reference | Cloudinary

---

クラスメソッドはCloudinaryのパートナーとして導入のお手伝いをさせていただいています。お気軽にこちらからお問い合わせください。こちらから無料でもサインアップいただけます。