داده‌ها را به چت Google وارد کنید

با استفاده از Google Chat API، می‌توانید داده‌ها را از دیگر پلتفرم‌های پیام‌رسانی خود به Google Chat وارد کنید. می‌توانید پیام‌ها، پیوست‌ها، واکنش‌ها، عضویت‌ها و موجودیت‌های فضایی موجود را از دیگر پلتفرم‌های پیام‌رسانی خود به منابع Chat API مربوطه وارد کنید. می توانید این داده ها را با ایجاد فضاهای چت در حالت واردات و وارد کردن داده ها به آن فضاها وارد کنید. پس از اتمام موفقیت آمیز فرآیند، این فضاها به فضاهای چت استاندارد تبدیل می شوند.

در زیر مراحل کامل واردات توضیح داده شده است:

1. واردات خود را برنامه ریزی کنید
2. مجوز را برای برنامه چت پیکربندی کنید
3. ایجاد یک فاصله در حالت واردات
4. منابع وارداتی
5. اعتبار سنجی منابع وارداتی
6. تطبیق تفاوت های منابع وارد شده با داده های منبع
7. حالت واردات کامل
8. اجازه دسترسی به فضا پس از حالت واردات
9. عیب یابی

پیش نیازها

واردات خود را برنامه ریزی کنید

بر این اساس برای مقدار داده‌ای که باید وارد شود برنامه‌ریزی کنید، درک کنید که محدودیت‌ها و سهمیه‌های استفاده چگونه می‌توانند بر فرآیند واردات تأثیر بگذارند، و از انواع فضاهای چت پشتیبانی‌شده هنگام وارد کردن به فضای جدید آگاه باشید.

محدودیت های استفاده از API را مرور کنید

زمان مورد نیاز برای وارد کردن داده ها به چت بسته به تعداد منابع چت برای وارد کردن می تواند بسیار متفاوت باشد. محدودیت‌های استفاده برنامه گپ و مقدار داده‌های برنامه‌ریزی‌شده برای وارد کردن از پلت فرم پیام‌رسانی مبدأ را مرور کنید تا یک جدول زمانی تخمینی تعیین کنید.

هنگام وارد کردن پیام‌ها به یک فضا، توصیه می‌کنیم که تماس‌ها را به متد messages.create() در رشته‌های پیام مختلف پخش کنید.

فضاهای پشتیبانی شده برای وارد کردن را شناسایی کنید

حالت واردات فقط از SpaceType of SPACE پشتیبانی می کند. از DIRECT_MESSAGE پشتیبانی نمی کند. اگر عضو برنامه پیش‌نمایش برنامه‌نویس هستید، GROUP_CHAT نیز پشتیبانی می‌شود. برای اطلاعات بیشتر به مستندات SpaceType مراجعه کنید.

ایجاد یک فاصله در حالت واردات

برای ایجاد فاصله در حالت import، متد create را در منبع Space فراخوانی کنید و importMode روی true تنظیم کنید.

هنگامی که فضا را در حالت واردات ایجاد می کنید، به موارد زیر توجه کنید.

• تاریخ و زمان - به یاد داشته باشید، حالت واردات باید ظرف 30 روز تکمیل شود. اگر پس از 30 روز از زمان فراخوانی متد spaces.create() همچنان در حالت import باشد، به طور خودکار حذف می شود و غیرقابل دسترسی و غیرقابل بازیابی می شود.
  • از مقدار فیلد createTime برای پیگیری انقضای بازه زمانی 30 روزه استفاده نکنید. این همیشه مانند زمانی نیست که متد spaces.create() فراخوانی می کنید. هنگام استفاده از حالت واردات، قسمت createTime را می توان روی مهر زمانی تاریخی که در آن فضا در منبع ایجاد شده است تنظیم کرد تا زمان ایجاد اصلی حفظ شود.
• نام منبع فضا ( name ) - شناسه منحصر به فردی که برای بازیابی اطلاعات مربوط به فضای خاص استفاده می شود و در مراحل بعدی هنگام وارد کردن محتوا به فضا به آن ارجاع داده می شود.

برای حفظ زمان ایجاد موجودیت فضایی معادل از پلت فرم پیام منبع، می توانید createTime فضا را تنظیم کنید. این createTime باید روی مقداری بین 1 ژانویه 2000 و زمان حال تنظیم شود.

