التشغيل السريع: إنشاء تطبيق Go مع `gocql` العميل لإدارة Azure Cosmos DB لبيانات Apache Cassandra

مقالة
08/15/2024

ينطبق على: كاساندرا

Azure Cosmos DB عبارة عن خدمة قاعدة بيانات متعددة النماذج تتيح لك إنشاء قواعد بيانات المستندات والجدول والقيمة الرئيسية والرسم البياني والاستعلام عنها بسرعة مع إمكانات التوزيع العام والقياس الأفقي. في هذا التشغيل السريع، ستبدأ بإنشاء Azure Cosmos DB لحساب Apache Cassandra. ستقوم بعد ذلك بتشغيل تطبيق Go لإنشاء مفتاح Cassandra، وجدول، وتنفيذ بعض العمليات. يستخدم تطبيق Go هذا gocql، وهو عميل Cassandra خاص بلغة Go.

المتطلبات الأساسية

حساب Azure مع اشتراك نشط. أنشئ حسابًا مجانًا. أو جرب Azure Cosmos DB مجاناً بدون اشتراك Azure.
Go مُثبَّت على جهاز الكمبيوتر لديك، ومعرفة عملية بـ Go.
Git.

أنشئ «حساب قاعدة البيانات».

قبل أن تتمكن من إنشاء قاعدة بيانات، تحتاج إلى إنشاء حساب Cassandra باستخدام Azure Cosmos DB.

من قائمة مدخل Azure أو الصفحة الرئيسية، حدد Create a resource.
في الصفحة جديد، ابحث عن Azure Cosmos DB وحدده.
في صفحة Azure Cosmos DB ، حدد Create.
في صفحة API ، حدد Create ضمن قسم Cassandra .

تحدد واجهة API نوع الحساب المقرر إنشاؤه. يوفر Azure Cosmos DB خمس واجهات برمجة تطبيقات: NoSQL لقواعد بيانات المستندات، وGremlin لقواعد بيانات الرسم البياني، وMongoDB لقواعد بيانات المستندات، وAzure Table، وCassandra. يجب إنشاء حساب منفصل لكل API.

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

تعرف على المزيد حول واجهة برمجة التطبيقات ل Cassandra.

في صفحة إنشاء حساب Azure Cosmos DB، أدخل الإعدادات الأساسية لحساب Azure Cosmos DB الجديد.

الإعداد	قيمة	‏‏الوصف
الاشتراك	اشتراكك	حدد اشتراك Azure الذي تريد استخدامه لحساب Azure Cosmos DB هذا.
مجموعة الموارد	إنشاء و الجديدة في ثم أدخل نفس اسم الحساب	حدد إنشاء جديد. ثم أدخل اسم مجموعة موارد جديدة لحسابك. للبساطة، استخدم نفس اسم حساب Azure Cosmos DB.
اسم الحساب	أدخل اسماً فريداً	أدخل اسماً فريداً لتعريف حساب Azure Cosmos DB الخاص بك. سيكون حساب URI الخاص بك cassandra.cosmos.azure.com وسيُلحق باسم حسابك الفريد. لا يمكن أن يستخدم اسم الحساب سوى الأحرف الصغيرة والأرقام والواصلات (-)، ويجب أن يتراوح طولها بين 3 و31 حرفًا.
الموقع	المنطقة الأقرب إلى مستخدميك	حدد موقعًا جغرافيًّا لاستضافة حساب Azure Cosmos DB. استخدم الموقع الأقرب إلى المستخدمين لمنحهم أسرع وصول إلى البيانات.
وضع السعة	معدل النقل المقدم أو بلا خادم	حدد "Provisioned throughput" لإنشاء حساب في وضع معدل النقل المتوفر. حدد Serverless لإنشاء حساب في وضع دون خادم.
تطبيق خصم طبقة Azure Cosmos DB المجاني	تطبيق أو عدم تطبيق	مع Azure Cosmos DB الطبقة الحرة، سوف تحصل على أول 1000 RU / ثانية و25 غيغابايت من التخزين مجانًا في حساب. تعرف على المزيد حول الطبقة المجانية.
ضع حدُا لمعدل نقل الحساب	حدد للحد من معدل نقل الحساب	وهذا مفيد إذا كنت تريد تحديد إجمالي معدل نقل الحساب إلى قيمة معينة.

