SoftLayer API 概要

SoftLayer のアプリケーション・プログラミング・インターフェース (API) は、開発者やシステム管理者が SoftLayer のバックエンド・システムと直接対話できるようにする開発用インターフェースです。API によって公開される機能を使用すると、ユーザーはリモート・サーバー管理やモニターを実行し、会計システム、在庫システム、DNS システムなどの SoftLayer の各種システムから情報を取り出すことができます。API は、SoftLayer カスタマー・ポータルの多くの機能を強化します。これは、通常、カスタマー・ポータルで対話が可能であれば、API でも実行できることを意味します。

API の使用者

SoftLayer API (SLAPI) は、すべての SoftLayer のお客様に追加料金なしでご利用いただけます。オブジェクト指向プログラミングの基本的な知識をお持ちのお客様は、SLAPI が提供する機能を十分に活用してくださるようお勧めします。SoftLayer のお客様はさまざまなタスクに SLAPI を使用すると同時に、API 内で SoftLayer 環境のあらゆる部分とプログラマチックに対話できることから、大部分のお客様は SLAPI を使用して作業を自動化することができます。

SoftLayer API の使用

はじめる前に

SLAPI では、ユーザーはカスタマー・ポータルを実行するオブジェクトと直接対話することができます。SLAPI 用の開発を行う前に、オブジェクト、プロパティー、メソッド、継承などの基本的なオブジェクト指向プログラミングの概念を理解しておくことが非常に有益です。SLAPI のメソッドは、バックエンド・システム内のサービス・オブジェクトに対して実行されます。これにより、SoftLayer 固有のデータ・タイプ・オブジェクトと標準のデータ・タイプ (整数、ブール、ストリングなど) の両方が戻されます。
SLAPI は、リモート・プロシージャー・コール・システムです。各呼び出しには、API エンドポイントへのデータの送信と、それと引き換えに構造化データの受信が含まれます。SLAPI を使用したデータの送信と受信に使用される形式は、選択した API の実装方法によって異なります。SLAPI は現在、データ伝送に SOAPXML-RPC または REST を使用します。API 呼び出しを行う前に、ご使用のプログラミング言語またはスクリプト言語でこれらのプロトコルを使用する方法を理解しておくと役立ちます。ご使用のアプリケーションでどの実装方法でも使用できます。また、github プロファイルに、サポートされているさまざまな言語で使用可能なサービス固有の複数の API クライアントも用意しています。

API ユーザーの作成

SLAPI への各呼び出しは、カスタマー・ポータルのアカウントによって認証されます。カスタマー・ポータルのアカウントには、複数のユーザーを含むことができます。API 呼び出しを実行するために固有のカスタマー・ポータル・ユーザーを作成することを強くお勧めします。お客様がアプリケーションを開発しているか、他のユーザーが開発した API ベースのアプリケーションを使用しているかにかかわらず、アカウントのすべての側面に関する情報にアクセスし、すべての側面と対話するには、プログラム内で認証する必要があります。SLAPI に対する認証には、カスタマー・ポータルのユーザー名と API キー (API メソッド呼び出し用に予約されている特殊な認証トークン) が必要です。カスタマー・ポータルで定義されるユーザー許可は、API 呼び出しに反映されます。

パブリック・ネットワークまたはプライベート・ネットワークの選択

SLAPI エンドポイント・サーバーは、SoftLayer のパブリック・ネットワークとプライベート・ネットワークに存在します。API ベースのアプリケーションは、インターネット上の任意のホストから接続できます。ただし、SoftLayer のプライベート・ネットワークは、データ・セキュリティー層を追加してセキュリティーを強化します。さらに、SoftLayer は、プライベート・ネットワークに接続しているときにのみアクセス可能な各種プライベート・ネットワーク API エンドポイントを提供します。SoftLayer アカウントに関連付けられているすべてのサーバーとコンピューティング・インスタンスは、プライベート・ネットワークに直接接続でき、追加の認証は必要ありません。別のデバイスからプライベート・エンドポイントを使用したい場合は、プライベート・ネットワークとの VPN 接続が必要です。

API 基本概念

サービス

サービスとは、内部 SoftLayer システムに関連付けられているエンドポイントです。各サービスは、実行できるメソッドまたはアクションの集合です。すべての SLAPI サービスのリストは、このサイトの Reference セクションにあります。
目的の API のサービス・セクションにアクセスした後、すべての使用可能なサービスのリストが、画面の左側に表示されます。すべての SoftLayer サービスは「SoftLayer_」で始まり、サービスが提供する一般的な機能を定義する追加の用語 (「Hardware」、「Account」、「Billing」、「Network」など) が含まれています。そこから、各サービスは、その特定のサブセット内のサービスの固有機能を定義する名前で拡張されます。SoftLayer API に関連付けられている各サービスには、固有の名前があります。SoftLayer_Account や SoftLayer_Account_Address などの一部のサービスは共通の接頭部を共用できますが、それらの対話は必ずしも同じではなく、同じような名前のサービスを直接継承することはありません。このため、各サービスには個々にアプローチする必要があります。
特定のサービスの詳細を表示するには、サービス名をクリックします。各サービスのページには、そのサービスに使用可能なメソッドのリストが含まれ、そのサービスを説明する簡単な概要も含まれている場合があります。各サービスは固有のメソッドの集合を提供しますが、多くのサービスは getObject メソッドを提供します。これらのメソッドは、同じタイプのオブジェクトを API から取得するのに使用できます。例えば、SoftLayer_Network_Subnet サービスで getObject メソッドを呼び出すと、SoftLayer_Network_Subnet データ・タイプ・オブジェクトが戻されます。

