En iyi uygulamalar

İş ortağı entegrasyonlarını tesisler için öngörülebilir, izlenebilir ve güvenli tutmak üzere bu kalıpları kullanın.

Tesisleri tutarlı biçimde tanımlayın

İş ortağı hesabınız için yapılandırılmış bağlama yöntemini seçin ve tutarlı biçimde kullanın:

Direct Link - tesisler uç noktasının döndürdüğü Performance Hub facility_id değerini kullanın.
Linking Identifier - şube kimliği, konum kodu veya mağaza numarası gibi kendi konum tanımlayıcınızı kullanın.

Aynı istekte iki tanımlayıcıyı birden göndermeyin. Performance Hub istekleri, iş ortağı hesabınız için yapılandırılmış bağlama yöntemini kullanarak çözümler.

Kurulum yönergeleri için İş Ortağı Bağlama Yöntemleri sayfasına bakın.

Toplu yazma işlemlerini dikkatli yapın

Partner API, JSON istek gövdelerini kabul eder ve belgelendiği yerlerde toplu işleme odaklı eşitleme iş akışları için tasarlanmıştır. Toplu işlemleri sınırlı ve yeniden denenebilir tutun.

Varsayılan yönergeler:

En iyi performans için toplu istek başına en fazla 1000 öğe kullanın.
Yükleri 10MB altında tutun.
Uç nokta başına saniyede 5 istek sınırında kalın.

Hız sınırları ayarlanabilir ve Performance Hub iş ortağı hesap yöneticiniz tarafından duruma göre yapılandırılabilir. Yüksek hacimli içe aktarmalar, lansman trafiği veya raporlama geri doldurmaları bekliyorsanız gereken işlem hacmini değişiklik penceresinden önce kararlaştırın.

Büyük bir veri kümesini eşitlemeniz gerekiyorsa onu belirlenimci parçalara bölün ve her parçanın kimliğini kendi tarafınızda kaydedin. Bu, başarısız yeniden denemeleri anlamayı kolaylaştırır.

Güvenli şekilde yeniden deneyin

429, 500, 502, 503 ve 504 gibi geçici hatalar için üstel geri çekilme kullanın.

Sıkı yeniden deneme döngülerinden kaçının. İyi bir başlangıç noktası şudur:

1 saniye sonra yeniden deneyin.
2 saniye sonra yeniden deneyin.
4 saniye sonra yeniden deneyin.
İşlem hâlâ başarısız oluyorsa durun ve uyarı verin.

400 veya 422 gibi doğrulama hataları için yeniden denemeden önce isteği düzeltin.

Desteklendiği yerlerde idempotency kullanın

Door/Gate Controller kilit açma uç noktası isteğe bağlı bir idempotency_key destekler. Aynı iş ortağı, tesis ve kapı için aynı anahtarı yeniden kullanmak, varsa mevcut sonucu döndürür.

Gerçekleştirilen eylem için sabit bir anahtar kullanın; örneğin sisteminizdeki bir check-in kimliği veya erişim olayı kimliği.

O uç nokta için belgelenmedikçe her yazma uç noktasının idempotency'yi desteklediğini varsaymayın.

Kaynak verileri temiz tutun

Mümkün olan her yerde sabit, normalleştirilmiş değerler gönderin:

Kaynak sisteminizdeki tutarlı üye, plan, tesis ve check-in kimliklerini kullanın.
Tarihler ve saatler için ISO 8601 zaman damgaları kullanın.
Mümkün olduğunda telefon numaralarını uluslararası biçimde gönderin.
Para birimlerini her uç nokta için belgelenen alanları kullanarak gönderin.
Serbest metin alanlarını yapılandırılmış alanlara ait verilerle aşırı yüklemekten kaçının.

Artımlı ve tam eşitlemeler için tasarlayın

Çoğu iş ortağı entegrasyonu ikisine de ihtiyaç duyar:

Günlük değişiklikler için artımlı eşitlemeler.
Kaçırılan olayları, geçmiş içe aktarmaları veya veri kaymasını düzeltmek için tam mutabakat eşitlemeleri.

Entegrasyonunuz bir üye, üyelik planı veya rapor anlık görüntüsünün güncel durumunu, önceki bir isteğin başarılı olmasına bağlı olmadan yeniden gönderebilmelidir.

Access Time Windows'u güvenli şekilde yayımlayın

Her üyenin access_time_windows değerini eksiksiz ve bağımsız olarak revizyonlanan bir anlık görüntü olarak ele alın:

Artımlı ve mutabakat çalışanları genelinde tekdüze artan tek bir access_time_windows_revision akışını koordine edin.
Belirsiz veya geçici bir teslimatı aynı revizyon ve normalleştirilmiş yükle yeniden deneyin.
access_time_windows değerini güncellemiyorsanız göndermeyin.
[] değerini yalnızca başarılı ve yetkili bir kaynak sorgusu hiçbir pencere kalmadığını kanıtladıktan sonra gönderin. Bir üst kaynak zaman aşımını, kısmi sonucu veya ayrıştırma hatasını asla iptale dönüştürmeyin.
external_id ve scope_key değerlerini sabit tutun ve üretimden önce her kapsam eşlemesini sertifikalandırın.
Kaynak yaşını o entegrasyon için kararlaştırılan güncellik ilkesine göre izleyin.

Eksiksiz anlık görüntüler, saat dilimleri, yaz saati uygulaması, iptal ve test vektörleri için yetkili Access Time Windows üretici kılavuzuna bakın.

Erişim denetimini güvenlik açısından kritik olarak ele alın

Door/Gate Controller kilit açma işlemleri için:

Sisteminiz Performance Hub'ı çağırmadan önce kişinin girişine izin verilip verilmeyeceğine karar vermelidir.
Performance Hub, yalnızca sahadaki kontrol cihazı rölenin fiziksel olarak kilidinin açıldığını onayladıktan sonra 200 döndürür.
Onayların çoğu 3-5 saniye içinde tamamlanır.
Zaman aşımı, arka planda gerçekleşen bir başarı değil, açık bir başarısız kilit açma işlemidir.
Yalnızca kendi erişim ve güvenlik kurallarınıza göre yeniden deneyin.

Kilit açma uç noktasının döndürdüğü event_id ve command_id değerlerini her zaman kaydedin.

Entegrasyonunuzu izleyin

Geliştirme ve lansman sırasında Partner Console istek kayıtlarını kullanın. Üretimde ayrıca şu bilgileri içeren kendi kayıtlarınızı tutun:

İstek zaman damgası.
Uç nokta.
Kaynak kayıt kimliği.
Tesis tanımlayıcısı.
HTTP durum kodu.
Performance Hub yanıt gövdesi veya hata mesajı.

Bu alanlar, bir müşteri ne olduğunu sorduğunda destek ve mutabakat işlemlerini çok daha hızlı hale getirir.