Langkau ke kandungan utama

API Overview

Gambaran ini hanya menunjukkan kepada anda cara menggunakan API Casbin dan tidak menerangkan bagaimana Casbin dipasang atau bagaimana ia berfungsi. Anda boleh mencari tutorial tersebut di sini: Pemasangan Casbin dan Cara Casbin Berfungsi. Oleh itu, apabila anda mula membaca tutorial ini, kami menganggap bahawa anda telah memasang dan mengimport Casbin sepenuhnya ke dalam kod anda.

Lakukan API​

Mari kita mulai dengan API Lakukan Casbin. Kami akan memuatkan model RBAC dari model.conf dan memuatkan polisi dari policy.csv. Anda boleh belajar tentang sintaks Model di sini, dan kami tidak akan membincangkannya dalam tutorial ini. Kami menganggap bahawa anda boleh memahami fail konfigurasi yang diberikan di bawah:

model.conf

[request_definition]
r = sub, obj, act

[policy_definition]
p = sub, obj, act

[role_definition]
g = _, _

[policy_effect]
e = some(where (p.eft == allow))

[matchers]
m = g(r.sub, p.sub) && r.obj == p.obj && r.act == p.act

policy.csv

p, admin, data1, read
p, admin, data1, write
p, admin, data2, read
p, admin, data2, write
p, alice, data1, read
p, bob, data2, write
g, amber, admin
g, abc, admin

Selepas membaca fail konfigurasi, sila baca kod berikut.

// Load information from files.
enforcer, err := casbin.NewEnforcer("./example/model.conf", "./example/policy.csv")
if err != nil {
    log.Fatalf("Error, detail: %s", err)
}
ok, err := enforcer.Enforce("alice", "data1", "read")

Kod ini memuatkan model kawalan akses dan polisi dari fail lokal. Fungsi casbin.NewEnforcer() akan mengembalikan enforcer. Ia akan mengenali dua parameternya sebagai laluan fail dan memuatkan fail dari sana. Ralat yang berlaku dalam proses ini disimpan dalam pemboleh ubah err. Kod ini menggunakan penyesuai lalai untuk memuatkan model dan dasar, dan tentu saja, anda boleh mencapai hasil yang sama dengan menggunakan penyesuai pihak ketiga.

Kod ok, err := enforcer.Enforce("alice", "data1", "read") digunakan untuk mengesahkan kebenaran akses. Jika Alice boleh mengakses data1 dengan operasi baca, nilai yang dikembalikan oleh ok akan menjadi true; jika tidak, ia akan menjadi false. Dalam contoh ini, nilai ok adalah true.

EnforceEx API​

Kadang kala anda mungkin tertanya-tanya dasar mana yang membenarkan permintaan, jadi kami telah menyediakan fungsi EnforceEx(). Anda boleh menggunakannya seperti ini:

ok, reason, err := enforcer.EnforceEx("amber", "data1", "read")
fmt.Println(ok, reason) // true [admin data1 read]

Fungsi EnforceEx() akan mengembalikan rentetan dasar yang tepat dalam nilai kembali reason. Dalam contoh ini, amber mempunyai peranan admin, jadi polisi p, admin, data1, read membenarkan permintaan ini menjadi true. Output kod ini ada dalam komen.

Casbin telah menyediakan banyak API yang serupa dengan ini. API ini menambah beberapa fungsi tambahan kepada yang asas. Antara lain:

  • ok, err := enforcer.EnforceWithMatcher(matcher, request)

    Fungsi ini menggunakan pencocok.

  • ok, reason, err := enforcer.EnforceExWithMatcher(matcher, request)

    Ini adalah gabungan EnforceWithMatcher() dan EnforceEx().

  • boolArray, err := enforcer.BatchEnforce(requests)

    Fungsi ini membolehkan senarai pekerjaan dan mengembalikan array.

Ini adalah kes penggunaan mudah Casbin. Anda boleh menggunakan Casbin untuk memulakan pelayan pengkalan dengan menggunakan API ini. Kami akan menunjukkan kepada anda beberapa jenis API lain dalam perenggan berikut.

API Pengurusan​

API Dapatkan​

API ini digunakan untuk mengambil objek tertentu dalam dasar. Dalam contoh ini, kami memuatkan enforcer dan mengambil sesuatu daripadanya.

Sila lihat kod berikut:

enforcer, err := casbin.NewEnforcer("./example/model.conf", "./example/policy.csv")
if err != nil {
    fmt.Printf("Error, details: %s\n", err)
}
allSubjects := enforcer.GetAllSubjects()
fmt.Println(allSubjects)

Serupa dengan contoh sebelumnya, empat baris pertama digunakan untuk memuatkan maklumat yang diperlukan dari fail tempatan. Kami tidak akan membincangkan perkara itu di sini lagi.

Kod allSubjects := enforcer.GetAllSubjects() mengambil semua subjek dalam fail polisi dan mengembalikannya sebagai array. Kami kemudian mencetak array tersebut.