إشعار

يمكنك الحصول على حساب طبقةAzure Cosmos DB مجانية واحدة لكل اشتراك Azure ويجب عليك الاشتراك عند إنشاء الحساب. إذا لم تشاهد خيار تطبيق خصم الطبقة المجانية، فهذا يعني أنه تم تمكين حساب آخر في الاشتراك بالفعل مع طبقة مجانية.

صفحة الحساب الجديدة ل Azure Cosmos DB ل Apache Cassandra

في علامة تبويب Global Distributionكوّن التفاصيل التالية. يمكنك ترك القيم الافتراضية لغرض هذه البداية السريعة:

الإعداد	قيمة	‏‏الوصف
التكرار الجغرافي	تعطيل	تمكين التوزيع العمومي على حسابك أو تعطيله عن طريق إقران منطقتك بمنطقة زوج. يمكنك إضافة المزيد من المناطق إلى حسابك لاحقًا.
كتابات متعددة المناطق	تعطيل	تتيح لك إمكانية الكتابة متعددة المناطق الاستفادة من الإنتاجية المقدمة لقواعد البيانات والحاويات الخاصة بك في جميع أنحاء العالم.
مجموعات التوافر	تعطيل	مناطق التوفر هي مواقع معزولة داخل منطقة Azure. تتكون كل منطقة من مركز بيانات واحد أو أكثر مزود بمصدر طاقة وتبريد وشبكات مستقلة.

إشعار

الخيارات التالية غير متوفرة إذا قمت بتحديد دون خادمباعتبارهاوضع السعة:

تطبيق خصم من الدرجة المجانية
Geo-redundancy
كتابات متعددة المناطق

اختياريًا يمكنك تكوين تفاصيل إضافية في علامات التبويب التالية:
- شبكة الاتصال - تكوين الوصول من شبكة اتصال ظاهرية.
- نهج النسخ الاحتياطي - تكوين نهج النسخ الاحتياطي الدوري أو المستمر.
- التشفير - استخدم إما مفتاحًا مُدارًا بواسطة الخدمة أو مفتاحًا مُدارًا من قِبل العميل.
- العلامات - العلامات هي أزواج الاسم/القيم التي تمكنك من تصنيف الموارد وعرض الفوترة الموحدة من خلال تطبيق نفس العلامة على موارد متعددة ومجموعات موارد متعددة.
حدد "Review + create".
راجع الإعدادات، ثم حدد Create. يستغرق إنشاء جهاز ظاهر بضع دقائق. انتظر حتى يتم عرض صفحة المدخل، اكتمل النشر.
حدد الانتقال إلى المورد للانتقال إلى صفحة حساب Azure Cosmos DB.

استنساخ نموذج التطبيق

ابدأ باستنساخ التطبيق من GitHub.

افتح موجه أوامر وقم بإنشاء مجلد جديد وقم بتسميته git-samples.
```
md "C:\git-samples"
```
افتح نافذة طرفية git، مثل git bash. استخدم الأمر cd للتغيير إلى المجلد الجديد وتثبيت نموذج التطبيق.
```
cd "C:\git-samples"
```
قم بتشغيل الأمر التالي لاستنساخ مستودع النموذج. يقوم هذا الأمر بإنشاء نسخة من نموذج التطبيق على جهاز الكمبيوتر الخاص بك.
```
git clone https://github.com/Azure-Samples/azure-cosmos-db-cassandra-go-getting-started.git
```

مراجعة الرمز

هذه الخطوة اختيارية. إذا كنت مهتمًا بمعرفة كيفية إنشاء التعليمات البرمجية لموارد قاعدة البيانات، يمكنك مراجعة قصاصات التعليمات البرمجية التالية. وإلا، يمكنك الانتقال مباشرة إلى لتشغيل التطبيق