برای ایجاد فضای خارجی در حالت import، externalUserAllowed را روی true تنظیم کنید. پس از اینکه وارد کردن با موفقیت انجام شد، می توانید کاربران خارجی اضافه کنید.

مثال زیر نحوه ایجاد فاصله در حالت import را نشان می دهد:

function createSpaceInImportMode() {
  const space = Chat.Spaces.create({
      spaceType: 'SPACE',
      displayName: 'DISPLAY_NAME',
      importMode: true,
      createTime: (new Date('January 1, 2000')).toJSON()
  });
  console.log(space.name);
}

"""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': 'DISPLAY_NAME',
            'importMode': True,
            'createTime': f'{datetime.datetime(2000, 1, 1).isoformat()}Z',
        }
    )
    .execute()
)

print(result)

موارد زیر را جایگزین کنید:

• EMAIL : آدرس ایمیل حساب کاربری که شما جعل هویت آن را در سراسر دامنه جعل می کنید.
• DISPLAY_NAME : نام فضای ایجاد شده در حالت واردات. این باید یک نام منحصر به فرد برای فضایی باشد که به کاربران چت نمایش داده می شود. توصیه می‌کنیم از همان نام نمایشی فضایی که داده‌ها را از آن وارد می‌کنید استفاده کنید.

منابع وارداتی

برای وارد کردن منابع از دیگر پلتفرم‌های پیام‌رسان، منابع چت Google (مانند پیام‌ها، واکنش‌ها، پیوست‌ها) را در فضای حالت واردات ایجاد می‌کنید. وقتی منبعی را در فضا ایجاد می‌کنید، داده‌هایی را از منبع مرتبط از پلتفرم پیام که از آن مهاجرت می‌کنید مشخص می‌کنید.

پیام ها

برنامه‌های گپ شما می‌توانند پیام‌ها را با استفاده از اختیارات خودشان یا از طرف یک کاربر از طریق جعل هویت وارد کنند. نویسنده پیام روی حساب کاربری جعل شده تنظیم شده است. برای اطلاعات بیشتر، به مجوز برنامه‌های گپ مراجعه کنید. برای وارد کردن یک پیام در فضای حالت واردات، روش create را در منبع Message فراخوانی کنید. به منظور حفظ زمان ایجاد پیام اصلی از پلت فرم پیام منبع، می‌توانید createTime پیام را تنظیم کنید. این createTime باید روی مقداری بین زمان ایجاد فضایی که قبلاً تنظیم کرده‌اید و زمان فعلی تنظیم شود.

پیام‌های موجود در یک فضا نمی‌توانند حاوی همان createTime باشند، حتی اگر پیام‌های قبلی با آن زمان حذف شوند.

پیام‌های حاوی نشانی‌های وب شخص ثالث در فضاهای حالت واردات نمی‌توانند پیش‌نمایش پیوند را در چت Google ارائه دهند.

وقتی پیام‌ها را در حالت واردات ایجاد می‌کنید، فضاها به هیچ کاربری اطلاع نمی‌دهند یا ایمیل ارسال نمی‌کنند، از جمله پیام‌هایی که حاوی ذکر کاربر هستند.

مثال زیر نحوه ایجاد یک پیام در فضای حالت واردات را نشان می دهد:

"""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 API آپلود کند . برای اطلاعات در مورد روش‌های منبع و انواع پشتیبانی احراز هویت در فضاهای حالت واردات، به مجوز برنامه‌های گپ مراجعه کنید. با این حال، ما به شدت توصیه می‌کنیم که از Google Drive API برای آپلود پیوست‌ها به‌عنوان فایل‌های Google Drive استفاده کنید و URI فایل‌ها را به پیام‌های مربوطه در فضاهای حالت واردات پیوند دهید تا پیوست‌ها را از دیگر پلت‌فرم‌های پیام‌رسان وارد کنید تا از محدودیت داخلی Google Chat برای آپلود پیوست جلوگیری کنید.

عضویت های تاریخی

عضویت‌های تاریخی عضویت‌هایی هستند که برای کاربرانی ایجاد شده‌اند که قبلاً موجودیت فضای اصلی را از پلتفرم پیام‌رسانی مبدأ ترک کرده‌اند، اما شما می‌خواهید داده‌های آن‌ها را در Chat حفظ کنید . برای اطلاعات در مورد افزودن اعضای جدید پس از اینکه فضا دیگر در حالت واردات نیست، به ایجاد منبع عضویت مراجعه کنید.

