استخدام BigQuery مع C#

1. نظرة عامة

‫BigQuery هو مستودع بيانات إحصاءات مُدار بالكامل ومنخفض التكلفة على نطاق بيتابايت من Google. لا تتطلّب BigQuery أي عمليات، إذ لا تحتاج إلى إدارة أي بنية أساسية ولا تحتاج إلى مسؤول قاعدة بيانات، ما يتيح لك التركيز على تحليل البيانات للعثور على إحصاءات مفيدة واستخدام لغة SQL المألوفة والاستفادة من نموذج الدفع حسب الاستخدام.

في هذا الدرس العملي حول الترميز، ستستخدم مكتبات برامج Google Cloud للعملاء في ‎ .NET لطلب البحث في مجموعات بيانات BigQuery العامة باستخدام C#.

ما ستتعلمه

كيفية استخدام Cloud Shell
كيفية تفعيل BigQuery API
كيفية مصادقة طلبات البيانات من واجهة برمجة التطبيقات
كيفية تثبيت مكتبة برامج Google Cloud للغة C#
كيفية البحث عن أعمال شكسبير
كيفية تشغيل طلب بحث في مجموعة بيانات GitHub
كيفية ضبط إعدادات التخزين المؤقت وعرض الإحصاءات

المتطلبات

مشروع على Google Cloud Platform
متصفّح، مثل Chrome أو Firefox
الإلمام باستخدام C#

استطلاع الرأي

كيف ستستخدم هذا البرنامج التعليمي؟

قراءة المحتوى فقط

قراءة المحتوى وإكمال التمارين

كيف تقيّم تجربتك مع لغة C#؟

مبتدئ

متوسط

متمكّن

ما هو تقييمك لتجربة استخدام خدمات Google Cloud Platform؟

مبتدئ

متوسط

متقدّم

2. الإعداد والمتطلبات

إعداد البيئة بالسرعة التي تناسبك

سجِّل الدخول إلى Google Cloud Console وأنشِئ مشروعًا جديدًا أو أعِد استخدام مشروع حالي. إذا لم يكن لديك حساب على Gmail أو Google Workspace، عليك إنشاء حساب.

اسم المشروع هو الاسم المعروض للمشاركين في هذا المشروع. وهي سلسلة أحرف لا تستخدمها Google APIs. ويمكنك تعديلها في أي وقت.
رقم تعريف المشروع هو معرّف فريد في جميع مشاريع Google Cloud ولا يمكن تغييره بعد ضبطه. تنشئ Cloud Console تلقائيًا سلسلة فريدة، ولا يهمّك عادةً ما هي. في معظم دروس البرمجة، عليك الرجوع إلى رقم تعريف مشروعك (يُشار إليه عادةً باسم PROJECT_ID). إذا لم يعجبك رقم التعريف الذي تم إنشاؤه، يمكنك إنشاء رقم تعريف عشوائي آخر. يمكنك بدلاً من ذلك تجربة اسم مستخدم من اختيارك ومعرفة ما إذا كان متاحًا. لا يمكن تغيير هذا الخيار بعد هذه الخطوة وسيظل ساريًا طوال مدة المشروع.
للعلم، هناك قيمة ثالثة، وهي رقم المشروع، تستخدمها بعض واجهات برمجة التطبيقات. يمكنك الاطّلاع على مزيد من المعلومات عن كل هذه القيم الثلاث في المستندات.

بعد ذلك، عليك تفعيل الفوترة في Cloud Console لاستخدام موارد/واجهات برمجة تطبيقات Cloud. لن تكلفك تجربة هذا الدرس التطبيقي حول الترميز الكثير، إن وُجدت أي تكلفة على الإطلاق. لإيقاف الموارد وتجنُّب تحمّل تكاليف تتجاوز هذا البرنامج التعليمي، يمكنك حذف الموارد التي أنشأتها أو حذف المشروع. يمكن لمستخدمي Google Cloud الجدد الاستفادة من برنامج الفترة التجريبية المجانية بقيمة 300 دولار أمريكي.

بدء Cloud Shell

