Object Store v2 REST API

Object Store v2 API により、REST を使用して次の操作を実行できます。

  • アプリケーションに関連付けられたオブジェクトストアとキーのリストを取得する。

  • オブジェクトストアでキー-値ペアを保存して取得する。

  • オブジェクトストアからキー-値ペアを削除する。

  • 組織の Object Store の使用量統計を取得する。

Object Store には次の API が用意されています。

Object Store API を使用した認証

  • [Object Store API]

    Object Store API を使用して認証するにはベアラートークンが必要です。 ベアラートークンを取得するには、アプリケーションのクライアント ID とクライアントシークレットが必要です。

  • Object Store Stats API

    Object Store Stats API を使用して認証するにはアクセストークンが必要です。 アクセストークンを取得するには、​組織のシステム管理者​ロールが割り当てられたユーザの Anypoint Platform ユーザ名とパスワードが必要です。

前提条件

  • Object Store v2 を使用するアプリケーションを作成し、CloudHub にデプロイします。

    「CloudHub へのデプロイ」​を参照してください。

  • オブジェクトストアにキー-値ペアを保存します。

  • Anypoint Platform ユーザのアクセストークン (​ACCESS_TOKEN​) を取得します。

    Object Store Stats API にアクセスするには、ユーザに​組織のシステム管理者​ロールが割り当てられている必要があります。

    Object Store Stats API を使用して認証するにはアクセストークンが必要です。

    「アクセス管理 API」​の 「認証」​を参照してください。

  • 組織 ID (​ORG_ID​) を取得します。

    Object Store API および Object Store Stats API を使用した操作には組織 ID が必要です。

    「アクセス管理 API」​の ​/api/me​ エンドポイントを参照してください。

  • 環境 ID (​ENV_ID​) を取得します。

    Object Store API および Object Store Stats API を使用した操作には環境 ID が必要です。

    「アクセス管理 API」​の ​/api/organizations/ORG_ID/environments​ エンドポイントを参照してください。

  • アプリケーションのクライアント ID (​CLIENT_ID​) とクライアントシークレット (​CLIENT_SECRET​) を取得します。

    ベアラートークンを取得するにはクライアント ID とクライアントシークレットが必要です。

  • アプリケーションのベアラートークン (​BEARER_TOKEN​) を取得します。

    Object Store API を使用して認証するにはベアラートークンが必要です。

    「アクセス管理 API」​の ​/accounts/oauth2/token​ エンドポイントを参照してください。

    ベアラートークンを取得するには、アプリケーションのクライアント ID とクライアントシークレットが必要です。

アプリケーションのクライアント ID とクライアントシークレットを取得する

アプリケーションのクライアント ID とクライアントシークレットを取得する手順は、次のとおりです。

  1. [Anypoint Platform] > [Runtime Manager]​ にログインします。

  2. アプリケーションをクリックし、​[Manage Application (アプリケーションを管理)]​ をクリックします。

  3. アプリケーションが Object Store に関連付けられていない場合、​[Use Object Store v2 (Object Store v2 を使用)]​ をクリックして変更を適用します。

  4. 左ナビゲーション領域の ​[Object Store]​ をクリックし、​[Show Client Credentials (クライアントのログイン情報を表示)]​ をクリックします。

  5. [Client ID (クライアント ID)]​ の ​[Copy to Clipboard (クリップボードにコピー)]​ をクリックして ​CLIENT_ID​ の値として保存します。

  6. [Client Secret (クライアントシークレット)]​ の ​[Copy to Clipboard (クリップボードにコピー)]​ をクリックして ​CLIENT_SECRET​ の値として保存します。

Object Store に関する API

Object Store API で読み取りおよび書き込みを行う ​key,list​ 値は、​key,value​ 形式での読み取りおよび書き込みを行うオブジェクトストア用 Anypoint Connector (Object Store Connector) とは異なります。

次の表では、Object Store REST API 操作を Object Store Connector 操作と比較しています。

Object Store v2 API Object Store v2 REST API 操作 Object Store Connector 操作