در بسیاری از موارد، زمانی که آن اعضای تاریخی مشمول خط‌مشی حفظ داده در Google هستند، می‌خواهید داده‌ها (مانند پیام‌ها و واکنش‌ها) ایجاد شده توسط عضویت‌های تاریخی را قبل از وارد کردن آنها به گپ در یک فضا حفظ کنید. در حالی که فضا در حالت واردات است، می‌توانید آن عضویت‌های تاریخی را با استفاده از روش create در منبع Membership وارد فضا کنید. برای حفظ زمان مرخصی عضویت تاریخی، باید deleteTime عضویت را تنظیم کنید. این زمان مرخصی باید دقیق باشد زیرا روی داده‌هایی که برای آن عضویت‌ها حفظ شود تأثیر می‌گذارد. علاوه بر این، این deleteTime باید بعد از مهر زمانی ایجاد فضا باشد و نباید مهر زمانی آینده باشد.

علاوه بر deleteTime ، می‌توانید createTime نیز تنظیم کنید تا زمان عضویت اصلی عضویت تاریخی حفظ شود. برخلاف deleteTime ، createTime اختیاری است. اگر تنظیم نشود، createTime به طور خودکار با کم کردن 1 میکروثانیه از deleteTime محاسبه می‌شود. در صورت تنظیم، createTime باید قبل از deleteTime باشد و باید در زمان ایجاد فضا یا بعد از آن باشد. این اطلاعات createTime برای تعیین حفظ داده ها استفاده نمی شود و در ابزارهای سرپرست مانند کنسول Google Admin و Google Vault قابل مشاهده نیست.

در حالی که ممکن است چندین راه وجود داشته باشد که کاربر بتواند به پلتفرم پیام‌رسانی مبدأ بپیوندد و یک فضای خالی بگذارد (از طریق دعوت، پیوستن توسط خود، اضافه شدن توسط کاربر دیگری)، در Chat، این اقدامات همه با فیلدهای عضویت تاریخی createTime و deleteTime نشان داده می‌شوند. به عنوان اضافه یا حذف شده است.

مثال زیر نحوه ایجاد یک عضویت تاریخی در فضای حالت import را نشان می دهد:

