ベストプラクティス

これらのパターンを使用して、パートナー連携の動作を予測可能かつ監視可能にし、施設にとって安全な状態を保ってください。

施設を一貫した方法で識別する

パートナーアカウントに設定されているリンク方法を選択し、一貫して使用してください。

同じリクエストで両方の識別子を送信しないでください。Performance Hub は、パートナーアカウントに設定されているリンク方法を使用してリクエストを解決します。

設定方法については、パートナーのリンク方法を参照してください。

Partner API は JSON のリクエスト本文を受け付け、ドキュメントに記載されている場合はバッチ単位の同期ワークフロー向けに設計されています。バッチのサイズに上限を設け、再試行可能な状態にしてください。

標準的な目安:

レート制限は調整可能で、Performance Hub のパートナーアカウントマネージャーが個別に設定できます。大量のインポート、リリース時のトラフィック、レポートのバックフィルが見込まれる場合は、変更作業の時間帯より前に必要なスループットについて合意してください。

大規模なデータセットを同期する必要がある場合は、決定論的なチャンクに分割し、各チャンクの ID をお使いのシステム側で記録してください。これにより、失敗した再試行の状況を把握しやすくなります。

429、500、502、503、504 などの一時的なエラーには、指数バックオフを使用してください。

間隔の短い再試行ループは避けてください。最初の目安は次のとおりです。

400 や 422 などの検証エラーの場合は、リクエストを修正してから再試行してください。

ドア/ゲートコントローラーの解錠エンドポイントは、省略可能な idempotency_key をサポートしています。同じパートナー、施設、ドアに対して同じキーを再利用すると、既存の結果がある場合はその結果が返されます。

お使いのシステムのチェックイン ID やアクセスイベント ID など、実行する操作に対して安定したキーを使用してください。

エンドポイントのドキュメントに記載されていない限り、すべての書き込みエンドポイントが冪等性をサポートしているとは想定しないでください。

可能な限り、安定した正規化済みの値を送信してください。

ほとんどのパートナー連携では、次の両方が必要です。

連携では、以前のリクエストが成功したかどうかに依存せずに、会員、会員プラン、レポートのスナップショットの現在の状態を再送信できるようにしてください。

各会員の access_time_windows の値は、独立してリビジョン管理される完全なスナップショットとして扱ってください。

差分同期と照合のワーカー全体で、単調増加する access_time_windows_revision のストリームを 1 つに統一します。
配信結果が不確かな場合や一時的なエラーの場合は、同じリビジョンと正規化されたペイロードで再試行します。
access_time_windows を更新しない場合は省略します。
[] は、信頼できるソースからの取得に成功し、残っているウィンドウがないことが確認された場合にのみ送信します。上流のタイムアウト、部分的な結果、解析エラーを失効として扱わないでください。
external_id と scope_key を安定した値に保ち、本番稼働前にすべてのスコープのマッピングを認定します。
その連携で合意した鮮度ポリシーに照らして、ソースデータの経過時間を監視します。

完全なスナップショット、タイムゾーン、夏時間、キャンセル、テストベクターについては、正式な Access Time Windows プロデューサーガイドを参照してください。

ドア/ゲートコントローラーの解錠について:

解錠エンドポイントから返される event_id と command_id は必ず記録してください。

開発中とリリース時には、Partner Console のリクエストログを使用してください。本番環境では、次の情報を含む独自のログも管理してください。

これらのフィールドがあれば、お客様から何が起きたのかを尋ねられた際に、サポートや照合を大幅に迅速化できます。