さくらの専用サーバ PHY：APIドキュメント
API docs by Redocly

さくらの専用サーバ PHY APIドキュメント (1.1.0)

Download OpenAPI specification:Download

License: Copyright(C) 2021 SAKURA Internet Inc. all rights reserved. Terms of Service

「さくらの専用サーバ PHY」が提供するAPIの利用方法とサンプルを公開しております。

基本的な使い方

APIキーの発行

APIを利用するためには、認証のための「APIキー」が必要です。事前にキーを発行しておきます。 APIキーは「ユーザーID」「パスワード」に相当する「トークン」と呼ばれる認証情報で構成されています。

項目名 APIキー発行時の項目名 このドキュメント内での例
ユーザーID アクセストークン(UUID) 01234567-89ab-cdef-0123-456789abcdef
パスワード アクセストークンシークレット SAMPLETOKENSAMPLETOKENSAMPLETOKENSAM
操作マニュアル

入力パラメーター

APIの入力には送信先URLに対して、いくつかのヘッダーとAPIキーを送信します。

  • APIのURLは https://secure.sakura.ad.jp/cloud/api/dedicated-phy/1.0/(エンドポイント)/ となります。
  • 認証方式はHTTP Basic認証です。APIキーのアクセストークンをユーザーID、アクセストークンシークレットをパスワードとして指定します。
  • GET 以外のメソッドでは、CSRFの対策として、ヘッダーに X-Requested-With: XMLHttpRequest を指定します。
# 入力サンプル
curl -u '01234567-89ab-cdef-0123-456789abcdef:SAMPLETOKENSAMPLETOKENSAMPLETOKENSAM' \
     -H 'X-Requested-With: XMLHttpRequest' \
     'https://secure.sakura.ad.jp/cloud/api/dedicated-phy/1.0/servers/'

出力結果と応答コード（HTTPステータスコード）

APIからの結果は、「応答コード（HTTPステータスコード）」と、「JSON形式(UTF-8)の結果」として出力されます。

応答コードは、リクエストが成功したのか、失敗したのか大まかな情報を判断することができるもので、例えば失敗したときには、なぜこのような結果になったのかなど、具体的な情報は応答コードと主に返された本文を見ることで把握することができます。

結果 応答コード/status
成功 (要求を受け付けた) 2xx
失敗（要求が受け付けられなかった） 4xx, 5xx 
# 出力結果サンプル 
{
"type": "about:blank",
"title": "not_found",
"detail": "string",
"status": 404
}

API実行回数の制限(Rate Limiting)

  • 時間あたりで実行できるリクエスト回数に上限があります
    • 基本はご利用の アカウントごとに300リクエスト/1時間 まで
    • サーバーのネットワーク設定を行うエンドポイントは、 サーバーごとに5リクエスト/5分間 まで
      • サーバーインターフェースの冗長化設定(ボンディング)
      • サーバーインターフェースの有効/無効設定
      • サーバーインターフェースのネットワーク接続設定
  • リクエスト回数の上限に達した場合、リクエストは処理されず HTTP 429 となります
  • これらの制限は、今後のお客様の利用状況により変更する場合があります

サービス情報

サービス一覧

サービスの一覧を取得します。

Authorizations:
account_api_key
query Parameters
product_category
string
Enum: "server" "dedicated_subnet" "private_network" "firewall" "load_balancer"

サービスの種類で絞りこむ

tag
Array of strings <= 10 items [ items <= 50 characters ]

タグで絞り込む
このクエリーパラメーターを複数指定した場合は すべてのタグを設定済み(AND) のものにマッチ

free_word
Array of strings <= 5 items [ items <= 50 characters ]

フリーワード検索 下記項目の いずれか にマッチしたものを抽出する

  • 名前(部分一致)
  • 説明(部分一致)
  • タグ(部分一致)

このクエリーパラメーターを複数指定した場合は 複数の語句すべてを含む(AND) ものにマッチ

limit
integer
Default: 10

取得数を指定する

offset
integer
Default: 0

取得開始位置を指定する

ordering
string
Default: "-activated"
Enum: "activated" "-activated" "nickname" "-nickname"

並び順指定, - から始まる場合は降順指定

  • activated - 利用開始日順
  • nickname - 名称順

Responses

Response samples

Content type
application/json
{
  • "meta": {
    },
  • "services": [
    ]
}

サービス 詳細

サービス 詳細

Authorizations:
account_api_key
path Parameters
service_id
required
string^\d{12}$

サービスコード

Responses

Response samples

Content type
application/json
{
  • "service": {
    }
}

サービスの名称・説明の変更

サービス名称・説明の変更

