MCP Tools Reference: calendarmcp.googleapis.com

الأداة: get_event

تعرض هذه الطريقة حدثًا واحدًا من تقويم معيّن.

استخدِم هذه الأداة للاستعلامات مثل:

  • الحصول على تفاصيل اجتماع الفريق
  • اعرض لي الحدث الذي يحمل رقم التعريف event123 في تقويمي.

مثال:

get_event(
            eventId='event123'
        )
        # Returns the event details for the event with id `event123` on the user's primary calendar.

يوضّح المثال التالي كيفية استخدام curl لاستدعاء أداة get_event MCP.

طلب Curl 
curl --location 'https://calendarmcp.googleapis.com/mcp' \
--header 'content-type: application/json' \
--header 'accept: application/json, text/event-stream' \
--data '{
  "method": "tools/call",
  "params": {
    "name": "get_event",
    "arguments": {
      // provide these details according to the tool MCP specification
    }
  },
  "jsonrpc": "2.0",
  "id": 1
}'

مخطط الإدخال

GetEventRequest

تمثيل JSON 
{
  "eventId": string,

  "calendarId": string
}
الحقول
eventId

string

الحقل مطلوب. رقم تعريف الحدث المطلوب الحصول عليه.

حقل الربط _calendar_id

يمكن أن يكون التعليق _calendar_id إحدى القيم التالية فقط:
calendarId

string

اختياريّ. رقم تعريف التقويم الذي سيتم استرداد الحدث منه الإعداد التلقائي هو التقويم الأساسي للمستخدم.

مخطط النتائج

الحدث

تمثيل JSON 
{
  "id": string,
  "status": string,
  "htmlLink": string,
  "created": string,
  "updated": string,
  "summary": string,
  "description": string,
  "location": string,
  "creator": {
    object (Principal)
  },
  "organizer": {
    object (Principal)
  },
  "start": {
    object (DateOrDateTime)
  },
  "end": {
    object (DateOrDateTime)
  },
  "recurrence": [
    string
  ],
  "recurringEventId": string,
  "originalStartTime": {
    object (DateOrDateTime)
  },
  "transparency": string,
  "visibility": string,
  "attendees": [
    {
      object (Attendee)
    }
  ],
  "eventType": string,
  "conferenceUrl": string,
  "colorId": string,
  "overrideReminders": [
    {
      object (Reminder)
    }
  ]
}
الحقول
id

string

معرّف مبهم للحدث. عند إنشاء أحداث جديدة لمرة واحدة أو متكرّرة، يمكنك تحديد معرّفاتها. يجب أن تلتزم بطاقات التعريف المقدَّمة بالقواعد التالية:

  • الأحرف المسموح بها في المعرّف هي تلك المستخدَمة في ترميز base32hex، أي الأحرف الصغيرة من a إلى v والأرقام من 0 إلى 9، راجِع القسم 3.1.2 في RFC2938
  • يجب أن يتراوح طول المعرّف بين 5 و1024 حرفًا
  • يجب أن يكون المعرّف فريدًا لكل تقويم

نظرًا إلى طبيعة النظام الموزّعة على مستوى العالم، لا يمكننا ضمان رصد تعارضات أرقام التعريف عند إنشاء الحدث. للحدّ من خطر حدوث تعارضات، ننصحك باستخدام خوارزمية UUID ثابتة، مثل تلك الموضّحة في RFC4122.

إذا لم تحدّد معرّفًا، سيتم إنشاؤه تلقائيًا بواسطة الخادم.

يُرجى العِلم أنّ icalUID والمعرّف ليسا متطابقَين ويجب توفير أحدهما فقط عند إنشاء الحدث. أحد الاختلافات في دلالاتها هو أنّه في الأحداث المتكرّرة، يكون لكل تكرار لحدث واحد معرّفات مختلفة، بينما تشترك جميعها في معرّفات icalUID نفسها.
status

string

تمثّل هذه السمة حالة الحدث. اختياريّ. القيم المحتملة هي:

  • ‫confirmed: تم تأكيد الحدث. هذه هي الحالة التلقائية.
  • tentative: تم تأكيد الحدث بشكل مبدئي.
  • cancelled: تم إلغاء الحدث (حذفه). لا تعرض طريقة القائمة الأحداث الملغاة إلا عند المزامنة التدريجية (عند تحديد syncToken أو updatedMin) أو إذا تم ضبط العلامة showDeleted على "صحيح". تعرض الطريقة get هذه القيم دائمًا.

