التشغيل السريع: مكتبة Azure Cosmos DB ل NoSQL ل Go

ينطبق على: NoSQL

• NET.
• JavaScript/Node.js
• Java
• Python
• ذهب

ابدأ مع مكتبة عميل Azure Cosmos DB ل NoSQL ل Go للاستعلام عن البيانات في حاوياتك وتنفيذ العمليات الشائعة على العناصر الفردية. اتبع هذه الخطوات لنشر الحد الأدنى من الحل إلى البيئة الخاصة بك باستخدام Azure Developer CLI.

الوثائق | المرجعية لواجهة برمجة التطبيقات حزمة التعليمات البرمجية | المصدر لمكتبة (Go) | Azure Developer CLI

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

• حساب Azure مع اشتراك نشط. أنشئ حساباً مجاناً.
• حساب GitHub

• حساب Azure مع اشتراك نشط. أنشئ حساباً مجاناً.
• Azure Developer CLI
• Docker Desktop

الإعداد

نشر حاوية تطوير هذا المشروع إلى البيئة الخاصة بك. ثم استخدم Azure Developer CLI (azd) لإنشاء حساب Azure Cosmos DB ل NoSQL ونشر نموذج تطبيق حاوية. يستخدم نموذج التطبيق مكتبة العميل لإدارة البيانات النموذجية وإنشاءها وقراءتها والاستعلام عن البيانات.

هام

تتضمن حسابات GitHub استحقاق التخزين والساعات الأساسية دون أي تكلفة. لمزيد من المعلومات، راجع التخزين المضمن والساعات الأساسية لحسابات GitHub.

1. افتح محطة طرفية في الدليل الجذر للمشروع.

2. المصادقة على Azure Developer CLI باستخدام azd auth login. اتبع الخطوات المحددة بواسطة الأداة للمصادقة على CLI باستخدام بيانات اعتماد Azure المفضلة لديك.

   azd auth login
   

3. استخدم azd init لتهيئة المشروع.

   azd init --template cosmos-db-nosql-go-quickstart
   

   إشعار

   يستخدم هذا التشغيل السريع مستودع GitHub لقالب azure-samples/cosmos-db-nosql-go-quickstart . سيقوم Azure Developer CLI تلقائيا باستنساخ هذا المشروع إلى جهازك إذا لم يكن موجودا بالفعل.

4. أثناء التهيئة، قم بتكوين اسم بيئة فريد.

   تلميح

   سيتم أيضا استخدام اسم البيئة كاسم مجموعة الموارد الهدف. لهذا التشغيل السريع، ضع في اعتبارك استخدام msdocs-cosmos-db.

5. انشر حساب Azure Cosmos DB باستخدام azd up. تنشر قوالب Bicep أيضا نموذج تطبيق ويب.

   azd up
   

6. أثناء عملية التوفير، حدد اشتراكك والموقع المطلوب. انتظر حتى اكتمال عملية التوفير. قد تستغرق العملية حوالي خمس دقائق.

7. بمجرد توفير موارد Azure الخاصة بك، يتم تضمين عنوان URL لتطبيق الويب قيد التشغيل في الإخراج.

   Deploying services (azd deploy)
   
     (✓) Done: Deploying service web
   - Endpoint: <https://[container-app-sub-domain].azurecontainerapps.io>
   
   SUCCESS: Your application was provisioned and deployed to Azure in 5 minutes 0 seconds.
   

8. استخدم عنوان URL في وحدة التحكم للانتقال إلى تطبيق الويب الخاص بك في المستعرض. لاحظ إخراج التطبيق قيد التشغيل.

   

تثبيت مكتبة العميل

تتوفر مكتبة العميل من خلال Go، كحزمة azcosmos .

1. افتح terminal وانتقل إلى /src المجلد.

   cd ./src
   

2. إذا لم يكن مثبتا بالفعل، فقم بتثبيت الحزمة azcosmos باستخدام go install.

   go install github.com/Azure/azure-sdk-for-go/sdk/data/azcosmos
   

3. أيضا، قم بتثبيت الحزمة azidentity إذا لم تكن مثبتة بالفعل.

   go install github.com/Azure/azure-sdk-for-go/sdk/azidentity
   

4. افتح الملف src/go.mod وراجعه للتحقق من وجود github.com/Azure/azure-sdk-for-go/sdk/data/azcosmos الإدخالين وgithub.com/Azure/azure-sdk-for-go/sdk/azidentity.

نموذج الكائن

Name	‏‏الوصف
CosmosClient	هذه الفئة هي فئة العميل الأساسية وتستخدم لإدارة بيانات التعريف أو قواعد البيانات على مستوى الحساب.
CosmosDatabase	تمثل هذه الفئة قاعدة بيانات داخل الحساب.
CosmosContainer	تستخدم هذه الفئة بشكل أساسي لتنفيذ عمليات القراءة والتحديث والحذف على الحاوية أو العناصر المخزنة داخل الحاوية.
PartitionKey	تمثل هذه الفئة مفتاح قسم منطقي. هذه الفئة مطلوبة للعديد من العمليات والاستعلامات الشائعة.

أمثلة على التعليمات البرمجية

• مصادقة العميل
• الحصول على قاعدة بيانات
• الحصول على حاوية
• إنشاء عنصر
• الحصول على عنصر
• عناصر الاستعلام

