باستخدام Google Chat API، يمكنك استيراد البيانات من المنصات الأخرى للمراسلة إلى Google Chat. يمكنك استيراد الرسائل والمرفقات والتفاعلات والمشتركين والكيانات الحالية في المساحات من منصات المراسلة الأخرى إلى موارد Chat API المقابلة. يمكنك استيراد هذه البيانات من خلال إنشاء مساحات Chat في وضع الاستيراد واستيراد البيانات إلى تلك المساحات.
في ما يلي نظرة عامة على الخطوات المتضمنة في استيراد البيانات باستخدام مساحة وضع الاستيراد:
- راجِع حدود استخدام واجهة برمجة التطبيقات وخطِّط مسبقًا.
- اضبط التفويض لتطبيق Chat.
- إنشاء مساحة في وضع الاستيراد
- استيراد الموارد
- التحقّق من صحة الموارد التي تم استيرادها
- تسوية الاختلافات في الموارد المستورَدة من بيانات المصدر.
- وضع الاستيراد الكامل
- أنشئ موارد الاشتراك.
المتطلبات الأساسية
برمجة تطبيقات
- حساب على Google Workspace يمكنه الوصول إلى Google Chat
- هو تطبيق Chat منشور. لإنشاء تطبيق في Chat، اتّبِع quickstart.
Python
- Python 3.6 أو أحدث
- تتيح لك أداة إدارة الحِزم pip
أحدث مكتبات عملاء Google للغة Python. لتثبيتها أو تحديثها، شغّل الأمر التالي في واجهة سطر الأوامر:
pip3 install --upgrade google-api-python-client google-auth
تطبيق Chat منشور. لإنشاء تطبيق Chat ونشر تطبيق Chat، يُرجى الاطّلاع على المقالة إنشاء تطبيق Google Chat.
تم ضبط التفويض لتطبيق Chat. يجب أن يكون تطبيق Chat مفوَّضًا على مستوى النطاق في أي نطاقات يستورد التطبيق المحتوى فيها. يُرجى الاطّلاع على مقالة تفويض تطبيقات Chat.
راجِع الحدود القصوى المسموح بها لاستخدام واجهة برمجة التطبيقات وخطِّط بشكل مسبق.
قد يختلف الوقت اللازم لاستيراد البيانات إلى Chat بشكل كبير استنادًا إلى كمية موارد Chat المُراد استيرادها. ننصحك بالتخطيط مسبقًا من خلال مراجعة حدود الاستخدام لتطبيق Chat ومقدار البيانات المجدولة للاستيراد من منصة المراسلة المصدر لتحديد مخطط زمني مقدَّر.
إنشاء مساحة في وضع الاستيراد
لإنشاء مساحة في وضع الاستيراد، عليك استدعاء
طريقة create
على
Space
المورد
وضبط importMode
على true
. للحفاظ على وقت إنشاء كيان المساحة المكافئ من منصة المراسلة المصدر، يمكنك ضبط createTime
للمساحة. يجب ضبط createTime
على قيمة تتراوح بين 1 كانون الثاني (يناير) 2000 والوقت الحالي.
دوِّن name
في المساحة التي تنشئها كي تتمكّن من الرجوع إليها في خطوات لاحقة عند استيراد المحتوى إلى المساحة.
من وقت استدعاء طريقة create
، يتم منح التطبيقات في Chat
30 يومًا
لاستيراد الموارد
إلى المساحة،
وإكمال وضع الاستيراد،
وإنشاء موارد الاشتراك باستخدام
نطاقchat.import
. سيظل بإمكان تطبيقات Chat إنشاء اشتراكات بعد
30 يومًا باستخدام نطاقات العضوية العادية في Chat API.
بعد 30 يومًا، إذا كانت المساحة لا تزال في وضع الاستيراد، سيتم حذفها تلقائيًا
ولن يتمكّن تطبيق Chat من الوصول إليها ولن يتمكّن من استردادها. ننصحك بالتخطيط مسبقًا من خلال مراجعة
حدود الاستخدام
لتطبيق Chat لضمان إمكانية استيراد جميع الموارد المُجدوَلة إلى Chat
ضمن هذا الإطار الزمني.
يوضّح المثال التالي كيفية إنشاء مساحة في وضع الاستيراد:
برمجة تطبيقات
function createSpaceInImportMode() {
const space = Chat.Spaces.create({
spaceType: 'SPACE',
displayName: 'Import Mode Space',
importMode: true,
createTime: (new Date('January 1, 2000')).toJSON()
});
console.log(space.name);
}
Python
"""Create a space in import mode."""
import datetime
from google.oauth2 import service_account
from googleapiclient.discovery import build
# Specify required scopes.
SCOPES = [
'https://www.googleapis.com/auth/chat.import',
]
CREDENTIALS = (
service_account.Credentials.from_service_account_file('credentials.json')
.with_scopes(SCOPES)
.with_subject('EMAIL')
)
# Build a service endpoint for Chat API.
service = build('chat', 'v1', credentials=CREDENTIALS)
result = (
service.spaces()
.create(
body={
'spaceType': 'SPACE',
'displayName': 'Import Mode Space',
'importMode': True,
'createTime': f'{datetime.datetime(2000, 1, 1).isoformat()}Z',
}
)
.execute()
)
print(result)
استبدل ما يلي:
EMAIL
: عنوان البريد الإلكتروني لحساب المستخدم الذي تنتحل صفته باستخدام مرجع على مستوى النطاق
استيراد الموارد
لاستيراد الموارد من منصات المراسلة الأخرى، يمكنك إنشاء موارد Google Chat (مثل الرسائل والتفاعلات والمرفقات) في مساحة وضع الاستيراد. عند إنشاء مورد في المساحة، عليك تحديد بيانات من المورد ذي الصلة من النظام الأساسي للرسائل الذي يتم نقل البيانات منه.
الرسائل
يمكن لتطبيقات Chat استيراد الرسائل باستخدام تفويضها الخاص أو
نيابةً عن مستخدم من خلال انتحال الهوية. (تم ضبط مؤلف الرسالة على
حساب المستخدم الذي ينتحل الهوية). لمزيد من المعلومات، يُرجى الاطّلاع على
تفويض تطبيقات Chat.
لاستيراد رسالة في مساحة وضع الاستيراد، عليك استدعاء طريقة create
في المورد Message
.
من أجل الحفاظ على وقت إنشاء الرسالة الأصلية من النظام الأساسي للمراسلة المصدر، يمكنك ضبط createTime
للرسالة. يجب ضبط
createTime
هذا على قيمة بين وقت إنشاء المساحة الذي
ضبطته في السابق والوقت الحالي.
لا يمكن أن تحتوي الرسائل في المساحة نفسها على السمة createTime
نفسها، حتى
إذا تم حذف الرسائل السابقة التي تم إنشاؤها في ذلك الوقت.
لا يمكن للرسائل التي تحتوي على عناوين URL تابعة لجهات خارجية في مساحات وضع الاستيراد عرض معاينات الروابط داخل Google Chat.
عند إنشاء الرسائل في وضع الاستيراد، لا تُعلِم المساحات أي مستخدم بالرسائل الإلكترونية أو ترسِلها إلى أي مستخدم، بما في ذلك الرسائل التي تحتوي على إشارات المستخدمين.
يوضّح المثال التالي كيفية إنشاء رسالة في مساحة وضع الاستيراد:
Python
"""Create a message in import mode space."""
import datetime
from google.oauth2 import service_account
from googleapiclient.discovery import build
# Specify required scopes.
SCOPES = [
'https://www.googleapis.com/auth/chat.import',
]
CREDENTIALS = (
service_account.Credentials.from_service_account_file('credentials.json')
.with_scopes(SCOPES)
.with_subject('EMAIL')
)
# Build a service endpoint for Chat API.
service = build('chat', 'v1', credentials=CREDENTIALS)
NAME = 'spaces/SPACE_NAME'
result = (
service.spaces()
.messages()
.create(
parent=NAME,
body={
'text': 'Hello, world!',
'createTime': f'{datetime.datetime(2000, 1, 2).isoformat()}Z',
},
)
.execute()
)
print(result)
استبدل ما يلي:
EMAIL
: عنوان البريد الإلكتروني لحساب المستخدم الذي تنتحل صفته من خلال مرجع على مستوى النطاق.SPACE_NAME
: اسم المساحة التي تم إنشاؤها في وضع الاستيراد
التفاعلات
يمكن لتطبيق Chat استيراد التفاعلات مع الرسائل باستخدام Chat API. للحصول على معلومات عن طرق الموارد وأنواع دعم المصادقة في مساحات وضع الاستيراد، يُرجى الاطّلاع على مقالة تفويض تطبيقات Chat.
المرفقات
يمكن لتطبيقك في Chat تحميل المرفقات باستخدام Chat API. للحصول على معلومات عن طرق الموارد وأنواع دعم المصادقة في مساحات وضع الاستيراد، يُرجى الاطّلاع على مقالة تفويض تطبيقات Chat.
الاشتراكات السابقة
الاشتراكات الداعمة السابقة هي اشتراكات تم إنشاؤها للمستخدمين الذين غادروا وحدة المساحة الأصلية من منصة المراسلة المصدر، ولكنك تريد الاحتفاظ ببياناتهم في Chat. للحصول على معلومات عن إضافة أعضاء جدد بعد انتهاء المساحة في وضع الاستيراد، يُرجى الاطّلاع على المقالة إنشاء مورد عضوية.
وفي كثير من الحالات، عندما يخضع هؤلاء الأعضاء السابقون لسياسة الاحتفاظ بالبيانات في Google، يجب الاحتفاظ بالبيانات (مثل الرسائل والتفاعلات) التي تم إنشاؤها من خلال الاشتراكات السابقة في مساحة قبل استيرادها إلى Chat.
عندما تكون المساحة في وضع الاستيراد، يمكنك استيراد تلك العضويات السابقة
إلى المساحة، وذلك باستخدام
طريقة create
على
المرجع Membership
.
من أجل الحفاظ على وقت مغادرة الاشتراك السابق، عليك ضبط
deleteTime
للعضوية. يجب أن يكون وقت المغادرة هذا دقيقًا لأنّها تؤثر في البيانات التي يجب الاحتفاظ بها لهذه العضويات. بالإضافة إلى ذلك، يجب أن يأتي هذا deleteTime
بعد الطابع الزمني لإنشاء المساحة، ويجب ألا يكون طابعًا زمنيًا في المستقبل.
بالإضافة إلى deleteTime
، يمكنك أيضًا ضبط createTime
للحفاظ على
وقت الانضمام الأصلي للعضوية السابقة. وعلى عكس deleteTime
، تُعدّ السمة createTime
اختيارية. في حال ترك السياسة بدون ضبط، يتم احتساب createTime
تلقائيًا من خلال
طرح 1 ميكرو ثانية من deleteTime
. في حال ضبط هذه السياسة، يجب أن يقع createTime
قبل
deleteTime
ويجب أن يتم تشغيله في وقت إنشاء المساحة أو بعده. لا يتم استخدام معلومات createTime
هذه لتحديد الاحتفاظ بالبيانات وهي غير مرئية في أدوات
المشرفين، مثل "وحدة تحكّم المشرف في Google" وGoogle Vault.
على الرغم من أنّه قد تتوفّر عدة طرق يمكن للمستخدم من خلالها الانضمام ومغادرة مساحة في منصة المراسلة المصدر (من خلال إرسال الدعوات أو الانضمام بشكل منفرد أو الإضافة بواسطة مستخدم آخر)، في Chat، يتم تمثيل جميع هذه الإجراءات في حقلَي createTime
وdeleteTime
للعضوية السابقة مع إضافة أو إزالة هذه الإجراءات.
يوضّح المثال التالي كيفية إنشاء اشتراك سابق في مساحة وضع الاستيراد:
Python
"""Create a historical membership in import mode space."""
import datetime
from google.oauth2 import service_account
from googleapiclient.discovery import build
# Specify required scopes.
SCOPES = [
'https://www.googleapis.com/auth/chat.import',
]
CREDENTIALS = (
service_account.Credentials.from_service_account_file('credentials.json')
.with_scopes(SCOPES)
.with_subject('EMAIL')
)
# Build a service endpoint for Chat API.
service = build('chat', 'v1', credentials=CREDENTIALS)
NAME = 'spaces/SPACE_NAME'
USER = 'users/USER_ID'
result = (
service.spaces()
.members()
.create(
parent=NAME,
body={
'createTime': f'{datetime.datetime(2000, 1, 3).isoformat()}Z',
'deleteTime': f'{datetime.datetime(2000, 1, 4).isoformat()}Z',
'member': {'name': USER, 'type': 'HUMAN'},
},
)
.execute()
)
print(result)
استبدل ما يلي:
EMAIL
: عنوان البريد الإلكتروني لحساب المستخدم الذي تنتحل صفته من خلال مرجع على مستوى النطاق.SPACE_NAME
: اسم المساحة التي تم إنشاؤها في وضع الاستيرادUSER_ID
: المعرّف الفريد للمستخدم.
التحقّق من صحة الموارد التي تم استيرادها
يمكن لتطبيق Chat القراءة والتحقّق من صحة محتوى مساحة وضع الاستيراد من خلال طلب طريقة list
في المرجع Message
.
يمكنك قراءة موارد Reaction
وAttachment
من أي حقلَي
emojiReactionSummaries
وattachment
للرسالة التي يتم عرضها. ولا يمكن لتطبيقات Chat استدعاء هذه الطريقة
إلا نيابةً عن مستخدم من خلال انتحال الهوية. لمزيد من المعلومات،
يُرجى الاطّلاع على تفويض تطبيقات Chat.
يمكن لتطبيق Chat أيضًا قراءة الرسائل الفردية
للتحقّق منها من خلال استدعاء
طريقة get
على المرجع Message
.
يمكن لتطبيقات Chat استدعاء هذه الطريقة فقط لقراءة رسائلها باستخدام تفويضها الخاص. لمزيد من المعلومات، يُرجى الاطّلاع على
تفويض تطبيقات Chat.
يمكن لتطبيقات Chat أيضًا إدراج الاشتراكات السابقة من خلال استدعاء
طريقة list
في
المرجع Membership
.
بعد خروج المساحة من وضع الاستيراد، لن تعرض طريقة list
الاشتراكات السابقة بعد ذلك. لا يمكن لتطبيقات Chat استدعاء هذه الطريقة
إلا نيابةً عن المستخدم باستخدام انتحال الهوية. لمزيد من المعلومات، يُرجى الاطّلاع على
تفويض تطبيقات Chat.
يمكنك قراءة خصائص مساحة وضع الاستيراد من خلال استدعاء طريقة get
في المورد Space
.
لا يمكن لتطبيقات Chat طلب هذه الطريقة إلا باستخدام مرجع تصديق خاص بها.
لمزيد من المعلومات، يُرجى الاطّلاع على
تفويض تطبيقات Chat.
تسوية الاختلافات في الموارد المستورَدة من بيانات المصدر
إذا لم يعُد أي مورد تم استيراده مطابقًا للكيان الأصلي من منصة المراسلة المصدر بسبب تغييرات في الكيان الأصلي أثناء الاستيراد، يمكن لتطبيقات Chat استدعاء واجهة برمجة التطبيقات Chat لتعديل مورد المحادثة الذي تم استيراده. على سبيل المثال، إذا عدَّل مستخدم رسالة في منصة المراسلة المصدر بعد إنشاء هذه الرسالة في Chat، يمكن لتطبيقات Chat تعديل الرسالة المستورَدة بحيث تعكس المحتوى الحالي من الرسالة الأصلية.
الرسائل
لتعديل
الحقول المتوافقة
في رسالة في مساحة وضع الاستيراد، عليك استدعاء
طريقة update
في
Message
المورد.
ويمكن لتطبيقات Chat طلب هذه الطريقة فقط باستخدام المرجع نفسه
الذي تم استخدامه أثناء إنشاء الرسالة الأولية. إذا استخدمت انتحال هوية المستخدم أثناء الإنشاء الأولي للرسالة، يجب عليك استخدام نفس المستخدم الذي تم انتحال هويته لتعديل هذه الرسالة.
لحذف رسالة في مساحة وضع الاستيراد، يمكنك استدعاء
طريقة delete
في
مورد Message
.
لا يلزم حذف الرسائل في مساحة وضع الاستيراد من قِبل منشئ الرسائل
الأصلية، ويمكن حذفها من خلال انتحال هوية أي مستخدم في النطاق.
لا يمكن لتطبيقات Chat حذف رسائلها إلا باستخدام تفويضها. لمزيد من المعلومات، يُرجى الاطّلاع على
تفويض تطبيقات Chat.
التفاعلات
لحذف تفاعل مع رسالة في مساحة وضع الاستيراد، استخدِم
طريقة delete
في المورد reactions
. للحصول على معلومات عن طرق الموارد وأنواع دعم المصادقة في مساحات وضع الاستيراد، يُرجى الاطّلاع على مقالة
تفويض تطبيقات Chat.
المرفقات
لتعديل مرفقات رسالة في مساحة وضع الاستيراد، يمكنك استخدام طريقة upload
في المورد media
. للحصول على معلومات عن طرق الموارد وأنواع خدمات المصادقة
في مساحات وضع الاستيراد، يُرجى الاطّلاع على مقالة
تفويض التطبيقات في Chat.
الاشتراكات السابقة
لحذف اشتراك سابق في مساحة وضع الاستيراد، استخدِم
طريقة delete
في
مورد Membership
. بعد
خروج أي مسافة من وضع الاستيراد، لن تسمح لك طريقة delete
بحذف الاشتراكات السابقة.
لا يمكنك تعديل اشتراك سابق في مساحة وضع الاستيراد. إذا أردت تصحيح عضوية سابقة تم استيرادها بشكل غير صحيح، عليك حذفها أولاً ثم إعادة إنشائها عندما لا تزال المساحة في وضع الاستيراد.
المساحات
لتعديل الحقول المتوافقة في مساحة وضع الاستيراد، استخدِم طريقة patch
في مورد spaces
.
لحذف مساحة وضع الاستيراد، استخدِم
طريقة delete
في مورد spaces
.
للحصول على معلومات عن طرق الموارد وأنواع دعم المصادقة في مساحات وضع الاستيراد، يُرجى الاطّلاع على مقالة تفويض التطبيقات في Chat.
إكمال وضع الاستيراد
قبل استدعاء الإجراء completeImport
، عليك التأكّد من إكمال
التحقّق من الصحة
وتسوية الاختلافات في الموارد. إنّ الخروج من مساحة خارج وضع الاستيراد هو عملية لا يمكن التراجع عنها
وتحويل مساحة وضع الاستيراد إلى مساحة عادية. ما مِن مؤشر في Chat ينسب هذه المساحات إلى عملية استيراد بيانات.
لإكمال وضع الاستيراد وإتاحة الوصول إلى المساحة للمستخدمين،
يمكن لتطبيق Chat استدعاء طريقة completeImport
على
مورد Space
.
ولا يمكن لتطبيقات Chat طلب هذه الطريقة إلا نيابةً عن مستخدم من خلال
انتحال الهوية. لمزيد من المعلومات، يُرجى الاطّلاع على
تفويض تطبيقات Chat.
تتم إضافة المستخدم الذي يتم انتحال هويته إلى المساحة كمدير مساحة بعد اكتمال هذه الطريقة. يجب طلب هذه الطريقة خلال 30 يومًا من
طلب إجراء create.space
الأول. إذا حاولت استدعاء هذه الطريقة بعد انقضاء مدة 30 يومًا، سيؤدّي ذلك إلى حدوث إخفاقات بسبب حذف مساحة وضع الاستيراد
ولم يعد بإمكان تطبيق Chat الوصول إليها.
ولا يلزم أن يكون المستخدم الذي يتم انتحال هويته في طريقة completeImport
هو منشئ المساحة.
يوضّح المثال التالي كيفية إكمال وضع الاستيراد:
Python
"""Complete import."""
from google.oauth2 import service_account
from googleapiclient.discovery import build
# Specify required scopes.
SCOPES = [
'https://www.googleapis.com/auth/chat.import',
]
CREDENTIALS = (
service_account.Credentials.from_service_account_file('credentials.json')
.with_scopes(SCOPES)
.with_subject('EMAIL')
)
# Build a service endpoint for Chat API.
service = build('chat', 'v1', credentials=CREDENTIALS)
NAME = 'spaces/SPACE_NAME'
result = service.spaces().completeImport(name=NAME).execute()
print(result)
استبدل ما يلي:
EMAIL
: عنوان البريد الإلكتروني لحساب المستخدم الذي تنتحل صفته من خلال مرجع على مستوى النطاق.SPACE_NAME
: اسم المساحة التي تم إنشاؤها في وضع الاستيراد
إنشاء موارد الاشتراك
لإضافة اشتراكات مستخدمين في مساحة مكتملة وضع الاستيراد، عليك استدعاء
طريقة create
في
مورد Membership
.
يمكن لتطبيقات Chat مواصلة استخدام نطاق chat.import
وانتحال هوية المستخدم لطلب هذه الطريقة خلال 30 يومًا من استدعاء طريقة create.space
الأولية. يجب أن يكون المستخدم الذي تم انتحال هويته مدير مساحة.
بعد انقضاء 30 يومًا، تتطلب تطبيقات Chat نطاقات عضوية إضافية للاستعانة بهذه الطريقة.
ننصحك بأن تنشئ التطبيقات في Chat موارد الاشتراك
مباشرةً بعد اكتمال عملية الاستيراد، كي تتمكّن التطبيقات في Chat من مواصلة استخدام نطاق chat.import
لإنشاء العضوية ولمنح جميع الأعضاء
إذن الوصول إلى المساحة التي تم استيرادها.