トップ > Salesforce > Data Cloud のクレジット消費量を Flow で監視する

Data Cloud のクレジット消費量を Flow で監視する

Salesforce Data Cloud

こんにちは。エンジニアの山下です。

今回は Data Cloud のクレジット消費量の監視方法について書きたいと思います。

Data Cloud にはクレジット消費を管理するための DLO 群が用意されているのですが、これらの DLO が持つフィールドの定義については Salesforce の公式ドキュメントのどこにも解説されていません。従って、いざクレジット消費量を監視しようとすると開発者が実際のレコードを眺めながら DLO の各フィールドの意味を推理するという謎の工程が必要になります。

当然、この手の虚無でしかない時間は少なければ少ないほどよいので、今回は筆者が実際の DLO レコードを解析して得た知見と共に、クレジット消費量を監視するための Flow の構築方法を紹介します。

概要

実は Data Cloud のクレジット消費量を監視するフローについては Salesforce の Technical Document にその作成方法が記載されています。しかし、上述の通り、この Technical Document にもクレジット監視のための DLO 群についての詳細は含まれていないため、今回はその行間を補完した作成方法について書きたいと思います。

今回作成する Flow は以下の２つです。

  1. クレジット消費量の変動を監視する Flow
  2. クレジット残高の逼迫を監視する Flow

1 は過去 X 日間の平均を大きく超えるようなクレジット消費量の変動がないかを日ごとに確認する Flow で、2 はクレジットの総消費量がクレジット上限の X % に達していないかどうかを時間ごとに確認する Flow になります。なお、いずれの Flow でも異常検知時には特定の宛先にメールを送信して通知することにしておきます。

Data Cloud のクレジットは Card と呼ばれる種別に分けて管理されていますが、1 では Card に関わらず 1 日のクレジット消費量全体を対象とし、2 では Card ごとに消費割合を算出して判定することにしておきます。クレジット残高は Card 単位で決定されるので 2 は Card 単位である必要がありますが、1 については大まかに全体の変動が分かれば OK としています。

データスペースへの DLO の追加

クレジット消費を管理するための DLO はデフォルトではデータスペースに含まれておらず、開発者が自分で追加する必要があります。データスペースへの DLO の追加方法については こちら の公式ドキュメントに記載されているので、そちらを参照して実施してください。

今回追加する必要がある DLO は以下の３つです。

  • TenantDailyEntitlementConsumption
  • TenantHourlyEntitlementConsumption
  • TenantEntitlementTransaction

概ね名前から察しがつくと思いますが、上２つが日毎・時間毎に作成されるクレジット消費量の情報を持つ DLO で、最後の TenantEntitlementTransaction は取引記録になっています。これらの DLO が持つフィールドの内容がやや複雑なのですが、詳細については後述します。

上記の追加後、それぞれの DLO に対応する DMO を作成してマッピングを設定しておきます。Flow からは DMO しか参照することできないため、忘れずに実施しておきましょう。

クレジット消費量の変動を監視する Flow を作成する

というわけで、早速１つ目の Flow を作成していきます。１つ目の Flow は過去 X 日分の平均クレジット消費量を見て、本日分のクレジット消費量が平均から大きく変動していないかを確認するというものでした。

この Flow では日毎の情報を参照したいので TenantDailyEntitlementConsumption を使用します。なお、この DLO は日ごとに１件だけ作成されるわけではなく、その日のクレジットの情報がクレジットの種別ごとに作成されるので注意が必要です。

ともあれ、この DLO に含まれているクレジット消費量の情報さえ特定できれば簡単に実装できそうです。というわけで、この DLO が持つフィールドを探ってみると、以下の４つが見つかります。

  • Unit
  • Unit Consumed
  • Multiplier
  • Raw Usage

どれもあまりピンとこない名前で困るのですが、これらからクレジット消費量を計算する方法を開拓しなければなりません。つらい。

クレジット消費量の計算方法

この問題を解くヒントは以下の Trailhead に書かれています。

trailhead.salesforce.com

この記事には以下のような説明が書かれています。

Each usage type has a unit and multiplier. The unit represents how much data is considered 1 unit of usage. This is 1 million for every usage type. For Data Cloud, the multiplier represents how many credits are consumed by 1 unit of usage. Multiply this number by your usage to get the total credits consumed. Refer to the rate card linked in the Resources section for current multipliers. To calculate how many credits are consumed in a usage event, you need to know the usage type, the multiplier for the usage type, and how much data was processed.

d represents the total amount of data processed. m represents the multiplier for the usage type.

Credits consumed = (d/1,000,000) * m

