ייבוא נתונים ל-Google Chat

באמצעות Google Chat API, אפשר לייבא נתונים מפלטפורמות אחרות להעברת הודעות ל-Google Chat. אתם יכולים לייבא הודעות קיימות, קבצים מצורפים, תגובות, חברי מועדון וישויות במרחב המשותף מפלטפורמות אחרות להעברת הודעות, למשאבים מתאימים של Chat API. כדי לייבא את הנתונים האלה, צריך ליצור מרחבים משותפים ב-Chat במצב ייבוא ולייבא את הנתונים למרחבים האלה. בסיום התהליך, המרחבים האלה יהפכו למרחבים רגילים ב-Chat.

בהמשך מפורט תהליך הייבוא המלא:

  1. תכנון הייבוא
  2. הגדרת הרשאה לאפליקציית Chat
  3. יצירת מרחב משותף במצב ייבוא
  4. ייבוא משאבים
  5. אימות משאבים מיובאים
  6. התאמת הבדלים במשאבים המיובאים מנתוני המקור
  7. מצב ייבוא מלא
  8. מתן גישה למרחב המשותף אחרי מצב הייבוא
  9. פתרון בעיות

דרישות מוקדמות

Apps Script

Python

תכנון הייבוא

כדאי לתכנן בהתאם את כמות הנתונים שרוצים לייבא, להבין איך המגבלות והמכסות לשימוש יכולות להשפיע על תהליך הייבוא, ולהכיר את סוגי המרחבים המשותפים ב-Chat שנתמכים בייבוא למרחב משותף חדש.

בדיקת המגבלות על השימוש ב-API

משך הזמן הנדרש לייבוא נתונים ל-Chat עשוי להשתנות מאוד בהתאם לכמות המשאבים ב-Chat שרוצים לייבא. כדי לקבוע לוח זמנים משוער, כדאי לבדוק את מגבלות השימוש באפליקציית Chat ואת כמות הנתונים שתזמנו לייבוא מפלטפורמת ההודעות המקורית.

כשמייבאים הודעות למרחב משותף, מומלץ לפזר את הקריאות ל-method‏ messages.create() בשרשור הודעות שונים.

זיהוי המרחבים המשותפים הנתמכים לייבוא

מצב הייבוא תומך רק ב-SpaceType של SPACE ו-GROUP_CHAT. אין תמיכה ב-DIRECT_MESSAGE. למידע נוסף, ראו מאמרי העזרה של SpaceType.

יצירת מרחב משותף במצב ייבוא

כדי ליצור מרחב משותף במצב ייבוא, צריך לבצע קריאה ל-method‏ create במשאב Space ולהגדיר את importMode כ-true.

כשיוצרים את המרחב המשותף במצב ייבוא, חשוב לשים לב לנקודות הבאות.

  • התאריך והשעה – חשוב לזכור שצריך להשלים את תהליך הייבוא תוך 30 יום. אם המרחב המשותף עדיין נמצא במצב ייבוא אחרי 30 יום ממועד הקריאה ל-method‏ spaces.create(), הוא יימחק באופן אוטומטי ולא תהיה גישה אליו ולא ניתן יהיה לשחזר אותו.
    • אין להשתמש בערך של השדה createTime כדי לעקוב אחרי תפוגת מסגרת הזמן של 30 הימים. היא לא תמיד זהה ל-method spaces.create(). כשמשתמשים במצב ייבוא, אפשר להגדיר את השדה createTime לחותמת הזמן ההיסטורית שבה המרחב המשותף נוצר במקור, כדי לשמור על זמן היצירה המקורי.
  • שם המשאב של המרחב המשותף (name) – המזהה הייחודי שמשמש לאחזור מידע על המרחב המשותף הספציפי, והוא מופיע בשלבים מאוחרים יותר בזמן ייבוא התוכן למרחב המשותף.

כדי לשמור את זמן היצירה של הישות המקבילה של המרחב המשותף מפלטפורמת האימייל המקורית, אפשר להגדיר את createTime של המרחב המשותף. צריך להגדיר את createTime הזה לערך בין 1 בינואר 2000 לבין השעה הנוכחית.

כדי ליצור מרחב משותף חיצוני במצב ייבוא, מגדירים את externalUserAllowed לערך true. אחרי שההעלאה תושלם, תוכלו להוסיף משתמשים חיצוניים.

בדוגמה הבאה מוסבר איך יוצרים מרחב משותף במצב ייבוא:

Apps Script

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);
}

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

print(result)

