דף זה תורגם על ידי Cloud Translation API.

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

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

לפניכם סקירה כללית של השלבים לייבוא נתונים באמצעות שימוש במרחב של מצב ייבוא:

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

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

Apps Script

חשבון Google Workspace עם גישה ל-Google Chat.
אפליקציה שפורסמה ב-Chat. כדי ליצור אפליקציה ל-Chat, תוכלו להיעזר בquickstart.

Python

Python 3.6 ואילך
הכלי pip לניהול חבילות
ספריות הלקוח העדכניות של Google ל-Python. כדי להתקין או לעדכן אותם, מריצים את הפקודה הבאה בממשק שורת הפקודה:
```
pip3 install --upgrade google-api-python-client google-auth
```
אפליקציה שפורסמה ב-Chat. במאמר פיתוח אפליקציית Google Chat מוסבר איך ליצור ולפרסם אפליקציות ל-Chat.
הרשאות שהוגדרו לאפליקציית Chat. לאפליקציית Chat צריכה להיות סמכות ברמת הדומיין בכל דומיין שהאפליקציה מייבאת תוכן אליו. במאמר מתן הרשאה לאפליקציות ל-Chat

בדיקת מגבלות השימוש ב-API ותכנון מראש

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

איך יוצרים מרחבים משותפים במצב ייבוא

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

שימו לב לname של המרחב המשותף שאתם יוצרים כדי שתוכלו להפנות אליו בשלבים מאוחרים יותר כשמייבאים תוכן.

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

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

Apps Script

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

הודעות באותו מרחב משותף לא יכולות להכיל את אותו createTime, גם אם ההודעות הקודמות עם השעה הזו נמחקות.

אי אפשר לעבד ב-Google Chat תצוגות מקדימות של קישורים בהודעות שמכילות כתובות URL של צד שלישי במרחבים משותפים שבהם נמצאים במצב ייבוא.

כשיוצרים את ההודעות במצב ייבוא, במרחבים משותפים לא נשלחות התראות או אימיילים למשתמשים, כולל הודעות שמכילות אזכורים של משתמשים.

הדוגמה הבאה מציגה איך ליצור הודעה במרחב של מצב ייבוא:

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 API כדי לייבא תגובות להודעות באפליקציית Chat. במאמר אישור אפליקציות ל-Chat תוכלו לקרוא מידע נוסף על שיטות המשאבים והסוגים של התמיכה באימות במרחבים משותפים שבהם במצב ייבוא.

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

אתם יכולים להשתמש ב-Chat API כדי להעלות קבצים מצורפים באפליקציית Chat. במאמר אישור אפליקציות ל-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)

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

EMAIL: כתובת האימייל של חשבון המשתמש שאליו אתם מתחזים באמצעות הרשאת גישה ברמת הדומיין.
SPACE_NAME: שם המרחב המשותף שנוצר במצב ייבוא.
USER_ID: המזהה הייחודי של המשתמש.

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

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

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

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

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

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

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

הודעות

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

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

תגובות

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

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

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

חברויות במועדונים היסטוריים

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

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

Spaces

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

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

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

השלמת מצב הייבוא

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

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

יצירת משאבים למנויים

כדי להוסיף משתמשים במרחב משותף שמצב הייבוא הסתיים, צריך להפעיל את השיטה method create במשאב Membership. אפליקציות Chat יכולות להמשיך להשתמש בהיקף chat.import ובהתחזות למשתמש כדי לקרוא לשיטה הזו תוך 30 יום מהקריאה הראשונית ל-method create.space. המשתמש שמתחזים אליו צריך להיות מנהל/ת המרחב המשותף.

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

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