Oracle Cloud Infrastructure REST APIをリクエストしてみた vol.4:サービス詳細編

皆さんこんにちは。近所でエナジードリンクとコーヒーが80~100円の金額でセールをしていて思わず買い溜めしてしまったid:k-furusawa--dです。カフェインの摂りすぎには注意しましょう。

今回はREST APIを呼び出してみよう第四弾ということで、オラクルサービスの詳細を取得するちょっと風変わりなやつを呼び出してみようと思います。

API名は ServiceProduct と言います。MyServiceAPIの一部なのですが、なんとドキュメントが存在しません! 怖いですね。privateなAPIかと思ったのですが、別にそういうわけでもなく普通に呼び出し可能です。ちなみにprivateなAPIはURI中にprivateとストレートに記載されていたりします。分かりやすくていいと思います。

ドキュメントがないので紹介が書きにくいことこの上ないのですが、呼び出しURIがMyServiceAPIと同等なのでMyServiceAPIのドキュメントを張っておきます。

docs.cloud.oracle.com

本記事の目次

ServiceProduct とは

この ServiceProduct ですがサービスの詳細な情報を取得することができるAPIです。

サービスの詳細というのは、例えば単価であったり表示名であったり略名であったりします。分かりやすいのはOCIの料金計算画面ですね。

f:id:k-furusawa--g:20190711145112j:plain
料金表

ここでのMFやPayGの単価表示や、サービス名リソース名の表示を提供してくれるAPIです。

やろうと思えばExcel内で呼び出して自分だけの料金計算表が作れちゃったりしそうですね!

基本URI

呼び出しの基本URIです。2種類あります。

サービス詳細一覧取得

サービスの一覧を返してくれるAPIです。表示名や短縮名などに加え、単価やレートが返ります。

curl -X GET \
  -H 'Authorization: Basic ay5m.....' \
  -H 'Content-Type: application/json' \
  -H 'X-ID-TENANT-NAME: {IdentityServiceId}' \
  -H 'X-Oracle-Accept-CurrencyCode: JPY' \
 'https://itra.oraclecloud.com/itas/{tenantName}/myservices/api/v1/products'
サービスプリセット一覧取得

サービスのプリセット一覧を返してくれるAPIです。単価やレートは返りませんが説明や詳細なカテゴリ情報、言語別文言などが返ります。

curl -X GET \
  -H 'Authorization: Basic ay5m.....' \
  -H 'Content-Type: application/json' \
  -H 'X-ID-TENANT-NAME: {IdentityServiceId}' \
  -H 'Referer: https://cloud.oracle.com/ja_JP/cost-estimator' \
  -H 'Accept-Language: ja,en'
 'https://itra.oraclecloud.com/itas/{tenantName}/myservices/api/v1/productPresets'

基本的なURIは他のMyServiceAPIと同じです。tenantname は実は正確でなくても動きます。試しにaaaa などを入力しても動くので、IdentityServiceId だけちゃんと入力してください。

IdentityServiceId の調べ方は記事にしてあるので、そちらをご参照ください。

OCIの複雑なIDとそのほか設定値を確認する方法【決定版を目指す】 - Cloudii blog

リクエスト設定について

リクエスト時の設定についてご説明します。

  • レートを変える

    ヘッダに以下の指定を行うと円やドルといった単価のレートを変更できます。

    X-Oracle-Accept-CurrencyCode:JPY

    JPY で日本円、USD でアメリカドルです。デフォルトは USD です。

  • サービスを絞る

    partNumber パラメータで取得するサービスを絞ることが可能です。

    partNumber パラメータに取得したいサービスのGSIProductIdを指定します。GSIProductId と聞いてピンときたあなたは私と同じくMeteringAPIに悩まされた人ですね?

    GSIProductId はMeteringAPIのレスポンス内に含まれているパラメータの一つです。なのでコスト画面でも確認が可能です。GSIProductId はOCI上での各サービスに割り当てられている製品番号のようなものです。Part番号というようです。以下のPDFが詳しいです。

    http://www.oracle.com/us/corporate/contracts/paas-iaas-universal-credits-3940775.pdf

  • 親サービスで絞る

    parentProductPartNumber (サービスプリセットの場合は presetItemProductParentProductPartNumbers)パラメータでサービス単体で絞る以外にも、親サービスで絞ることが可能です。例えば、 PaaSおよびIaaSを示す B88206 というIDを指定すると、それに属するすべてのサービスの詳細を取得できるようになります。今のところB88206以外に親として指定できる製品番号を見つけられていません。ほかの番号を知っている方がいらっしゃれば教えてください!

    注意点として、このパラメータにサービス単体のGSIProductIdを指定しても、BadRequestか空の配列が返ります。飽くまでも配下の情報を返すだけになるようです。

  • 言語設定を変える

    デフォルトでは英語ですが、ヘッダ設定で日本語のサービス詳細を取得できます。以下の2ヘッダを追加してください。

    Accept-Language:jp

    Referer:https://cloud.oracle.com/ja_JP/cost-estimator

    英語と日本語を両方で取得したい場合は、Accept-Language:jp,en と指定します。レスポンスの項でも説明しますが、複数取れる場合は languageLocalizations に配列で格納されて返却されます。ちなみに Accept-Language:en,ja と順番を逆に指定すると英語が優先されてしまうので注意してください。