מחליפים את מה שכתוב בשדות הבאים:

  • EMAIL: כתובת האימייל של חשבון המשתמש שאתם מתחזים אליו עם הרשאה ברמת הדומיין.
  • DISPLAY_NAME: השם של המרחב שנוצר במצב ייבוא. השם חייב להיות ייחודי למרחב המשותף, והוא יוצג למשתמשים ב-Chat. מומלץ להשתמש באותו שם תצוגה כמו זה של המרחב המשותף שממנו מייבאים את הנתונים.

ייבוא משאבים

כדי לייבא משאבים מפלטפורמות אחרות להעברת הודעות, אתם יוצרים משאבים ב-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)

מחליפים את מה שכתוב בשדות הבאים:

תגובות

אפליקציית Chat יכולה לייבא תגובות להודעות באמצעות Chat API. מידע על שיטות המשאבים ועל סוגי התמיכה באימות במרחבים משותפים במצב ייבוא זמין במאמר אימות אפליקציות Chat.

קבצים מצורפים

אפליקציית Chat יכולה להעלות קבצים מצורפים באמצעות ה-API של Chat. מידע על שיטות המשאבים ועל סוגי התמיכה באימות במרחבים משותפים במצב ייבוא זמין במאמר אימות אפליקציות Chat. עם זאת, מומלץ מאוד להשתמש ב-Google Drive API כדי להעלות קבצים מצורפים כקובצי Google Drive ולקשר את מזהי ה-URI של הקבצים להודעות המתאימות במרחבי מצב הייבוא, כדי לייבא קבצים מצורפים מפלטפורמות אחרות להעברת הודעות, מבלי להגיע למגבלה הפנימית של Google Chat להעלאת קבצים מצורפים.

מינויים היסטוריים

מינויים היסטוריים הם מינויים שנוצרו למשתמשים שכבר עזבו את הישות המקורית של המרחב המשותף בפלטפורמת ההודעות המקורית, אבל אתם רוצים לשמור את הנתונים שלהם ב-Chat. מידע נוסף על הוספת חברים חדשים אחרי שהמרחב המשותף כבר לא נמצא במצב ייבוא זמין במאמר יצירת משאב חברות.

במקרים רבים, כשהחברים הקודמים כפופים למדיניות שמירת הנתונים ב-Google, כדאי לשמור את הנתונים (כמו הודעות ותגובות) שנוצרו על ידי חברים קודמים במרחב המשותף לפני שמייבאים אותם ל-Chat. כשהמרחבים המשותפים נמצאים במצב ייבוא, אפשר לייבא את החברויות ההיסטוריות שלהם באמצעות השיטה create במשאב Membership. כדי לשמור את מועד היציאה מהמינוי ההיסטורי, צריך להגדיר את deleteTime של המינוי. זמן העזיבה חייב להיות מדויק, כי הוא משפיע על הנתונים שיישמרו עבור מועדון החברים של הערוץ. בנוסף, הערך של deleteTime חייב להיות אחרי חותמת הזמן של יצירת המרחב המשותף, ולא יכול להיות חותמת זמן עתידית.

בנוסף ל-deleteTime, אפשר גם להגדיר את createTime כדי לשמור את זמן ההצטרפות המקורי של המינוי ההיסטורי. בניגוד ל-deleteTime, הערך createTime הוא אופציונלי. אם לא מגדירים את הערך, createTime מחושב באופן אוטומטי על ידי חיסור מיקרו-שנייה אחת מ-deleteTime. אם המדיניות מוגדרת, הערך createTime חייב להיות לפני deleteTime, וצריך להיות מאוחר יותר ממועד יצירת המרחב המשותף או אחריו. המידע ב-createTime לא משמש לקביעת משך שמירת הנתונים, והוא לא גלוי בכלים לאדמינים כמו מסוף Google Admin ו-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)

מחליפים את מה שכתוב בשדות הבאים:

ייבוא משאבים במרחב חיצוני

אפשר ליצור מרחב חיצוני עם מצב ייבוא רק באמצעות פרטי כניסה ששייכים למשתמשים בארגון Workspace שלכם. זה רלוונטי רק כשהמרחב במצב ייבוא. אחרי שהמרחב המשותף משלים את תהליך הייבוא, אפשר להזמין משתמשים חיצוניים להצטרף למרחבים המשותפים שיובאו (ראו קטע הגישה), וניתן להשתמש בפרטי הכניסה שלהם כדי לבצע קריאה ל-Chat API.

אימות משאבים מיובאים

כדי לקרוא ולתקף את התוכן של מרחבים במצב ייבוא באפליקציית Chat, צריך להפעיל את השיטה list במשאב Message. אפשר לקרוא את המשאבים של Reaction ו-Attachment מהשדות emojiReactionSummaries ו-attachment של כל הודעה שחוזרת. אפליקציות צ'אט יכולות להפעיל את השיטה הזו רק בשם המשתמש באמצעות התחזות. מידע נוסף זמין במאמר אישור אפליקציות ב-Chat.

