التخطي إلى المحتوى الرئيسي

API Overview

هذا العرض يوضح لك فقط كيفية استخدام واجهات برمجة تطبيقات Casbin ولا يشرح كيفية تثبيت Casbin أو كيف يعمل. يمكنك العثور على هذه الدروس هنا: تثبيت Casbin و كيف يعمل Casbin. لذا، عندما تبدأ بقراءة هذا الدرس، نفترض أنك قد قمت بتثبيت Casbin بالكامل واستوردته إلى كودك.

واجهة برمجة تطبيقات Enforce​

لنبدأ مع واجهات برمجة تطبيقات Enforce الخاصة بـ Casbin. سنقوم بتحميل نموذج RBAC من model.conf وتحميل السياسات من policy.csv. يمكنك التعرف على بناء جملة النموذج هنا، ولن نناقش ذلك في هذا الدرس. نفترض أنك تستطيع فهم ملفات الإعدادات المعطاة أدناه:

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

بعد قراءة ملفات الإعدادات، يرجى قراءة الكود التالي.

// 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")

هذا الكود يقوم بتحميل نموذج التحكم في الوصول والسياسات من ملفات محلية. الدالة casbin.NewEnforcer() ستعيد مُنفذ. سوف تتعرف على معامليها كمسارات ملفات وتحمل الملفات من هناك. الأخطاء التي حدثت في العملية يتم تخزينها في المتغير err. هذا الكود يستخدم المحول الافتراضي لتحميل النموذج والسياسات، وبالطبع، يمكنك تحقيق نفس النتيجة باستخدام محول طرف ثالث.

الكود ok, err := enforcer.Enforce("alice", "data1", "read") يستخدم لتأكيد أذونات الوصول. إذا كانت Alice تستطيع الوصول إلى data1 بعملية القراءة، فإن القيمة المعادة لـ ok ستكون true؛ وإلا، ستكون false. في هذا المثال، قيمة ok هي true.

EnforceEx API​

أحيانًا قد تتساءل عن السياسة التي سمحت بالطلب، لذا فقد أعددنا الدالة EnforceEx(). يمكنك استخدامها مثل هذا:

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

دالة EnforceEx() ستعيد السلسلة الدقيقة للسياسة في قيمة العودة reason. في هذا المثال، amber هو دور admin، لذا فإن السياسة p, admin, data1, read سمحت بهذا الطلب ليكون true. ناتج هذا الكود موجود في التعليق.

قدمت Casbin العديد من واجهات برمجة التطبيقات المشابهة لهذه. تضيف هذه الواجهات بعض الوظائف الإضافية إلى الوظائف الأساسية. تشمل:

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

    هذه الدالة تستخدم مطابق.

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

    هذه مزيج من EnforceWithMatcher() و EnforceEx().

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

    هذه الدالة تسمح بقائمة من الوظائف وتعيد مصفوفة.

هذه حالة استخدام بسيطة لـ Casbin. يمكنك استخدام Casbin لبدء خادم تفويض باستخدام هذه الواجهات. سنعرض لك بعض أنواع واجهات برمجة التطبيقات الأخرى في الفقرات التالية.

واجهة برمجة تطبيقات الإدارة​

واجهة برمجة تطبيقات الاسترجاع​

تستخدم هذه الواجهات لاسترجاع كائنات محددة في السياسات. في هذا المثال، نحن نقوم بتحميل مُنفذ واسترجاع شيء منه.

يرجى النظر إلى الكود التالي:

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)

مشابهًا للمثال السابق، الأربعة أسطر الأولى تستخدم لتحميل المعلومات الضرورية من ملفات محلية. لن نناقش ذلك هنا بعد الآن.

الكود allSubjects := enforcer.GetAllSubjects() يسترجع جميع الأشخاص في ملف السياسة ويعيدهم كمصفوفة. ثم نقوم بطباعة تلك المصفوفة.

عادةً، ناتج الكود يجب أن يكون:

[admin alice bob]

يمكنك أيضًا تغيير الدالة GetAllSubjects() إلى GetAllNamedSubjects() للحصول على قائمة الأشخاص التي تظهر في السياسة المسماة الحالية.

بشكل مماثل، أعددنا دوال GetAll لـ Objects, Actions, Roles. للوصول إلى هذه الدوال، تحتاج فقط إلى استبدال كلمة Subject في اسم الدالة بالفئة المرغوبة.

