さくらのクラウド さくらのクラウド API ポータル クラウドマニュアルへ
API docs by Redocly

ネットワークスイート (CR) API (0.2.1)

Download OpenAPI specification:Download OpenAPI Spec (YAML)Download OpenAPI Spec (JSON)

URL: https://www.sakura.ad.jp/ License: Copyright(C) SAKURA internet Inc. all rights reserved.

ネットワークスイート (CR) APIは、さくらのクラウドのネットワークスイート機能 (Networking Suite) を提供するAPIです。

基本的な使い方

APIキーの発行

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

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

入力パラメータ

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

  • 認証方式はHTTP Basic認証です。APIキーのアクセストークンをユーザーID、アクセストークンシークレットをパスワードとして指定します。
# 入力サンプル
curl \
  -u '01234567-89ab-cdef-0123-456789abcdef:SAMPLETOKENSAMPLETOKENSAMPLETOKENSAM' \
  -X GET \
  'https://secure.sakura.ad.jp/cloud/zone/is1c/api/cloud/1.1/networking-suite/subnet-groups'

APIエンドポイント

ネットワークスイートでは、作成するリソースのスコープに応じてAPIエンドポイントのゾーンを指定します。

  • リージョン単位のリソースを操作する場合は、リージョンに対応するゾーンを指定します。
    • 例: is1 リージョンの場合、is1c ゾーンを指定します。
  • ゾーン単位のリソースを操作する場合は、対象のリソースが属するゾーンを指定します。
    • 例: is1c ゾーンにサブネットを作成する場合、is1c ゾーンを指定します。

リソースのスコープ

リソース種 リソース種識別子 スコープ
サブネットグループ sakura.networking-suite.subnet-group リージョン
サブネット sakura.networking-suite.subnet ゾーン
インターフェースコネクション sakura.networking-suite.interface-connection ゾーン
サブネットアドレス sakura.networking-suite.address ゾーン
NIC (インターフェース) sakura.iaas.interface ゾーン

リソース種識別子についての詳細は「さくらのリソース名 (Sakura resource name, SRN)」の項目をご参照ください。

「さくらのリソース名 (Sakura resource name, SRN)」について

さくらのリソース名 (Sakura resource name, SRN) は、さくらのクラウドのリソースを一意に識別するための文字列です。SRNは、リソースのスコープや種類、IDなどを含む構造化された文字列であり、リソースを特定するために使用されます。 ネットワークスイート (CR) APIでは、SRNを使用してサブネットグループやサブネットなどのリソースを識別します。SRNは、リソースの種類やIDを含むため、API呼び出し時にリソースを指定する際に便利です。

SRNは以下の構造を持ちます。

srnv1:{{ロケーション識別子}}:{{リソース種識別子}}:{{ID}}
項目 概要 形式例
ロケーション識別子 リソースの所在を示す識別子です。 sakura-is1c (石狩第3ゾーン), sakura-is1 (石狩リージョン)
リソース種識別子 リソースの種類を示す識別子です。 sakura.networking-suite.subnet-group (サブネットグループ), sakura.iaas.interface (インターフェース)
ID リソースのIDです。 (形式はリソースによって異なります)

例1: 石狩リージョンにあるサブネットグループのSRNは以下のような形式です。

srnv1:sakura-is1:sakura.networking-suite.subnet-group:1234567890

例2: 石狩第3ゾーンにあるNIC (インターフェース)のSRNは以下のような形式です。

srnv1:sakura-is1c:sakura.iaas.interface:2345678901

具体的なSRNの値や指定方法については、各APIごとのドキュメントをご参照ください。

ドキュメント上に記載のないフィールドについて

ネットワークスイート (CR) APIのレスポンスには、ドキュメント上に記載のないフィールドが含まれる場合があります。これらのフィールドは、将来的な拡張あるいは後方互換性のために予告無く追加・削除されることがあります。ドキュメント上に記載のないフィールドは、アプリケーションでの利用は行わないようにしてください。

サブネットグループ操作

