はじめに

この記事は、以下の記事の続きです。
http://qiita.com/testnin2/items/f04ca0cee9b2f0a8f830

Step2 - 特定のlocal propertyを取得する

step2.py

import SoftLayer
import pprint
pp = pprint.PrettyPrinter(indent=4)
client = SoftLayer.create_client_from_env()
acct = client['Account'].getObject(mask='id, firstName, lastName, email')
pp.pprint(acct)

前回の例では、local propertyに対するmask指定がなかったため、local propertyの全てが取得されていました。client['XXXXXX'].method()が返すデータ型オブジェクトのpropertyのうち、特定のpropertyのみを取得する際には、methodの引数にmaskを引数として渡します。この例だと、id, firstName, lastName, emailのみが取得されます。

実行結果
# python step2.py
{   'email': 'xxxxx@xxxxx',
    'firstName': 'Shinobu',
    'id': xxxxx,
    'lastName': 'Yasuda'}

Step3 - 特定のlocal propertyや、relational property/count propertyを取得する

step3.py

import SoftLayer
import pprint
pp = pprint.PrettyPrinter(indent=4)
client = SoftLayer.create_client_from_env()
acct = client['Account'].getObject(mask='id, virtualGuests, virtualGuestCount')
pp.pprint(acct)

Step2では、**"localプロパティの一部"を出力していましたが、maskの指定はlocalプロパティだけに限るものではありません。実は、「ルール4: オブジェクトのpropertyを指定する時にはmask値を使用する。local propertyだけでなく、relational propertyやcount propertyであっても、mask値を指定すれば取得可能」**です。
client['Account'].getObject()の返り値はAccountデータ型オブジェクトでした。ということは、maskを指定することでAccountデータ型オブジェクトに属するlocal property, relational property, count propertyを自由に指定することができます。この例では、idはlocal propertyですが、virtualGuestsはrelational propertyですし、virtualGuestCountはcount propertyです。

実行結果
# python step3.py
[root@sing articles]# python test3.py
{   'id': 319556,
    'virtualGuestCount': 50,
    'virtualGuests': [   {   'accountId': xxxxxx,
                             'createDate': '2014-11-10T23:33:36-06:00',
                             'dedicatedAccountHostOnlyFlag': False,
                             'domain': 'example.com',
                             'fullyQualifiedDomainName': 'xxx.example.com',
                             'globalIdentifier': 'xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx',
                             'hostname': 'xxxxx',
                             'id': xxxxxxx,
                             'lastPowerStateId': '',
                             'lastVerifiedDate': '',
                             'maxCpu': 1,
                             'maxCpuUnits': 'CORE',
                             'maxMemory': 2048,
                             'metricPollDate': '',
                             'modifyDate': '2014-12-24T04:22:01-06:00',
                             'primaryBackendIpAddress': '10.xx.xx.xx',
                             'primaryIpAddress': '119.xx.xx.xx',
                             'startCpus': 1,
                             'status': {   'keyName': 'ACTIVE',
                                           'name': 'Active'},
                             'statusId': 1001,
                             'uuid': 'xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx'},
（途中略）

Step4 - クイズ：どっちがたくさん出力されていますか？

先ほどの解説で、何も指定がない限りは、objectの
acct = client['Account'].getObject(mask='id, virtualGuests')
と
acct = client['Account'].getObject(mask='virtualGuests')
の出力結果を比較してみてください。どっちがたくさん出力されていますか？
・
・
・
・
・
もちろん（！？）後者です。後者には、Accountデータ型オブジェクトのpropertyが全て出力されていると思います。
もう一度前回のルール3を読み直してみてください。前者はlocal propertyとしてidを指定しているので、Accountオブジェクトのうちidのみを出力します。後者はlocal propertyに対して何も指定していないのですから、Accountオブジェクトのlocal propertyが全て出力されます。

Step5 getObject()以外のmethodにおけるmask設定

今まで、getObject()を唯一のmethodとして取り上げて来ましたが、当然他のmethodでもmaskの指定はできます。重要なのはmethodで取得したデータ型オブジェクトのどのpropertyを取得するのかをmask値で指定するということです。
今までの例ではgetObject()の取得値がAccountデータ型オブジェクトだったため、Accountのlocal property/relational property/count propertyをmask値で指定してきましたが、
vgs = client['Account'].getVirtualGuests(mask='id, datacenter')
のような書き方も問題ありません。この場合、getVirtualGuests()がvirtualGuestデータ型オブジェクトを返すので、virtualGuestのproperyをmask値で指定(idはlocal property、datacenterはrelational property）しているのですね。

step5.py

[root@sing gomi2]# cat step5.py
import SoftLayer
import pprint
pp = pprint.PrettyPrinter(indent=4)
client = SoftLayer.create_client_from_env()
vgs = client['Account'].getVirtualGuests(mask='id, datacenter')
pp.pprint(vgs)

実行結果
# python step5.py
[   {   'datacenter': {   'id': 449604, 'longName': 'Tokyo 2', 'name': 'tok02'},
        'id': xxxxxxx},

    {   'datacenter': {   'id': 138124, 'longName': 'Dallas 5', 'name': 'dal05'},
        'id': xxxxxxx},
（以下略）

続きは次回！