على الرغم من إمكانية تشغيل Google Cloud عن بُعد من الكمبيوتر المحمول، ستستخدم في هذا الدرس العملي Google Cloud Shell، وهي بيئة سطر أوامر تعمل في السحابة الإلكترونية.

تفعيل Cloud Shell

من Cloud Console، انقر على تفعيل Cloud Shell .

إذا كانت هذه هي المرة الأولى التي تبدأ فيها Cloud Shell، ستظهر لك شاشة وسيطة توضّح ماهية هذه الخدمة. إذا ظهرت لك شاشة وسيطة، انقر على متابعة.

يستغرق توفير Cloud Shell والاتصال به بضع لحظات فقط.

يتم تحميل هذا الجهاز الافتراضي بجميع أدوات التطوير اللازمة. توفّر هذه الخدمة دليلًا رئيسيًا دائمًا بسعة 5 غيغابايت وتعمل في Google Cloud، ما يؤدي إلى تحسين أداء الشبكة والمصادقة بشكل كبير. يمكن إنجاز معظم عملك في هذا الدرس التطبيقي حول الترميز، إن لم يكن كله، باستخدام متصفح.

بعد الاتصال بـ Cloud Shell، من المفترض أن يظهر لك أنّه تم إثبات هويتك وأنّه تم ضبط المشروع على رقم تعريف مشروعك.

نفِّذ الأمر التالي في Cloud Shell للتأكّد من إكمال عملية المصادقة:

gcloud auth list

ناتج الأمر

 Credentialed Accounts
ACTIVE  ACCOUNT
*       <my_account>@<my_domain.com>

To set the active account, run:
    $ gcloud config set account `ACCOUNT`

نفِّذ الأمر التالي في Cloud Shell للتأكّد من أنّ أمر gcloud يعرف مشروعك:

gcloud config list project

ناتج الأمر

[core]
project = <PROJECT_ID>

إذا لم يكن كذلك، يمكنك تعيينه من خلال هذا الأمر:

gcloud config set project <PROJECT_ID>

ناتج الأمر

Updated property [core/project].

3- تفعيل BigQuery API

يجب أن تكون BigQuery API مفعَّلة تلقائيًا في جميع مشاريع Google Cloud. يمكنك التحقّق من صحة ذلك باستخدام الأمر التالي في Cloud Shell: يجب أن تكون مدرَجًا في BigQuery:

gcloud services list

من المفترض أن يظهر BigQuery في القائمة:

NAME                              TITLE
bigquery-json.googleapis.com      BigQuery API
...

في حال عدم تفعيل BigQuery API، يمكنك استخدام الأمر التالي في Cloud Shell لتفعيلها:

gcloud services enable bigquery-json.googleapis.com

4. تثبيت مكتبة برامج BigQuery للغة C#

أولاً، أنشئ تطبيقًا بسيطًا لوحدة تحكّم C# ستستخدمه لتشغيل نماذج BigQuery API.

dotnet new console -n BigQueryDemo

من المفترض أن يظهر لك التطبيق الذي تم إنشاؤه وتم حلّ التبعيات:

The template "Console Application" was created successfully.
Processing post-creation actions...
...
Restore succeeded.

بعد ذلك، انتقِل إلى المجلد BigQueryDemo:

cd BigQueryDemo

وأضِف حزمة Google.Cloud.BigQuery.V2 NuGet إلى المشروع:

dotnet add package Google.Cloud.BigQuery.V2

info : Adding PackageReference for package 'Google.Cloud.BigQuery.V2' into project '/home/atameldev/BigQueryDemo/BigQueryDemo.csproj'.
log  : Restoring packages for /home/atameldev/BigQueryDemo/BigQueryDemo.csproj...
...
info : PackageReference for package 'Google.Cloud.BigQuery.V2' version '1.2.0' added to file '/home/atameldev/BigQueryDemo/BigQueryDemo.csproj'.

أنت الآن جاهز لاستخدام BigQuery API.

5- الاستعلام عن أعمال شكسبير