"""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 : شناسه منحصر به فرد کاربر .

واردات منابع در فضای خارجی

فقط می‌توانید با استفاده از اطلاعات کاربری متعلق به کاربران داخل سازمان Workspace خود، یک فضای خارجی با حالت واردات ایجاد کنید. این فقط زمانی اعمال می شود که فضا در حالت واردات است. هنگامی که فضا حالت واردات را کامل کرد ، کاربران خارجی را می توان برای پیوستن به فضاهای وارد شده دعوت کرد (به بخش دسترسی مراجعه کنید) و اعتبار آنها را می توان برای فراخوانی Chat API استفاده کرد.

اعتبار سنجی منابع وارداتی

برنامه چت شما می‌تواند با فراخوانی روش list موجود در منبع Message ، محتوای یک فضای حالت واردات را بازخوانی و اعتبارسنجی کند. می‌توانید منابع Reaction و Attachment را از emojiReactionSummaries و هر پیام بازگردانده‌شده در فیلدهای attachment بخوانید. برنامه‌های چت فقط می‌توانند این روش را از طرف کاربر از طریق جعل هویت فراخوانی کنند. برای اطلاعات بیشتر، به مجوز برنامه‌های گپ مراجعه کنید.

برنامه چت شما همچنین می‌تواند با فراخوانی روش get در منبع Message ، پیام‌های جداگانه را برای تأیید اعتبار بخواند. برنامه‌های چت فقط می‌توانند با استفاده از اختیارات خود با این روش تماس بگیرند تا پیام‌های خود را بخوانند. برای اطلاعات بیشتر، به مجوز برنامه‌های گپ مراجعه کنید.

برنامه‌های گپ همچنین می‌توانند با فراخوانی روش list در منبع Membership ، عضویت‌های تاریخی را فهرست کنند. پس از خروج فضا از حالت واردات، روش list دیگر عضویت های تاریخی را نشان نمی دهد. برنامه‌های چت فقط می‌توانند این روش را از طرف کاربر از طریق جعل هویت فراخوانی کنند. برای اطلاعات بیشتر، به مجوز برنامه‌های گپ مراجعه کنید.

با فراخوانی متد get در منبع Space می‌توانید ویژگی‌های فضای حالت واردات را بخوانید. برنامه‌های چت فقط می‌توانند با استفاده از اختیارات خود این روش را فراخوانی کنند. برای اطلاعات بیشتر، به مجوز برنامه‌های گپ مراجعه کنید.

تطبیق تفاوت های منابع وارد شده با داده های منبع

اگر به دلیل تغییرات در موجودیت اصلی در حین وارد کردن، هر منبع وارد شده دیگر با موجودیت اصلی از پلتفرم پیام‌رسانی منبع مطابقت ندارد، برنامه‌های چت می‌توانند با Chat API تماس بگیرند تا منبع چت وارد شده را تغییر دهند. به عنوان مثال، اگر کاربر پس از ایجاد آن پیام در چت، پیامی را در بستر پیام‌رسانی مبدأ ویرایش کند، برنامه‌های چت می‌توانند پیام وارد شده را به‌روزرسانی کنند تا محتوای فعلی پیام اصلی را منعکس کند.

پیام ها

برای به‌روزرسانی فیلدهای پشتیبانی شده در یک پیام در فضای حالت واردات، روش update را در منبع Message فراخوانی کنید. برنامه‌های چت فقط می‌توانند با استفاده از همان مرجعی که در هنگام ایجاد پیام اولیه استفاده شده بود، این روش را فراخوانی کنند. اگر در طول ایجاد پیام اولیه از جعل هویت کاربر استفاده کرده اید، باید از همان کاربر جعل شده برای به روز رسانی آن پیام استفاده کنید.

برای حذف یک پیام در فضای حالت واردات، روش delete را در منبع Message فراخوانی کنید. پیام‌های موجود در فضای حالت واردات نیازی به حذف توسط سازنده پیام اصلی ندارند و می‌توانند با جعل هویت هر کاربر در دامنه حذف شوند. برنامه‌های چت فقط می‌توانند پیام‌های خود را با استفاده از اختیارات خود حذف کنند. برای اطلاعات بیشتر، به مجوز برنامه‌های گپ مراجعه کنید.

واکنش ها

برای حذف یک واکنش برای یک پیام در فضای حالت واردات، از روش delete در منبع reactions استفاده کنید. برای اطلاعات در مورد روش‌های منبع و انواع پشتیبانی احراز هویت در فضاهای حالت واردات، به مجوز برنامه‌های گپ مراجعه کنید.

پیوست ها

برای به‌روزرسانی پیوست‌ها برای یک پیام در فضای حالت واردات، از روش upload در منبع media استفاده کنید. برای اطلاعات در مورد روش‌های منبع و انواع پشتیبانی احراز هویت در فضاهای حالت واردات، به مجوز برنامه‌های گپ مراجعه کنید.

عضویت های تاریخی

برای حذف یک عضویت تاریخی در فضای حالت واردات، از روش delete در منبع Membership استفاده کنید. پس از خروج فضا از حالت واردات، روش delete دیگر به شما اجازه نمی‌دهد عضویت‌های تاریخی را حذف کنید.

نمی‌توانید عضویت تاریخی را در فضای حالت واردات به‌روزرسانی کنید. اگر می‌خواهید یک عضویت تاریخی وارد شده اشتباه را تصحیح کنید، باید ابتدا آن را حذف کنید و سپس در حالی که فضا هنوز در حالت واردات است، آن را دوباره ایجاد کنید.

فضاها

برای به روز رسانی فیلدهای پشتیبانی شده در فضای حالت واردات، از روش patch در منبع spaces استفاده کنید.

برای حذف فضای حالت واردات، از روش delete در منبع spaces استفاده کنید.

برای کسب اطلاعات در مورد روش‌های منابع و انواع پشتیبانی احراز هویت در فضاهای حالت واردات، و به مجوز برنامه‌های گپ مراجعه کنید.

حالت واردات کامل

قبل از فراخوانی روش completeImport ، باید اطمینان حاصل کنید که اعتبارسنجی و تطبیق تفاوت‌های منابع تکمیل شده است. خروج از یک فضای خارج از حالت واردات یک فرآیند غیرقابل برگشت است و فضای حالت واردات را به یک فضای معمولی تبدیل می کند. هیچ نشانگری در Chat وجود ندارد که این فضاها را به وارد کردن داده نسبت دهد.

تاریخ و ساعتی را که با completeImport تماس می‌گیرید، نام منبع کاربری که تماس برقرار کرده است و پاسخ برگشتی را یادداشت کنید. اگر باید با هر مشکلی مواجه شوید و باید آنها را بررسی کنید، این می تواند مفید باشد.

برای تکمیل حالت وارد کردن و در دسترس قرار دادن فضا برای کاربران، برنامه Chat می‌تواند روش completeImport را در منبع Space فراخوانی کند. برنامه‌های چت فقط می‌توانند این روش را از طرف کاربر از طریق جعل هویت فراخوانی کنند. برای اطلاعات بیشتر، به مجوز برنامه‌های گپ مراجعه کنید. کاربر جعل هویت پس از تکمیل این روش به عنوان مدیر فضا به فضا اضافه می شود. این متد باید ظرف 30 روز از فراخوانی اولیه متد create.space فراخوانی شود. اگر بعد از سپری شدن مدت 30 روز سعی کنید با این روش تماس بگیرید، تماس با شکست مواجه می شود زیرا فضای حالت واردات حذف شده و دیگر برای برنامه چت قابل دسترسی نیست.

لازم نیست کاربر جعل هویت در روش completeImport خالق فضا باشد.

مثال زیر نحوه تکمیل حالت واردات را نشان می دهد:

"""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 : نام فضای ایجاد شده در حالت واردات .