サブネットグループの作成、取得、更新、削除を行います。

サブネットグループの作成

サブネットグループを作成します。

Request Body schema: application/json
required
Name
required
string

名前

Description
required
string

説明

IPv4AddressRangeCIDR
required
string

IPv4アドレス範囲 (CIDR形式)

マニュアル内「仕様」に記載の条件を満たすIPアドレス範囲をCIDR形式で表現します。

required
object (Region)

リージョン

Responses

Request samples

Content type
application/json
{
  • "Name": "サブネットグループ名",
  • "Description": "サブネットグループの説明",
  • "IPv4AddressRangeCIDR": "10.0.0.0/20",
  • "Region": {
    }
}

Response samples

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

サブネットグループ一覧の取得

サブネットグループの一覧を取得します。

Responses

Response samples

Content type
application/json
{
  • "Count": 1,
  • "From": 0,
  • "SubnetGroups": [
    ],
  • "Total": 1
}

サブネットグループ詳細の取得

サブネットグループの詳細を取得します。

path Parameters
subnetgroupid
required
string
Examples:
  • 1234567890 - サブネットグループ詳細の取得

サブネットグループのID

サブネットグループのSRNの末尾、ID部分の値を指定します。 例: srnv1:sakura-is1:sakura.networking-suite.subnet-group:1234567890 の場合は 1234567890 を指定します。

Responses

Response samples

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

サブネットグループ詳細の更新

サブネットグループの詳細を更新します。

名前 (Name) と説明 (Description) のみ更新可能です。

path Parameters
subnetgroupid
required
string
Examples:
  • 1234567890 - サブネットグループ更新

サブネットグループのID

サブネットグループのSRNの末尾、ID部分の値を指定します。 例: srnv1:sakura-is1:sakura.networking-suite.subnet-group:1234567890 の場合は 1234567890 を指定します。

Request Body schema: application/json
required
Name
required
string

名前

Description
required
string

説明

Responses

Request samples

Content type
application/json
{
  • "Name": "新しいサブネットグループ名",
  • "Description": "新しいサブネットグループの説明"
}

Response samples

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

サブネットグループの削除

サブネットグループを削除します。

サブネットグループを削除するには、サブネットグループに属するサブネットがすべて削除されている必要があります。

path Parameters
subnetgroupid
required
string
Examples:
  • 1234567890 - サブネットグループの削除

サブネットグループのID

サブネットグループのSRNの末尾、ID部分の値を指定します。 例: srnv1:sakura-is1:sakura.networking-suite.subnet-group:1234567890 の場合は 1234567890 を指定します。

Responses

Response samples

Content type
application/json
{
  • "serial": "4f464bf7db102d5e8e2092876506bc77",
  • "error_code": "forbidden",
  • "error_msg": "要求された操作は許可されていません。権限エラー。"
}

サブネット操作

サブネットの作成、取得、更新、削除を行います。

サブネットの作成

サブネットグループにサブネットを作成します。

Request Body schema: application/json
required
Name
required
string

名前

Description
required
string

説明

IPv4AddressRangeCIDR
required
string

IPv4アドレス範囲 (CIDR形式)

マニュアル内「仕様」に記載の条件を満たすIPアドレス範囲をCIDR形式で表現します。 IPv4アドレス範囲は、親サブネットグループのIPv4アドレス範囲に含まれ、かつ、同一親サブネットグループ下の他サブネットと重複しない範囲である必要があります。

required
object (Zone)

ゾーン

required
object (SakuraResourceNameRef)

親サブネットグループ

Responses

Request samples

Content type
application/json
{
  • "Name": "サブネット名",
  • "Description": "サブネットの説明",
  • "IPv4AddressRangeCIDR": "10.0.0.0/26",
  • "Zone": {
    },
  • "SubnetGroup": {
    }
}

Response samples

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

サブネット一覧の取得

サブネットの一覧を取得します。