Authorizations:
account_api_key
path Parameters
service_id
required
string^\d{12}$

サービスコード

header Parameters
X-Requested-With
required
string
Value: "XMLHttpRequest"

CSRF防止用ヘッダー

Request Body schema: application/json

サービス情報

nickname
string <= 64 characters

名称：サーバーやネットワークなどの表示名

description
string or null <= 1000 characters

メモ：サーバーやネットワークなどの説明

Responses

Request samples

Content type
application/json
{
  • "nickname": "サーバーやネットワークの簡潔な名前",
  • "description": "サーバーやネットワークの利用用途などを\n自由に記述"
}

Response samples

Content type
application/json
{
  • "service": {
    }
}

サーバー

サーバー一覧

サーバー一覧

Authorizations:
account_api_key
query Parameters
power_status
string
Enum: "on" "off"

キャッシュされた電源状態で絞りこむ

internet
string
Example: internet=123456789012

インターネット接続状態の絞り込み

  • common - 共用グローバルネットワークを利用
  • void - インターネット接続なし
  • {dedicated_subnet_id} - 指定した専用グローバルネットワークを利用
private_network
Array of strings <= 5 items
Example: private_network=123456789012

ローカルネットワークの接続状態の絞り込み このパラメーターが複数ある場合は**全てのネットワークに接続済み(AND)**が対象

  • void - ローカル接続なし
  • {private_network_id} - 指定したローカルネットワークを利用
tag
Array of strings <= 10 items [ items <= 50 characters ]

タグで絞り込む
このクエリーパラメーターを複数指定した場合は すべてのタグを設定済み(AND) のものにマッチ

free_word
Array of strings <= 5 items [ items <= 50 characters ]

フリーワード検索 下記項目の いずれか にマッチしたものを抽出する

  • 名前(部分一致)
  • 説明(部分一致)
  • タグ(部分一致)

このクエリーパラメーターを複数指定した場合は 複数の語句すべてを含む(AND) ものにマッチ

limit
integer
Default: 10

取得数を指定する

offset
integer
Default: 0

取得開始位置を指定する

ordering
string
Default: "-activated"
Enum: "activated" "-activated" "nickname" "-nickname" "power_status_stored" "-power_status_stored"

並び順の指定, - から始まる場合は降順指定

  • activated - 利用開始日順
  • nickname - 名称順
  • power_status_stored - 電源状態更新日時順

Responses

Response samples

Content type
application/json
{
  • "meta": {
    },
  • "servers": [
    ]
}

サーバー

サーバーの詳しい情報を表示

Authorizations:
account_api_key
path Parameters
server_id
required
string^\d{12}$

サーバーのサービスコード

Responses

Response samples

Content type
application/json
{
  • "server": {
    }
}

サーバーのRAID状態を取得

サーバーのRAID状態を取得 サーバー本体の電源が入っている必要があります

Authorizations:
account_api_key
path Parameters
server_id
required
string^\d{12}$

サーバーのサービスコード

query Parameters
refresh
boolean
Default: false

実機の最新状態を取得

Responses

Response samples

Content type
application/json
{
  • "raid_status": {
    }
}

インストール可能OS一覧

インストール可能OS一覧

Authorizations:
account_api_key
path Parameters
server_id
required
string^\d{12}$

サーバーのサービスコード

Responses

Response samples

Content type
application/json
{
  • "os_images": [
    ]
}

OSインストールの実行

OSインストールの実行

このエンドポイントはサーバーのロック状態がoperationalの場合のみ実行可能で OSインストールの実行中はロック状態がos_installに変わります

Authorizations:
account_api_key
path Parameters
server_id
required
string^\d{12}$

サーバーのサービスコード

header Parameters
X-Requested-With
required
string
Value: "XMLHttpRequest"

CSRF防止用ヘッダー

Request Body schema: application/json

OSインストール情報

