さくらのクラウドのAPI情報はどこで調べる？ — 運用自動化の入口、新APIポータルを使おう

はじめに

API経由でクラウドのリソースを操作すると、コントロールパネルで行う煩雑な操作を自動化できます。たとえば、サーバーの起動・停止や設定変更をスクリプトに組み込むことで、再現性の向上、ヒューマンエラーの削減、大規模な一括運用、CI/CDパイプラインとの連携といった効果が得られます。

本記事は、システムエンジニアの方を対象に、APIを使うときの入口となる「さくらのクラウド APIポータル」を紹介します。さらに、さくらのクラウドAPIの基本的な使い方を解説します。本記事を読み終えたときには、APIポータルで確認できる情報の概要と、APIキーを発行してリクエストを送る基本的な流れを把握できるはずです。

まずは、API情報の入口である「さくらのクラウドAPIポータル」から見ていきましょう。

さくらのクラウドAPIポータル — API情報の入口

さくらのクラウド向けAPIの仕様は、これまでマニュアルサイトの複数の場所に分散していました。新しく公開されたさくらのクラウドAPIポータルは、それらを「目的から探せる」入口として整備したWebページです。

APIポータルを利用することで、従来のドキュメント横断検索が不要になり、機能単位でAPI仕様を迅速に確認できます。

さくらのクラウドAPIポータルは、次のリンクからアクセスできます。また「さくらのクラウドマニュアル」の左側メニューにもリンクがあります。

さくらのクラウドAPIポータル

「さくらのクラウド」マニュアルの一部として、ログインは不要で、ブラウザからすぐに閲覧できます。使いたいAPIの仕様を調べるときは、まずこのポータルを開くのがおすすめです。

APIポータルのトップページは、次のようになっています。

トップページでAPIの種類を選ぶと、OpenAPIベースのAPIリファレンス（Redoc形式）で仕様を確認できます。次の画面は、IAM APIのリファレンスです。

詳細画面では、サービス別に、エンドポイント・リクエストパラメータ・レスポンスの例などを一画面で閲覧できます。機能が多いAPIの場合でも、左側のメニューで読みたい項目をすばやく探せます。

なお、すべてのAPIがOpenAPI形式に移行済みではありません。IaaS APIなど一部は、ポータルから旧ドキュメント（API v1.1）へのリンクになっています。仕様の掲載場所は異なりますが、IaaS APIの認証もさくらのクラウドAPIキー（Basic認証）が基本です。古い形式のドキュメントも順次移行する予定です。

また、ポータル上の多くのAPIページには「APIキーの発行」などの節があり、APIキーのマニュアルへリンクされています。認証の詳細は各マニュアルを参照してください。

さくらのクラウドAPIは、次の用途に向いています。

独自アプリケーションの開発
CI/CDとの連携
独自運用ツール

手動運用やインフラ構成管理(IaC)には、次のツールも用意していますので、合わせて参考にしてください。

さくらのクラウドAPIの基本操作

ポータルで仕様を確認したら、実際にAPIリクエストを送ってみましょう。ここでは基本的な流れのみを紹介します。

APIの概要

さくらのクラウドAPIのリクエストとレスポンスはJSONです。接続はHTTPSのみ、文字コードはUTF-8です。

APIはゾーンごとにエンドポイントが異なります。操作対象のゾーンに対応したURLにアクセスする必要があります。たとえば石狩第1ゾーン（is1a）のエンドポイントは、URLパスに「is1a」が含まれます。

APIエンドポイント	ゾーン名
https://secure.sakura.ad.jp/cloud/zone/tk1a/api/cloud/1.1/	東京第1ゾーン
https://secure.sakura.ad.jp/cloud/zone/tk1b/api/cloud/1.1/	東京第2ゾーン
https://secure.sakura.ad.jp/cloud/zone/is1a/api/cloud/1.1/	石狩第1ゾーン
https://secure.sakura.ad.jp/cloud/zone/is1b/api/cloud/1.1/	石狩第2ゾーン
https://secure.sakura.ad.jp/cloud/zone/is1c/api/cloud/1.1/	石狩第3ゾーン
https://secure.sakura.ad.jp/cloud/zone/tk1v/api/cloud/1.1/	Sandbox

なお、リージョンやゾーンに依存しないグローバルリソースのサービスには、専用のエンドポイントはありません。is1aなどいずれかのゾーンのエンドポイントに対してAPIを呼び出します。いずれのゾーンを選択した状態でも、同じプロジェクトのデータを返します。

また、いくつかのAPIではエンドポイントが異なる場合があります。例えば、請求関連APIがこれに該当します。詳細は、APIポータルの各APIの定義ファイル(YAML or JSON)をご確認ください。

アクセストークンとシークレットの発行

APIを利用するには、認証情報としてアクセストークンとシークレットの発行が必要です。

コントロールパネルで APIキーを発行するには次のように操作します。