تمثّل الحالة "تم إلغاؤه" حالتين مختلفتين حسب نوع الحدث:

  1. تشير الاستثناءات الملغاة لحدث متكرّر غير ملغى إلى أنّه يجب ألا يتم عرض هذه النسخة للمستخدم بعد الآن. على العملاء تخزين هذه الأحداث طوال مدة الحدث المتكرّر الرئيسي.ولا يُضمن أن تحتوي الاستثناءات الملغاة على قيم إلا للحقول id وrecurringEventId وoriginalStartTime. قد تكون الحقول الأخرى فارغة.
  2. تمثّل جميع الأحداث الملغاة الأخرى الأحداث المحذوفة. على العملاء إزالة النُسخ التي تمت مزامنتها على أجهزتهم. وستختفي هذه الأحداث الملغاة في النهاية، لذا لا تعتمد على توفّرها إلى أجل غير مسمى. يتم ضمان تعبئة حقل المعرّف فقط للأحداث المحذوفة.

في تقويم المنظِّم، تواصل الأحداث الملغاة عرض تفاصيل الحدث (الملخّص والموقع الجغرافي وما إلى ذلك) حتى يمكن استعادتها (إلغاء حذفها). وبالمثل، تستمر الأحداث التي تمت دعوة المستخدم إليها وأزالها يدويًا في تقديم التفاصيل. ومع ذلك، لن تعرض طلبات المزامنة التدريجية التي تم ضبط showDeleted فيها على "خطأ" هذه التفاصيل.

إذا غيّر حدث ما منظّمه (على سبيل المثال، من خلال عملية النقل) ولم يكن المنظّم الأصلي في قائمة المشاركين، سيؤدي ذلك إلى ترك حدث تم إلغاؤه حيث يكون حقل المعرّف فقط مضمونًا أنّه سيتم ملؤه.
htmlLink

string

رابط مطلق يؤدي إلى هذا الحدث في واجهة مستخدم الويب الخاصة بـ "تقويم Google" للقراءة فقط.
created

string

تمثّل هذه السمة وقت إنشاء الحدث (كطابع زمني منسَّق وفقًا لمعيار ISO 8601). للقراءة فقط.
updated

string

تمثّل هذه السمة وقت آخر تعديل لبيانات الأحداث الرئيسية (كطابع زمني منسَّق بتنسيق ISO 8601). لن يؤدي تعديل تذكيرات الأحداث إلى تغيير ذلك. للقراءة فقط.
summary

string

تمثل هذه الخاصية عنوان الفعالية.
description

string

تمثّل هذه السمة وصف الفعالية. يمكن أن يحتوي على HTML. اختياريّ.
location

string

تمثّل هذه السمة الموقع الجغرافي للحدث كنص حر. اختياريّ.
creator

object (Principal)

تمثّل هذه السمة الجهة التي أنشأت الفعالية. للقراءة فقط.
organizer

object (Principal)

تمثّل هذه السمة منظّم الحدث. إذا كان المنظّم ضيفًا أيضًا، يتم الإشارة إلى ذلك بإدخال منفصل في قائمة الضيوف مع ضبط حقل المنظّم على "صحيح". للقراءة فقط.
start

object (DateOrDateTime)

وقت بدء الحدث (شامل) بالنسبة إلى حدث متكرّر، هذا هو وقت بدء المرة الأولى.
end

object (DateOrDateTime)

تمثّل هذه السمة وقت انتهاء الحدث (غير شامل). بالنسبة إلى حدث متكرّر، يكون هذا هو وقت انتهاء المثال الأول.
recurrence[]

string

قائمة بأسطر RRULE وEXRULE وRDATE وEXDATE لحدث متكرّر، كما هو محدّد في RFC5545. يُرجى العِلم أنّه لا يُسمح باستخدام سطرَي DTSTART وDTEND في هذا الحقل، بل يتم تحديد وقتَي بدء الحدث وانتهائه في حقلَي البدء والانتهاء. يتم حذف هذا الحقل للأحداث الفردية أو مثيلات الأحداث المتكررة.
recurringEventId