password
string <password> (password_input) [ 8 .. 32 ] characters [0-9a-zA-Z!"#$%&'()*+,\-./:;<=>?@[\]^_`{|}~]+...

英数字と記号の組み合わせ 1文字以上のアルファベットと1文字以上の数字が必須

os_image_id
required
string

インストールするOSイメージ名

manual_partition
boolean

リモートコンソールを利用し手動パーティション指定を行う (OSが対応している場合のみ)

ssh_public_keys
Array of strings <= 20 items
Default: []

専用サーバーに登録するSSH公開鍵のリスト

SSH公開鍵認証に対応したOSイメージでのみ有効なパラメータです allow_password_loginが偽の場合は1つ以上の要素が必要です

allow_password_login
boolean
Default: true

パスワードでのSSHログインの許可

SSH公開鍵認証に対応したOSイメージでのみ有効なパラメータです

Responses

Request samples

Content type
application/json
{
  • "password": "passw0rd",
  • "os_image_id": "centos7-x86_64",
  • "manual_partition": true,
  • "ssh_public_keys": [
    ],
  • "allow_password_login": true
}

Response samples

Content type
application/json
{
  • "type": "about:blank",
  • "title": "invalid",
  • "detail": "string",
  • "status": 400,
  • "invalid_parameters": {
    }
}

サーバーの電源

サーバーの電源情報を取得する

サーバーの電源情報を取得する

Authorizations:
account_api_key
path Parameters
server_id
required
string^\d{12}$

サーバーのサービスコード

Responses

Response samples

Content type
application/json
{
  • "power_status": {
    }
}

サーバーの電源操作

サーバーの電源操作

Authorizations:
account_api_key
path Parameters
server_id
required
string^\d{12}$

サーバーのサービスコード

header Parameters
X-Requested-With
required
string
Value: "XMLHttpRequest"

CSRF防止用ヘッダー

Request Body schema: application/json
operation
required
string
Enum: "on" "soft" "reset" "off"

操作内容

  • on - 電源ON
  • soft - ACPIシャットダウン(OSでの電源シャットダウン)
  • reset - ハードウェア電源リセット(電源OFF+電源ON)
  • off - ハードウェア電源OFF

Responses

Request samples

Content type
application/json
{
  • "operation": "on"
}

Response samples

Content type
application/json
{
  • "type": "about:blank",
  • "title": "invalid",
  • "detail": "string",
  • "status": 400,
  • "invalid_parameters": {
    }
}

サーバーネットワーク設定

ポートチャネル状態取得

ポートチャネル状態取得

Authorizations:
account_api_key
path Parameters
server_id
required
string^\d{12}$

サーバーのサービスコード

port_channel_id
required
integer

ポートチャネルID

Responses

Response samples

Content type
application/json
{
  • "port_channel": {
    }
}

ポートチャネル ボンディング設定

ポートチャネル ボンディング設定

このエンドポイントを実行すると配下の {port_id} が新たに採番され 論理ポート情報がリセットされる

Authorizations:
account_api_key
path Parameters
server_id
required
string^\d{12}$

サーバーのサービスコード

port_channel_id
required
integer

ポートチャネルID

header Parameters
X-Requested-With
required
string
Value: "XMLHttpRequest"

CSRF防止用ヘッダー

Request Body schema: application/json
bonding_type
required
string
Enum: "lacp" "static" "single"

ボンディング方式指定

  • lacp - LACP
  • static - static link aggregation
  • single - ボンディングなし(単体構成)
port_nicknames
Array of strings or null
Default: null

作成するポート名称の指定

  • nullの場合は自動設定
  • ボンディング構成する場合は1要素の配列
  • ボンディングなしの場合は2要素の配列

Responses

Request samples

Content type
application/json
{
  • "bonding_type": "lacp",
  • "port_nicknames": [
    ]
}

Response samples

Content type
application/json
{
  • "port_channel": [
    ]
}

ポート情報取得

ポート情報取得

Authorizations:
account_api_key
path Parameters
server_id
required
string^\d{12}$

サーバーのサービスコード

port_id
required
integer

ポートID

Responses

Response samples

Content type
application/json
{
  • "port": {
    }
}

ポート名称設定

ポート名称設定

Authorizations:
account_api_key
path Parameters
server_id
required
string^\d{12}$

サーバーのサービスコード

port_id
required
integer

ポートID

header Parameters
X-Requested-With
required
string
Value: "XMLHttpRequest"

CSRF防止用ヘッダー

Request Body schema: application/json
nickname
required
string <= 50 characters

ポート名称

Responses

Request samples

Content type
application/json
{
  • "nickname": "ポート名称1"
}

Response samples

Content type
application/json
{
  • "port": [
    ]
}

トラフィックデータ取得

トラフィックデータ取得

Authorizations:
account_api_key
path Parameters
server_id
required
string^\d{12}$

サーバーのサービスコード

port_id
required
integer

ポートID

query Parameters
since
string <date-time>

取得範囲始点(過去31日前まで,未指定時は7日前)

until
string <date-time>

取得範囲終点(未指定時は現在時刻)

step
integer
Default: 300
Enum: 300 600 3600 21600

データポイント間隔(秒)

Responses

Response samples

Content type
application/json
{
  • "traffic_graph": {
    }
}

ポート有効/無効設定

ポート有効/無効設定

Authorizations:
account_api_key
path Parameters
server_id
required
string^\d{12}$

サーバーのサービスコード

port_id
required
integer

ポートID

header Parameters
X-Requested-With
required
string
Value: "XMLHttpRequest"

CSRF防止用ヘッダー

Request Body schema: application/json
enable
required
boolean

通信を有効にする場合に true

Responses

Request samples

Content type
application/json
{
  • "enable": true
}

Response samples

Content type
application/json
{
  • "port": {
    }
}

ネットワーク接続設定の変更

ネットワーク接続設定の変更

Authorizations:
account_api_key
path Parameters
server_id
required
string^\d{12}$

サーバーのサービスコード

port_id
required
integer

ポートID

header Parameters
X-Requested-With
required
string
Value: "XMLHttpRequest"

CSRF防止用ヘッダー

Request Body schema: application/json
mode
required
string
Enum: "access" "trunk"

ポートモード

  • access - アクセスポート
  • trunk - トランクポート
internet_type
string or null
Default: null
Enum: null "common_subnet" "dedicated_subnet"
  • null - インターネット接続なし
  • common_subnet - 共用グローバルネットワーク利用
  • dedicated_subnet - 専用グローバルネットワーク利用
dedicated_subnet_id
string or null
Default: null

専用グローバルネットワークのサービスコード指定 global_network_typeがdedicated_subnetの場合に必須

private_network_ids
Array of strings or null
Default: null

接続先ローカルネットワークの配列

Responses

Request samples

Content type
application/json
{
  • "mode": "access",
  • "internet_type": "dedicated_subnet",
  • "dedicated_subnet_id": "345678901234",
  • "private_network_ids": null
}

Response samples

Content type
application/json
{
  • "port": {
    }
}

専用グローバルネットワーク

専用グローバルネットワーク 一覧

専用グローバルネットワーク 一覧

Authorizations:
account_api_key
query Parameters
tag
Array of strings <= 10 items [ items <= 50 characters ]

タグで絞り込む
このクエリーパラメーターを複数指定した場合は すべてのタグを設定済み(AND) のものにマッチ

free_word
Array of strings <= 5 items [ items <= 50 characters ]

フリーワード検索 下記項目の いずれか にマッチしたものを抽出する

  • 名前(部分一致)
  • 説明(部分一致)
  • タグ(部分一致)

このクエリーパラメーターを複数指定した場合は 複数の語句すべてを含む(AND) ものにマッチ

limit
integer
Default: 10

取得数を指定する

offset
integer
Default: 0

取得開始位置を指定する

ordering
string
Default: "-activated"
Enum: "activated" "-activated" "nickname" "-nickname"

並び順指定, - から始まる場合は降順指定

  • activated - 利用開始日順
  • nickname - 名称順

Responses

Response samples

Content type
application/json
{
  • "meta": {
    },
  • "dedicated_subnets": [
    ]
}

専用グローバルネットワーク

専用グローバルネットワーク

Authorizations:
account_api_key
path Parameters
dedicated_subnet_id
required
string^\d{12}$

専用グローバルネットワークのサービスコード

query Parameters
refresh
boolean
Default: true

IPv6有効状態の最新状態を取得する

Responses

Response samples

Content type
application/json
{
  • "dedicated_subnet": {
    }
}

ローカルネットワーク

ローカルネットワーク 一覧

ローカルネットワーク 一覧

Authorizations:
account_api_key
query Parameters
tag
Array of strings <= 10 items [ items <= 50 characters ]

タグで絞り込む
このクエリーパラメーターを複数指定した場合は すべてのタグを設定済み(AND) のものにマッチ

free_word
Array of strings <= 5 items [ items <= 50 characters ]

フリーワード検索 下記項目の いずれか にマッチしたものを抽出する

  • 名前(部分一致)
  • 説明(部分一致)
  • タグ(部分一致)

このクエリーパラメーターを複数指定した場合は 複数の語句すべてを含む(AND) ものにマッチ

limit
integer
Default: 10

取得数を指定する

offset
integer
Default: 0

取得開始位置を指定する

ordering
string
Default: "-activated"
Enum: "activated" "-activated" "nickname" "-nickname"

並び順指定, - から始まる場合は降順指定

  • activated - 利用開始日順
  • nickname - 名称順

Responses

Response samples

Content type
application/json
{
  • "meta": {
    },
  • "private_networks": [
    ]
}

ローカルネットワーク 詳細

ローカルネットワーク 詳細

Authorizations:
account_api_key
path Parameters
private_network_id
required
string^\d{12}$

ローカルネットワークのサービスコード

Responses

Response samples

Content type
application/json
{
  • "private_network": {
    }
}