تحميل بيان الجدول

إذا كنت بحاجة إلى مزيد من المرونة في تحميل الجداول إلى Google Earth Engine (EE) مقارنةً بما توفره واجهة مستخدم "محرر الرموز" أو الأمر upload في أداة سطر الأوامر "earthengine" ، يمكنك إجراء ذلك من خلال وصف عملية تحميل جدول باستخدام ملف JSON يُعرف باسم "بيان" واستخدام الأمر upload table --manifest في أداة سطر الأوامر.

عملية إعداد لمرة واحدة

1. لا تعمل عمليات تحميل البيان إلا مع الملفات المتوفّرة في Google Cloud Storage. لبدء استخدام Google Cloud Storage، أنشئ مشروعًا على Google Cloud، إذا لم يكن لديك مشروع. يُرجى العِلم أنّ عملية الإعداد تتطلّب تحديد بطاقة ائتمان لأغراض الفوترة. لا تفرض شركة EE رسومًا على أي مستخدم في الوقت الحالي، ولكن سيتم فرض تكلفة صغيرة على نقل الملفات إلى Google Cloud Storage قبل تحميلها إلى EE. بالنسبة إلى أحجام بيانات التحميل المعتادة (عشرات أو مئات غيغابايت)، ستكون التكلفة منخفضة جدًا.
2. ضمن مشروعك، فعِّل واجهة برمجة التطبيقات Cloud Storage API و أنشئ حزمة.
3. ثبِّت عميل Earth Engine Python. يتضمّن هذا الإصدار أداة سطر الأوامر earthengine التي سنستخدمها لتحميل البيانات.
4. بالنسبة إلى عمليات التحميل المبرمَجة، ننصحك باستخدام حساب خدمة على Google Cloud مرتبط بمشروعك. لست بحاجة إلى حساب خدمة للاختبار، ولكن عندما يكون لديك بعض الوقت، يُرجى البدء في التعرّف على كيفية استخدامه.

أرقام تعريف مواد العرض وأسماءها

بالنسبة إلى مواد العرض في مشاريع Cloud، استخدِم projects/my_cloud_project/assets/my_asset.

بالنسبة إلى المشاريع القديمة، يجب أن يكون اسم مادة العرض في البيان مختلفًا قليلاً عن رقم تعريف مادة العرض الظاهر في أماكن أخرى في Earth Engine. لتحميل مواد عرض تبدأ أرقام تعريفها بحرف users/some_user أو projects/some_project، يجب أن يتضمّن اسم مادة العرض فيملف البيان السلسلة projects/earthengine-legacy/assets/ قبل المعرّف. على سبيل المثال، يجب تحميل رقم تعريف مادة العرض EE‏ users/username/my_table باستخدام الاسم projects/earthengine-legacy/assets/users/username/my_table.

نعم، هذا يعني أنّ أرقام التعريف مثل projects/some_projects/some_asset يتم تحويلها إلى أسماء يتم فيها ذكر projects مرّتين: projects/earthengine-legacy/assets/projects/some_projects/some_asset. قد يكون هذا الأمر مربكًا، ولكنه ضروري للالتزام بمعايير Google Cloud API.

استخدام ملفات البيان

في ما يلي أبسط بيان ممكن. يتم تحميل ملف باسم small.csv من حزمة Google Cloud Storage باسم gs://earthengine-test.

{
  "name": "projects/some-project-id/assets/some-asset-id",
  "sources": [
    {
      "uris": [
        "gs://earthengine-test/small.csv"
      ]
    }
  ]
}

لاستخدامه، احفظه في ملف باسم manifest.json وشغِّل:

earthengine upload table --manifest /path/to/manifest.json