string

بالنسبة إلى مثيل لحدث متكرّر، هذا هو معرّف الحدث المتكرّر الذي ينتمي إليه هذا المثيل. غير قابل للتغيير
originalStartTime

object (DateOrDateTime)

بالنسبة إلى نسخة من حدث متكرّر، هذا هو الوقت الذي سيبدأ فيه هذا الحدث وفقًا لبيانات التكرار في الحدث المتكرّر الذي تم تحديده بواسطة recurringEventId. يحدّد هذا المعرّف بشكل فريد الموعد ضمن سلسلة الأحداث المتكرّرة حتى إذا تم نقل الموعد إلى وقت مختلف. غير قابل للتغيير
transparency

string

تحديد ما إذا كان الحدث يحظر وقتًا في التقويم اختياريّ. القيم المحتملة هي:

  • ‫opaque - القيمة التلقائية يؤدي الحدث إلى حظر الوقت في التقويم. هذا الإعداد يعادل ضبط "الحالة" على "مشغول" في واجهة مستخدم "تقويم Google".
  • transparent: لا يحجز الحدث وقتًا في التقويم. هذا الإعداد يعادل ضبط خيار "الحالة" على "متاح" في واجهة مستخدم "تقويم Google".
visibility

string

تمثّل هذه السمة مستوى رؤية الحدث. اختياريّ. القيم المحتملة هي:

  • default - يستخدم مستوى الظهور التلقائي للأحداث في التقويم. هذه هي القيمة التلقائية.
  • public: الحدث علني وتفاصيله مرئية لجميع قارئي التقويم.
  • private - الحدث خاص ويمكن للمدعوين فقط الاطّلاع على تفاصيله.
  • confidential: الحدث خاص. يتم توفير هذه القيمة لأسباب تتعلّق بالتوافق.
attendees[]

object (Attendee)

تمثّل هذه السمة المشاركين في الفعالية.
eventType

string

نوع الحدث المحدّد. لا يمكن تعديل هذا الخيار بعد إنشاء الحدث. القيم المحتملة هي:

  • birthday: حدث خاص يستمر طوال اليوم ويتكرر سنويًا.
  • default: حدث عادي أو لم يتم تحديد نوعه بشكل أكبر.
  • focusTime: حدث لوقت التركيز
  • fromGmail: حدث من Gmail لا يمكن إنشاء هذا النوع من الأحداث.
  • outOfOffice: حدث بأنّك خارج المكتب
  • ‫workingLocation: حدث مكان العمل
conferenceUrl

string

رابط Google Meet الخاص بالحدث
colorId

string

رقم تعريف لون الحدث (السلسلة 1-11):

  • ‫1: الخزامى
  • ‫2: Sage
  • ‫3: عنب
  • ‫4: Flamingo
  • ‫5: موز
  • ‫6: برتقالي محمرّ
  • ‫7: طاووس
  • ‫8: غرافيت
  • ‫9: أزرق توتي
  • ‫10: الريحان
  • ‫11: طماطم

في "تقويم Google"، تعمل ألوان الأحداث كفئات يمكن ضبطها لكل حدث أو لكل سلسلة أحداث. يمكن للمستخدمين تعيين تصنيفات مخصّصة للألوان في واجهة المستخدم على الويب (مثل 1:1s وBreak)، ولكن لا تعرض واجهة برمجة التطبيقات سوى المعرّفات الرقمية، وليس هذه التصنيفات. يؤثّر ذلك فقط على طريقة عرض تقويمك، إذ يتحكّم كل مشارِك في لون الحدث الخاص به.
overrideReminders[]

object (Reminder)

تذكيرات محدّدة لهذا الحدث، مع تجاهل التذكيرات التلقائية للتقويم في حال عدم ضبط هذه السياسة، يتم استخدام التذكيرات التلقائية في التقويم.

أساسي

تمثيل JSON 
{
  "email": string,
  "displayName": string,
  "self": boolean
}
الحقول
email

string

عنوان البريد الإلكتروني للكيان الذي يمكن المصادقة عليه (التقويم)
displayName

string

