يوضّح هذا الدليل طريقة استخدام طريقة patch
على مورد Message
لواجهة برمجة تطبيقات Google Chat
لتعديل رسالة نصية أو رسالة بطاقة في مساحة. عدِّل رسالة لتغيير سمات الرسالة، مثل ما تتضمنها، أو محتوى بطاقة. يمكنك أيضًا إلحاق رسالة نصية برسالة
بطاقة، أو إلحاق بطاقة برسالة نصية.
تتيح Chat API أيضًا استخدام
طريقة update
،
لكن ننصحك بشدة باستدعاء
طريقة patch
لأنها تستخدم طلب HTTP PATCH
بينما يستخدم
update
طلب
PUT
HTTP. لمزيد من المعلومات، راجِع
قسم PATCH
وPUT
من AIP-134.
يمثّل
مورد Message
رسالة
نص
أو
بطاقة
في Google Chat. يمكنك create
أو get
أو update
أو delete
رسالة في Google Chat API من خلال استدعاء الطرق المطابِقة. لمزيد من المعلومات عن الرسائل النصية ورسائل البطاقات، راجِع
نظرة عامة على رسائل Google Chat.
المتطلبات الأساسية
Python
- Python 3.6 أو أحدث
- إنّ أداة إدارة الحِزم pip
أحدث مكتبات عملاء Google للغة Python. لتثبيتها أو تحديثها، شغّل الأمر التالي في واجهة سطر الأوامر:
pip3 install --upgrade google-api-python-client google-auth-oauthlib google-auth
- مشروع على Google Cloud تم فيه تفعيل Google Chat API وضبطه لمعرفة الخطوات، يُرجى الاطّلاع على مقالة إنشاء تطبيق Google Chat.
تم ضبط التفويض لتطبيق Chat:
- يتوافق تعديل
رسالة نصية
مع طريقتَي المصادقة التاليتَين:
- يمكن لمصادقة المستخدم، باستخدام نطاق التفويض
chat.messages
، تعديل الرسائل التي أنشأها هذا المستخدم. - يمكن لمصادقة التطبيقات
باستخدام نطاق التفويض
chat.bot
تعديل الرسائل التي أنشأها هذا التطبيق.
- يمكن لمصادقة المستخدم، باستخدام نطاق التفويض
- يتطلب تعديل
رسالة بطاقة
مصادقة التطبيق
مع نطاق تفويض
chat.bot
.
- يتوافق تعديل
رسالة نصية
مع طريقتَي المصادقة التاليتَين:
تعديل رسالة نصية أو إضافة رسالة نصية قبل رسالة بطاقة، وذلك باستخدام آلية مصادقة المستخدم
لتعديل رسالة نصية باستخدام مصادقة المستخدم، عليك اجتياز ما يلي في طلبك:
- نطاق تفويض
chat.messages
. name
للرسالة المطلوب تعديلها.updateMask='text'
body
يحدّد الرسالة المعدّلة.
إذا كانت الرسالة المعدّلة هي رسالة بطاقة، ستتم إضافة الرسالة النصية قبل رسالة البطاقة (التي يستمر عرضها).
إليك كيفية تعديل رسالة نصية أو إضافة رسالة نصية إلى بداية رسالة بطاقة باستخدام مصادقة المستخدم:
Python
- في دليل العمل، أنشِئ ملفًا باسم
chat_update_text_message_user.py
. ضمِّن الرمز التالي في
chat_update_text_message_user.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.messages"] def main(): ''' Authenticates with Chat API via user credentials, then updates a message. ''' # 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) # Update a Chat message. result = chat.spaces().messages().patch( # The message to update, and the updated message. # # Replace SPACE with a space name. # Obtain the space name from the spaces resource of Chat API, # or from a space's URL. # # Replace MESSAGE with a message name. # Obtain the message name from the response body returned # after creating a message asynchronously with Chat REST API. name='spaces/SPACE/messages/MESSAGE', updateMask='text', body={'text': 'Updated message!'} ).execute() # Prints details about the updated message. print(result) if __name__ == '__main__': main()
في التعليمة البرمجية، استبدل ما يلي:
SPACE
: اسم مساحة يمكنك الحصول عليه من طريقةspaces.list
في Chat API أو من عنوان URL الخاص بالمساحة.MESSAGE
: اسم رسالة يمكنك الحصول عليه من نص الردّ الذي يتم عرضه بعد إنشاء رسالة بشكل غير متزامن مع Chat API أو من خلال تحديد الاسم المخصّص للرسالة عند إنشائها
في دليل العمل، أنشئ النموذج وقم بتشغيله:
python3 chat_update_text_message_user.py
تعديل رسالة نصية أو إضافة رسالة نصية قبل رسالة بطاقة، وذلك باستخدام ميزة مصادقة التطبيقات
لتعديل رسالة نصية باستخدام مصادقة التطبيقات، عليك تمرير ما يلي في طلبك:
- نطاق تفويض
chat.bot
. name
للرسالة المطلوب تعديلها.updateMask='text'
body
يحدّد الرسالة المعدّلة.
إذا كانت الرسالة المعدّلة هي رسالة بطاقة، ستتم إضافة الرسالة النصية قبل رسالة البطاقة (التي تستمر في الظهور).
في ما يلي كيفية تعديل رسالة نصية إلى رسالة نصية، أو إضافة رسالة نصية قبل رسالة بطاقة باستخدام مصادقة التطبيقات:
Python
- في دليل العمل، أنشِئ ملفًا باسم
chat_update_text_message_app.py
. ضمِّن الرمز التالي في
chat_update_text_message_app.py
:from google.oauth2 import service_account from apiclient.discovery import build # Specify required scopes. SCOPES = ['https://www.googleapis.com/auth/chat.bot'] # Specify service account details. CREDENTIALS = ( service_account.Credentials.from_service_account_file('credentials.json') .with_scopes(SCOPES) ) # Build the URI and authenticate with the service account. chat = build('chat', 'v1', credentials=CREDENTIALS) # Update a Chat message. result = chat.spaces().messages().patch( # The message to update, and the updated message. # # Replace SPACE with a space name. # Obtain the space name from the spaces resource of Chat API, # or from a space's URL. # # Replace MESSAGE with a message name. # Obtain the message name from the response body returned # after creating a message asynchronously with Chat REST API. name='spaces/SPACE/messages/MESSAGE', updateMask='text', body={'text': 'Updated message!'} ).execute() # Print Chat API's response in your command line interface. print(result)
في التعليمة البرمجية، استبدل ما يلي:
SPACE
: اسم مساحة يمكنك الحصول عليه من طريقةspaces.list
في Chat API أو من عنوان URL الخاص بالمساحة.MESSAGE
: اسم رسالة يمكنك الحصول عليه من نص الردّ الذي يتم عرضه بعد إنشاء رسالة بشكل غير متزامن مع Chat API أو من خلال تحديد الاسم المخصّص للرسالة عند إنشائها
في دليل العمل، أنشئ النموذج وقم بتشغيله:
python3 chat_update_text_message_app.py
تعديل رسالة بطاقة أو إضافة رسالة بطاقة إلى رسالة نصية
لتحديث رسالة بطاقة، مرر ما يلي في طلبك:
- نطاق تفويض
chat.bot
. يتطلب تعديل رسالة البطاقة مصادقة التطبيق. name
للرسالة المطلوب تعديلها.updateMask='cardsV2'
body
يحدّد الرسالة المعدّلة.
إذا كانت الرسالة المعدّلة هي رسالة نصية، سيتم إلحاق بطاقة بالرسالة النصية (التي ستستمر في العرض). إذا كانت الرسالة المعدّلة هي بطاقة بحد ذاتها، سيتم تعديل البطاقة المعروضة.
إليك كيفية تحديث رسالة إلى رسالة بطاقة:
Python
- في دليل العمل، أنشِئ ملفًا باسم
chat_update_card_message.py
. ضمِّن الرمز التالي في
chat_update_card_message.py
:from google.oauth2 import service_account from apiclient.discovery import build # Specify required scopes. SCOPES = ['https://www.googleapis.com/auth/chat.bot'] # Specify service account details. CREDENTIALS = ( service_account.Credentials.from_service_account_file('credentials.json') .with_scopes(SCOPES) ) # Build the URI and authenticate with the service account. chat = build('chat', 'v1', credentials=CREDENTIALS) # Update a Chat message. result = chat.spaces().messages().patch( # The message to update, and the updated message. # # Replace SPACE with a space name. # Obtain the space name from the spaces resource of Chat API, # or from a space's URL. # # Replace MESSAGE with a message name. # Obtain the message name from the response body returned # after creating a message asynchronously with Chat REST API. name='spaces/SPACE/messages/MESSAGE', updateMask='cardsV2', body= { 'cardsV2': [{ 'cardId': 'updateCardMessage', 'card': { 'header': { 'title': 'An Updated Card Message!', 'subtitle': 'Updated with Chat REST API', 'imageUrl': 'https://developers.google.com/chat/images/chat-product-icon.png', 'imageType': 'CIRCLE' }, 'sections': [ { 'widgets': [ { 'buttonList': { 'buttons': [ { 'text': 'Read the docs!', 'onClick': { 'openLink': { 'url': 'https://developers.google.com/chat' } } } ] } } ] } ] } }] } ).execute() # Print Chat API's response in your command line interface. print(result)
في التعليمة البرمجية، استبدل ما يلي:
SPACE
: اسم مساحة يمكنك الحصول عليه من طريقةspaces.list
في Chat API أو من عنوان URL الخاص بالمساحة.MESSAGE
: اسم رسالة يمكنك الحصول عليه من نص الردّ الذي يتم عرضه بعد إنشاء رسالة بشكل غير متزامن مع Chat API أو من خلال تحديد الاسم المخصّص للرسالة عند إنشائها
في دليل العمل، أنشئ النموذج وقم بتشغيله:
python3 chat_update_card_message.py
تعرِض Chat API مثيل Message
الذي يوضِّح الرسالة التي تم تعديلها.
تعديل رسالة باستخدام مسارات حقول متعدّدة في آنٍ واحد
عند تعديل رسالة، يمكنك تعديل مسارات متعدّدة لحقول الرسائل في
وقت واحد. على سبيل المثال، في طلب تعديل رسالة، يمكنك تحديد تغيير في مسارَي الحقلين text
وcardsv2
في الوقت نفسه، ما يؤدّي إلى تعديل كلّ من نص الرسالة وبطاقتها. إذا كانت الرسالة تحتوي على نص فقط بدون بطاقة،
تتم إضافة بطاقة إلى الرسالة. لمزيد من المعلومات عن مسارات الحقول المتوافقة،
راجِع مَعلمات updateMask
.
لتعديل كلٍّ من
text
وcard
من رسالة تتضمّن
مصادقة المستخدم،
عليك إكمال ما يلي في طلبك:
- نطاق تفويض
chat.messages
. name
للرسالة المطلوب تعديلها.تمثّل هذه السمة
updateMask
الذي يحدد مسارات حقل الرسالة المطلوب تعديلها، ويتم الفصل بينها بفاصلات:updateMask='text', 'cardsV2'
.body
الذي يحدد الرسالة المعدَّلة، بما في ذلك جميع مسارات الحقول المعدَّلة.
في ما يلي طريقة تعديل مسارَي الحقل text
وcardsV2
في رسالة باستخدام مصادقة المستخدم:
Python
- في دليل العمل، أنشِئ ملفًا باسم
chat_update_text_message_user.py
. ضمِّن الرمز التالي في
chat_update_text_message_user.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.messages"] def main(): ''' Authenticates with Chat API via user credentials, then updates a message. ''' # 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) # Update a Chat message. result = chat.spaces().messages().patch( # The message to update, and the updated message. # # Replace SPACE with a space name. # Obtain the space name from the spaces resource of Chat API, # or from a space's URL. # # Replace MESSAGE with a message name. # Obtain the message name from the response body returned # after creating a message asynchronously with Chat REST API. name='spaces/SPACE/messages/MESSAGE', updateMask='text,cardsV2', body= {'text': 'Updated message!', 'cardsV2': [{ 'cardId': 'updateCardMessage', 'card': { 'header': { 'title': 'An Updated Card Message!', 'subtitle': 'Updated with Chat REST API', 'imageUrl': 'https://developers.google.com/chat/images/chat-product-icon.png', 'imageType': 'CIRCLE' }, 'sections': [ { 'widgets': [ { 'buttonList': { 'buttons': [ { 'text': 'Read the docs!', 'onClick': { 'openLink': { 'url': 'https://developers.google.com/chat' } } } ] } } ] } ] } }] } ).execute() # Prints details about the updated message. print(result) if __name__ == '__main__': main()
في التعليمة البرمجية، استبدل ما يلي:
SPACE
: اسم مساحة يمكنك الحصول عليه من طريقةspaces.list
في Chat API أو من عنوان URL الخاص بالمساحة.MESSAGE
: اسم رسالة يمكنك الحصول عليه من نص الردّ الذي يتم عرضه بعد إنشاء رسالة بشكل غير متزامن مع Chat API أو من خلال تحديد الاسم المخصّص للرسالة عند إنشائها
في دليل العمل، أنشئ النموذج وقم بتشغيله:
python3 chat_update_text_message_user.py