POST

  • オブジェクトストア

    • オブジェクトストアの TTL (秒)

      最大 TTL は 2,592,000 秒 (30 日) です。

      指定された ​entryTtl​ 値が 30 日より大きい場合、値のデフォルトは 2592000 秒 (30 日) になり、エラーは返されません。

    • 永続性プロパティ

    • アプリケーションまたは環境ごとの使用制限。キーまたはサイズに基づいて制限するオプションやその適用方法を含みます

  • キーおよびリスト (項目) 値

Store (保存)

GET

  • Get keys (キーを取得)

  • Get item (項目を取得)

  • Get items (複数の項目を取得)

  • Get all items (すべての項目を取得)

  • Get regions for an organization (組織のリージョンを取得)

Contains (包含チェック) + Retrieve (取得) + Retrieve all keys (すべてのキーを取得) + Retrieve and store (取得して保存) (Retrieve 部分)

PUT

  • Put item as string (項目を文字列として更新)

  • Put item as number (項目を数値として更新)

  • Put item as confirmable string (項目を確認可能な文字列として更新)

  • Put store (更新して保存)

Dual Store (2 段階保存) ​​ + Store (保存)

DELETE

  • Remove object store (オブジェクトストアを削除)

  • Delete key (キーを削除)

  • Delete item (項目を削除)

Remove (削除)

​ Object Store Connector の Dual Store 操作は、キーで値を保存する操作と、その後に値でキーを保存する操作の 2 つで構成されます。 Dual Store 操作は、Object Store v2 で 2 つの「Put item as String」 (項目を文字列として更新) コールを実行して次の結果を得るのと同様に動作します。

  1. objectStore.store(key, value);

  2. objectStore.store(value, key);

1 回の GET 操作で最大 25 個のキーを取得できます。

制限事項

アプリケーションが REST インターフェースを使用してオブジェクトストアに書き込み、Mule 3 用 Object Store Connector を使用して同じキーから読み取る場合、この読み取りでは要素 0 の値しか取得できません。 そのため、REST API を使用する場合は、API を使用してオブジェクトストアの内容を読み書きします。 そうしないと、API を使用して書き込める先はインデックス 0 のみになります。

この制限は、Mule 4 用 Object Store Connector と Anypoint Studio Object Store Connector には適用されません。

Object Store API にアクセスする

  1. オブジェクトストアにアクセスするために、Postman などのアプリケーションをセットアップします。

  2. オブジェクトストアのアクセス URL を設定し、​ORG_ID​ を組織 ID に、 ENV_ID​ を環境 ID に置き換えます。

    BASE_URL/api/v1/organizations/ORG_ID/environments/ENV_ID/stores/myTestStoreId/objects

    デプロイメントリージョンに応じて、アクセス URL の ​BASE_URL​ の値では次のドメインのいずれかを使用できます。

    コントロールプレーン ​BASE_URL リージョン

    米国

    object-store-us-east-1.anypoint.mulesoft.com

    米国東部 (北バージニア)

    object-store-us-east-2.anypoint.mulesoft.com

    米国東部 (オハイオ)

    object-store-us-west-1.anypoint.mulesoft.com

    米国西部 (北カリフォルニア)

    object-store-us-west-2.anypoint.mulesoft.com

    米国西部 (オレゴン)

    object-store-ap-southeast-1.anypoint.mulesoft.com

    アジア太平洋 (シンガポール)

    object-store-ap-southeast-2.anypoint.mulesoft.com

    アジア太平洋 (シドニー)

    object-store-ap-northeast-1.anypoint.mulesoft.com

    アジア太平洋 (東京)

    object-store-ca-central-1.anypoint.mulesoft.com

    カナダ (中央部)

    object-store-eu-central-1.anypoint.mulesoft.com

    欧州 (フランクフルト)

    object-store-eu-west-1.anypoint.mulesoft.com

    欧州 (ロンドン)

    object-store-eu-west-2.anypoint.mulesoft.com

    欧州 (アイルランド)

    object-store-sa-east-1.anypoint.mulesoft.com

    南米 (サンパウロ)

    米国

    MuleSoft Government Cloud

    object-store-us-gov-west-1.gov.anypoint.mulesoft.com

    US Gov West (米国政府西部)

    EU

    object-store-eu-central-1.eu1.anypoint.mulesoft.com

    欧州 (フランクフルト)

    object-store-eu-west-1.eu1.anypoint.mulesoft.com

    欧州 (アイルランド)

  3. オブジェクトストアに対して値の保存や読み取りができるように、HTTP ヘッダーおよび本文でアプリケーションを設定します。

  4. 操作を Object Store API に送信します。