レスポンスについて

実行すると返ってくるレスポンス内容について、重要な部分のみご説明します。

  • partNumber

    サービスを特定するためのIDです。リクエストパラメータにも指定可能です。MeteringAPI実行時にレスポンスパラメータに含まれている GSIProductId と同一のものです。

  • currencyCode

    レートです。ヘッダで指定したものが返ります。指定なしだとデフォルトで USD となります。

  • description

    サービスの簡単な説明です。詳細な説明が含まれてることもあります。

  • displayName

    サービスの表示名です。OCIのコスト画面で表示されているものと似ていますが違います。ここにも GSIProductId が先頭に含まれています。

  • shortDisplayName

    短縮名称です。料金画面ではこちらが利用されているようです。

  • metricDisplayName(サービス詳細取得のみ)

    料金の単価表示です。OCPU Per Hour といった内容が返ります。

  • serviceCategoryDisplayName(サービス詳細取得のみ)

    サービス詳細のカテゴリ名です。例えば、Oracle CASB for IaaS のサービス情報を取得すると、ここには Cloud Access Security Broker - IaaS と入ります。

  • prices(サービス詳細取得のみ)

    単価情報です。大体のサービスは PAY_AS_YOU_GOMONTHLY_COMMIT の2つの情報が入ります。

  • languageLocalizations(サービスプリセット取得のみ)

    言語別の詳細説明が入ります。言語設定を複数にすると、こちらに多言語での表示名や説明が入ります。英語が優先されるようでリクエスト時に英語を先に指定するとこの項目の中身もすべて英語になります。

  • categories(サービスプリセット取得のみ)

    カテゴリの詳細情報です。カテゴリの正式名称と表示名を返します。

実行例

実行例を示します。非常に長いので一部になります。

Compute-StandardE2-(B90425)のサービス詳細を取得する。

  • Request
GET -X GET \
  -H 'Authorization: Basic ay5....' \
  -H 'X-ID-TENANT-NAME: idcs-8f....' \
  -H 'Content-Type: application/json' \
  -H 'X-Oracle-Accept-CurrencyCode: JPY' \
  'https://itra.oraclecloud.com/itas/{tenantName}/myservices/api/v1/products?partNumber=B90425'
  • Response
{
    "items": [
        {
            "id": "12200",
            "partNumber": "B90425",
            "partInventoryItemId": "4269179",
            "language": "en",
            "currencyCode": "JPY",
            "displayName": "B90425 - Oracle Cloud Infrastructure - Compute - Standard - E2 - OCPU Per Hour",
            "shortDisplayName": "Compute - Standard - E2",
            "metricDisplayName": "OCPU Per Hour",
            "serviceCategoryDisplayName": "Compute",
            "serviceDefinition": {
                "id": "546989214",
                "canonicalLink": "/itas/atomitech/myservices/api/v1/serviceDefinitions/546989214"
            },
            "prices": [
                {
                    "model": "PAY_AS_YOU_GO",
                    "value": 3.6
                },
                {
                    "model": "MONTHLY_COMMIT",
                    "value": 3.6
                }
            ],
            "languageLocalizations": [
                {
                    "language": "en",
                    "displayName": "B90425 - Oracle Cloud Infrastructure - Compute - Standard - E2 - OCPU Per Hour",
                    "shortDisplayName": "Compute - Standard - E2",
                    "metricDisplayName": "OCPU Per Hour",
                    "serviceCategoryDisplayName": "Compute"
                }
            ],
            "canonicalLink": "/itas/atomitech/myservices/api/v1/products/12200"
        }
    ],
    "canonicalLink": "/itas/atomitech/myservices/api/v1/products",
    "hasMore": false,
    "limit": 25,
    "offset": 0
}

