모범 사례

다음 패턴을 사용하여 파트너 통합을 예측 가능하고, 관찰 가능하며, 시설에 안전하게 유지하십시오.

시설을 일관되게 식별

파트너 계정에 구성된 연결 방법을 선택하고 일관되게 사용하십시오.

같은 요청에 두 식별자를 모두 보내지 마십시오. Performance Hub는 파트너 계정에 구성된 연결 방법을 사용하여 요청을 처리합니다.

설정 지침은 파트너 연결 방법을 참조하십시오.

Partner API는 JSON 요청 본문을 허용하며, 문서화된 경우 배치 중심의 동기화 워크플로에 맞게 설계되었습니다. 배치 크기를 제한하고 재시도할 수 있도록 유지하십시오.

기본 지침:

속도 제한은 조정할 수 있으며, Performance Hub 파트너 계정 관리자가 사례별로 구성할 수 있습니다. 대량 가져오기, 출시 트래픽 또는 보고서 백필이 예상되면 변경 기간 전에 필요한 처리량을 합의하십시오.

대규모 데이터 세트를 동기화해야 하는 경우 결정론적인 청크로 나누고 귀사 측에서 각 청크 ID를 기록하십시오. 이렇게 하면 실패한 재시도를 더 쉽게 파악할 수 있습니다.

429, 500, 502, 503, 504와 같은 일시적인 실패에는 지수 백오프를 사용하십시오.

짧은 간격의 반복 재시도는 피하십시오. 다음과 같이 시작하는 것이 좋습니다.

400 또는 422와 같은 유효성 검사 실패의 경우 재시도하기 전에 요청을 수정하십시오.

Door/Gate Controller 잠금 해제 엔드포인트는 선택적 idempotency_key를 지원합니다. 같은 파트너, 시설, 출입문에 같은 키를 다시 사용하면 기존 결과가 있는 경우 해당 결과를 반환합니다.

수행 중인 작업에 대해 안정적인 키를 사용하십시오. 예를 들어 귀사 시스템의 체크인 ID나 출입 이벤트 ID를 사용할 수 있습니다.

해당 엔드포인트에 문서화되어 있지 않은 한 모든 쓰기 엔드포인트가 멱등성을 지원한다고 가정하지 마십시오.

가능하면 안정적이고 정규화된 값을 보내십시오.

대부분의 파트너 통합에는 두 가지가 모두 필요합니다.

통합은 이전 요청의 성공 여부에 의존하지 않고 회원, 멤버십 플랜 또는 보고서 스냅샷의 현재 상태를 다시 보낼 수 있어야 합니다.

각 회원의 access_time_windows 값을 독립적으로 리비전이 관리되는 완전한 스냅샷으로 취급하십시오.

증분 작업자와 조정 작업자 전반에서 단조 증가하는 단일 access_time_windows_revision 스트림을 조율하십시오.
불확실하거나 일시적으로 실패한 전송은 같은 리비전과 정규화된 페이로드로 재시도하십시오.
access_time_windows를 업데이트하지 않을 때는 생략하십시오.
신뢰할 수 있는 원본 조회에 성공하여 남은 시간 창이 없음이 확인된 경우에만 []를 보내십시오. 업스트림 제한 시간 초과, 부분 결과 또는 구문 분석 실패를 절대 권한 취소로 처리하지 마십시오.
external_id와 scope_key를 안정적으로 유지하고, 프로덕션 전에 모든 범위 매핑을 인증하십시오.
해당 통합에 대해 합의한 최신성 정책을 기준으로 원본 데이터의 경과 시간을 모니터링하십시오.

완전한 스냅샷, 시간대, 일광 절약 시간, 취소, 테스트 벡터에 대해서는 권위 있는 Access Time Windows 생산자 가이드를 참조하십시오.

Door/Gate Controller 잠금 해제의 경우:

잠금 해제 엔드포인트에서 반환된 event_id와 command_id를 항상 기록하십시오.

개발 및 출시 중에는 Partner Console 요청 로그를 사용하십시오. 프로덕션에서는 다음 항목을 포함한 자체 로그도 유지하십시오.

이러한 필드가 있으면 고객이 무슨 일이 있었는지 물을 때 지원과 조정을 훨씬 빠르게 처리할 수 있습니다.