Biasanya, output kod tersebut sepatutnya:

[admin alice bob]

Anda juga boleh menukar fungsi GetAllSubjects() kepada GetAllNamedSubjects() untuk mendapatkan senarai subjek yang muncul dalam polisi bernama semasa.

Begitu juga, kami telah menyediakan fungsi GetAll untuk Objects, Actions, Roles. Untuk mengakses fungsi-fungsi ini, anda hanya perlu menggantikan perkataan Subject dalam nama fungsi dengan kategori yang diinginkan.

Selain itu, terdapat lebih banyak getter yang tersedia untuk polisi. Kaedah panggilan dan nilai pulangan adalah serupa dengan yang dinyatakan di atas.

  • policy = e.GetPolicy() mengambil semua peraturan kebenaran dalam polisi.
  • filteredPolicy := e.GetFilteredPolicy(0, "alice") mengambil semua peraturan keizinan dalam dasar dengan penapis medan yang ditentukan.
  • namedPolicy := e.GetNamedPolicy("p") mengambil semua peraturan keizinan dalam dasar bernama.
  • filteredNamedPolicy = e.GetFilteredNamedPolicy("p", 0, "bob") mengambil semua peraturan keizinan dalam dasar bernama dengan penapis medan yang ditentukan.
  • groupingPolicy := e.GetGroupingPolicy() mengambil semua peraturan warisan peranan dalam dasar.
  • filteredGroupingPolicy := e.GetFilteredGroupingPolicy(0, "alice") mengambil semua peraturan warisan peranan dalam dasar dengan penapis medan yang ditentukan.
  • namedGroupingPolicy := e.GetNamedGroupingPolicy("g") mengambil semua peraturan warisan peranan dalam dasar.
  • namedGroupingPolicy := e.GetFilteredNamedGroupingPolicy("g", 0, "alice") mengambil semua peraturan warisan peranan dalam dasar dengan penapis medan yang ditentukan.

Tambah, Hapus, Kemas Kini API​

Casbin menyediakan pelbagai API untuk menambah, menghapus, atau mengubah suai dasar secara dinamik pada waktu runtime.

Kod berikut menunjukkan bagaimana untuk menambah, mengeluarkan, dan mengemas kini dasar, serta bagaimana untuk memeriksa sama ada dasar wujud:

// load information from files
enforcer, err := casbin.NewEnforcer("./example/model.conf", "./example/policy.csv")
if err != nil {
    fmt.Printf("Error, details: %s\n", err)
}

// add a policy and use HasPolicy() to confirm
enforcer.AddPolicy("added_user", "data1", "read")
hasPolicy := enforcer.HasPolicy("added_user", "data1", "read")
fmt.Println(hasPolicy) // true, the policy was added successfully

// remove a policy and use HasPolicy() to confirm
enforcer.RemovePolicy("alice", "data1", "read")
hasPolicy = enforcer.HasPolicy("alice", "data1", "read")
fmt.Println(hasPolicy) // false, the policy was removed successfully

// update a policy and use HasPolicy() to confirm
enforcer.UpdatePolicy([]string{"added_user", "data1", "read"}, []string{"added_user", "data1", "write"})
hasPolicy = enforcer.HasPolicy("added_user", "data1", "read")
fmt.Println(hasPolicy) // false, the original policy has expired
hasPolicy = enforcer.HasPolicy("added_user", "data1", "write")
fmt.Println(hasPolicy) // true, the new policy is in effect

Dengan menggunakan API ini, anda boleh mengedit polisi anda secara dinamik. Begitu juga, kami telah menyediakan API yang serupa untuk FilteredPolicy, NamedPolicy, FilteredNamedPolicy, GroupingPolicy, NamedGroupingPolicy, FilteredGroupingPolicy, FilteredNamedGroupingPolicy. Untuk menggunakannya, gantikan sahaja perkataan Policy dalam nama fungsi dengan kategori yang sesuai.

Selain itu, dengan mengubah parameter kepada tatasusunan, anda boleh melakukan pengeditan kumpulan polisi anda.

Sebagai contoh, pertimbangkan fungsi seperti ini:

enforcer.UpdatePolicy([]string{"eve", "data3", "read"}, []string{"eve", "data3", "write"})

Jika kita menukar Policy kepada Policies dan mengubah parameter seperti berikut:

enforcer.UpdatePolicies([][]string{{"eve", "data3", "read"}, {"jack", "data3", "read"}}, [][]string{{"eve", "data3", "write"}, {"jack", "data3", "write"}})

maka kita boleh melakukan pengeditan kumpulan polisi ini.

Operasi yang sama juga boleh dikenakan kepada GroupingPolicy, NamedGroupingPolicy.

API AddEx​

Casbin menyediakan siri API AddEx untuk membantu pengguna menambah peraturan secara kumpulan.