query Parameters
subnetGroupSRN
required
string
Examples:
  • subnetGroupSRN=subnetGroupSRN=srnv1:sakura-is1:sakura.networking-suite.subnet-group:1234567890 - 指定したサブネットグループに属するサブネットの一覧を取得

サブネットグループのSRN

指定されたサブネットグループに属するサブネットの一覧のみを取得します。

Responses

Response samples

Content type
application/json
{
  • "Count": 1,
  • "From": 0,
  • "Subnets": [
    ],
  • "Total": 1
}

サブネット詳細の取得

サブネットの詳細を取得します。

path Parameters
subnetid
required
string
Examples:
  • 2345678901 - サブネット詳細を取得

サブネットのID

サブネットのSRNの末尾、ID部分の値を指定します。 例: srnv1:sakura-is1c:sakura.networking-suite.subnet:2345678901 の場合は 2345678901 を指定します。

Responses

Response samples

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

サブネット詳細の更新

サブネットの詳細を更新します。

名前 (Name) と説明 (Description) のみ更新可能です。

path Parameters
subnetid
required
string
Examples:
  • 2345678901 - サブネット詳細の更新

サブネットのID

サブネットのSRNの末尾、ID部分の値を指定します。 例: srnv1:sakura-is1c:sakura.networking-suite.subnet:2345678901 の場合は 2345678901 を指定します。

Request Body schema: application/json
required
Name
required
string

名前

Description
required
string

説明

Responses

Request samples

Content type
application/json
{
  • "Name": "新しいサブネット名",
  • "Description": "新しいサブネットの説明"
}

Response samples

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

サブネットの削除

サブネットを削除します。

サブネットを削除するには、サブネットに接続されているNICがすべて切断されている必要があります。インターフェースコネクションを削除することで、NICをサブネットから切断します。

path Parameters
subnetid
required
string
Examples:
  • 2345678901 - サブネット削除

サブネットのID

サブネットのSRNの末尾、ID部分の値を指定します。 例: srnv1:sakura-is1c:sakura.networking-suite.subnet:2345678901 の場合は 2345678901 を指定します。

Responses

Response samples

Content type
application/json
{
  • "serial": "4f464bf7db102d5e8e2092876506bc77",
  • "error_code": "forbidden",
  • "error_msg": "要求された操作は許可されていません。権限エラー。"
}

インターフェース操作

NIC (インターフェース) をサブネットに接続するためのインターフェースコネクションの作成、削除を行います。

NIC (インターフェース) をサブネットに接続

NIC (インターフェース) をサブネットに接続するために、インターフェースコネクションを作成します。

ネットワークスイートでは、NICとサブネットの接続関係をインターフェースコネクションというリソースで管理します。 また、NICをサブネットに接続する際に、エフェメラルIPアドレスを確保のうえ、インターフェースコネクションと紐付けて管理します。エフェメラルIPアドレスはサブネット内で一時的に割り当てられるIPアドレスであり、NICがサブネットから切断されると自動的に解放されます。

NICのSRNは、以下の手順で取得できます。

  1. NICを接続しているサーバーの詳細情報 (GET /server/{serverid}; 詳細) のレスポンスに含まれる Server.Interfaces[].ID を取得します
  2. 取得した Server.Interfaces[].ID を用いて、NICのSRNを組み立てます
    • 例: Server.Interfaces[].ID が 3456789012 の場合、SRNは srnv1:<ロケーション識別子>:sakura.iaas.interface:3456789012 となります

接続するNICとサブネットは同一ゾーンに存在する必要があります。異なるゾーンのNICとサブネットを接続することはできません。

Request Body schema: application/json
required
EphemeralIPv4Address
string

IPv4アドレス

required
object (SakuraResourceNameRef)

サーバーNIC (インターフェース)

required
object (SakuraResourceNameRef)

サブネット

Responses

Request samples

Content type
application/json
Example

NICをサブネットに接続する際、EphemeralIPv4Address フィールドを省略することで、空いている未使用のエフェメラルIPアドレスを自動的に割り当てます。

{
  • "Interface": {
    },
  • "Subnet": {
    }
}