コントロールパネルにログイン
左メニューから「APIキー」をクリック
右上の「APIキーの作成」をクリック
名前・アクセスレベルを入力
作成ボタンをクリック
表示された以下を控える
- アクセストークン
- アクセストークンシークレット

シークレット情報は一度しか表示されないので、確実に記録するよう注意してください。CSVファイルとしてダウンロードできるので、それを利用するのが確実です。

リクエストの例

本記事ではAPIキーを使った代表的な例を示します。

API呼び出し時には、コントロールパネルで発行したAPIキー（アクセストークンとシークレット）をBasic認証で送ります。そのため、事前に以下の環境変数を設定しておきます。

export SAKURA_ACCESS_TOKEN="取得したアクセストークン"
export SAKURA_ACCESS_TOKEN_SECRET="取得したシークレット"

次の例では、ゾーン情報を取得するAPIを呼び出しています。

# ゾーン情報を取得
# APIキーは環境変数に設定
curl -u "$SAKURA_ACCESS_TOKEN:$SAKURA_ACCESS_TOKEN_SECRET" \
  -H "X-Requested-With: XMLHttpRequest" \
  "https://secure.sakura.ad.jp/cloud/zone/is1a/api/cloud/1.1/zone"

このコマンドを実行すると、次のようなレスポンスが返ってきます。

{
  "From": 0, "Count": 6, "Total": 6,
  "Zones": [
    {
      "Index": 0,
      "ID": 21001,
      "DisplayOrder": 20021001,
      "Name": "tk1a",
      "Description": "東京第1ゾーン",
      "IsDummy": false,
	  (中略...)
    },
	(中略...)
  ],
  "is_ok": true
}

※ 注意：環境変数に設定したAPIキーは、そのセッションのプロセスから参照可能です。不要になった場合はシェルを終了するか、環境変数の値を削除してください。

よくあるトラブル

うまく動かない場合は、次の点を確認してみてください。

認証エラー（401） → アクセストークン・シークレットが誤っている
PowerShellでcurlが動かない → curl.exe を明示する

APIキーなどシークレット情報の取り扱い

APIキーのアクセストークンとシークレットは、パスワードと同様に扱ってください。ソースコードや設定ファイルへの直書き、チャットやメールでの共有、Gitリポジトリへの混入は避けましょう。先ほどのサンプルでは環境変数（$SAKURA_ACCESS_TOKEN など）で参照しています。

公開してしまった場合は、すみやかにシークレット情報を無効化し、再発行してください。

システム内でのシークレット情報を取り扱う場合は、お客様のシークレット情報を安全に管理・保管する「シークレットマネージャ」が利用可能です。

認証方式とアクセス権

さくらのクラウドAPIには、人・手元のスクリプト向けのAPIキー（Basic認証） と、システム連携向けのサービスプリンシパル（Bearer認証） があります。

IaaS API（API v1.1）などでは、同じエンドポイントをどちらの方式でも呼び出せます。権限はAPIキーならアクセスレベル、サービスプリンシパルならIAMポリシーで付与します。

主体	認証	権限
人・スクリプト	APIキー（Basic）	アクセスレベル
システム連携	サービスプリンシパル（Bearer）	IAMポリシー

本記事のcurl例はAPIキーによる呼び出しです。サービスプリンシパルの詳細はサービスプリンシパルを参照してください。

例外として、シンプルMQメッセージAPIのようにサービス固有の認証が必要な場合があります。各APIのマニュアルで方式を確認してください。

APIポータルの制約と今後の発展

さくらのクラウドでは、ポータルへの集約とAPI情報のOpenAPIベース化を順次進めています。

以下のAPIはポータル外のマニュアルで提供していますが、準備が整い次第、ポータルへの掲載とOpenAPI形式での提供を行います。

API/サービス	ドキュメント
シンプル通知	API リファレンス
ウェブアクセラレータ公開API	API リファレンス

本記事では、さくらのクラウドAPIの情報をどこで調べて、どう使い始めるかを整理しました。

まずは、さくらのクラウドAPIポータルを開き、利用したいサービスのAPI仕様を確認してみてください。

さくらのクラウドAPIポータル

さくらのクラウドのAPI情報はどこで調べる？ — 運用自動化の入口、新APIポータルを使おう

はじめに

さくらのクラウドAPIポータル — API情報の入口

さくらのクラウドAPIの基本操作

APIの概要

アクセストークンとシークレットの発行

リクエストの例

よくあるトラブル

APIキーなどシークレット情報の取り扱い

認証方式とアクセス権

APIポータルの制約と今後の発展

関連ページ

AppRun

高火力DOK

さくらのAI Engine

オブジェクトストレージ

シンプルMQ

シンプル通知

バックアップスイート

ショートメッセージ

さくらのモノプラットフォーム

セキュアモバイルコネクト

シンプルAI

その他