要約すると、課金に関わるデータ量は Unit の値が定める単位で集計され、消費するクレジットはこの集計値に Multiplier というクレジット種別ごとに定められた消費倍率を乗じて計算されると書かれています。つまり、集計対象のデータが API リクエスト数で、Unit の値が 1000 で Multiplier が 3 であれば、API を 1000 回呼ぶごとに 3 クレジット消費されるというようなイメージです。

TenantDailyEntitlementConsumption では課金に関わるデータ量（上記の例の API リクエスト数にあたる値）は Raw Usage というフィールドに格納されるので、計算式に表すと以下のようになります。

Credits Consumed = (Raw Usage / Unit) * Multiplier

ちなみに Trailhead には Unit は常に 1,000,000 であると書かれていますが、実際のデータを観察していると 1,000,000 以外の値が入ることもあるようなので注意しましょう。何故嘘をつくんだ。

これでクレジット消費量についてはバッチリと言いたいところですが、実はこんな計算をせずともクレジット消費量を得る方法があります。というのは、名前が微妙でわかりづらいのですが、実は Unit Consumed がクレジット消費量そのものを表すフィールドだからです。

これは実際のデータを眺めていて気づきました。以下に実際のデータの一部を掲載します。先ほどの計算式に従って計算すると、Unit Consumed がちゃんとクレジット消費量に一致していることが確認できます。

というわけで、クレジット消費量を得るには Unit Consumed を参照すればよいことがわかりました。やったぜ。

Flow の実装

あとは単に実装すればよいだけです。少々長いですが、Flow の全体像は以下のようになります。

一見複雑そうに見えなくもないですが、やっていることは至ってシンプルです。上から順に説明すると以下のような感じです。

  1. 日ごとに定期実行するために Schedule-Triggered Flow で実装します。
  2. Schedule-Triggered Flow ではコールアウトの前に待機要素を呼ばなくてはならないという意味不明な制約があり、このコールアウトには DMO の検索も含まれます。そのため Flow の冒頭で待機要素を呼んでおきます。公式ドキュメント には $Flow.CurrentDateTime を使用した最小時間待機の方法が書かれていますが、面倒であれば適当に１分程度待機しても問題ないです。
  3. 過去 X 日分の TenantDailyEntitlementConsumption を取得します。検索条件には Drawdown Day フィールドを使用します。X 日前の日付は数式を使って定義することができます。
  4. 過去 X 日分の TenantDailyEntitlementConsumption でループして１日あたりのクレジット消費量 = Unit Consumed の平均値を得ます。既に述べた通り、この DMO は１日ごとにクレジットの種別分だけレコードを作成するため、平均値算出の際の除算はレコード数ではなく X で行う必要があります。
  5. 続いて当日の日付の TenantDailyEntitlementConsumption を検索します。こちらも Drawdown Day を使って検索すれば OK です。
  6. 当日の日付の TenantDailyEntitlementConsumption でループして当日のクレジット消費量の合計値を得ます。
  7. 4 で得た平均値に適当な乗数をかけて閾値とし、当日のクレジット消費量がそれを超えているかどうかで分岐します。閾値を超えた場合はメールで通知します。参考までに筆者の環境では乗数を 1.25 倍として 25 % 程度の振れ幅を許容しています。なお、同様の方法でクレジット消費量が過剰に少ない場合も検出できるので、必要に応じて実装してください。

DLO の定義さえわかってしまえばどうということはないですね。

クレジット残高の逼迫を監視する Flow

続いて２つ目の Flow です。これはクレジットの総消費量がライセンスが定めるクレジット上限の X % に達していないかどうかを時間ごとに確認するためのものでした。冒頭で述べた通り、この処理は Card 単位で行います。

ある Card において全体の何割のクレジットを消費したかを知るには、該当の Card で消費したクレジットの総量とクレジット上限の２つの情報が必要になります。この Flow では冒頭でデータスペースに取り込んだ DLO のうち、先ほど使用しなかった２つの DLO を使ってこれらの情報を計算します。

消費したクレジットの総量

TenantHourlyEntitlementConsumption には Unit Consumed が含まれているので、ライセンス適用期間内の全てのレコードの Unit Consumed の値を合算すれば消費したクレジットの総量を計算することが可能ですが、実はもっと簡単に計算する方法があります。

TenantHourlyEntitlementConsumption には Card Definition Balance というフィールドが定義されており、このフィールドには該当の Card におけるクレジットの残高が格納されます。この残高と次項で計算するクレジット上限を合わせれば、クレジット消費量は以下のように計算できます。