تمثّل هذه السمة اسم مدير المدرسة، إذا كان ذلك منطبقًا.
self

boolean

تُستخدَم لتحديد ما إذا كان هذا العنصر الأساسي يتوافق مع التقويم الذي تظهر فيه هذه النسخة من الحدث. للقراءة فقط. القيمة التلقائية هي False.

DateOrDateTime

تمثيل JSON 
{
  "date": string,
  "dateTime": string,
  "timeZone": string
}
الحقول
date

string

تمثّل هذه السمة تاريخًا بتنسيق ISO 8601 في منتصف الليل بالتوقيت العالمي المنسّق، مثل 2019-11-20T00:00:00Z. في حال ضبط هذا الحقل، يجب عدم ضبط date_time.
dateTime

string

طابع زمني بتنسيق ISO 8601، مثل 2019-11-20T08:19:06-07:00 أو 2019-11-20T08:19:06Z في حال ضبط هذا الحقل، يجب عدم ضبط date.
timeZone

string

اسم المنطقة الزمنية TZDB إذا كان متاحًا

المشارِك

تمثيل JSON 
{
  "id": string,
  "email": string,
  "displayName": string,
  "organizer": boolean,
  "self": boolean,
  "resource": boolean,
  "optionalAttendee": boolean,
  "responseStatus": string,
  "comment": string,
  "additionalGuests": integer
}
الحقول
id

string

معرّف الملف الشخصي للمشارك، إذا كان متاحًا
email

string

عنوان البريد الإلكتروني للمشارِك، إذا كان متاحًا يجب توفُّر هذا الحقل عند إضافة مشارِك. يجب أن يكون عنوان بريد إلكتروني صالحًا وفقًا لمعيار RFC5322. مطلوبة عند إضافة ضيف.
displayName

string

تمثّل هذه السمة اسم المشارك، إذا كان ذلك متاحًا. اختياريّ.
organizer

boolean

تُستخدَم لتحديد ما إذا كان المشارِك هو المنظّم للحدث. للقراءة فقط. القيمة التلقائية هي False.
self

boolean

تُستخدَم لتحديد ما إذا كان هذا الإدخال يمثّل التقويم الذي تظهر فيه هذه النسخة من الحدث. للقراءة فقط. القيمة التلقائية هي False.
resource

boolean

تُستخدَم لتحديد ما إذا كان المشارِك عبارة عن مورد. لا يمكن ضبطها إلا عند إضافة المشارِك إلى الحدث للمرة الأولى. ويتم تجاهل التعديلات اللاحقة. اختياريّ. القيمة التلقائية هي False.
optionalAttendee

boolean

تُستخدَم لتحديد ما إذا كان الضيف اختياريًا. اختياريّ. القيمة التلقائية هي False.
responseStatus

string

تمثّل هذه السمة حالة استجابة الضيف. القيم المحتملة هي:

  • ‫needsAction: لم يردّ المشارِك على الدعوة (يُنصح به للأحداث الجديدة).
  • declined: رفض الضيف الدعوة.
  • ‫tentative: قبل الضيف الدعوة مبدئيًا.
  • accepted: قبل المشارِك الدعوة.
comment

string

تعليق رد الضيف اختياريّ.
additionalGuests

integer

عدد الضيوف الإضافيين اختياريّ. القيمة التلقائية هي 0.

تذكير

تمثيل JSON 
{

  "method": string

  "minutes": integer
}
الحقول

حقل الربط _method

يمكن أن يكون التعليق _method إحدى القيم التالية فقط:
method

string

الحقل مطلوب. توضّح هذه السمة طريقة إرسال التذكير إلى المستخدم. القيم المحتملة هي:

  • email: يتم إرسال التذكيرات عبر البريد الإلكتروني.
  • ‫popup: يتم إرسال التذكيرات من خلال نافذة منبثقة في واجهة المستخدم.

حقل الربط _minutes

يمكن أن يكون التعليق _minutes إحدى القيم التالية فقط:
minutes

integer

الحقل مطلوب. عدد الدقائق التي يجب أن يتم فيها إرسال التذكير مُسبقًا

التعليقات التوضيحية للأدوات

Destructive Hint: ❌ | Idempotent Hint: ✅ | Read Only Hint: ✅ | Open World Hint: ❌