اجازه دسترسی به فضا پس از حالت واردات

برای اینکه کاربران چت به فضایی که اخیراً وارد شده است دسترسی داشته باشند، برنامه‌های چت می‌توانند به استفاده از محدوده chat.import و جعل هویت کاربر در عرض 30 روز از create.space() برای انجام کارهای زیر ادامه دهند:

• افزودن اعضا به فضا : متد create() را در منبع Membership فراخوانی کنید. توصیه می‌کنیم برنامه‌های چت بلافاصله پس از تکمیل وارد کردن فضا، منابع Membership را ایجاد کنند تا برنامه‌های چت بتوانند به استفاده از محدوده chat.import ادامه دهند و اطمینان حاصل کنند که همه اعضای وارد شده به فضا دسترسی دارند.
• تعیین مخاطب هدف : متد update() را در منبع Space فراخوانی کنید. برای آشنایی با نحوه ایجاد و افزودن مخاطبان هدف، به ایجاد فضای گپ Google قابل شناسایی برای کاربران خاص در سازمان Google Workspace مراجعه کنید.

برای استفاده از این روش‌ها با محدوده chat.import ، کاربر جعل هویت باید مدیر فضا باشد.

برای فضاهای خارجی، متد create() عضویت نیز اجازه می دهد تا کاربران خارج از سازمان Workspace خود را دعوت کنید. مطمئن شوید که تمام محدودیت های شناخته شده برای کاربران خارجی را درک کرده اید.

عیب یابی

اگر هنگام وارد کردن فضاهای چت با مشکل مواجه شدید، مسائل زیر را برای راهنمایی بررسی کنید. اگر با پاسخ خطایی مواجه شدید، آن را یادداشت کنید (متن را در یک سند کپی/پیست کنید یا یک اسکرین شات ذخیره کنید) برای مراجعات بعدی و عیب یابی.

وقتی فضایی با موفقیت وارد شد، CompleteImportSpace با وضعیت OK تکمیل می‌شود.

قبل از منقضی شدن پنجره 30 روزه، وارد کردن کامل نشد

همانطور که قبلا در Create a space in import mode توضیح داده شد، اگر بعد از 30 روز از زمان فراخوانی روش ایجاد، فضا همچنان در حالت import باشد، به طور خودکار حذف می شود و غیرقابل دسترسی و غیرقابل بازیابی می شود.

متأسفانه فضای حذف شده دیگر در دسترس یا قابل بازیابی نیست و فرآیند واردات باید دوباره آغاز شود.

فضاهای گمشده را پیدا کنید

اگر نمی‌توانید فضای گپ جدید را پیدا کنید، جدول زیر را برای پاسخی که از CompleteImportSpace دریافت کرده‌اید بررسی کنید تا توضیح و نحوه حل آن را ببینید.