تُرجع الدالة GetSession (جزء من utils\utils.go) *gocql.Session الذي يُستخدم لتنفيذ عمليات المجموعة مثل الإدراج والعثور وما إلى ذلك.

func GetSession(cosmosCassandraContactPoint, cosmosCassandraPort, cosmosCassandraUser, cosmosCassandraPassword string) *gocql.Session {
    clusterConfig := gocql.NewCluster(cosmosCassandraContactPoint)
    port, err := strconv.Atoi(cosmosCassandraPort)
    
    clusterConfig.Authenticator = gocql.PasswordAuthenticator{Username: cosmosCassandraUser, Password: cosmosCassandraPassword}
    clusterConfig.Port = port
    clusterConfig.SslOpts = &gocql.SslOptions{Config: &tls.Config{MinVersion: tls.VersionTLS12}}
    clusterConfig.ProtoVersion = 4
    
    session, err := clusterConfig.CreateSession()
    ...
    return session
}

يتم تمرير مضيف Azure Cosmos DB Cassandra إلى gocql.NewCluster الوظيفة للحصول على *gocql.ClusterConfig بنية تم تكوينها بعد ذلك لاستخدام اسم المستخدم وكلمة المرور والمنفذ وإصدار TLS المناسب (متطلبات أمان تشفير HTTPS/SSL/TLS)

ثم يتم استدعاء الدالة GetSession من main الدالة ( main.go ).

func main() {
    session := utils.GetSession(cosmosCassandraContactPoint, cosmosCassandraPort, cosmosCassandraUser, cosmosCassandraPassword)
    defer session.Close()
    ...
}

يتم قبول معلومات الاتصال وبيانات الاعتماد في شكل متغيرات البيئة (يجري حلها بأسلوب init)

func init() {
    cosmosCassandraContactPoint = os.Getenv("COSMOSDB_CASSANDRA_CONTACT_POINT")
    cosmosCassandraPort = os.Getenv("COSMOSDB_CASSANDRA_PORT")
    cosmosCassandraUser = os.Getenv("COSMOSDB_CASSANDRA_USER")
    cosmosCassandraPassword = os.Getenv("COSMOSDB_CASSANDRA_PASSWORD")

    if cosmosCassandraContactPoint == "" || cosmosCassandraUser == "" || cosmosCassandraPassword == "" {
        log.Fatal("missing mandatory environment variables")
    }
}

ثم يتم استخدامه لتنفيذ عمليات مختلفة (جزء operations\setup.go من) على Azure Cosmos DB بدءًا من إنشاء keyspace وtable.

كما يوحي الاسم، تقوم الدالة DropKeySpaceIfExists بإسقاط keyspace فقط في حالة إذا كانت موجودة.

const dropKeyspace = "DROP KEYSPACE IF EXISTS %s"

func DropKeySpaceIfExists(keyspace string, session *gocql.Session) {
    err := utils.ExecuteQuery(fmt.Sprintf(dropKeyspace, keyspace), session)
    if err != nil {
        log.Fatal("Failed to drop keyspace", err)
    }
    log.Println("Keyspace dropped")
}

تُستخدم الدالةCreateKeySpace لإنشاء keyspace ( user_profile )

const createKeyspace = "CREATE KEYSPACE %s WITH REPLICATION = { 'class' : 'NetworkTopologyStrategy', 'datacenter1' : 1 }"

func CreateKeySpace(keyspace string, session *gocql.Session) {
    err := utils.ExecuteQuery(fmt.Sprintf(createKeyspace, keyspace), session)
    if err != nil {
        log.Fatal("Failed to create keyspace", err)
    }
    log.Println("Keyspace created")
}

ويتبع ذلك إنشاء الجدول ( user ) الذي يهتم بالدالة CreateUserTable

const createTable = "CREATE TABLE %s.%s (user_id int PRIMARY KEY, user_name text, user_bcity text)"