クレジット消費量 = クレジット上限 - クレジット残高

なお、クレジットの消費割合が 100 % を超えた場合、このフィールドには負の値が格納されるようになっているので、クレジット消費量がクレジット付与量を超過した場合でも上の式は適切に働きます。偉い。

クレジット上限

クレジット上限を得るには TenantEntitlementTransaction を使用します。この DLO はクレジットの取引記録を管理するためのオブジェクトで、これまでに付与ないし消費されたクレジットの情報が全て格納されています。

そもそもクレジット上限とはライセンスの購入等によって Salesforce から付与されたクレジットの総量のことなので、この取引記録からクレジット付与のレコードのみを抽出して合算すればそれがクレジット上限です。具体的には Transaction Type フィールドが Add になっているレコードのみを抽出し、Quantity フィールドの値を合算すれば OK です。

結論だけ見ると割とコンパクトなのですが、先述の通り、フィールドの定義が記載されたドキュメント等は一切ないので、一から解析すると割と苦労します。なお、上記の結論は実際に計算して得た値が Data Cloud の Consumption Cards に記載される Total Credits の値と一致することをもって確認しています。

また TenantEntitlementTransaction には Entitlement Card Definition Dev Name というフィールドが含まれており、こちらには Card の種別が格納されています。従って、ある Card における付与されたクレジットの総量を取得する場合は Transaction Type と Entitlement Card Definition Dev Name の２つのフィールドを検索条件に指定する形になります。

Flow の実装

というわけで、必要な情報は揃ったので実装していきます。実装する Flow の全体像は以下になります。

こちらも上から順に解説していきます。

  1. TenantHourlyEntitlementConsumption レコードの作成をトリガーとする Data Cloud-Triggered Flow で実装します。これは対象の DMO に含まれるクレジット残高と Card の種別を使うのが最も利便性が高いことに因ります。
  2. クレジット上限を計算するために TenantEntitlementTransaction を取得します。以下の２つの検索条件を全て満たすレコードを取得します。
    • Transaction Type が Add であること
    • Entitlement Card Definition Dev Name がトリガーレコードの Card Definition Developer Name と一致すること（トリガーレコードの Card 種別と同じ種別のレコードのみを集計対象とするための条件）
  3. 取得した TenantEntitlementTransaction を使ってクレジット上限を計算します。単にループして Quantity を合算すれば OK です。また、数式を使って消費したクレジットの総量も計算できるようにしておきます。
  4. 3 で得た結果からクレジットの消費割合を算出して分岐します。今回は消費割合が 50 % と 100 % に到達した場合にそれぞれメールで通知することにしています。

こちらも DLO の定義さえわかってしまえば特に難しい点はないと思います。

まとめ

というわけで、Data Cloud のクレジット消費量を監視する Flow を定義することができました。

Data Cloud のクレジット計算体系はそこそこ複雑なので、消費量の監視はそれなりに重要な項目だと思っています。比較的新しいサービスであるためか、Data Cloud-Triggered Flow を作成すると Data Cloud 上に Data Action が作成されてクレジット消費が発生するなど、利用する側からは把握が難しい箇所も散見されます。クレジットが枯渇すると当然ながら追加請求に繋がるので、こういった予期せぬ消費を早期発見できるように備えておきたいですね。

毎度の感想ですが、Salesforce の開発者向けのドキュメントはもう少しちゃんと整備してもらいたい感がありますね。この記事が開発者の皆様の負担を少しでも軽減できれば幸いです。

以上です。最後までお読みいただき、ありがとうございました。

おまけ：Card の種別の対応関係

各種 DLO に Card Definition Developer Name として格納される Card 種別を表す文字列は Consumption Cards に記載される名前と微妙に異なり、視認性が非常に悪いです。どの Card 種別文字列が Consumption Cards のどの項目に対応するのかも今回の実装中に調べたので、そちらの内容をおまけとして記載しておきたいと思います。

以下が対応表になります。

Consumption Cards Card Definition Developer Name
Conversations DigitalEngagementConversation
Data Services Credits PlatformServicesCard
Einstein Requests EinsteinAI_Einstein1
Data Storage Allocation DataStorageCard
Segmentations Activations Personalization

この表の内容は実際に計算したクレジット総消費量とクレジット上限が一致していることをもって確認しています。ただし、Segmentations Activations に関してはフレクトの環境でクレジット消費がなく、他４つの対応関係が埋まったことで消去法的に決定しています。従って、Segmentations Activations に限ってはあまり自信はありません。

情報に誤りがある等あればご指摘いただけると助かります。