例: Object Store API

例: オブジェクトストアのリストを取得する

オブジェクトストアのリストを表示するには、次のような ​curl​ コマンドを送信し、​BASE_URL​ をリージョンのドメインに、​BEARER_TOKEN​ をベアラートークンに、​ORG_ID​ を組織 ID に、​ENV_ID​ を環境 ID に置き換えます。

curl -X GET \
-H 'authorization: bearer BEARER_TOKEN' \
'https://BASE_URL/api/v1/organizations/ORG_ID/environments/ENV_ID/stores'

このコマンドにより、次のような出力が返されます。

  {"values":[{"storeId":"APP_os-simple-flow__defaultPersistentObjectStore","encrypted":true,"permanentOsFlag":false,
    "persistent":true,"defaultTtlSeconds":2592000,"defaultConfirmationTtlSeconds":600,"isFixedTtl":null},
  {"storeId":"APP_scheduler-tests__defaultPersistentObjectStore","encrypted":true,"permanentOsFlag":false,
    "persistent":true,"defaultTtlSeconds":2592000,"defaultConfirmationTtlSeconds":600,"isFixedTtl":null}
  {"storeId":"APP_sending-a-csv-file-thru-email-using-smtp__defaultPersistentObjectStore","encrypted":true,"permanentOsFlag":false,
    "persistent":true,"defaultTtlSeconds":2592000,"defaultConfirmationTtlSeconds":600,"isFixedTtl":null}],"nextPageToken":null}

例: パーティションのリストを取得する

パーティションのリストを表示するには、次のような ​curl​ コマンドを送信し、​BASE_URL​ をリージョンのドメインに、​BEARER_TOKEN​ をベアラートークンに、​ORG_ID​ を組織 ID に、​ENV_ID​ を環境 ID に、​STORE_ID​ をオブジェクトストアリストの ​storeId​ に置き換えます。

curl -X GET \
  https://BASE_URL/api/v1/organizations/ORG_ID/environments/ENV_ID/stores/STORE_ID/partitions \
  -H "Authorization: Bearer ACCESS_TOKEN"

このコマンドにより、次のような出力が返されます。

  {"values":["PARTITION_ID"],"nextPageToken":null}

例: パーティションのキーのリストを取得する

パーティションのキーを表示するには、次のような ​curl​ コマンドを送信し、​BASE_URL​ をリージョンのドメインに、​BEARER_TOKEN​ をベアラートークンに、​ORG_ID​ を組織 ID に、​ENV_ID​ を環境 ID に、​STORE_ID​ をオブジェクトストアの名前に、PARTITION をパーティションの名前に置き換えます。

curl -X GET \
  https://BASE_URL/api/v1/organizations/ORG_ID/environments/ENV_ID/stores/STORE_ID/partitions/PARTITION_ID/keys \
  -H "Authorization: Bearer ACCESS_TOKEN"

このコマンドにより、次のような出力が返されます。

{"values":[{"keyId":"KeyTwo"},{"keyId":"KeyOne"}],"nextPageToken":null}

例: キーの値を取得する

キーの値を表示するには、次のような ​curl​ コマンドを送信し、​BASE_URL​ をリージョンのドメインに、​BEARER_TOKEN​ をベアラートークンに、​ORG_ID​ を組織 ID に、​ENV_ID​ を環境 ID に、​STORE_ID​ をオブジェクトストアの名前に、PARTITION をパーティションの名前に、​KEY_ID​ をキー ID に置き換えます。

curl -X GET \
  https://BASE_URL/api/v1/organizations/ORG_ID/environments/ENV_ID/stores/STORE_ID/partitions/PARTITION_ID/keys/KEY_ID \
  -H "Authorization: Bearer ACCESS_TOKEN"