func CreateUserTable(keyspace, table string, session *gocql.Session) {
    err := session.Query(fmt.Sprintf(createTable, keyspace, table)).Exec()
    if err != nil {
        log.Fatal("failed to create table ", err)
    }
    log.Println("Table created")
}

بمجرد إنشاء مساحة المفتاح والجدول، فإننا نستدعي عمليات CRUD (جزء من operations\crud.go).

يُستخدم InsertUser لإنشاء User . يقوم بتعيين معلومات المستخدم (المعرف والاسم والمدينة) باعتبارها وسيطات الاستعلام باستخدام Bind

const createQuery = "INSERT INTO %s.%s (user_id, user_name , user_bcity) VALUES (?,?,?)"

func InsertUser(keyspace, table string, session *gocql.Session, user model.User) {
    err := session.Query(fmt.Sprintf(createQuery, keyspace, table)).Bind(user.ID, user.Name, user.City).Exec()
    if err != nil {
        log.Fatal("Failed to create user", err)
    }
    log.Println("User created")
}

يُستخدم FindUser للبحث عن مستخدم (model\user.go) باستخدام معرف مستخدم معين بينما Scan يربط سمات المستخدم (المرتجَعة بواسطة Cassandra) بالمتغيرات الفردية (userid، name، city) - إنها مجرد إحدى الطرق التي يمكنك من خلالها استخدام النتيجة التي تم الحصول عليها كنتيجة استعلام البحث

const selectQuery = "SELECT * FROM %s.%s where user_id = ?"

func FindUser(keyspace, table string, id int, session *gocql.Session) model.User {
    var userid int
    var name, city string
    err := session.Query(fmt.Sprintf(selectQuery, keyspace, table)).Bind(id).Scan(&userid, &name, &city)

    if err != nil {
        if err == gocql.ErrNotFound {
            log.Printf("User with id %v does not exist\n", id)
        } else {
            log.Printf("Failed to find user with id %v - %v\n", id, err)
        }
    }
    return model.User{ID: userid, Name: name, City: city}
}

يُستخدم FindAllUsers لجلب جميع المستخدمين. يُستخدم SliceMap باعتباره اختصارًا للحصول على جميع معلومات المستخدم في شكل شريحة من map. فكر في كل map كأزواج قيم المفاتيح حيث يكون اسم العمود (على سبيل المثال، user_id) عبارة عن المفتاح بالإضافة إلى القيمة الخاصة به.

const findAllUsersQuery = "SELECT * FROM %s.%s"

func FindAllUsers(keyspace, table string, session *gocql.Session) []model.User {
    var users []model.User
    results, _ := session.Query(fmt.Sprintf(findAllUsersQuery, keyspace, table)).Iter().SliceMap()

    for _, u := range results {
        users = append(users, mapToUser(u))
    }
    return users
}

يتم تحويل كل map من معلومات المستخدم إلى User باستخدام mapToUserالتي تستخرج ببساطة القيمة من العمود الخاص بها وتستخدمها لإنشاء مثيل من البنية User

func mapToUser(m map[string]interface{}) model.User {
    id, _ := m["user_id"].(int)
    name, _ := m["user_name"].(string)
    city, _ := m["user_bcity"].(string)

    return model.User{ID: id, Name: name, City: city}
}

شغّل التطبيق

كما ذكرنا سابقًا، يقبل التطبيق الاتصال وبيانات الاعتماد في شكل متغيرات البيئة.

في حسابك في Azure Cosmos DB في مدخل Azure، حدد سلسلة الاتصال.

انسخ قيم السمات التالية (CONTACT POINT وPORT وUSERNAME وPRIMARY PASSWORD) واضبطها على متغيرات البيئة ذات الصلة

set COSMOSDB_CASSANDRA_CONTACT_POINT=<value for "CONTACT POINT">
set COSMOSDB_CASSANDRA_PORT=<value for "PORT">
set COSMOSDB_CASSANDRA_USER=<value for "USERNAME">
set COSMOSDB_CASSANDRA_PASSWORD=<value for "PRIMARY PASSWORD">

