拡張された利用状況総計値

拡張された利用状況総計値の有効化

取得する利用状況総計値を増やすには、拡張された利用状況総計値をメタデータ API で有効にします。PlatformEventSettings で enableEnhancedUsageMetrics 項目を true に設定します。詳細は、『メタデータ API 開発者ガイド』の「PlatformEventSettings」を参照してください。

クエリの例: イベント名で集計された過去 24 時間の利用状況総計値の取得

クエリで StartDate と EndDate を指定しない場合は、デフォルトで過去 24 時間のデータが返されます。次のクエリ例では、SELECT ステートメントに EventName 項目が指定されているため、結果はイベントごとに集計されます。また、TimeSegment 項目で指定されたとおり、データは 1 時間ごとに集計されます。このクエリでは、イベント種別と利用状況種別も指定されています。

1SELECT EventName, EventType, UsageType, Value, StartDate, EndDate 
2FROM PlatformEventUsageMetric 
3WHERE TimeSegment='Hourly'

次の結果例では、すべてのイベント、つまり Order_Event__e と AccountChangeEvent について、公開されたイベントと配信されたイベントの利用状況データが返されています。このクエリでは、利用状況データが 1 時間ごとに集計されます。

有効な TimeSegment の値については、『Salesforce Platform のオブジェクトリファレンス』で PlatformEventUsageMetric の TimeSegment 項目を確認してください。

WHERE 句に項目を追加して、クエリ結果を絞り込むことができます。特定の利用状況種別についてのみ利用状況データを表示するには、WHERE 句に UsageType 項目を追加します。たとえば、配信されたイベントの利用状況のみを対象にクエリを実行する場合は、次の条件を追加します。

1WHERE UsageType='DELIVERY'

公開されたイベントを対象にする場合は、次の条件を追加します。

1WHERE UsageType='PUBLISH'

クエリはイベント種別で絞り込むことができます。たとえば、カスタムプラットフォームイベントのみを対象にクエリを実行する場合は、次の条件を追加します。

1WHERE EventType='CUSTOM_PLATFORM_EVENT'

変更イベントを対象にする場合は、次の条件を追加します。

1WHERE UsageType='CHANGE_EVENT'

利用状況を照会できるのは、1 つのイベントのみです。次に例を示します。

1WHERE EventName='Order_Event__e'

クエリのルール

• WHERE 句で StartDate と EndDate を指定していない場合、クエリの期間はデフォルトで過去 24 時間になります。
• WHERE 句で、StartDate と EndDate 項目の値を指定するか、または両方とも指定しないようにする必要があります。StartDate と EndDate のいずれか一方のみを指定すると、エラーが発生します。
• StartDate から EndDate の期間は最大で 30 日です。
• StartDate から EndDate の期間は最小で 15 分です。
• StartDate 項目は 60 日以内の日付を参照できます。
• TimeSegment 項目は、クエリの WHERE 句に必ず指定する必要があります。必要な場合は、SELECT ステートメントに含めることもできます。
• WHERE 句の StartDate から EndDate の期間が、選択した TimeSegment 値に対して有効であることを確認します。『Salesforce Platform のオブジェクトリファレンス』で PlatformEventUsageMetric の TimeSegment 項目を確認してください。
• クエリでは、SELECT 句または WHERE 句に Name、EventType、または EventName の項目を 1 つ以上指定する必要があります。
• EventName または EventType を使用するクエリでは、SELECT 句または WHERE 句に UsageType も指定する必要があります。

クエリの考慮事項

• StartDate と EndDate はクエリの SELECT ステートメントに含めることをお勧めします。これらの項目を含めることで、クエリ結果の解釈に役立ち、それぞれの結果を対応する時間セグメントに対応付けることができます。
• クエリが開始日と終了日の間のすべての時間セグメントを網羅するように指定するには、WHERE 句の StartDate と EndDate で >= と <= 論理演算子を使用します。たとえば次のようにします: StartDate >= DateTime1 AND EndDate <= DateTime2。
• 日付項目では、日付値の他に LAST_WEEK のような日付リテラル使用できます。詳細は、『SOQL および SOSL リファレンス』の「WHERE での日付形式と日付リテラル」を参照してください。
• 拡張された利用状況総計値のクエリで返される行の最大数は 2,000 行です。クエリで 2,000 行以上が生成された場合、エラーが発生し、結果は返されません。
• LIMIT 句はサポートされていません。
• SUM() や MAX() などの SOQL 集計関数はサポートされていません。詳細は、『SOQL および SOSL リファレンス』の「集計関数」を参照してください。

利用が最も多い時間枠へのドリルダウン