يستخدم نموذج التعليمات البرمجية في القالب قاعدة بيانات باسم cosmicworks وحاوية باسم products. products تحتوي الحاوية على تفاصيل مثل الاسم والفئة والكمية والمعرف الفريد وعلامة البيع لكل منتج. تستخدم الحاوية الخاصية /category كمفتاح قسم منطقي.

مصادقة العميل

يجب التصريح بطلبات التطبيق إلى معظم خدمات Azure. DefaultAzureCredential استخدم النوع كطريقة مفضلة لتنفيذ اتصال بدون كلمة مرور بين تطبيقاتك وAzure Cosmos DB ل NoSQL. DefaultAzureCredential يدعم أساليب مصادقة متعددة ويحدد الأسلوب الذي يجب استخدامه في وقت التشغيل.

هام

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

ينشئ هذا النموذج مثيلا CosmosClient جديدا لاستخدام azcosmos.NewClient المثيل والمصادقة عليه DefaultAzureCredential .

credential, err := azidentity.NewDefaultAzureCredential(nil)
if err != nil {
    return err
}

clientOptions := azcosmos.ClientOptions{
    EnableContentResponseOnWrite: true,
}

client, err := azcosmos.NewClient(endpoint, credential, &clientOptions)
if err != nil {
    return err
}

الحصول على قاعدة بيانات

استخدم client.NewDatabase لاسترداد قاعدة البيانات الموجودة المسماة cosmicworks.

database, err := client.NewDatabase("cosmicworks")
if err != nil {
    return err
}

الحصول على حاوية

استرداد الحاوية الموجودة products باستخدام database.NewContainer.

container, err := database.NewContainer("products")
if err != nil {
    return err
}

إنشاء عنصر

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

type Item struct {
    Id 			string	`json:"id"`
    Category 	string	`json:"category"`
    Name 		string	`json:"name"`
    Quantity 	int		`json:"quantity"`
    Price		float32	`json:"price"`
    Clearance	bool	`json:"clearance"`
}

إنشاء عنصر في الحاوية باستخدام container.UpsertItem. هذا الأسلوب "upserts" العنصر استبدال العنصر بشكل فعال إذا كان موجودا بالفعل.

item := Item {
    Id:			"70b63682-b93a-4c77-aad2-65501347265f",
    Category:	"gear-surf-surfboards",
    Name:		"Yamba Surfboard",
    Quantity:	12,
    Price:		850.00,
    Clearance:	false,
}

partitionKey := azcosmos.NewPartitionKeyString("gear-surf-surfboards")

context := context.TODO()

bytes, err := json.Marshal(item)
if err != nil {
    return err
}

response, err := container.UpsertItem(context, partitionKey, bytes, nil)
if err != nil {
    return err
}

قراءة عنصر

تنفيذ عملية قراءة نقطة باستخدام كل من المعرف الفريد (id) وحقول مفتاح القسم. استخدم container.ReadItem لاسترداد العنصر المحدد بكفاءة.

partitionKey := azcosmos.NewPartitionKeyString("gear-surf-surfboards")

context := context.TODO()

itemId := "70b63682-b93a-4c77-aad2-65501347265f"

response, err := container.ReadItem(context, partitionKey, itemId, nil)
if err != nil {
    return err
}

if response.RawResponse.StatusCode == 200 {
    read_item := Item{}
    err := json.Unmarshal(response.Value, &read_item)
    if err != nil {
        return err
    }

عناصر الاستعلام

تنفيذ استعلام عبر عناصر متعددة في حاوية باستخدام container.NewQueryItemsPager. ابحث عن كافة العناصر ضمن فئة محددة باستخدام هذا الاستعلام الذي تم تحديد معلمات له:

SELECT * FROM products p WHERE p.category = @category

partitionKey := azcosmos.NewPartitionKeyString("gear-surf-surfboards")

query := "SELECT * FROM products p WHERE p.category = @category"

queryOptions := azcosmos.QueryOptions{
    QueryParameters: []azcosmos.QueryParameter{
        {Name: "@category", Value: "gear-surf-surfboards"},
    },
}

pager := container.NewQueryItemsPager(query, partitionKey, &queryOptions)

تحليل النتائج المرقمة للاستعلام عن طريق التكرار الحلقي عبر كل صفحة من النتائج باستخدام pager.NextPage. استخدم pager.More لتحديد ما إذا كانت هناك أي نتائج متبقية في بداية كل حلقة.

context := context.TODO()

items := []Item{}

requestCharge := float32(0)

for pager.More() {
    response, err := pager.NextPage(context)
    if err != nil {
        return err
    }

    requestCharge += response.RequestCharge

    for _, bytes := range response.Items {
        item := Item{}
        err := json.Unmarshal(bytes, &item)
        if err != nil {
            return err
        }
        items = append(items, item)
    }
}

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

عندما لم تعد بحاجة إلى نموذج التطبيق أو الموارد، قم بإزالة التوزيع المقابل وجميع الموارد.

azd down

في GitHub Codespaces، احذف مساحة التعليمات البرمجية قيد التشغيل لزيادة استحقاقات التخزين والذاكرة الأساسية إلى أقصى حد.

المحتوى ذو الصلة

• التشغيل السريع ل .NET
• التشغيل السريع ل JavaScript/Node.js
• التشغيل السريع ل Java
• التشغيل السريع ل Python

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

حزمة Go