تعديل حالة قراءة مساحة المستخدم

يوضِّح هذا الدليل كيفية استخدام طريقة updateSpaceReadState على مورد SpaceReadState لواجهة برمجة تطبيقات Google Chat لوضع علامة "مقروءة" أو "غير مقروءة" على المساحات.

مورد SpaceReadState هو مورد مفرد يمثّل تفاصيل حول آخر رسالة مقروءة لمستخدم محدّد في مساحة Google Chat.

المتطلبات الأساسية

Python

  • Python 3.6 أو أحدث
  • تتيح لك أداة إدارة الحِزم pip

  • أحدث مكتبات عملاء Google للغة Python. لتثبيتها أو تحديثها، شغّل الأمر التالي في واجهة سطر الأوامر:

    pip3 install --upgrade google-api-python-client google-auth-oauthlib
  • مشروع على Google Cloud تم فيه تفعيل Google Chat API وضبطه لمعرفة الخطوات، يُرجى الاطّلاع على مقالة إنشاء تطبيق Google Chat.

  • تم ضبط التفويض لتطبيق Chat. للحصول على تفاصيل حول حالة القراءة للمستخدم داخل مساحة، يجب توفير مصادقة المستخدم مع نطاق التفويض chat.users.readstate.

Node.js

  • Node.js وnpm

  • أحدث مكتبات عملاء Google لنظام Node.js. ولتثبيتها، شغِّل الأمر التالي في واجهة سطر الأوامر:

    npm install @google-cloud/local-auth @googleapis/chat
  • مشروع على Google Cloud تم فيه تفعيل Google Chat API وضبطه لمعرفة الخطوات، يُرجى الاطّلاع على مقالة إنشاء تطبيق Google Chat.

  • تم ضبط التفويض لتطبيق Chat. للحصول على تفاصيل حول حالة القراءة للمستخدم داخل مساحة، يجب توفير مصادقة المستخدم مع نطاق التفويض chat.users.readstate.

برمجة تطبيقات

  • حساب على Google Workspace يمكنه الوصول إلى Google Chat
  • هو تطبيق Chat منشور. لإنشاء تطبيق في Chat، اتّبِع quickstart.
  • تم ضبط التفويض لتطبيق Chat. للحصول على تفاصيل حول حالة القراءة للمستخدم داخل مساحة، يجب توفير مصادقة المستخدم مع نطاق التفويض chat.users.readstate.

تعديل حالة قراءة مساحة المستخدم المتصل

لتعديل حالة القراءة لمستخدم في مساحة، عليك تضمين ما يلي في طلبك:

  • حدِّد نطاق تفويض chat.users.readstate.
  • استدعِ طريقة updateSpaceReadState في المورد SpaceReadState.
  • مرِّر name لحالة القراءة للمساحة للحصول عليها، والتي تتضمّن رقم تعريف المستخدم أو العنوان البديل للبريد الإلكتروني ومعرّف المساحة. لا يتيح الحصول على حالة قراءة المساحة سوى الحصول على حالة القراءة للمستخدم المتصل، والتي يمكن تحديدها من خلال ضبط أحد الخيارات التالية:
    • العنوان البديل للبريد الإلكتروني me. مثلاً، users/me/spaces/SPACE/spaceReadState.
    • عنوان البريد الإلكتروني على Workspace للمستخدم الذي يتصل بك مثلاً، users/user@example.com/spaces/SPACE/spaceReadState.
    • رقم تعريف المستخدم الخاص بالمستخدم المتصل مثلاً، users/USER/spaces/SPACE/spaceReadState.
  • مرِّر العلامة updateMask التي تحدّد جوانب حالة قراءة المساحة المطلوب تعديلها، والتي تتيح استخدام مسارات الحقول التالية:
    • lastReadTime: الوقت الذي تم فيه تعديل حالة قراءة مساحة المستخدم وعادةً ما يتوافق ذلك مع الطابع الزمني لآخر رسالة مقروءة، أو طابع زمني يحدّده المستخدم لوضع علامة على آخر موضع قراءة في مساحة. عند توفُّر lastReadTime قبل وقت إنشاء آخر رسالة، تظهر المساحة على أنّها "غير مقروءة" في واجهة المستخدم. لوضع علامة "مقروءة" على المساحة، اضبط lastReadTime على أي قيمة بعد (أكبر) من وقت إنشاء آخر رسالة. تم إجبار lastReadTime على مطابقة أحدث وقت لإنشاء رسالة. يُرجى العلم بأنّ حالة قراءة المساحة لا تؤثّر إلا في حالة قراءة الرسائل التي تظهر في المحادثة ذات المستوى الأعلى في المساحة. لا تتأثر الردود في سلاسل المحادثات بهذا الطابع الزمني، بل تعتمد بدلاً من ذلك على حالة قراءة سلسلة المحادثات.

يعدِّل المثال التالي حالة قراءة مساحة المستخدم المتصل:

Python

  1. في دليل العمل، أنشِئ ملفًا باسم chat_spaceReadState_update.py.

  2. ضمِّن الرمز التالي في chat_spaceReadState_update.py:

    from google_auth_oauthlib.flow import InstalledAppFlow
from googleapiclient.discovery import build

# Define your app's authorization scopes.
# When modifying these scopes, delete the file token.json, if it exists.
SCOPES = ["https://www.googleapis.com/auth/chat.users.readstate"]

def main():
    '''
    Authenticates with Chat API via user credentials,
    then updates the space read state for the calling user.
    '''

    # Authenticate with Google Workspace
    # and get user authorization.
    flow = InstalledAppFlow.from_client_secrets_file(
                      'client_secrets.json', SCOPES)
    creds = flow.run_local_server()

    # Build a service endpoint for Chat API.
    chat = build('chat', 'v1', credentials=creds)

    # Use the service endpoint to call Chat API.
    result = chat.users().spaces().updateSpaceReadState(

        # The space read state to update.
        #
        # Replace USER with the calling user's ID, Workspace email,
        # or the alias me.
        #
        # Replace SPACE with a space name.
        # Obtain the space name from the spaces resource of Chat API,
        # or from a space's URL.
        name='users/me/spaces/SPACE/spaceReadState',
        updateMask='lastReadTime',
        body={'lastReadTime': f'{datetime.datetime(2000, 1, 3).isoformat()}Z'}

      ).execute()

    # Prints the API's response.
    print(result)

if __name__ == '__main__':
    main()

  3. في التعليمة البرمجية، استبدل ما يلي:

    • SPACE: اسم مساحة يمكنك الحصول عليه من خلال طريقة spaces.list في Chat API أو من عنوان URL الخاص بالمساحة

  4. في دليل العمل، أنشئ النموذج وقم بتشغيله:

    python3 chat_spaceReadState_update.py

Node.js

  1. في دليل العمل، أنشِئ ملفًا باسم chat_spaceReadState_update.js.

  2. ضمِّن الرمز التالي في chat_spaceReadState_update:

    const chat = require('@googleapis/chat');
const {authenticate} = require('@google-cloud/local-auth');

/**
* Authenticates with Chat API via user credentials,
* then updates the space read state for the calling user.
* @return {!Promise<!Object>}
*/
async function updateSpaceReadState() {

  /**
  * Authenticate with Google Workspace
  * and get user authorization.
  */
  const scopes = [
    'https://www.googleapis.com/auth/chat.users.readstate',
  ];

  const authClient =
      await authenticate({scopes, keyfilePath: 'client_secrets.json'});

  /**
  * Build a service endpoint for Chat API.
  */
  const chatClient = await chat.chat({version: 'v1', auth: authClient});

  /**
  * Use the service endpoint to call Chat API.
  */
  return await chatClient.users.spaces.updateSpaceReadState({

    /**
    * The space read state to update.
    *
    * Replace USER with the calling user's ID, Workspace email,
    * or the alias me.
    *
    * Replace SPACE with a space name.
    * Obtain the space name from the spaces resource of Chat API,
    * or from a space's URL.
    */
    name: 'users/me/spaces/SPACE/spaceReadState',
    updateMask: 'lastReadTime',
    requestBody: {
      lastReadTime: '{datetime.datetime(2000, 1, 3).isoformat()}Z'
    }
  });
}

/**
* Use the service endpoint to call Chat API.
*/
getSpaceReadState().then(console.log);

  3. في التعليمة البرمجية، استبدل ما يلي:

    • SPACE: اسم مساحة يمكنك الحصول عليه من خلال طريقة spaces.list في Chat API أو من عنوان URL الخاص بالمساحة

  4. في دليل العمل، أنشئ النموذج وقم بتشغيله:

    node chat_spaceReadState_update.js

برمجة تطبيقات

يستدعي هذا المثال واجهة Chat API باستخدام Advanced Chat Service.

  1. أضِف نطاق تفويض chat.users.readstate إلى ملف appsscript.json لمشروع "برمجة تطبيقات Google":

    "oauthScopes": [
  "https://www.googleapis.com/auth/chat.users.readstate"
]

  2. أضِف دالة مثل هذه إلى رمز مشروع برمجة التطبيقات:

    /**
* Authenticates with Chat API via user credentials,
* then updates the space read state for the calling user.
* @param {string} spaceReadStateName The resource name of the space read state.
*/
function updateSpaceReadState(spaceReadStateName) {
  try {
    const time = new Date('January 1, 2000')).toJSON();
    const body = {'lastReadTime': time};
    Chat.Users.Spaces.updateSpaceReadState(spaceReadStateName, body);
  } catch (err) {
    // TODO (developer) - Handle exception
    console.log('Failed to update read state with error %s', err.message);
  }
}

تعدِّل Google Chat API حالة قراءة المساحة المحدّدة وتعرض مثيل من مورد SpaceReadState.