AddPoliciesEx(rules [][]string) (bool, error)
AddNamedPoliciesEx(ptype string, rules [][]string) (bool, error)
AddGroupingPoliciesEx(rules [][]string) (bool, error)
AddNamedGroupingPoliciesEx(ptype string, rules [][]string) (bool, error)
SelfAddPoliciesEx(sec string, ptype string, rules [][]string) (bool, error)

Perbezaan antara kaedah-kaedah ini dan kaedah-kaedah tanpa akhiran Ex adalah bahawa jika salah satu peraturan sudah wujud, mereka akan terus menyemak peraturan seterusnya bukannya mengembalikan salah serta-merta.

Sebagai contoh, mari bandingkan AddPolicies dan AddPoliciesEx.

Anda boleh menjalankan dan mengamati kod berikut dengan menyalinnya ke dalam ujian di bawah casbin.

func TestDemo(t *testing.T) {
    e, err := NewEnforcer("examples/basic_model.conf", "examples/basic_policy.csv")
    if err != nil {
        fmt.Printf("Error, details: %s\n", err)
    }
    e.ClearPolicy()
    e.AddPolicy("user1", "data1", "read")
    fmt.Println(e.GetPolicy())
    testGetPolicy(t, e, [][]string{{"user1", "data1", "read"}})

    // policy {"user1", "data1", "read"} now exists

    // Use AddPolicies to add rules in batches
    ok, _ := e.AddPolicies([][]string{{"user1", "data1", "read"}, {"user2", "data2", "read"}})
    fmt.Println(e.GetPolicy())
    // {"user2", "data2", "read"} failed to add because {"user1", "data1", "read"} already exists
    // AddPolicies returns false and no other policies are checked, even though they may not exist in the existing ruleset
    // ok == false
    fmt.Println(ok)
    testGetPolicy(t, e, [][]string{{"user1", "data1", "read"}})

    // Use AddPoliciesEx to add rules in batches
    ok, _ = e.AddPoliciesEx([][]string{{"user1", "data1", "read"}, {"user2", "data2", "read"}})
    fmt.Println(e.GetPolicy())
    // {"user2", "data2", "read"} is added successfully
    // because AddPoliciesEx automatically filters the existing {"user1", "data1", "read"}
    // ok == true
    fmt.Println(ok)
    testGetPolicy(t, e, [][]string{{"user1", "data1", "read"}, {"user2", "data2", "read"}})
}

RBAC API​

Casbin menyediakan beberapa API untuk anda mengubah model dan polisi RBAC. Jika anda biasa dengan RBAC, anda boleh menggunakan API ini dengan mudah.

Di sini, kami hanya menunjukkan kepada anda cara menggunakan API RBAC Casbin dan tidak akan membincangkan tentang RBAC itu sendiri. Anda boleh mendapatkan lebih banyak butiran di sini.

Kami menggunakan kod berikut untuk memuatkan model dan polisi, sama seperti sebelumnya.

enforcer, err := casbin.NewEnforcer("./example/model.conf", "./example/policy.csv")
if err != nil {
    fmt.Printf("Error, details: %s\n", err)
}

Kemudian, kita boleh menggunakan contoh Enforcer enforcer untuk mengakses API ini.

roles, err := enforcer.GetRolesForUser("amber")
fmt.Println(roles) // [admin]
users, err := enforcer.GetUsersForRole("admin")
fmt.Println(users) // [amber abc]

GetRolesForUser() mengembalikan satu tatasusunan yang mengandungi semua peranan yang dimiliki oleh amber. Dalam contoh ini, amber hanya mempunyai satu peranan, iaitu admin, jadi tatasusunan roles adalah [admin]. Begitu juga, anda boleh menggunakan GetUsersForRole() untuk mendapatkan pengguna yang tergolong dalam suatu peranan. Nilai pulangan fungsi ini juga adalah satu tatasusunan.

enforcer.HasRoleForUser("amber", "admin") // true

Anda boleh menggunakan HasRoleForUser() untuk mengesahkan sama ada pengguna itu tergolong dalam peranan tersebut. Dalam contoh ini, amber adalah ahli dari admin, jadi nilai pulangan fungsi tersebut adalah true.

fmt.Println(enforcer.Enforce("bob", "data2", "write")) // true
enforcer.DeletePermission("data2", "write")
fmt.Println(enforcer.Enforce("bob", "data2", "write")) // false

Anda boleh menggunakan DeletePermission() untuk memadamkan satu kebenaran.

fmt.Println(enforcer.Enforce("alice", "data1", "read")) // true
enforcer.DeletePermissionForUser("alice", "data1", "read")
fmt.Println(enforcer.Enforce("alice", "data1", "read")) // false

Dan gunakan DeletePermissionForUser() untuk memadamkan satu kebenaran untuk seorang pengguna.

Casbin mempunyai banyak API seperti ini. Kaedah pemanggilan dan nilai pulangan mereka mempunyai gaya yang sama dengan API di atas. Anda boleh mencari API ini dalam dokumen seterusnya.