この文章は Salesforce 機械翻訳システムを使用して翻訳されました。詳細はこちらをご参照ください。

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

API バージョン 58.0 以降では、拡張された利用状況総計値を有効にし、より多くの項目と時間区分を取得して、PlatformEventUsageMetric を照会できます。利用状況総計値は、イベント名、クライアント ID、イベント種別、および利用状況の種別で分類できます。利用状況データは、1 日間、1 時間、15 分間などの粒度の時間区分で取得できます。

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

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

クエリのルール

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

クエリの例: イベント名で集計された過去 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 時間ごとに集計されます。

1Order_Event__e, CUSTOM_PLATFORM_EVENT, DELIVERY, 1154, 2023-04-01T00:00:00.000+0000, 2023-04-01T01:00:00.000+0000
2Order_Event__e, CUSTOM_PLATFORM_EVENT, DELIVERY, 1316, 2023-04-01T01:00:00.000+0000, 2023-04-01T02:00:00.000+0000
3Order_Event__e, CUSTOM_PLATFORM_EVENT, PUBLISH, 577, 2023-04-01T00:00:00.000+0000, 2023-04-01T01:00:00.000+0000
4Order_Event__e, CUSTOM_PLATFORM_EVENT, PUBLISH, 658, 2023-04-01T01:00:00.000+0000, 2023-04-01T02:00:00.000+0000
5AccountChangeEvent, CHANGE_EVENT, PUBLISH, 15, 2023-04-01T01:00:00.000+0000, 2023-04-01T02:00:00.000+0000
6AccountChangeEvent, CHANGE_EVENT, DELIVERY, 15, 2023-04-01T01:00:00.000+0000, 2023-04-01T02:00:00.000+0000

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

1WHERE UsageType='DELIVERY'

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

1WHERE UsageType='PUBLISH'

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

1WHERE EventType='CUSTOM_PLATFORM_EVENT'

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

1WHERE UsageType='CHANGE_EVENT'

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

1WHERE EventName='Order_Event__e'

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

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

これらの例で照会する項目の 1 つに Client 項目があります。登録者クライアントについて Client 項目が入力されるのは、イベント配信の利用状況の場合です。公開者クライアントの場合、Client 項目が入力されるのは、クライアント ID が使用可能であるときです。それ以外の場合は、空になります。

イベント名とクライアントで集計された 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 つのクライアントのみが受信します。

1Order_Event__e, CUSTOM_PLATFORM_EVENT, client1, 31327, 2023-04-01T00:00:00.000+0000, 2023-04-02T00:00:00.000+0000
2Order_Event__e, CUSTOM_PLATFORM_EVENT, client1, 20801, 2023-04-02T00:00:00.000+0000, 2023-04-03T00:00:00.000+0000
3Order_Event__e, CUSTOM_PLATFORM_EVENT, client2, 399, 2023-04-01T00:00:00.000+0000, 2023-04-02T00:00:00.000+0000
4Order_Event__e, CUSTOM_PLATFORM_EVENT, client2, 27, 2023-04-02T00:00:00.000+0000, 2023-04-03T00:00:00.000+0000
5AccountChangeEvent, CHANGE_EVENT, client3, 1009, 2023-04-01T00:00:00.000+0000, 2023-04-02T00:00:00.000+0000
6AccountChangeEvent, CHANGE_EVENT, client3, 780,  2023-04-02T00:00:00.000+0000, 2023-04-03T00:00:00.000+0000

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 イベントを受信し、それぞれについて利用状況データが計算されます。簡潔にするため、結果の一部のみを示しています。

1Order_Event__e, client1, 1136, 2023-04-01T00:00:00.000+0000, 2023-04-01T01:00:00.000+0000
2Order_Event__e, client1, 1301, 2023-04-01T01:00:00.000+0000, 2023-04-01T02:00:00.000+0000
3Order_Event__e, client1, 903, 2023-04-01T02:00:00.000+0000, 2023-04-01T03:00:00.000+0000
4Order_Event__e, client2, 17, 2023-04-01T00:00:00.000+0000, 2023-04-01T01:00:00.000+0000
5Order_Event__e, client2, 15, 2023-04-01T01:00:00.000+0000, 2023-04-01T02:00:00.000+0000
6Order_Event__e, client2, 13, 2023-04-01T02:00:00.000+0000, 2023-04-01T03:00:00.000+0000

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 分ごとに返されています。2 つのクライアントが Order_Event__e イベントを受信し、それぞれについて利用状況データが計算されます。

1Order_Event__e, client1, 321, 2023-04-01T22:00:00.000+0000, 2023-04-01T22:15:00.000+0000
2Order_Event__e, client1, 399, 2023-04-01T22:15:00.000+0000, 2023-04-01T22:30:00.000+0000
3Order_Event__e, client1, 265, 2023-04-01T22:30:00.000+0000, 2023-04-01T22:45:00.000+0000
4Order_Event__e, client1, 298, 2023-04-01T22:45:00.000+0000, 2023-04-01T23:00:00.000+0000

プラットフォームイベント開発者ガイド