في نافذة Terminal، قم بالتغيير إلى المجلد الصحيح. على سبيل المثال:

cd "C:\git-samples\azure-cosmosdb-cassandra-go-getting-started"

في نافذة Terminal، قم بتشغيل الأمر التالي لإنشاء التطبيق.

go run main.go

تعرض نافذة المحطة الطرفية إشعارات للعمليات المختلفة، بما في ذلك إعداد مساحة المفاتيح والجدول وإنشاء المستخدم وما إلى ذلك.
في مدخل Microsoft Azure، افتح Data Explorer للاستعلام عن هذه البيانات الجديدة، وتعديلها، والعمل عليها.

مراجعة اتفاقيات مستوى الخدمة في مدخل Azure

يراقب مدخل Azure معدل نقل حساب Azure Cosmos DB والتخزين والتوافر وزمن الانتقال والاتساق. المخططات الخاصة بالمقاييس المقترنة بـ اتفاقية مستوى خدمة Azure Cosmos DB (SLA) تعرض قيمة اتفاقية مستوى الخدمة مقارنة بالأداء الفعلي. هذه المجموعة من المقاييس تجعل مراقبة اتفاقيات مستوى الخدمة الخاصة بك شفافة.

لمراجعة المقاييس واتفاقيات مستوى الخدمة:

حدد Metrics في قائمة التنقل لحساب Azure Cosmos DB.
حدد علامة تبويب مثل زمن الانتقال، وحدد إطارًا زمنيًا على اليسار. قارن الأسطر الفعلية واتفاقية مستوى الخدمة على المخططات.
راجع المقاييس في علامات التبويب الأخرى.

تنظيف الموارد

عند الانتهاء من تطبيقك وحساب Azure Cosmos DB، يمكنك حذف موارد Azure التي أنشأتها حتى لا تتحمل المزيد من الرسوم. لحذف الموارد:

في شريط البحث في مدخل Azure، ابحث عن مجموعات المواردوحددها.
من القائمة، حدد مجموعة الموارد التي أنشأتها خلال هذا التشغيل السريع.
في صفحة نظرة عامة على مجموعة الموارد، حدد حذف مجموعة الموارد.
في النافذة التالية، أدخل اسم مجموعة الموارد لحذفها، ثم حدد حذف.

الخطوات التالية

في هذا التشغيل السريع، تعلمت كيفية إنشاء حساب Azure Cosmos DB باستخدام واجهة برمجة التطبيقات ل Cassandra، وتشغيل تطبيق Go الذي ينشئ قاعدة بيانات وحاوية Cassandra. يمكنك الآن استيراد بيانات إضافية إلى حساب Azure Cosmos DB.

استيراد بيانات Cassandra إلى Azure Cosmos DB

مشاركة عبر

التشغيل السريع: إنشاء تطبيق Go مع `gocql` العميل لإدارة Azure Cosmos DB لبيانات Apache Cassandra

المتطلبات الأساسية

أنشئ «حساب قاعدة البيانات».

استنساخ نموذج التطبيق

مراجعة الرمز

شغّل التطبيق

مراجعة اتفاقيات مستوى الخدمة في مدخل Azure

تنظيف الموارد

الخطوات التالية

الملاحظات

الموارد الإضافية

مشاركة عبر

التشغيل السريع: إنشاء تطبيق Go مع gocql العميل لإدارة Azure Cosmos DB لبيانات Apache Cassandra

المتطلبات الأساسية

أنشئ «حساب قاعدة البيانات».

استنساخ نموذج التطبيق

مراجعة الرمز

شغّل التطبيق

مراجعة اتفاقيات مستوى الخدمة في مدخل Azure

تنظيف الموارد

الخطوات التالية

الملاحظات

الموارد الإضافية

التشغيل السريع: إنشاء تطبيق Go مع `gocql` العميل لإدارة Azure Cosmos DB لبيانات Apache Cassandra