Oracle PaaS および LaaS(B88206)のサービスプリセットを取得する。

  • Request
GET -X GET \
  -H 'Authorization: Basic ay5....' \
  -H 'X-ID-TENANT-NAME: idcs-8f....' \
  -H 'Content-Type: application/json' \
  -H 'X-Oracle-Accept-CurrencyCode: JPY' \
  -H 'Accept-Language: ja,en' \
  -H 'Referer: https://cloud.oracle.com/ja_JP/cost-estimator' \
  'https://itra.oraclecloud.com/itas/{tenantName}/myservices/api/v1/productPresets?presetItemProductParentProductPartNumbers=B88206&limit=200'
  • Response
{
    "items": [
        {
            "id": "10453",
            "weight": 760,
            "name": "APP_CONT_V1",
            "language": "ja",
            "displayName": "Oracle Application Container Cloud Service",
            "description": "軽量でクラウドネイティブな、あらゆる言語のアプリケーションの初期環境",
            "status": "AVAILABLE",
            "languageLocalizations": [
                {
                    "language": "en",
                    "displayName": "Oracle Application Container Cloud Service",
                    "description": "Starter environment for lightweight cloud-native application in any language"
                }
            ],
            "categories": [
                {
                    "id": "10251",
                    "name": "APPLICATION_DEVELOPMENT_V1",
                    "displayName": "アプリケーション開発",
                    "canonicalLink": "/itas/atomitech/myservices/api/v1/productPresetCategories/10251"
                }
            ],
            "presetItems": [
                {
                    "quantity": 200,
                    "minQuantity": 0,
                    "weight": 100,
                    "product": {
                        "id": "10150",
                        "partNumber": "B88285",
                        "displayName": "B88285 - Oracle Cloud Infrastructure - Object Storage Classic - ギガバイト・ストレージ容量/月",
                        "shortDisplayName": "オブジェクト・ストレージ",
                        "parentProducts": [
                            {
                                "id": "10052",
                                "partNumber": "B88206",
                                "canonicalLink": "/itas/atomitech/myservices/api/v1/products/10052"
                            }
                        ],
                        "canonicalLink": "/itas/atomitech/myservices/api/v1/products/10150"
                    }
                },
                {
                    "quantity": 1,
                    "minQuantity": 0,
                    "weight": 100,
                    "product": {
                        "id": "10021",
                        "partNumber": "B88283",
                        "displayName": "B88283 - Oracle Cloud Infrastructure - Object Storage Classic - GETおよびその他のリクエスト - 10,000リクエスト/月",
                        "shortDisplayName": "オブジェクト・ストレージ - GETおよびその他のリクエスト",
                        "parentProducts": [
                            {
                                "id": "10052",
                                "partNumber": "B88206",
                                "canonicalLink": "/itas/atomitech/myservices/api/v1/products/10052"
                            }
                        ],
                        "canonicalLink": "/itas/atomitech/myservices/api/v1/products/10021"
                    }
                },
                {
                    "quantity": 1,
                    "minQuantity": 0,
                    "weight": 100,
                    "product": {
                        "id": "10083",
                        "partNumber": "B88284",
                        "displayName": "B88284 - Oracle Cloud Infrastructure - Object Storage Classic - PUT、COPY、POSTまたはLISTリクエスト - 1,000リクエスト/月",
                        "shortDisplayName": "オブジェクト・ストレージ - PUT、COPY、POSTまたはLISTリクエスト",
                        "parentProducts": [
                            {
                                "id": "10052",
                                "partNumber": "B88206",
                                "canonicalLink": "/itas/atomitech/myservices/api/v1/products/10052"
                            }
                        ],
                        "canonicalLink": "/itas/atomitech/myservices/api/v1/products/10083"
                    }
                },
                {
                    "quantity": 2,
                    "minQuantity": 0,
                    "weight": 100,
                    "product": {
                        "id": "10070",
                        "partNumber": "B88305",
                        "displayName": "B88305 - Oracle Application Container Cloud Service - ギガバイト・メモリー/時間",
                        "shortDisplayName": "Standard",
                        "parentProducts": [
                            {
                                "id": "10052",
                                "partNumber": "B88206",
                                "canonicalLink": "/itas/atomitech/myservices/api/v1/products/10052"
                            }
                        ],
                        "canonicalLink": "/itas/atomitech/myservices/api/v1/products/10070"
                    }
                }
            ],
            "createdOn": "2017-12-01T14:28:06.810Z",
            "modifiedOn": "2019-06-26T17:16:42.206Z",
            "canonicalLink": "/itas/atomitech/myservices/api/v1/productPresets/10453"
        },
        {
            "id": "10454",
            "weight": 870,
            "name": "DB_BIGDATA_STR_V1",
            "language": "ja",
            "displayName": "Oracle Big Data Cloud Service ",
            "description": "Hadoop、SparkおよびKafkaの包括的サービスには、統計、グラフ、空間などの分析機能が含まれます。",
            "status": "AVAILABLE",
            "languageLocalizations": [
                {
                    "language": "en",
                    "displayName": "Oracle Big Data Cloud Service ",
                    "description": "Comprehensive Hadoop, Spark and Kafka Service, includes Statistical, Graph, Spatial and more analytical capabilities."
                }
            ],
            "categories": [
                {
                    "id": "10305",
                    "name": "DATA_MANAGEMENT_V1",
                    "displayName": "データ管理",
                    "canonicalLink": "/itas/atomitech/myservices/api/v1/productPresetCategories/10305"
                }
            ],
            "presetItems": [
                {
                    "quantity": 1,
                    "minQuantity": 0,
                    "weight": 100,
                    "product": {
                        "id": "10019",
                        "partNumber": "B88603",
                        "description": "ノード当たり32のOCPUを持つ、3つのノード。  \nノード当たり256GBのRAMおよび48TBのストレージ。  \nBig Data Connector (制限付きの使用を含む: Oracle Data Integrator Enterprise Edition)およびBig Data Spatial and Graph。",
                        "displayName": "B88603 - Oracle Big Data Cloud Service - スタータ・パック - 3ノード - ホストされる環境/時間",
                        "shortDisplayName": "スタータ・パック - 3ノード",
                        "parentProducts": [
                            {
                                "id": "10052",
                                "partNumber": "B88206",
                                "canonicalLink": "/itas/atomitech/myservices/api/v1/products/10052"
                            }
                        ],
                        "canonicalLink": "/itas/atomitech/myservices/api/v1/products/10019"
                    }
                },
                {
                    "quantity": 0,
                    "minQuantity": 0,
                    "weight": 100,
                    "product": {
                        "id": "10110",
                        "partNumber": "B88604",
                        "description": "ノード当たり32のOCPUを持つ、1つのノード。  \nノード当たり256GBのRAMおよび48TBのストレージ。  \nBig Data Connector (制限付きの使用を含む: Oracle Data Integrator Enterprise Edition)およびBig Data Spatial and Graph。",
                        "displayName": "B88604 - Oracle Big Data Cloud Service - 追加ノード - ホストされるノード/時間",
                        "shortDisplayName": "追加ノード",
                        "parentProducts": [
                            {
                                "id": "10052",
                                "partNumber": "B88206",
                                "canonicalLink": "/itas/atomitech/myservices/api/v1/products/10052"
                            }
                        ],
                        "canonicalLink": "/itas/atomitech/myservices/api/v1/products/10110"
                    }
                }
            ],
            "createdOn": "2017-12-01T14:28:07.043Z",
            "modifiedOn": "2019-06-26T17:16:57.380Z",
            "canonicalLink": "/itas/atomitech/myservices/api/v1/productPresets/10454"
        },

以下略

おしまいに

ドキュメントには存在しないAPIですが、なかなかに面白い情報を返してくれるAPIだと思います。

本来であればこの情報とUsageReportの利用情報を組み合わせてコスト計算などを行うのが定石なのですが、UsageReportの記事にも書かせていただいたように、UsageReport側にサービスIDなどが割り振られていないので、実際にはかなり難しいです。

せっかく存在するAPIなのですから、もっと有効活用したいですね。

次回も何か変わったREST APIのご紹介ができればいいと思います。