Response samples

Content type
application/json
Example

NICをサブネットに接続する際、EphemeralIPv4Address フィールドを省略することで、空いている未使用のエフェメラルIPアドレスを自動的に割り当てます。

{
  • "InterfaceConnection": {
    }
}

NIC (インターフェース) をサブネットから切断

インターフェースコネクションを削除することで、NIC (インターフェース) をサブネットから切断します。

NICをサブネットから切断すると、NICに割り当てられていたエフェメラルIPアドレスは自動的に解放されます。

インターフェースコネクションを削除してNICをサブネットから切断するには、NICが接続されたサーバーが停止している必要があります。サーバーが起動中の場合、インターフェースコネクションを削除することはできません。

path Parameters
interfaceconnectionid
required
string
Examples:
  • 4567890123 - インターフェースコネクションを削除してNICをサブネットから切断

インターフェースコネクションのID

インターフェースコネクションのSRNの末尾、ID部分の値を指定します。

インターフェースコネクションのIDは、以下のいずれかの方法で取得できます:

  • NIC (インターフェース) をサブネットへ接続する際 (POST /networking-suite/interface-connections) のレスポンスに含まれる InterfaceConnection.SRN を参照します
    • 例: InterfaceConnection.SRN が srnv1:sakura-is1c:sakura.networking-suite.interface-connection:4567890123 の場合、IDは 4567890123 となります
  • NICを接続しているサーバーの詳細情報 (GET /server/{serverid}; 詳細) のレスポンスに含まれる Server.Interfaces[].NetworkingSuiteInterfaceConnection.ID を参照します

Responses

Response samples

Content type
application/json
{
  • "serial": "4f464bf7db102d5e8e2092876506bc77",
  • "error_code": "forbidden",
  • "error_msg": "要求された操作は許可されていません。権限エラー。"
}

アドレス操作

サブネットで割り当て済みのIPアドレスの取得を行います。

アドレス一覧の取得

割り当て済みのIPアドレスの一覧を取得します。

query Parameters
subnetSRN
required
string
Examples:
  • subnetSRN=subnetSRN=srnv1:sakura-is1c:sakura.networking-suite.subnet:2345678901 - サブネットとインターフェースコネクションを指定してアドレス取得

サブネットのSRN

指定されたサブネットで割り当て済みのIPアドレスの一覧のみを取得します。

interfaceConnectionSRN
string
Examples:
  • interfaceConnectionSRN=interfaceConnectionSRN=srnv1:sakura-is1c:sakura.networking-suite.interface-connection:4567890123 - サブネットとインターフェースコネクションを指定してアドレス取得

インターフェースコネクションのSRN

指定されたインターフェースコネクションに割り当て済みのIPアドレスのみを取得します。

インターフェースコネクションのSRNは以下のいずれかの方法で取得できます:

  • NIC (インターフェース) をサブネットへ接続する際 (POST /networking-suite/interface-connections) のレスポンスに含まれる InterfaceConnection.SRN を参照します
  • NICを接続しているサーバーの詳細情報 (GET /server/{serverid}; 詳細) のレスポンスに含まれる Server.Interfaces[].NetworkingSuiteInterfaceConnection.ID を用いてSRNを組み立てます
    • 例: Server.Interfaces[].NetworkingSuiteInterfaceConnection.ID が 4567890123 の場合、SRNは srnv1:<ロケーション識別子>:sakura.networking-suite.interface-connection:4567890123 となります

Responses

Response samples

Content type
application/json
{
  • "Total": 0,
  • "From": 0,
  • "Count": 0,
  • "Addresses": [
    ]
}

アドレス詳細の取得

割り当て済みのIPアドレスの詳細情報を取得します。

path Parameters
addressid
required
string
Example: 5678901234

アドレスのID

アドレスのSRNの末尾、ID部分の値を指定します。 例: srnv1:sakura-is1c:sakura.networking-suite.address:5678901234 の場合は 5678901234 を指定します。

Responses

Response samples

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