このセクションの例では、最初に複数日にわたる時間範囲を対象にし、そこからより狭い時間枠にドリルダウンして、利用が最も多い時間枠を探します。最初の例では、1 日あたりの利用状況を取得します。2 番目と 3 番目の例では、それぞれ 1 時間あたりの利用状況と 15 分あたりの利用状況にドリルダウンします。

これらの例で使用する項目の 1 つに Client 項目があります。登録者クライアントについて Client 項目が入力されるのは、イベント配信の利用状況の場合です。公開者クライアントの場合、Client 項目が入力されるのは、クライアント ID が使用可能であるときです。それ以外の場合は、空になります。クエリ結果の例では、わかりやすくするために Client 項目にプレースホルダーの値が含まれています。

イベント名とクライアントで集計された 1 日あたりの利用状況総計値の取得

次のクエリ例では、2 日間に配信されたイベントをイベント名とクライアントでグループ化し、その 1 日あたりの利用状況総計値を取得します。このクエリがイベントとクライアントごとに結果を集計するのは、SELECT ステートメントで EventName と Client の項目が指定されているためです。

1SELECT EventName, EventType, Client, Value, StartDate, EndDate
2FROM PlatformEventUsageMetric
3WHERE TimeSegment='Daily'
4AND UsageType='DELIVERY'
5AND StartDate >= 2023-04-01T00:00:00.000Z  
6AND EndDate <= 2023-04-03T00:00:00.000Z

次の結果例では、すべてのイベント、つまり Order_Event__e と AccountChangeEvent について、利用状況データが��されています。このクエリでは、利用状況データがクライアントごとに集計されます。2 つのクライアントが Order_Event__e イベントを受信し、それぞれについて利用状況データが計算されます。AccountChangeEvent イベントは、1 つのクライアントのみが受信します。

1 つのイベントの 1 時間あたりの利用状況総計値の取得

1 時間あたりの利用状況を照会すると、配信されたイベントのイベント利用状況が、最大 24 時間の範囲で 1 時間ごとに表示されます。次のクエリ例では、Order_Event__e という 1 つのイベントの利用状況総計値が取得されます。このクエリでは、TimeSegment 項目で指定されたとおり、結果を 1 時間の間隔に集計します。EventName 項目と Client 項目が SELECT ステートメントで指定されているため、結果はイベントおよびクライアントごとにグループ化されます。

前記の 1 日あたりの利用状況の例の場合、利用が最も多かったのは、4 月 1 日です。あるイベントについて、該当する日の利用状況にドリルダウンするには、その日付を照会します。

1SELECT EventName,Client, Value, StartDate, EndDate
2FROM PlatformEventUsageMetric
3WHERE TimeSegment='Hourly'
4AND UsageType='DELIVERY'
5AND EventName='Order_Event__e'
6AND StartDate >= 2023-04-01T00:00:00.000Z  
7AND EndDate <= 2023-04-02T00:00:00.000Z

次の結果例では、Order_Event__e について、4 月 1 日の 1 時間あたりの利用状況データが返されています。このクエリでは、利用状況データがクライアントごとに集計されます。2 つのクライアントが Order_Event__e イベントを受信し、それぞれについて利用状況データが計算されます。簡潔にするため、結果の一部のみを示しています。

15 分間の粒度での利用状況総計値の取得

最大 1 時間の範囲について、15 分間へと集計されたイベント利用状況を取得します。次のクエリ例では、Order_Event__e という 1 つのイベントについて、イベント配信の利用状況総計値が取得されます。このクエリでは、TimeSegment 項目で指定されたとおり、結果を 15 分の間隔に集計します。EventName 項目と Client 項目が SELECT ステートメントで指定されているため、結果はイベントおよびクライアントごとにグループ化されます。

前記の 1 時間あたりの利用状況の例の場合、利用が最も多いのは、4 月 1 日の 01:00:00 から 02:00:00 の間の時間です。あるイベントについて、該当する日の利用状況にドリルダウンするには、その日付を照会します。

1SELECT EventName,Client, Value, StartDate, EndDate
2FROM PlatformEventUsageMetric
3WHERE TimeSegment='FifteenMinutes'
4AND UsageType='DELIVERY'
5AND EventName='Order_Event__e'
6AND client='client1'
7AND StartDate >= 2023-04-01T01:00:00.000Z  
8AND EndDate <= 2023-04-01T02:00:00.000Z

次の結果例では、4 月 1 日の 01:00:00 から 02:00:00 の間の時間範囲で、client1 の Order_Event__e の利用状況データが 15 分ごとに返されています。