بالإضافة إلى ذلك، هناك المزيد من الحصولات المتاحة للسياسات. طريقة الاستدعاء وقيم العودة مشابهة لتلك المذكورة أعلاه.

  • يسترجع policy = e.GetPolicy() جميع قواعد التفويض في السياسة.
  • يسترجع filteredPolicy := e.GetFilteredPolicy(0, "alice") جميع قواعد التفويض في السياسة مع مرشحات الحقول المحددة.
  • يسترجع namedPolicy := e.GetNamedPolicy("p") جميع قواعد التفويض في السياسة المسماة.
  • يسترجع filteredNamedPolicy = e.GetFilteredNamedPolicy("p", 0, "bob") جميع قواعد التفويض في السياسة المسماة مع مرشحات الحقول المحددة.
  • يسترجع groupingPolicy := e.GetGroupingPolicy() جميع قواعد توريث الأدوار في السياسة.
  • يسترجع filteredGroupingPolicy := e.GetFilteredGroupingPolicy(0, "alice") جميع قواعد توريث الأدوار في السياسة مع مرشحات الحقول المحددة.
  • يسترجع namedGroupingPolicy := e.GetNamedGroupingPolicy("g") جميع قواعد توريث الأدوار في السياسة.
  • يسترجع namedGroupingPolicy := e.GetFilteredNamedGroupingPolicy("g", 0, "alice") جميع قواعد توريث الأدوار في السياسة مع مرشحات الحقول المحددة.

إضافة، حذف، تحديث واجهة برمجة التطبيقات​

Casbin توفر مجموعة متنوعة من واجهات برمجة التطبيقات لإضافة، حذف أو تعديل السياسات بشكل ديناميكي أثناء التشغيل.

يوضح الكود التالي كيفية إضافة، إزالة، وتحديث السياسات، بالإضافة إلى كيفية التحقق من وجود سياسة:

// 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

باستخدام هذه الواجهات، يمكنك تعديل سياساتك بشكل ديناميكي. بالمثل، قدمنا واجهات برمجة التطبيقات المماثلة لـ FilteredPolicy, NamedPolicy, FilteredNamedPolicy, GroupingPolicy, NamedGroupingPolicy, FilteredGroupingPolicy, FilteredNamedGroupingPolicy. لاستخدامها، ببساطة استبدل كلمة Policy في اسم الوظيفة بالفئة المناسبة.

علاوة على ذلك، من خلال تغيير المعاملات إلى مصفوفات، يمكنك إجراء تحرير دفعي لسياساتك.

على سبيل المثال، ضع في اعتبارك وظائف مثل هذه:

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

إذا قمنا بتغيير Policy إلى Policies وتعديل المعاملات على النحو التالي:

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

ثم يمكننا إجراء تحرير دفعي لهذه السياسات.

يمكن تطبيق نفس العمليات أيضًا على GroupingPolicy, NamedGroupingPolicy.

واجهة برمجة التطبيقات AddEx​

Casbin توفر سلسلة واجهات برمجة التطبيقات AddEx لمساعدة المستخدمين على إضافة القواعد دفعة واحدة.

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)

الفرق بين هذه الطرق والطرق بدون اللاحقة Ex هو أنه إذا كانت إحدى القواعد موجودة بالفعل، فإنها ستستمر في التحقق من القاعدة التالية بدلاً من العودة بقيمة خاطئة على الفور.

على سبيل المثال، دعونا نقارن بين AddPolicies و AddPoliciesEx.

يمكنك تشغيل ومراقبة الكود التالي عن طريق نسخه في الاختبار تحت 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 توفر بعض واجهات برمجة التطبيقات لتعديل نموذج RBAC والسياسات. إذا كنت مطلعًا على RBAC، يمكنك استخدام هذه الواجهات بسهولة.

هنا، نعرض لك فقط كيفية استخدام واجهات برمجة التطبيقات RBAC الخاصة بـ Casbin ولن نتحدث عن RBAC نفسه. يمكنك الحصول على المزيد من التفاصيل هنا.

نستخدم الكود التالي لتحميل النموذج والسياسات، تمامًا كما في السابق.

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

ثم، يمكننا استخدام نموذج المنفذ enforcer للوصول إلى هذه الواجهات.

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

GetRolesForUser() يعيد مصفوفة تحتوي على جميع الأدوار التي لدى amber. في هذا المثال، لدى amber دور واحد فقط، وهو admin، لذا فإن المصفوفة roles هي [admin]. بالمثل، يمكنك استخدام GetUsersForRole() للحصول على المستخدمين الذين ينتمون إلى دور. قيمة العودة لهذه الوظيفة أيضًا عبارة عن مصفوفة.

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

يمكنك استخدام HasRoleForUser() للتأكيد على ما إذا كان المستخدم ينتمي إلى الدور. في هذا المثال، amber عضو في admin، لذا فإن قيمة العودة للوظيفة هي true.

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

يمكنك استخدام DeletePermission() لحذف إذن.

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

واستخدم DeletePermissionForUser() لحذف إذن لمستخدم.

Casbin لديها العديد من واجهات برمجة التطبيقات مثل هذه. طرق الاستدعاء وقيم العودة لها نفس الأسلوب كما في واجهات برمجة التطبيقات المذكورة أعلاه. يمكنك العثور على هذه الواجهات في الوثائق التالية.