メソッド

メソッドとは、SLAPI サービスに対して実行できる特定のアクションです。各メソッドは、スカラー・データ・タイプまたは構造化データ・タイプを戻し、実行するのに特定のパラメーター、許可、またはヘッダーが必要な場合があります。メソッド・パラメーターは、各言語またはエンドポイントの資料で説明されている手法を使用して渡されなければなりません。複数のパラメーターが必要な状況では、メソッド・ページに表示される順に、上から下にパラメーターを渡してください。以下のスクリーン・ショットは、SoftLayer_Monitoring_Agent::getGraph メソッドに必要なパラメーターを表示しています。このメソッドを実行する場合は、configurationValues、beginDate、endDate の順にパラメーターを渡してください。
NOT FOUND: parameters.png
各メソッド・ページで、パラメーター、許可、およびヘッダーの詳細なリストが入手できます。

データ・タイプ

データ・タイプとは、スカラー値とその他のデータ・タイプの集合を含む構造です。ストリング、ブールまたは int などの従来のスカラー値に加えて、SLAPI は、SLAPI でメソッドに渡され、メソッドによって戻されるオブジェクトを定義するプロパティーを含む、複合データ・タイプも使用します。各データ・タイプには、複数のローカルリレーショナル、およびカウント・プロパティーが入っている場合があります。

ローカル・プロパティー

ローカル・プロパティーは、データ・タイプの直接の子です。ローカル・プロパティーは通常、getObject() が呼び出されるときに戻されます。createObject() の呼び出し時にこのデータ・タイプのインスタンスを作成する場合、全部ではないとしても、一部のローカル・プロパティーが必要です。

リレーショナル・プロパティー

リレーショナル・プロパティーは、データ・タイプの間接の子です。リレーショナル・プロパティーは、他のデータ・タイプまたはそれらのプロパティーで定義されます。例えば、SoftLayer_Account データ・タイプには、ハードウェアのリレーショナル・プロパティーがあります。このリレーショナル・プロパティーは、SoftLayer_Hardware データ・タイプのアレイです。このプロパティーは、オブジェクト・マスクと一緒に利用すると、アカウントのハードウェア・デバイスごとに SoftLayer_Hardware オブジェクトを含むアレイを戻します。

カウント・プロパティー

カウント・プロパティーは、プロパティーに関連付けられているオブジェクトの総数を判別するのに使用できる便利なプロパティーです。例えば、組み込まれている Softlayer_Hardware_Server->networkVlanCount と一緒にオブジェクト・マスクを使用すると、特定のサーバーに関連付けられている VLAN の総数を取得することができます。

API 上級概念

標準的な作成、読み取り、更新、および削除アクションの他に、SLAPI では、開発者は、特殊な API 呼び出しヘッダーを使用して各呼び出しからデータが戻される方法を定義することができます。これらのヘッダーでは、API によって戻されるデータ量の制御を強化することができます。

結果制限

結果制限とは、戻されるオブジェクトのオフセットと量を定義できるようにするサポート・メソッドです。これにより、ラージ・データ・セットのページ編集が可能になります。

オブジェクト・マスク

オブジェクト・マスクを使用すると、ユーザーは、メソッドから戻されるローカル・プロパティーを指定し、リレーショナル・プロパティーとカウント・プロパティーの両方で見つかる情報を取得することができます。マップ、すなわち ìmaskî は、戻り値に含まれる特定のデータを定義するために作成されます。例えば、SoftLayer_Hardware_Server::getObject を呼び出すときに ìnetworkVlans.idî にオブジェクト・マスクを指定することによって、SoftLayer_Hardware_Server で VLAN ごとの ID を収集することが可能です。

SLAPI に習熟する方法の 1 つは、オブジェクト・マスクをナビゲートして目的の結果を実現することです。たいていの場合、特定のデータ・ポイントに到達するには複数の方法があり、方法によって効率が異なる場合があります。

その他の参照先

基本の知識を習得したので、次はコーディングを開始します。「Getting Started Guide」を調べて、API ユーザーを作成して最初の呼び出しを行う方法を確認してください。また、以下の特定の言語用に複数のガイドも用意しています。

その他の役立つリンク: