ייבוא נתונים ל-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.

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

  • The date and time (תאריך ושעה) – זכרו, מצב ייבוא חייב להסתיים תוך 30 יום. אם המרחב המשותף עדיין נמצא במצב ייבוא אחרי 30 יום ממועד הקריאה ל-method‏ spaces.create(), הוא יימחק באופן אוטומטי ולא תהיה גישה אליו ולא ניתן יהיה לשחזר אותו.
    • אין להשתמש בערך של השדה createTime כדי לעקוב אחרי תפוגת מסגרת הזמן של 30 הימים. זה לא תמיד זהה לזה שמופיע כשמפעילים את השיטה 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 יכולה להעלות קבצים באמצעות Chat API. מידע על שיטות המשאבים ועל סוגי התמיכה באימות במרחבים משותפים במצב ייבוא זמין במאמר אימות אפליקציות Chat. עם זאת, מומלץ מאוד להשתמש ב-Google Drive API כדי להעלות קבצים מצורפים כקובצי Google Drive ולקשר את מזהי ה-URI של הקבצים להודעות המתאימות במרחבי מצב הייבוא, כדי לייבא קבצים מצורפים מפלטפורמות אחרות להעברת הודעות, מבלי להגיע למגבלה הפנימית של Google Chat להעלאת קבצים מצורפים.

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

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

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

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

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

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

מצב ייבוא מלא

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

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

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

המשתמש שאליו מתחזה ב-method 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. אין תיעוד של המרחב המשותף שיובאו בכלי לניהול המרחבים המשותפים, אבל הוא מופיע כמחוק ביומן הביקורת. המרחב המשותף יובא בהצלחה, אבל לאחר מכן נמחק. יוצרים מרחב חדש ומפעילים שוב את תהליך הייבוא.