אפליקציית Chat יכולה גם לקרוא הודעות ספציפיות לצורך אימות, על ידי קריאה לmethod‏ get במשאב Message. אפליקציות צ'אט יכולות להפעיל את השיטה הזו רק כדי לקרוא את ההודעות שלהן, באמצעות הרשאה משלהם. מידע נוסף זמין במאמר מתן הרשאה לאפליקציות Chat.

אפליקציות צ'אט יכולות גם להציג רשימה של החברויות ההיסטוריות על ידי קריאה לmethod‏ list במשאב Membership. אחרי שיוצאים ממצב הייבוא של המרחב המשותף, השיטה list לא חושפת יותר את פרטי החברים ההיסטוריים. אפליקציות צ'אט יכולות להפעיל את השיטה הזו בשם משתמש רק באמצעות התחזות. מידע נוסף זמין במאמר מתן הרשאה לאפליקציות ב-Chat.

כדי לקרוא את המאפיינים של מרחב במצב ייבוא, צריך להפעיל את ה-method‏ get במשאב Space. אפליקציות צ'אט יכולות להפעיל את השיטה הזו רק באמצעות הרשאה משלהם. מידע נוסף זמין במאמר מתן הרשאה לאפליקציות ב-Chat.

התאמת הבדלים בין משאבים מיובאים לנתוני המקור

אם משאב שיובא כבר לא תואם לישות המקורית מפלטפורמת ההודעות של המקור בגלל שינויים בישות המקורית במהלך הייבוא, אפליקציות Chat יכולות להפעיל את Chat API כדי לשנות את משאב הצ'אט שיובא. לדוגמה, אם משתמש עורך הודעה בפלטפורמת ההודעות המקורית אחרי שההודעה הזו נוצרה ב-Chat, אפליקציות Chat יכולות לעדכן את ההודעה המיובאת כך שתשקף את התוכן הנוכחי של ההודעה המקורית.

הודעות

כדי לעדכן שדות נתמכים בהודעה במרחב במצב ייבוא, צריך להפעיל את השיטה update במשאב Message. אפליקציות צ'אט יכולות להפעיל את השיטה הזו רק באמצעות אותה הרשאה שבה השתמשו במהלך יצירת ההודעה הראשונית. אם השתמשתם בהתחזות למשתמש במהלך היצירה הראשונית של ההודעה, תצטרכו להשתמש באותו משתמש שהתחזתם אליו כדי לעדכן את ההודעה הזו.

כדי למחוק הודעה במרחב עם מצב ייבוא, קוראים ל-method delete במשאב Message. יוצר ההודעה המקורי לא צריך למחוק הודעות במרחב במצב ייבוא, ואפשר למחוק אותן על ידי התחזות לכל משתמש בדומיין. אפליקציות צ'אט יכולות למחוק רק את ההודעות שלהן באמצעות הרשאה משלהם. מידע נוסף זמין במאמר מתן הרשאה לאפליקציות ב-Chat.

תגובות

כדי למחוק תגובה להודעה במרחב משותף במצב ייבוא, משתמשים בשיטה delete במשאב reactions. במאמר אישור אפליקציות ל-Chat תוכלו לקרוא על השיטות של המשאבים וסוגי התמיכה באימות במרחבים משותפים של מצב ייבוא.

קבצים מצורפים

כדי לעדכן את הקבצים המצורפים להודעה במרחב במצב ייבוא, משתמשים בשיטה upload במשאב media. מידע על שיטות המשאבים ועל סוגי התמיכה באימות במרחבים משותפים במצב ייבוא זמין במאמר אימות אפליקציות Chat.

מינויים היסטוריים

כדי למחוק חברות היסטורית במרחב במצב ייבוא, משתמשים בשיטה delete במשאב Membership. אחרי שהמרחב המשותף יצא ממצב הייבוא, השיטה delete לא מאפשרת יותר למחוק את חברי המרחב המשותף.

אי אפשר לעדכן חברות היסטורית במרחב במצב ייבוא. אם רוצים לתקן מינוי היסטורי שיובא באופן שגוי, צריך קודם למחוק אותו ואז ליצור אותו מחדש בזמן שהמרחב עדיין במצב ייבוא.

Spaces

כדי לעדכן שדות נתמכים במרחב של מצב ייבוא, צריך להשתמש ב-method patch במשאב spaces.

כדי למחוק מרחב משותף במצב ייבוא, משתמשים בשיטה delete במשאב spaces.

במאמר אישור של אפליקציות ל-Chat תוכלו לקרוא על השיטות של המשאבים וסוגי האימות במרחבים משותפים של מצב ייבוא.

מצב ייבוא מלא