مجموعة البيانات العامة هي أي مجموعة بيانات يتم تخزينها في BigQuery وتكون متاحة لعامة الجمهور. تتوفّر العديد من مجموعات البيانات العامة الأخرى التي يمكنك طلب البحث فيها، بعضها تستضيفه Google، والعديد منها تستضيفه جهات خارجية. يمكنك قراءة المزيد من المعلومات في صفحة مجموعات البيانات العامة.

بالإضافة إلى مجموعات البيانات العامة، توفّر BigQuery عددًا محدودًا من جداول العيّنات التي يمكنك طلب البحث فيها. يتم تضمين هذه الجداول في bigquery-public-data:samples dataset. أحد هذه الجداول يُسمى shakespeare. ويحتوي على فهرس كلمات لأعمال شكسبير، مع توضيح عدد المرات التي تظهر فيها كل كلمة في كل مجموعة نصوص.

في هذه الخطوة، ستستعلم عن جدول Shakespeare.

أولاً، افتح أداة تعديل الرموز من أعلى يسار Cloud Shell:

انتقِل إلى ملف Program.cs داخل مجلد BigQueryDemo واستبدِل الرمز بالرمز التالي. تأكَّد من استبدال projectId برقم تعريف مشروعك الفعلي:

using System;
using Google.Cloud.BigQuery.V2;

namespace BigQueryDemo
{
    class Program
    {
        static void Main(string[] args)
        {
            var client = BigQueryClient.Create("projectId");
            var table = client.GetTable("bigquery-public-data", "samples", "shakespeare");
            var sql = $"SELECT corpus AS title, COUNT(word) AS unique_words FROM {table} GROUP BY title ORDER BY unique_words DESC LIMIT 10";

            var results = client.ExecuteQuery(sql, parameters: null);

            foreach (var row in results)
            {
                Console.WriteLine($"{row["title"]}: {row["unique_words"]}");
            }
        }
    }
}

خصِّص دقيقة أو دقيقتين لدراسة الرمز البرمجي ومعرفة كيفية الاستعلام عن الجدول.

في Cloud Shell، شغِّل التطبيق:

dotnet run

ستظهر لك قائمة بالكلمات وعدد مرات تكرارها:

hamlet: 5318
kinghenryv: 5104
cymbeline: 4875
troilusandcressida: 4795
kinglear: 4784
kingrichardiii: 4713
2kinghenryvi: 4683
...

ملاحظة: إذا لم يعمل رمز C# هذا، تحقَّق من التعليمات التي نفّذتها أثناء خطوة مصادقة طلبات واجهة برمجة التطبيقات.

استخدِم الأمر التالي للتحقّق من قيمة متغيّر البيئة GOOGLE_APPLICATION_CREDENTIALS:

echo GOOGLE_APPLICATION_CREDENTIALS

يجب أن تعرض القيمة "~/key.json".

إذا كان الأمر كذلك، تحقَّق بعد ذلك من إنشاء حساب خدمة وتحديد موقعه في "~/key.json" باستخدام:

cat "~/key.json"

من المفترض أن يظهر لك محتوى مشابه لما يلي:

{

"type": "service_account",

"project_id": "PROJECT_ID",

"private_key_id": "ff31939192529e07f42e4535fb20bb029def1276",

"Private_key":...

إذا لم يكن الأمر كذلك، يُرجى إعادة زيارة خطوة مصادقة طلبات واجهة برمجة التطبيقات.

6. الاستعلام عن مجموعة بيانات GitHub

للتعرّف أكثر على BigQuery، ستُصدر الآن طلب بحث مقابل مجموعة بيانات GitHub العامة. يمكنك العثور على رسائل عمليات الإيداع الأكثر شيوعًا على GitHub. ستستخدم أيضًا وحدة تحكّم BigQuery على الويب لمعاينة طلبات البحث المخصّصة وتنفيذها.

للاطّلاع على شكل البيانات، افتح مجموعة بيانات GitHub في واجهة مستخدم الويب في BigQuery:

https://console.cloud.google.com/bigquery?p=bigquery-public-data&d=github_repos&t=commits&page=table

للحصول على معاينة سريعة لشكل البيانات، استخدِم زر "المعاينة":

using System;
using Google.Cloud.BigQuery.V2;

namespace BigQueryDemo
{
    class Program
    {
        static void Main(string[] args)
        {
            var client = BigQueryClient.Create("projectId");
            var table = client.GetTable("bigquery-public-data", "github_repos", "commits");
            
            var sql = $"SELECT subject AS subject, COUNT(*) AS num_duplicates FROM {table} GROUP BY subject ORDER BY num_duplicates DESC LIMIT 10";

            var results = client.ExecuteQuery(sql, parameters: null);

            foreach (var row in results)
            {
                Console.WriteLine($"{row["subject"]}: {row["num_duplicates"]}");
            }
        }
    }
}

يُرجى تخصيص دقيقة أو دقيقتين لدراسة الرمز البرمجي والاطّلاع على كيفية طلب الجدول للحصول على رسائل الالتزام الأكثر شيوعًا.

في Cloud Shell، شغِّل التطبيق:

dotnet run

ستظهر لك قائمة برسائل عمليات الدمج وعدد مرات حدوثها:

Update README.md: 2509242
: 1971725
Initial commit: 1942149
Mirroring from Micro.blog.: 838586
update: 575188
Update data.json: 548651
Update data.js: 548339
Add files via upload: 379941
*** empty log message ***: 358528
Can't you see I'm updating the time?: 286863

7. التخزين المؤقت والإحصاءات

بعد طلب البحث الأوّلي، تخزّن BigQuery النتائج مؤقتًا. نتيجةً لذلك، تستغرق الاستعلامات اللاحقة وقتًا أقل بكثير. يمكن إيقاف التخزين المؤقت باستخدام خيارات طلب البحث. يتتبّع BigQuery أيضًا بعض الإحصاءات حول طلبات البحث، مثل وقت الإنشاء ووقت الانتهاء وإجمالي عدد وحدات البايت التي تمت معالجتها.

في هذه الخطوة، ستوقف التخزين المؤقت وتعرض أيضًا بعض الإحصاءات حول طلبات البحث.

using System;
using Google.Cloud.BigQuery.V2;

namespace BigQueryDemo
{
    class Program
    {
        static void Main(string[] args)
        {
            var client = BigQueryClient.Create("projectId");
            var table = client.GetTable("bigquery-public-data", "github_repos", "commits");
            
            var sql = $"SELECT subject AS subject, COUNT(*) AS num_duplicates FROM {table} GROUP BY subject ORDER BY num_duplicates DESC LIMIT 10";
            var queryOptions = new QueryOptions {
                UseQueryCache = false
            };

            var results = client.ExecuteQuery(sql, parameters: null, queryOptions: queryOptions);

            foreach (var row in results)
            {
                Console.WriteLine($"{row["subject"]}: {row["num_duplicates"]}");
            }

            var job = client.GetJob(results.JobReference);
            var stats = job.Statistics;
            Console.WriteLine("----------");
            Console.WriteLine($"Creation time: {stats.CreationTime}");
            Console.WriteLine($"End time: {stats.EndTime}");
            Console.WriteLine($"Total bytes processed: {stats.TotalBytesProcessed}");
        }
    }
}

في ما يلي بعض الملاحظات حول الرمز. أولاً، يتم إيقاف التخزين المؤقت من خلال تقديم خيارات طلب البحث وضبط UseQueryCache على "خطأ". ثانيًا، يمكنك الوصول إلى إحصاءات حول الاستعلام من عنصر المهمة.

في Cloud Shell، شغِّل التطبيق:

dotnet run

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

Update README.md: 2509242
: 1971725
Initial commit: 1942149
Mirroring from Micro.blog.: 838586
update: 575188
Update data.json: 548651
Update data.js: 548339
Add files via upload: 379941
*** empty log message ***: 358528
Can't you see I'm updating the time?: 286863
----------
Creation time: 1533052057398
End time: 1533052066961
Total bytes processed: 9944197093

8. تحميل البيانات إلى BigQuery

إذا أردت طلب البحث عن بياناتك، عليك أولاً تحميل بياناتك إلى BigQuery. يتيح BigQuery تحميل البيانات من مصادر عديدة، مثل Google Cloud Storage وخدمات Google الأخرى ومصدر قابل للقراءة. يمكنك حتى بث بياناتك باستخدام عمليات الإدراج المتدفّقة. يمكنك الاطّلاع على مزيد من المعلومات في صفحة تحميل البيانات إلى BigQuery.

في هذه الخطوة، ستحمّل ملف JSON مخزَّنًا على Google Cloud Storage إلى جدول BigQuery. يقع ملف JSON في gs://cloud-samples-data/bigquery/us-states/us-states.json

إذا كنت مهتمًا بمعرفة محتوى ملف JSON، يمكنك استخدام أداة سطر الأوامر gsutil لتنزيله في Cloud Shell:

gsutil cp gs://cloud-samples-data/bigquery/us-states/us-states.json .

Copying gs://cloud-samples-data/bigquery/us-states/us-states.json...
/ [1 files][  2.0 KiB/  2.0 KiB]                                                
Operation completed over 1 objects/2.0 KiB.

يمكنك ملاحظة أنّها تحتوي على قائمة بالولايات الأمريكية، وكل ولاية هي مستند JSON في سطر منفصل:

less us-states.json

{"name": "Alabama", "post_abbr": "AL"}
{"name": "Alaska", "post_abbr":  "AK"}
...

لتحميل ملف JSON هذا إلى BigQuery، انتقِل إلى ملف Program.cs داخل المجلد BigQueryDemo واستبدِل الرمز بالرمز التالي. تأكَّد من استبدال projectId برقم تعريف مشروعك الفعلي:

using System;
using Google.Cloud.BigQuery.V2;

namespace BigQueryDemo
{
    class Program
    {
        static void Main(string[] args)
        {
            var gcsUri = "gs://cloud-samples-data/bigquery/us-states/us-states.json";
            var client = BigQueryClient.Create("projectId");
            var dataset = client.GetOrCreateDataset("us_states_dataset");

            var schema = new TableSchemaBuilder 
            {
                { "name", BigQueryDbType.String },
                { "post_abbr", BigQueryDbType.String }
            }.Build();

            var jobOptions = new CreateLoadJobOptions
            {
                SourceFormat = FileFormat.NewlineDelimitedJson
            };

            var table = dataset.GetTableReference("us_states_table");
            var loadJob = client.CreateLoadJob(gcsUri, table, schema, jobOptions);

            loadJob.PollUntilCompleted();
            loadJob.ThrowOnAnyError();
            Console.WriteLine("Json file loaded to BigQuery");
        }
    }
}

خصِّص دقيقة أو دقيقتَين لدراسة كيفية تحميل الرمز لملف JSON وإنشاء جدول باستخدام مخطط ضمن مجموعة بيانات.

في Cloud Shell، شغِّل التطبيق:

dotnet run

يتم إنشاء مجموعة بيانات وجدول في BigQuery

Json file loaded to BigQuery

للتأكّد من إنشاء مجموعة البيانات فعلاً، يمكنك الانتقال إلى وحدة تحكّم BigQuery. من المفترض أن تظهر لك مجموعة بيانات جديدة وجدول تم إنشاؤه. إذا انتقلت إلى علامة التبويب "معاينة" للجدول، يمكنك الاطّلاع على البيانات الفعلية:

9- تهانينا!

تعرّفت على كيفية استخدام BigQuery باستخدام C#.

تَنظيم

لتجنُّب تحمّل رسوم في حسابك على Google Cloud Platform مقابل الموارد المستخدَمة في هذا الدليل السريع، اتّبِع الخطوات التالية:

انتقِل إلى وحدة تحكّم Cloud Platform.
اختَر المشروع الذي تريد إيقافه، ثم انقر على "حذف" في أعلى الصفحة: يؤدي ذلك إلى تحديد موعد لحذف المشروع.

مزيد من المعلومات

‫Google BigQuery: https://cloud.google.com/bigquery/docs/
‫C#‎/.NET على Google Cloud Platform: https://cloud.google.com/dotnet/
برنامج Google Cloud .NET: https://googlecloudplatform.github.io/google-cloud-dotnet/

الترخيص

يخضع هذا العمل لترخيص المشاع الإبداعي مع نسب العمل إلى مؤلفه 2.0 Generic License.