このコマンドにより、次のような出力が返されます。

{"binaryValue":"++Kn0AIBAQBbwoABDiJLZXkgMiBWYWx1ZSL8rNmhAQEBAWphdmEuaW8uU2VyaWFsaXphYmzlgGFwcGxpY2F0aW9uL2pzb247IGNoYXJzZXQ9VVRGLbgAAAAAAAAADQ==","keyId":"KeyTwo","valueType":"BINARY"}

例: キー-値ペアを保存する

キー-値ペアを保存するには、次のような ​curl​ コマンドを送信し、​BASE_URL​ をリージョンのドメインに、​BEARER_TOKEN​ をベアラートークンに、​ORG_ID​ を組織 ID に、​ENV_ID​ を環境 ID に、​STORE_ID​ をオブジェクトストアの名前に、PARTITION をパーティションの名前に置き換えて、​KEY_ID​ の値を指定します。

KEY_ID=myTestKey; \
curl -X POST \
  https://BASE_URL/api/v1/organizations/ORG_ID/environments/ENV_ID/stores/STORE_ID/partitions/PARTITION_ID/keys/myTestKey \
  -H "Authorization: Bearer ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  --data '{"stringValue":"Hello World","keyId":"myTestKey","valueType":"STRING"}'

このコマンドでは、値は JSON 文字列になります。

キー-値ペアがオブジェクトストアにあることを確認するには、パーティションのキーのリストを取得します。

curl -X GET \
  https://BASE_URL/api/v1/organizations/ORG_ID/environments/ENV_ID/stores/STORE_ID/partitions/PARTITION_ID/keys \
  -H "Authorization: Bearer ACCESS_TOKEN"

このコマンドにより、次のような出力が返されます。

{"values":[{"keyId":"KeyTwo"},{"keyId":"KeyOne"},{"keyId":"myTestKey"}],"nextPageToken":null}

例: キーと値を削除する

キー-値ペアを削除するには、次のような ​curl​ コマンドを送信し、​BASE_URL​ をリージョンのドメインに、​BEARER_TOKEN​ をベアラートークンに、​ORG_ID​ を組織 ID に、​ENV_ID​ を環境 ID に、​STORE_ID​ をオブジェクトストアの名前に、PARTITION をパーティションの名前に、​KEY_ID​ をキー ID に置き換えます。

curl -X DELETE \
  https://BASE_URL/api/v1/organizations/ORG_ID/environments/ENV_ID/stores/STORE_ID/partitions/PARTITION_ID/keys/KEY_ID \
  -H "Authorization: Bearer ACCESS_TOKEN"

このコマンドでは、値は JSON 文字列になります。

キー-値ペアがオブジェクトストアからなくなったことを確認するには、パーティションのキーのリストを取得します。

curl -X GET \
  https://BASE_URL/api/v1/organizations/ORG_ID/environments/ENV_ID/stores/STORE_ID/partitions/PARTITION_ID/keys \
  -H "Authorization: Bearer ACCESS_TOKEN"

このコマンドにより、次のような出力が返されます。

{"values":[{"keyId":"KeyTwo"},{"keyId":"KeyOne"}],"nextPageToken":null}

Object Store Stats API

Object Store Stats API により、Object Store 使用量に関する統計を取得できます。

使用量統計はリアルタイムではなく、レイテンシが含まれている場合があります。

Stats API を使用して、請求目的で組織全体の Object Store の使用量を表示します。

  • マスタ組織とすべてのサブ組織ごとの使用量

  • 組織ごとの使用量

  • 環境ごとの使用量

Object Store Stats API にアクセスする

  1. オブジェクトストアにアクセスするために、Postman などのアプリケーションをセットアップします。

  2. アクセス URL を設定し、​ORG_ID​ を組織 ID に、 ENV_ID​ を環境 ID に置き換えます。

    https://object-store-stats.anypoint.mulesoft.com/api/v1/organizations/ORG_ID/environments/ENV_ID?startDate=...&endDate=...&period=...

  3. オブジェクトストアに対して値の保存や読み取りができるように、HTTP ヘッダーおよび本文でアプリケーションを設定します。

  4. 操作を Object Store Stats API に送信します。