לפני הקריאה ל-method completeImport, חשוב לוודא שהושלמו האימות וההתאמה של ההבדלים במשאבים. היציאה ממצב הייבוא של מרחבים משותפים היא תהליך בלתי הפיך, והיא הופכת את המרחב המשותף ממצב הייבוא למרחב משותף רגיל. אין ב-Chat אינדיקטור שמשייך את המרחבים האלה לייבוא נתונים.

שימו לב לתאריך ולשעה שבהם אתם קוראים ל-completeImport, לשם המשאב של המשתמש שביצע את הקריאה ולתגובה שחוזרת. זה יכול להיות שימושי אם נתקלתם בבעיות וצריך לבדוק אותן.

כדי להשלים את מצב הייבוא ולהפוך את המרחב המשותף לנגיש למשתמשים, אפליקציית Chat יכולה לקרוא ל-method completeImport במשאב Space. אפליקציות צ'אט יכולות להפעיל את השיטה הזו רק בשם המשתמש באמצעות התחזות. מידע נוסף זמין במאמר מתן הרשאה לאפליקציות ב-Chat. המשתמש שהתחזותם אליו יתווסף למרחב המשותף בתור מנהל המרחב המשותף בסיום השיטה הזו. צריך לקרוא לשיטה הזו תוך 30 יום מהקריאה הראשונית ל-method create.space. אם תנסה לבצע קריאה ל-method הזה אחרי 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)

מחליפים את מה שכתוב בשדות הבאים:

הענקת גישה למרחב המשותף אחרי מצב ייבוא

כדי לתת למשתמשי Chat גישה למרחב המשותף שיובאו לאחרונה, אפליקציות Chat יכולות להמשיך להשתמש בהיקף chat.import ובהתחזות למשתמש בתוך 30 יום ממועד הקריאה הראשונית ל-method‏ create.space() כדי לבצע את הפעולות הבאות:

כדי להשתמש בשיטות האלה בהיקף chat.import, המשתמש שמתחזה אליו צריך להיות מנהל המרחב המשותף.

במרחבים משותפים חיצוניים, שיטת החברות create() מאפשרת גם להזמין משתמשים מחוץ לארגון ב-Workspace. חשוב להבין את כל המגבלות הידועות לגבי משתמשים חיצוניים.

פתרון בעיות

נתקלתם בבעיה כשאתם מייבאים מרחבים ב-Chat? תוכלו להיעזר בבעיות הבאות. אם מופיעה תשובה עם שגיאה, כדאי לשים לב אליה (מעתיקים ומדביקים את הטקסט במסמך או שומרים צילום מסך) כדי להיעזר בו בעתיד ולפתור בעיות.

כשמרחב משותף מיובא בהצלחה, הפונקציה CompleteImportSpace מסתיימת עם הסטטוס OK.

לא השלמת את הייבוא לפני שחלון הזמנים של 30 הימים פג

כפי שמתואר בקטע יצירת מרחב משותף במצב ייבוא, אם המרחב המשותף עדיין נמצא במצב ייבוא אחרי 30 יום ממועד הקריאה ל-create method, הוא נמחק באופן אוטומטי ואי אפשר לגשת אליו או לשחזר אותו.

לצערנו, המרחב המשותף שנמחק כבר לא זמין או ניתן לשחזור, וצריך להתחיל מחדש את תהליך הייבוא.

איתור מרחבים חסרים

אם לא מצאתם את המרחב המשותף החדש ב-Chat, תוכלו לבדוק את התשובה שקיבלת מ-CompleteImportSpace בטבלה הבאה כדי לקבל הסבר ולגלות איך לפתור את הבעיה.

התקבלה תשובה שלבי החקירה הסבר רזולוציה
CompleteImportSpace מפעילה חריגה והקריאה ל-GetSpace מחזירה את הערך PERMISSION_DENIED. כדאי לבדוק ברשומות שלך מתי המרחב המשותף נוצר. אם חלפו יותר מ-30 ימים, הוא נמחק באופן אוטומטי. בנוסף, אין תיעוד של המרחב המיובא בכלי לניהול המרחבים או ביומן הביקורת. חלפו יותר מ-30 ימים מאז תחילת תהליך הייבוא והמרחב המשותף לא הצליח לצאת מההעברה. יוצרים מרחב חדש ומפעילים שוב את תהליך הייבוא.
CompleteImportSpace מחזירה את הערך OK והקריאה ל-GetSpace מחזירה את הערך PERMISSION_DENIED. אין תיעוד של המרחב המשותף שיובאו בכלי לניהול המרחבים המשותפים, אבל הוא מופיע כמחוק ביומן הביקורת. המרחב המשותף יובא בהצלחה, אבל לאחר מכן נמחק. יוצרים מרחב חדש ומפעילים שוב את תהליך הייבוא.