クラウド API (CAPI)

  • リリースバージョン: Xanadu
  • 更新日 2024年08月01日
  • 所要時間：10分

    • クラウド API (CAPI) を使用すると、REST API を使用して クラウドプロビジョニングとガバナンス をクラウドプロバイダとデータ連携できます。

    CAPI コンポーネント

    クラウドプロバイダとのデータ連携は、PUT、GET、POST、DELETE などの REST 呼び出しを使用して実行されます。CAPI は、クラウドベンダー REST API をデータ連携するためのフレームワークを提供し、インスタンスがクラウドプロバイダと通信してクラウドリソースを管理できるようにします。

    詳細については、「https://docs.servicenow.com/bundle/xanadu-api-reference/page/build/applications/concept/api-product-type.html」を参照してください。

    CAPI には、次のコンポーネントが含まれています。
    図 : 1. CAPI の概要
    CAPI の概要
    プロバイダ

    クラウドプロバイダは、接続できるクラウドです。クラウドプロビジョニングとガバナンス にはデフォルトで、AWS、Azure、VMware など、最も一般的に使用されるプロバイダが含まれています。各プロバイダには多くの製品があり、そのそれぞれにリソースタイプが用意されています。各リソースタイプは、1 つの CI タイプにマップされます。たとえば、AWS providerには AWS Elastic Compute Cloud 製品が含まれ、これには AWS::EC2::Instance リソースタイプが含まれます。このリソースタイプは、作成が可能な最も一般的なクラウドリソースの 1 つです。仮想マシンインスタンス [cmdb_ci_vm_instance] CI タイプに直接マップされ、そこで仮想マシンが CMDB に保存されます。

    インターフェイス

    インターフェイスは、クラウドプロバイダ API が想定する REST 呼び出しをシステムがビルドするために必要なフレームワークを定義します。インターフェイスは操作 (メソッドとも呼ばれる) と、各メソッドに必要なパラメーターを定義します。

    インターフェイスは再利用可能です。新しい製品と API を含むように CAPI を拡張する場合は、既存のインターフェイスを使用して同じ REST 呼び出しを行うことができます。

    API 一覧

    CAPI API は、製品とインターフェイスを結び付ける CAPI のコアコンポーネントです。API には、システムが実行する実際のコードが含まれます。

    各 CAPI API には、次のコンポーネントが含まれています。
    • CAPI メソッドマッパーは、インターフェイスで定義された操作にマップされるメソッドを提供します。CAPI メソッドマッパーから、JavaScript で MID サーバー スクリプトインクルードを作成して、クラウドプロバイダに何をすべきかを正確に指示します。クラウドプロバイダへの接続は、スクリプトインクルードを介して行われます。
      注:
      カスタム CAPI API を作成する場合、システムに用意された空のスクリプトインクルードをカスタマイズできます。必要に応じて、メソッドマッパーの既存のスクリプトインクルードを変更することもできます。ただし、クラウドプロビジョニングとガバナンス アプリケーションに付属しているデフォルトの API の多くは、変更可能なスクリプトインクルードを使用しません。接続は Java でハードコーディングされています。作成した新しいリソースブロックでは、これらの API を引き続き使用できますが、API を変更することはできません。
    • API 構成のオーバーライドには、キーなどの ID、秘密キーなどの認証情報、およびクラウドプロバイダが必要とするその他の重要なパラメーターが含まれます。これらのパラメーターは、クラウドプロバイダが [CAPI メソッドマッパー] 関連リストの操作を実行するのに役立ちます。API 構成のオーバーライドが必要なのは、システムが REST を介してクラウドプロバイダ API を呼び出すときに認証情報データが含まれないためです。リソースブロックは、API 構成オーバーライドで定義したパラメーターと値を使用して、認証情報ストアをクエリーします。API が実行されると、スクリプトインクルード内のすべてのメソッド呼び出しで属性が使用可能になります。

      オーバーライドのスコープ対象はこの API のみです。オーバーライドでは、他の API の何も上書きしません。

    複数のバージョンの CAPI API をわずかなバリエーションで定義できるため、必要な機能を維持したまま既存の API を (上書きせずに) 拡張できます。

    次の図は、クラウドプロビジョニングとガバナンス で提供されるデフォルトの CAPI 設定を使用して Azure 仮想マシンをプロビジョニングするときに使用される CAPI のコンポーネントを示しています。
    図 : 2. CAPI Azure
    CAPI Azure

    この例では、Microsoft.Compute 製品は Azure プロバイダに含まれています。Azure は Microsoft.Compute 製品を仮想マシンに使用します。インスタンスでは、Microsoft.Compute 製品が、CMDB の Virtual Machine Instance CI タイプに関連付けられている Microsoft.Compute/virtualMachines リソースタイプにマップされます。

    Compute インターフェイスには、実際の仮想マシンの作成方法を定義する CreateNode などのメソッドの定義が含まれています。CreateNode が使用する多くのパラメーターのうち、Location は、仮想マシンが存在するデータセンターをキャプチャします。

    Azure Compute API は、Microsoft.Compute 製品、および Compute インタフェースで定義された構造をまとめます。CreateNode メソッドの実装は、AzureComputeVirtualMachine MID サーバー スクリプトインクルードを呼び出す azure-compute-1.0-CreateNode MID サーバー スクリプトインクルードを呼び出します。このスクリプトインクルードは、Azure API の実際の呼び出しを行います。Azure アカウントにアクセスするには、SecretKey、ClientID、TenantID、および他のメソッドが構成オーバーラードに渡されます。

    CAPI でインスタンスとデータ連携する方法

    CAPI は、インスタンスの次のコンポーネントをデータ連携します。
    クラウドプロビジョニングとガバナンス リソースブロック

    リソースブロックは、仮想サーバー、仮想サーバーストレージ、データセンターなどの単一のクラウドリソースを表します。CMDB の CI タイプと考えることもできます。多数のリソースブロックを詳細計画にまとめると、クラウドカタログのカタログアイテム (スタックとも呼ばれる) として、ユーザーに表示されます。

    システムでは、各リソースブロックは CAPI を参照するコンテナーのようなもので、クラウドプロバイダからの応答を特定の CI にリンクします。リソースブロックは次のものを使用します。
    • 各操作 (プロビジョニング操作など) のために CAPI を呼び出し、クラウドプロバイダが操作を実行するために必要なパラメーター値を渡す操作ステップ。
    • プロバイダからの REST 応答を処理および解析し、CMDB のレコードを更新する応答プロセッサー。
    CMDB

    各リソースブロックは、CMDB の CI タイプに基づいています。クラウドプロビジョニングとガバナンス では、クラウド関連のすべての CI タイプは、デフォルトでサポートされるすべてのクラウドリソースに必要なすべての属性を提供するVirtual Machine Object CI クラスに基づいています。クラウドリソースの CI タイプがベースシステムに存在しない場合は、新しい CI クラスを作成し、必要な属性を追加する必要があります。

    新しい CI クラスを作成する場合は、次のものも作成する必要があります。
    • ユーザーが使用できる各リソースの CI クラス。すべての CI クラスは、仮想マシンオブジェクトクラスに基づいています。
    • オブジェクト ID を指定する 識別ルール。クラウド管理 のコンポーネントが CMDB 内の特定のクラウドリソースを参照する場合は常に、適切なクラウドリソースを見つけるためにオブジェクト ID が必要です。
    • リソースの CI クラスが他の CI クラスとどのように関連するかを指定する関係性ルール。たとえば、virtual server CI は datacenter CI と Hosted on::Hosts の関係を持つ必要があります。これらの関係性ルールは、識別および調整エンジン (IRE) によって処理される場合に CI の一意性を確保するために必要です。サービスアカウント、リソースのオブジェクト ID、およびリソースが配置されているデータセンター (または場所) の組み合わせによって、一意性が決まります。
    MID サーバー スクリプトインクルード
    CAPI API の各操作には、MID サーバー スクリプトインクルードを構成して含めることができます。スクリプトインクルードは、システムの他のスクリプトインクルードにすでに含まれている JavaScript クラスや、作成した JavaScript クラスを呼び出します。最終的には、呼び出し元クラスが呼び出され、REST 呼び出しがトリガーされます。MID サーバー スクリプトインクルードは ServiceNow インスタンスで構成されますが、MID サーバー で実行されます。

    次の図は、ユーザーがリソースをクラウドユーザーポータルからプロビジョニングしたときに、コンポーネントがどのように連携するかを示しています。

    CAPI とインスタンス

    クラウドプロバイダへの REST 呼び出し

    クラウドプロバイダへの REST 呼び出しは、CAPI API レコード内のスクリプト化された CAPI メソッドマッパーから参照される MID サーバー スクリプトインクルードからトリガーされます。独自の CAPI API を作成したり、カスタム MID サーバー スクリプトインクルード (CAPI メソッドマッパーの一部である) を作成したりするには、次の内容を理解する必要があります。
    たとえば、Azure への REST 呼び出しを行ってリソースグループを作成する方法については、Azure のトピック「リソースグループ - 作成または更新」を参照してください。Azure が必要とするエンドポイント、パラメーター、および要求本文、ならびにそれらが提供する応答を見つけることができます。次のことがわかります。
    • エンドポイントが management.azure.com である
    • PUT 操作で呼び出すメソッドは、subscriptions/{subscriptionId}/resourcegroups/{resourceGroupName}?api-version=2018-02-01 である。ここでサブスクリプション ID、リソースグループ名、API バージョンを指定します。

    REST API 呼び出しは、CAPI API メソッドマッパーに関連付けられた MID サーバー スクリプトインクルード内で行われることに注意してください。CloudAPIBase および CloudRESTAPIInvoker から拡張されたクラスを使用して、CAPI ですでに使用可能になっているメソッドを呼び出します。また、これらの基底クラスを拡張し、独自のクラスを作成するために、さらにスクリプトインクルードを作成することもできます。これらの基底クラスと、その中で使用できるメソッドについて理解してください。

    使用を開始する方法

    1. で提供されている CAPI API を確認する クラウドプロビジョニングとガバナンス デフォルトでは.
    2. デフォルトで提供されている CAPI クラスを確認します。これらのクラスは、CAPI API 操作の MID サーバー スクリプトインクルードから呼び出すことができます。
    3. Azure 仮想マシンと AWS 仮想マシンのプロビジョニングのウォークスルーにより、コンポーネントがどのように連携するかを確認します。Azure のウォークスルーでは、MID サーバー スクリプトインクルードを使用するので、プロビジョニング操作で使用されるさまざまな CAPI クラスを確認できます。AWS のウォークスルーでは、MID サーバー スクリプトインクルードは使用しません。
    4. CAPI の既存のプロバイダーに製品を追加する。
    5. 仮想クラウドリソースの CI クラスを作成する。
    6. CAPI インターフェイスを作成または拡張する。
    7. CAPI API を作成する、クラウドプロバイダへの REST 呼び出しを行うカスタム MID サーバー スクリプトインクルードを作成します。新しい CAPI API には、常に空の MID サーバー スクリプトインクルードが生成されます。このスクリプトインクルードを、他の JavaScript クラスやメソッド (Invoker クラスのメソッドなど) への呼び出しを使用して変更します。