例: Object Store Stats API

例: 組織ごとの使用状況メトリクスを取得する

デフォルトでは、Object Store Stats API エンドポイントでは、指定された ​ORG_ID​ の統計のみを取得します。 マスタ組織とすべてのサブ組織の使用量データを取得するには、​ORG_ID​ がマスタ組織の場合に ​isMaster​ を ​true​ に設定します。 isMaster=true​ を使用してサブ組織を照会した場合、エンドポイントでは結果は返されません。

2020 年 7 月 11 日から 2020 年 9 月 11 日までのマスタ組織とすべてのサブ組織の Object Store 使用量統計を表示するには、次のような ​curl​ コマンドを送信し、​ORG_ID​ をマスタ組織の組織 ID に、​BEARER_TOKEN​ をベアラートークンに置き換えます。

curl -X GET \
  'https://object-store-stats.anypoint.mulesoft.com/api/v1/organizations/ORG_ID?startDate=2020-07-11T17%3A51%3A54.000Z&endDate=2020-09-11T17%3A51%3A54.000Z&period=1month&isMaster=true' \
  -H 'authorization: Bearer BEARER_TOKEN'

この要求により、次のような応答が返されます。

[
 {"timeStamp":"2020-07-01T00:00:00Z","objectStoreRequestCount":0},
 {"timeStamp":"2020-08-01T00:00:00Z","objectStoreRequestCount":38},
 {"timeStamp":"2020-09-01T00:00:00Z","objectStoreRequestCount":28}
]

2021 年 2 月 10 日から 2021 年 4 月 10 日までのサブ組織の Object Store 使用量統計を表示するには、次のような ​curl​ コマンドを送信し、​ORG_ID​ をサブ組織の組織 ID に、​BEARER_TOKEN​ をベアラートークンに置き換えます。

curl -X GET \
  'https://object-store-stats.anypoint.mulesoft.com/api/v1/organizations/ORG_ID?startDate=2021-02-10T17%3A51%3A54.000Z&endDate=2021-04-10T17%3A51%3A54.000Z&period=1month' \
  -H 'authorization: Bearer BEARER_TOKEN'

この要求により、次のような応答が返されます。

[
 {"timeStamp":"2021-02-10T00:00:00Z","objectStoreRequestCount":1},
 {"timeStamp":"2021-03-10T00:00:00Z","objectStoreRequestCount":15},
 {"timeStamp":"2021-04-10T00:00:00Z","objectStoreRequestCount":2}
]

例: 環境別の使用状況メトリクスを取得する

2020 年 6 月 13 日から 2020 年 9 月 13 日までの環境の Object Store 使用量統計を表示するには、次のような ​curl​ コマンドを送信し、​ORG_ID​ を組織 ID に、​ENV_ID​ を環境 ID に、​BEARER_TOKEN​ をベアラートークンに置き換えます。

curl -X GET \
  'https://object-store-stats.anypoint.mulesoft.com/api/v1/organizations/ORG_ID/environments/ENV_ID?startDate=2020-06-13T17%3A51%3A54.000Z&endDate=2020-09-13T17%3A51%3A54.000Z&period=1month' \
  -H 'authorization: Bearer BEARER_TOKEN'

この要求により、次のような応答が返されます。

[
 {"timeStamp":"2020-06-01T00:00:00Z","objectStoreRequestCount":3},
 {"timeStamp":"2020-07-01T00:00:00Z","objectStoreRequestCount":30},
 {"timeStamp":"2020-08-01T00:00:00Z","objectStoreRequestCount":1},
 {"timeStamp":"2020-09-01T00:00:00Z","objectStoreRequestCount":25}
]

Exchange から Object Store API をダウンロードする

Exchange から Object Store API をダウンロードするには、​[Download (ダウンロード)]​ をクリックして RAML、OAS、または Mule 3 または Mule 4 のコネクタファイルの中からダウンロードする形式を選択します。

Exchange での Object Store API のダウンロード
Figure 1. 矢印は、Exchange の ​[Download (ダウンロード)]​ ボタンを示しています。