(يوجد الملف gs://earthengine-test/small.csv وهو قابل للقراءة للجميع، ويمكنك استخدامه للاختبار).

بالنسبة إلى عمليات تحميل ملفات Shapefile، حدِّد ملف ‎ .shp فقط، وسيتم رصد الملفات الأخرى تلقائيًا.

مصادر متعدّدة

من الممكن تحديد مصادر متعدّدة بتنسيق CSV أو Shapefile، مع ملف واحد لكل مصدر. في هذه الحالة، يجب أن يتضمّن كل ملف CSV البنية نفسها. على سبيل المثال، لدينا ملفان CSV ، region1.csv وregion2.csv:

id	الشكل
1	{"type":"Point","coordinates":[-119,36]}
2	{"type":"Point","coordinates":[-118,37]}
3	{"type":"Point","coordinates":[-117,38]}

id	الشكل
4	{"type":"Point","coordinates":[-112,40]}
5	{"type":"Point","coordinates":[-111,41]}
6	{"type":"Point","coordinates":[-110,42]}

ولهما البنية نفسها، ولكنهما مختلفان في المحتوى. تم تحميلها إلى حزمة تخزين في Cloud: gs://earthengine-test/region1.csv و gs://earthengine-test/region2.csv. لتحميلها كمادة عرض في Earth Engine ، أنشئ بيانًا يتضمّن إدخالَين في قائمة sources، على النحو التالي:

{
  "name": "projects/some-project-id/assets/some-asset-id",
  "sources": [
    {
      "uris": [
        "gs://earthengine-test/region1.csv"
      ]
    },
    {
      "uris": [
        "gs://earthengine-test/region2.csv"
      ]
    }
  ]
}

وقت البدء والانتهاء

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

يشير وقت البدء والانتهاء عادةً إلى وقت المراقبة، وليس وقت إنشاء الملف المصدر.

يتم التعامل مع وقت الانتهاء على أنّه حدّ حصري من أجل التبسيط. على سبيل المثال، بالنسبة إلى مواد العرض التي تمتدّ على مدار يوم واحد بالضبط، استخدِم منتصف الليل في يومَين متتاليين (على سبيل المثال، ‎1980-01-31T00:00:00 و‎1980-02-01T00:00:00) لوقتَي البدء والانتهاء. إذا لم تكن لمادة العرض مدة، اضبط وقت الانتهاء على أن يكون مطابقًا لوقت البدء. يجب تمثيل الأوقات في ملفات البيان على شكل سلاسل ISO 8601. ننصحك بافتراض أنّ وقت الانتهاء حصري (مثلاً، منتصف الليل في اليوم التالي لمادة العرض اليومية) لتبسيط قيم التاريخ.

مثال:

{
  "name": "projects/some-project-id/assets/some-asset-id",
  "sources": [
    {
      "uris": [
        "gs://bucket/table_20190612.csv"
      ]
    }
  ],
  "startTime": "1980-01-31T00:00:00Z",
  "endTime": "1980-02-01T00:00:00Z"
}

مرجع بنية البيان

تتضمّن بنية JSON التالية جميع حقول بيان تحميل الجداول الممكنة. ابحث عن تعريفات الحقول في قسم تعريفات حقول البيان التالي.

{
  "name": <string>,
  "sources": [
    {
      "uris": [
        <string>
      ],
      "charset": <string>,
      "maxErrorMeters": <double>,
      "maxVertices": <int32>,
      "crs": <string>,
      "geodesic": <boolean>,
      "primaryGeometryColumn": <string>,
      "xColumn": <string>,
      "yColumn": <string>,
      "dateFormat": <string>,
      "csvDelimiter": <string>,
      "csvQualifier": <string>,
    }
  ],
  "uriPrefix": <string>,
  "startTime": {
    "seconds": <integer>
  },
  "endTime": {
    "seconds": <integer>
  },
  "properties": {
    <unspecified>
  }
}

تعريفات حقول البيان

الاسم

string

اسم مادة العرض التي سيتم إنشاؤها. يكون name بالتنسيق "projects/*/assets/**" (على سبيل المثال، projects/earthengine-legacy/assets/users/USER/ASSET).

المصادر

list

قائمة بالحقول التي تحدّد خصائص ملف الجدول والملفات الجانبية راجِع sources حقول عناصر القاموس التالية للحصول على مزيد من المعلومات.

sources[i].uris

list

قائمة بمعرّفات الموارد المنتظمة للبيانات المطلوب نقلها في الوقت الحالي، لا تتوفّر سوى معرّفات الموارد المنتظمة (URI) لـ Google Cloud Storage. يجب تحديد كلّ معرّف موارد منتظم (URI) بالشكل التالي: gs://bucket-id/object-id. يجب أن يكون العنصر الأساسي هو العنصر الأول في القائمة، ويجب إدراج العناصر الجانبية بعد ذلك. يُضاف البادئة TableManifest.uri_prefix إلى كلّ معرّف موارد منتظم (URI) في حال ضبطها.

sources[i].charset

string

اسم ترميز الأحرف التلقائي المراد استخدامه لفك ترميز السلاسل. إذا كانت فارغة، يتم افتراض ترميز "UTF-8" تلقائيًا.

sources[i].maxErrorMeters

double

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

sources[i].maxVertices

int32

الحد الأقصى لعدد رؤوس الزوايا إذا لم يكن صفرًا، سيتم تقسيم الشكل الهندسي إلى أجزاء غير متصلة مكانيًا، وكل جزء منها يقل عن هذا الحد.

sources[i].crs

string

رمز نظام CRS التلقائي أو سلسلة WKT التي تحدّد نظام مرجعي للإحداثيات لأي شكل هندسي لم يتم تحديد نظام مرجعي له وإذا تُرك الحقل فارغًا، ستكون القيمة التلقائية هي EPSG:4326. لمصادر CSV/TFRecord فقط.

sources[i].geodesic

boolean

الاستراتيجية التلقائية لتفسير الحواف في الأشكال الهندسية التي لا تملك استراتيجية أخرى محدّدة إذا كانت القيمة false، تكون الحواف مستقيمة في الإسقاط. إذا كانت القيمة صحيحة، تكون الحواف منحنية لاتّباع أقصر مسار على سطح الأرض. عندما يكون الحقل فارغًا، يتم ضبطه تلقائيًا على خطأ إذا كان نظام CRS هو نظام إحداثيات مُسقط. لمصادر CSV/TFRecord فقط.

sources[i].primaryGeometryColumn

string

عمود الهندسة المراد استخدامه كهندسة أساسية للصف عندما يكون هناك أكثر من عمود هندسة واحد.

إذا تم ترك هذا الحقل فارغًا وكان هناك أكثر من عمود هندسي واحد، يتم استخدام أول عمود هندسي يتم العثور عليه. لمصادر CSV/TFRecord فقط.

sources[i].xColumn

string

اسم عمود الإحداثي العددي x لاحتساب شكل النقطة إذا تم تحديد yColumn أيضًا، وكان كلا العمودَين يحتويان على قيم رقمية، سيتم إنشاء عمود هندسة نقطة باستخدام قيم x وy في نظام الإحداثيات الوارد في نظام CRS. إذا تُرك الحقل فارغًا ولم يحدد نظام CRS ليس نظام إحداثيات مسقطة، تكون القيمة التلقائية هي "خط الطول". إذا تُرك الحقل فارغًا وحدّد نظام CRS نظام إحداثيات مسقطة، يتم ضبطه تلقائيًا على سلسلة فارغة ولا يتم إنشاء شكل نقطة.

سيتم تسمية عمود هندسة النقطة الذي تم إنشاؤه باسم {xColumn}_{yColumn}_N حيث يتم إلحاق N بحيث يكون{xColumn}_{yColumn}_N فريدًا إذا كان هناك عمود يحمل اسم {xColumn}_{yColumn} لمصادر CSV/TFRecord فقط.

sources[i].yColumn

string

اسم عمود الإحداثي y الرقمي لاحتساب الشكل الهندسي للنقطة إذا تم تحديد xColumn أيضًا، وكان كلا العمودَين يحتويان على قيم رقمية، سيتم إنشاء عمود هندسة نقطة باستخدام قيم x وy في نظام الإحداثيات الوارد في نظام CRS. إذا تُرك الحقل فارغًا ولم يحدد نظام CRS نظام إحداثيات مسقطة، يتم ضبط القيمة التلقائية على "خط العرض". إذا تُرك الحقل فارغًا وحدّد نظام CRS نظام إحداثيات مسقطة، يتم ضبطه تلقائيًا على سلسلة فارغة ولا يتم إنشاء شكل نقطة.

سيتم تسمية عمود هندسة النقطة الذي تم إنشاؤه باسم {xColumn}_{yColumn}_N حيث يتم إلحاق N بحيث يكون{xColumn}_{yColumn}_N فريدًا إذا كان هناك عمود يحمل اسم {xColumn}_{yColumn} لمصادر CSV/TFRecord فقط.

sources[i].dateFormat

string

تنسيق لتحليل الحقول التي تشفّر التواريخ يجب أن يكون نمط التنسيق على النحو الموضّح في مستندات فئة DateTimeFormat في Joda-Time. في حال ترك هذا الحقل فارغًا، سيتم استيراد التواريخ كسلاسل. لمصادر CSV/TFRecord فقط.

sources[i].csvDelimiter

string

عند نقل ملفات CSV، يتم استخدام حرف واحد كفاصل بين قيم الأعمدة في الصف. إذا تركت هذا الحقل فارغًا، سيتم ضبط القيمة التلقائية على ','. لمصادر ملفات CSV فقط.

sources[i].csvQualifier

string

عند نقل ملفات CSV، هو الحرف الذي يحيط بقيم الأعمدة (المعروف أيضًا باسم "حرف الاقتباس"). إذا تركت هذا الحقل فارغًا، سيتم ضبط القيمة التلقائية على ". لمصادر ملفات CSV فقط.

إذا لم تكن قيمة العمود محاطة بعناصر تصفية، يتم اقتطاع المسافات البادئة والختامية. على سبيل المثال:

    ..., test,...            <== this value is not qualified
becomes the string value:
    "test"                   <== leading whitespace is stripped

أثناء:

    ...," test",...          <== this value IS qualified with quotes
becomes the string value:
    " test"                  <== leading whitespace remains!

uriPrefix

string

بادئة اختيارية يتمّ وضعها قبل كلّ uris محدّد في البيان

startTime

integer

الطابع الزمني المرتبط بمادة العرض، إن وجد ويتوافق ذلك عادةً مع الوقت الذي تم فيه جمع البيانات. بالنسبة إلى مواد العرض التي تتوافق مع فاصل زمني، مثل متوسّط القيم على مدار شهر أو عام، يتوافق الطابع الزمني مع بداية هذا الفاصل الزمني. يتم تحديدها بالثواني (اختياريًا) بالنانوسيكون منذ بدء حساب الفترة (01‏-01‏-1970). يُفترض أنّه في المنطقة الزمنية للتوقيت العالمي المنسّق.

endTime

integer

بالنسبة إلى مواد العرض التي تتوافق مع فاصل زمني، مثل متوسط القيم على مدار شهر أو عام، يتوافق الطابع الزمني مع نهاية ذلك الفاصل (حصري). يتم تحديدها بالثواني (اختياريًا) بالنانوسيكون منذ بدء حساب الفترة (01‏-01‏-1970). يُفترض أنّه في المنطقة الزمنية للتوقيت العالمي المنسّق.

المواقع

dictionary

قاموس مسطّح عشوائي لأزواج المفاتيح والقيم يجب أن تكون المفاتيح سلاسل، ويمكن أن تكون القيم إما أرقامًا أو سلاسل. لا تتوفّر قيم القوائم بعد لمواد العرض التي يحمّلها المستخدم.

columnDataTypeOverrides

dictionary

إذا لم تعمل ميزة التعرّف التلقائي على النوع بشكل صحيح، استخدِم هذا الحقل مع أسماء الأعمدة كمفاتيح وإحدى الثابتات التالية كقيم: COLUMN_DATA_TYPE_STRING وCOLUMN_DATA_TYPE_NUMERIC وCOLUMN_DATA_TYPE_LONG.

القيود

حجم بيان JSON

الحد الأقصى لحجم ملف البيان بتنسيق JSON هو 10 ميغابايت. إذا كان لديك العديد من الملفات المطلوب تحميلها، ننصحك بالتفكير في طرق لتقليل عدد الأحرف اللازمة لوصف مجموعة البيانات. على سبيل المثال، استخدِم حقل uriPrefix لتجنُّب الحاجة إلى تقديم مسار حزمة Google Cloud Platform لكل معرّف موارد منتظم في قائمة uris. إذا كان حجم الملفات يحتاج إلى تصغير إضافي، حاوِل تقصير أسماء الملفات.