Go SDK
Go şablonunun kullandığı uygulama SDK'sı: kurulum, tipli çağrılar, imza doğrulama ve sahte platformla test.
appsdk, bir uygulamanın platformla konuşmak için ihtiyaç duyduğu her şeyi taşıyan Go paketidir: OAuth kurulumu, imza doğrulama, /api/v1 için tipli bir istemci ve sözleşmelerin tipleri. Yalnızca standart kitaplığa dayanır.
Go şablonu (biticaret app init) SDK'nın bir kopyasını sdk/ klasöründe getirir ve go.mod onu oraya bağlar:
require github.com/biticaret/biticaret v0.0.0-00010101000000-000000000000
replace github.com/biticaret/biticaret => ./sdk
import "github.com/biticaret/biticaret/pkg/appsdk"
sdk/ klasörünü düzenlemeyin; yeni bir şablon yeni bir kopya getirir.
Aşağıdaki örnekler şablonun main.go dosyasındandır veya onun yanında derlenir.
Kurmak
Üç değer uygulamanın her yerinde kullanılır:
s := &server{
clientID: clientID,
adminOrigin: env("ADMIN_ORIGIN", "https://admin.biticaret.com.tr"),
platform: appsdk.Platform{StoreDomain: env("STORE_DOMAIN", "mybiticaret.com.tr")},
verifier: appsdk.Verifier{Secrets: []string{secret}},
oauth: appsdk.OAuth{ClientID: clientID, ClientSecret: secret, Scopes: scopes, RedirectURI: appURL + callbackPath},
tokens: map[int64]string{},
}
Platform, mağazaların nerede sunulduğunu söyler.Platform.StoreURL(store)yalnızca gerçek bir mağaza adresi için bir URL verir; böylece gizli anahtarınız ve jetonlarınız, bir saldırganın sorguya yazdığı bir adrese gitmez.Verifier, platformun gönderdiği her şeyin imzasını denetler.Secretsbirden çok anahtar alır; anahtar yenilerken eskisini ve yenisini birlikte verin.OAuth, kurulum akışını yürütür.
Kurulum akışı
application_url işleyicisi imzalı sorguyu doğrular ve mağaza sahibini izin ekranına gönderir:
store, storeID, err := s.verifier.VerifyAppURL(r.URL.Query())
if err != nil {
http.Error(w, "Bu bağlantı platformdan gelmiyor ya da süresi doldu.", http.StatusUnauthorized)
return
}
storeURL, err := s.platform.StoreURL(store)
if err != nil {
http.Error(w, "Mağaza adresi geçersiz.", http.StatusBadRequest)
return
}
http.Redirect(w, r, s.oauth.AuthorizeURL(storeURL, state), http.StatusFound)
Geri dönüş işleyicisi imzayı ve state değerini denetler, sonra kodu jetona çevirir:
q := r.URL.Query()
if err := s.verifier.VerifyQuery(q); err != nil {
http.Error(w, "Bu bağlantı platformdan gelmiyor ya da süresi doldu.", http.StatusUnauthorized)
return
}
tok, err := s.oauth.Exchange(r.Context(), storeURL, q.Get("code"))
if err != nil {
log.Printf("code exchange for %s: %v", store, err)
http.Error(w, "Yükleme tamamlanamadı; yeniden deneyin.", http.StatusBadGateway)
return
}
s.mu.Lock()
s.tokens[tok.StoreID] = tok.AccessToken
s.mu.Unlock()
Jetonu tok.StoreID ile saklayın. Her takas önceki jetonu iptal eder: her takastan geleni kaydedin.
Tipli bir çağrı
Client bir mağazanın API'sini o kurulumun jetonuyla çağırır:
func productTitles(ctx context.Context, storeURL, token string) ([]string, error) {
c := &appsdk.Client{StoreURL: storeURL, Token: token}
var titles []string
pageInfo := ""
for {
products, next, err := c.ListProducts(ctx, pageInfo, 100)
if err != nil {
return nil, err
}
for _, p := range products {
titles = append(titles, p.Title)
}
if next == "" {
return titles, nil
}
pageInfo = next
}
}
storeURL, Platform.StoreURL çıktısıdır. HTTPClient boşsa istemci 15 saniyelik zaman aşımı kullanır; yönlendirmeleri hiç izlemez.
İstemci 429 yanıtında Retry-After kadar bekler (en çok MaxRateLimitWait, 10 saniye) ve yeniden dener (en çok 3 kez; sonra 429 bir *appsdk.APIError olur). Platformun diğer retleri *appsdk.APIError olarak döner:
func shopName(ctx context.Context, c *appsdk.Client) (string, error) {
shop, err := c.GetShop(ctx)
if appsdk.IsAPIErrorCode(err, http.StatusUnauthorized, "invalid_token") {
// Jeton iptal edilmiş: uygulama kaldırılmış ya da yeni bir takas yapılmış.
return "", err
}
if err != nil {
return "", err
}
return shop.Name, nil
}
appsdk.Retryable(err), aynı çağrının sonra başarılı olup olamayacağını söyler: 400, 409 ve 422 kesindir, diğerleri yeniden denenebilir.
Client şu kaynakların yöntemlerini taşır (adresler ve izinler: Uygulama API'si):
| Kaynak | Yöntemler |
|---|---|
| Mağaza | GetShop |
| Ürünler | ListProducts, GetProduct, CreateProduct, UpdateProduct, ListProductVariants, ProductVariants (250'den fazla varyantı olan bir ürünün bütün varyantları), SetVariantCost, SetVariantShipping |
| Koleksiyonlar | ListCollections, GetCollection |
| Stok | ListLocations, ListInventoryLevels, ListInventoryHistory, AdjustInventoryLevel, MoveInventoryLevel |
| Siparişler | ListOrders, GetOrder, CreateRefund, CreateFulfillment, CancelFulfillment, CreateFulfillmentEvent, CaptureOrder, CaptureOrderAsStaff |
| Müşteriler | GetCustomer, SetCustomerTags, ListMarketingAudience, SetMarketingConsent |
| Müşteri segmentleri | ListCustomerSegments, GetCustomerSegment, ListSegmentCustomers |
| İndirimler | CreateDiscountCode, GetDiscountCode, DeleteDiscountCode |
| Hediye kartları | ListGiftCards, GetGiftCard, CreateGiftCard (kartın kodu yalnızca bu yanıtta gelir), UpdateGiftCard, DisableGiftCard |
| Taslak siparişler ve kanallar | ListDraftOrders, GetDraftOrder, CreateDraftOrder, UpdateDraftOrder, DeleteDraftOrder, CompleteDraftOrder, SendDraftInvoice, CreateChannelOrder |
| Şirketler | ListCompanies, GetCompany, CreateCompany, UpdateCompany, DeleteCompany, CreateCompanyLocation, UpdateCompanyLocation, DeleteCompanyLocation, CreateCompanyContact, UpdateCompanyContact, DeleteCompanyContact |
| Meta alanlar | SetMetafield, DeleteMetafield |
| Meta nesneler | ListMetaobjectDefinitions, GetMetaobjectDefinition, CreateMetaobjectDefinition, UpdateMetaobjectDefinition, DeleteMetaobjectDefinition, ListMetaobjects, GetMetaobject, CreateMetaobject, UpdateMetaobject, DeleteMetaobject |
| Çeviriler | GetTranslations, SetTranslations |
| SMS | SendSMS, ReportSMSStatus |
| Web pikselleri | GetPixelSettings, SetPixelSettings |
| Faturalandırma | ListPlans, CreateAppSubscription, GetAppSubscription, ListAppSubscriptions, ActiveAppSubscription, ActivePlan, CancelAppSubscription, CreateUsageRecord, CreateAppCredit, ListAppCredits |
| Webhook teslimleri | ListWebhookDeliveries, ReplayWebhookDelivery |
| Ödeme uygulamaları | ConfigurePaymentsApp, ResolvePayment, RejectPayment, PendPayment, ResolveFollowUp, RejectFollowUp |
pageInfo alan listeler (ListProducts, ListCollections, ListGiftCards, ListMetaobjects gibi) bir sayfa ve sonraki sayfanın page_info imlecini döner; son sayfada imleç boştur.
Webhook doğrulamak
VerifyWebhookTopic, tek konuya hizmet eden bir adres içindir: imzayı denetler ve imzalı konu beklenen konu değilse isteği reddeder. Şablonun bütün webhook'ları şu sarmalayıcıdan geçer:
func (s *server) webhook(topic string, h func(storeID int64, body []byte) error) http.HandlerFunc {
return func(w http.ResponseWriter, r *http.Request) {
wh, err := appsdk.VerifyWebhookTopic(r, topic, s.verifier.Secrets...)
if err != nil {
appsdk.WriteError(w, http.StatusUnauthorized, "invalid_signature", "the signature or topic doesn't match")
return
}
var head struct {
StoreID int64 `json:"store_id"`
}
if json.Unmarshal(wh.Body, &head) != nil || !appsdk.ValidID(head.StoreID) {
appsdk.WriteError(w, http.StatusBadRequest, "invalid_json", "want a JSON body with store_id")
return
}
if err := h(head.StoreID, wh.Body); err != nil {
log.Printf("webhook %s for store %d: %v", topic, head.StoreID, err)
appsdk.WriteError(w, http.StatusInternalServerError, "internal_error", "the app couldn't handle the webhook")
return
}
w.WriteHeader(http.StatusOK)
}
}
mux.HandleFunc("POST /webhooks/app-uninstalled", s.webhook(appsdk.TopicAppUninstalled, s.forget))
mux.HandleFunc("POST /privacy/customers-data-request", s.webhook(appsdk.TopicCustomersDataRequest, nothingKept))
Dönen Webhook değeri doğrulanmış Body, Topic, EventID, StoreDomain ve TriggeredAt alanlarını taşır; bu başlıkları kendiniz okumayın. Konu adları sabittir (appsdk.TopicOrdersPaid ve diğerleri).
Oturum jetonunu doğrulamak
Yönetim panelindeki sayfanız sunucunuzu App Bridge'in oturum jetonuyla çağırır:
tok, err := s.verifier.VerifySessionToken(appsdk.BearerToken(r), s.clientID)
if err == nil && tok.Issuer != s.adminOrigin {
err = appsdk.ErrBadSessionToken
}
var store string
if err == nil {
store, err = s.platform.StoreFromDest(tok.Dest)
}
if err != nil {
appsdk.WriteError(w, http.StatusUnauthorized, "invalid_session_token", "Oturum doğrulanamadı.")
return
}
tok.StoreID mağazanın kimliğidir; kaydınızı onunla bulun.
Sayfanın kendisi için SDK şunları verir: appsdk.EmbeddedPage (sayfanın hazır kabuğu, içerik güvenliği kuralıyla; Routes sayfayı ve yüklediği dosyaları bağlar), appsdk.ServeAppBridge ve appsdk.ServeAppPage (istemci kitaplığını ve sayfa parçalarını sunar), appsdk.AppBridgeVersion ve appsdk.AppPageVersion (bağlantıların ?v= değerleri), appsdk.NewStaticFiles (static/ klasörünü sürümlü adreslerle sunar), appsdk.DesignSystemHead, appsdk.DesignSystemCSP ve appsdk.AppLoading (Biticaret Design System'in bt-* öğeleri, onların içerik güvenliği kuralı ve yükleniyor durumu). Sayfanın nasıl kurulduğu: Yönetim panelinde uygulama sayfası.
Uygulama vekilini doğrulamak
func (s *server) proxy(w http.ResponseWriter, r *http.Request) {
req, err := s.verifier.VerifyProxy(r.URL.Query())
if err != nil {
appsdk.WriteError(w, http.StatusUnauthorized, "invalid_signature", "the proxy signature doesn't match")
return
}
// req.StoreID mağaza, req.CustomerID giriş yapmış müşteridir (ziyaretçi için 0).
fmt.Fprintf(w, "store %d, customer %d", req.StoreID, req.CustomerID)
}
Sahte platformla test
appsdktest, bir uygulamanın testleri için sahte bir platformdur: bir mağaza için OAuth adreslerini ve /api/v1 kaynaklarını sunar, gönderdiklerini platform gibi imzalar ve uygulamanın yaptığı çağrıları kaydeder.
Paket platformun deposundadır (github.com/biticaret/biticaret/pkg/appsdk/appsdktest); şablonun sdk/ kopyası bugün onu içermez, yani bu örnek platformun deposundaki uygulamalarda derlenir.
func TestProductTitles(t *testing.T) {
p := appsdktest.New(t)
p.Scope = appsdk.ScopeReadProducts
p.AddProduct(appsdk.Product{ID: 101, Title: "Rehber"})
c := &appsdk.Client{StoreURL: p.StoreURL(), Token: p.CurrentToken(), HTTPClient: &http.Client{Transport: p.Transport()}}
products, _, err := c.ListProducts(context.Background(), "", 25)
if err != nil {
t.Fatal(err)
}
if len(products) != 1 || products[0].Title != "Rehber" {
t.Fatalf("products = %+v", products)
}
}
Uygulamanın kendisini test etmek için:
p.AppSDK()uygulamaya verilecekappsdk.Platformdeğeridir;p.Transport()uygulamanın HTTP istemcisine verilir.p.ClientID,p.ClientSecretvep.RedirectURIuygulamanın kimliğidir;RedirectURIkurulumdan önce uygulamanın OAuth dönüş adresi olmalıdır.p.AppURLLink(appURL)yönetim panelinin Kur ve Aç düğmelerinin açtığı imzalı bağlantıdır;p.CallbackURL(state)taze bir kodla imzalı OAuth dönüşüdür.p.SendWebhook(appURL, topic, body)uygulamaya platform gibi imzalı bir webhook gönderir;p.SendSMSWebhookbir SMS sağlayıcıyasms/sendgönderir,p.SMSes()vep.SMSStatusReports()uygulamanın istediği SMS'leri ve bildirdiği durumları verir.p.SessionToken(staffID)bir oturum jetonu imzalar.p.Calls()uygulamanın platforma yaptığı çağrıları verir.p.AddCollection,p.AddCustomerSegment(segmentin müşterileriyle),p.AddGiftCardvep.SetTranslationSourceuygulamanın okuyacağı koleksiyonları, segmentleri, hediye kartlarını ve çevrilecek metinleri ekler;p.GiftCard,p.Metaobjectsvep.Translationuygulamanın yazdıklarını verir.$app:ile başlayan meta nesne türlerip.AppSlug(boşsatest-app) uygulamasınındır.
Yönetim paneli sayfasının betiği için:
appsdktest.DrawAdminPage(t, appsdktest.AdminScript{…})sayfanın betiğini node'da, küçük bir DOM, sahte bir App Bridge ve sayfa parçalarıyla çalıştırır ve çizdiğini döner:Responsesuygulamanın sunucusunun JSON yanıtlarıdır,Stepssırayla basılacak düğmelerdir (bir düğmenin etiketi,@primary,@back,@secondary:<etiket>,@next,@previous). node yoksa test atlanır.appsdktest.CheckDesignSystem(t, sayfa, csp)sayfanın SDK'nın sabitlediği tasarım sistemi sürümünü bağladığını ve kaldırılmış eski sınıfları kullanmadığını denetler.