この記事は公開されてから1年以上経過しています。情報が古い可能性がありますので、ご注意ください。
画像最適化SaaSのCloudinaryの SDK ライブラリは様々な言語でサポートされています。今回は Node.js の始め方をご紹介します。
ライブラリのインストール
2020年8月20日、Nodeインストールとドキュメントを追記し、Cloudinaryライブラリのインストールを更新しました。
Node.js をインストールします。(最新の手順は nvm ドキュメントを確認してください!)
% curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.35.3/install.sh | bash
% nvm install node
% node -v
v14.8.0
% npm -v
6.14.7
ドキュメントを参考に、Cloudinary のライブラリをインストールします。(こちらも最新の手順はドキュメントをご確認ください!)
$ npm install cloudinary
+ cloudinary@1.22.0
added 4 packages from 6 contributors and audited 4 packages in 1.222s
$ npm ls
/Users/maiito
└─┬ cloudinary@1.22.0
├── core-js@3.6.5
├── lodash@4.17.20
└── q@1.5.1
クレデンシャル設定
クレデンシャルは、Cloudinary メソッドへの各呼び出しで指定するか、環境変数か config
メソッドを使ってグローバルで指定します。
環境変数として指定する場合は、下記のような形式となりますが、ダッシュボードの "Environment variable" から丸ごとコピーできます。
export CLOUDINARY_URL=cloudinary://my_key:my_secret@my_cloud_name
config
メソッドを使用する場合は、上記の情報を使用して下記例のように示します。
cloudinary.config({
cloud_name: 'sample',
api_key: '874837483274837',
api_secret: 'a676b67565c6767a6767d6767f676fe1',
secure_distribution: 'assets.example.com',
cname: 'assets.example.com',
private_cdn: true,
upload_prefix: 'https://api-ap.cloudinary.com'
});
※ cloud_name
、api_key
、api_secret
は必須項目で、それ以降は任意です。詳細はこちらのドキュメント参照。
※ upload_prefix
はアカウントのエンドポイント設定(プレミアム機能のみ利用可能)が、デフォルトのアメリカではなく、ヨーロッパかアジアパシフィックへ変更している場合に指定します。この設定されており、このパラメータの指定がないと、Cloud XXX belongs to ap geo, please access via api-ap.cloudinary.com'
のようなエラーが返されます。
そして、コードの先頭には下記の通り Cloudinary クラスを宣言します。
var cloudinary = require('cloudinary').v2;
Node.js SDK のアップロードや管理メソッドでは v2
を含める必要があり、Cloudinary のドキュメントの構文例では毎回これが含まれていますが、この宣言で含めることにより以降の呼び出しでは .v2
を省略してOKです。
実行してみた
では早速、下記の通りなんのオプションもなく手元の画像のアップロードを実行してみました。
$ node
> var cloudinary = require('cloudinary').v2;
undefined
> cloudinary.config({
... cloud_name: 'demo',
... api_key: '123',
... api_secret: '***'
... });
>
> cloudinary.uploader.upload("profile/hoya-matsuri.png",
... function(error, result) {console.log(result, error)});
結果は、下記のように出力されました。パブリックID(Cloudinary上でのファイル名)を指定しなかったためランダムの文字列が自動採番され、Cloudinaryのルート直下に画像がアップロードされました。他にも画像の縦横サイズやファイルサイズ、Etagなどの画像の情報、そしてCloudinaryのURLが返されています。
{ public_id: 'hbqdpdk7mybcpgj7dxft',
version: 1571995054,
signature: '3a809c70f89c15131c703f2dbeb01aa66f4bde41',
width: 361,
height: 361,
format: 'png',
resource_type: 'image',
created_at: '2019-10-25T09:17:34Z',
tags: [],
bytes: 157455,
type: 'upload',
etag: '3d99ea74d3ed6b5718d97d633d95b1f9',
placeholder: false,
url:
'http://res.cloudinary.com/demo/image/upload/v1571995054/hbqdpdk7mybcpgj7dxft.png',
secure_url:
'https://res.cloudinary.com/demo/image/upload/v1571995054/hbqdpdk7mybcpgj7dxft.png',
access_mode: 'public',
requester_ip: '<IPアドレス>',
original_filename: 'hoya-matsuri' } undefined
では、他にもいろいろやってみます。
オプション指定して画像をアップロード (1)
今度はupload メソッドのオプションを指定してアップロードします。下記では、ito-test フォルダ配下に元のファイル名でアップロードしています。
cloudinary.uploader.upload("Photos/Abendessen.jpg",
{
use_filename: true,
unique_filename: false,
folder: 'ito-test' },
function(error, result) {console.log(result, error)});
アップロード済み画像の名前変更・フォルダ移動
先ほどオプションなしでアップロードした画像のパブリックIDを変更し、フォルダ配下へ移動します。これは、rename メソッドを使用します。
cloudinary.uploader.rename('hbqdpdk7mybcpgj7dxft',
'ito-test/hoya-matsuri',
function(error, result) {console.log(result.public_id)});
アップロード済み画像にタグ付け
tags メソッドでアップロードした画像にタグを追加します。
cloudinary.uploader.add_tag('Node.js',
['ito-test/hoya-matsuri', 'ito-test/Abendessen'],
function(error, result) {console.log(result, error)});
特定タグの画像一覧を確認
resources を使って今度は付与したタグの画像一覧を取得します。
cloudinary.api.resources_by_tag('Node.js',
{
max_results: 5
},
function(error, result) {console.log(result, error); });
結果は、以下のように出力されました。
{ resources:
[ { public_id: 'ito-test/Abendessen',
format: 'jpg',
version: 1572257756,
resource_type: 'image',
type: 'upload',
created_at: '2019-10-28T10:15:56Z',
bytes: 792931,
width: 2304,
height: 1728,
access_mode: 'public',
url:
'http://res.cloudinary.com/demo/image/upload/v1572257756/ito-test/Abendessen.jpg',
secure_url:
'https://res.cloudinary.com/demo/image/upload/v1572257756/ito-test/Abendessen.jpg' },
{ public_id: 'ito-test/hoya-matsuri',
format: 'png',
version: 1572250358,
resource_type: 'image',
type: 'upload',
created_at: '2019-10-28T08:12:38Z',
bytes: 157455,
width: 361,
height: 361,
access_mode: 'public',
url:
'http://res.cloudinary.com/demo/image/upload/v1572250358/ito-test/hoya-matsuri.png',
secure_url:
'https://res.cloudinary.com/demo/image/upload/v1572250358/ito-test/hoya-matsuri.png' } ],
rate_limit_allowed: 5000,
rate_limit_reset_at: 2019-10-28T11:00:00.000Z,
rate_limit_remaining: 4990 }
オプション指定して画像をアップロード (2)
今度は、ローカルの画像ではなくパブリックURLの画像をアップロードしてみます。オプションでパブリックIDを指定し、タグ付与して、結果のうちHTTPS画像URLを取得しています。
cloudinary.uploader.upload("https://mesoko.jp/wp-content/uploads/2018/07/profile-stick-2-1.png",
{ public_id: "ito-test/mesoko", tags: "Node.js" },
function(error, result) {console.log(result.secure_url, error); });
画像変換用 URL を生成
画像変換パラメータの一覧を参考に、画像変換用のURLを生成することができます。以下は実行したコードと結果です。
> cloudinary.image("ito-test/mesoko",
... { transformation: [
..... { width: 300, height: 200, crop: "fill", gravity: "face", quality: 80 },
..... { overlay: "logo", width: 70, crop: "scale", opacity: 50, gravity: "south_east", x: 10, y: 10 }
..... ]})
'<img src=\'http://res.cloudinary.com/demo/image/upload/c_fill,g_face,h_200,q_80,w_300/c_scale,g_south_east,l_logo,o_50,w_70,x_10,y_10/v1/ito-test/mesoko\' />'
このURLにアクセスすると、下記のような画像となります。(※上記の結果はドメインを置き換えています)
変換パラメータの詳細についてはこちらの記事もご参考いただけます。
事前に画像を変換
先のように新たに生成した画像URLは、一度URLを開いてアクセスした際に初めて画像変換が行われます。2回目以降のアクセスでは変換した画像のCDNキャッシュが利用されるため高速に配信されますが、1回目のアクセスは少し時間がかかります。
これを避けるために、Explicit メソッドを使ってあらかじめ変換を行うことができます。
cloudinary.uploader.explicit("ito-test/mesoko",
{ type: "upload",
eager: [
{ width: 200, height: 200, crop: "thumb", gravity: "face" }
]},
function(error, result) {console.log(result, error);} )
コンソールで画像の変換ページから「View derived images」を開くと、上記の変換が既に含まれていることが確認できます。
画像を検索
Search API を使って、ここ3日以内(>3d
)でアップロードした画像を検索してみます。
cloudinary.search.expression('uploaded_at>3d').max_results(5).execute().then(result=>console.log(result));
画像を削除
Destroy メソッドを使って単一の画像を削除することができます。ここでは invalidate
オプションを付与して、デフォルトでは最大30日保持されるCDNのキャッシュも削除しています。(キャッシュの削除には数分〜最大1時間かかるようです。)
cloudinary.uploader.destroy('ito-test/Abendessen', { invalidate: true },
function(error,result) { console.log(result, error) });
このメソッドは、こちらの記事にあるように、fetch でキャッシュされた画像 や Auto-upload で既に取り込まれている画像を更新する際にも使用できます。
特定タグのすべての画像を削除
再び resources を使って、条件に合う複数の画像を削除することができます。下記はタグ Node.js
の付与された画像を削除しています。
cloudinary.api.delete_resources_by_tag('Node.js',
function(error, result) {console.log(result, error); });
上の destroy と同様、invalidate
オプションを入れることで、CDNキャッシュも合わせて削除することができます。
おしまい
以上、Node.js を使って Cloudinary を操作する方法をご紹介しました。今週の Dev.IO でもセッションで Cloudinary についてご紹介します。他にも様々なセッションに加え、相談会ブース、スポンサーブース、そしてコワーキングスペースがありますので、ぜひ遊びに来てください!
Cloudinary について、お問い合わせはこちらから、無料サインアップは こちらから。