list_events

Diese Referenz wird aus dem veröffentlichten Werkzeugvertrag erzeugt. Feldnamen und normative Beschreibungen im Schema sind Englisch.

Verhalten und Grenzen

Liest Termine ausgewählter Google-, Microsoft- oder CalDAV-Kalender in einem begrenzten UTC-Zeitraum, gefiltert nach der Detailstufe, die für diesen Assistenten gewählt ist (nur Verfügbarkeit, Titel und Zeit oder alle Details). CalDAV-Serien werden einschließlich Ausnahmen gelesen; CalDAV-RSVP und die Anlage von CalDAV-Serien werden nicht unterstützt. canEdit und canRespond berücksichtigen die aktuellen Assistentenrechte sowie Anbieter- und Kalendergrenzen. Jeder Termin enthält, soweit bekannt, den aktuellen Antwortstatus des verbundenen Nutzers. Termine, die den Zeitraum überschneiden, kommen mit echtem Beginn und echter Dauer zurück, auch wenn sie früher begonnen haben. Kann ein Kalender oder ein Teil des Zeitraums nicht gelesen werden, kommen die übrigen Termine trotzdem zurück, und warnings nennt je betroffener calendarId die fehlenden UTC-Zeiträume oder übersprungenen Termine; dem Nutzer sagen, dass das Ergebnis diese nicht abdeckt. Schreibaktionen prüfen Rechte und Anbieterzustand erneut. Wenn canEdit falsch ist, nennt editBlockedReason den bestätigten Sperrgrund oder unknown. Nur calendar_read_only bedeutet, dass der Kalender schreibgeschützt ist. Pro Aufruf sind höchstens 744 verstrichene Stunden (31 × 24 Stunden) erlaubt. Zeitumstellungen berücksichtigen und längere Zeiträume in aufeinanderfolgende Fenster teilen. Bei einem Eingabefehler die Zeitgrenzen korrigieren und erneut abfragen.

Berechtigungen

Freigegebene Scopes, Konten, Kalender und Sichtbarkeitsregeln begrenzen den Zugriff. Ein Workspace-Admin erhält dadurch keinen pauschalen Zugriff auf fremde Konten.

calendar:read

Freigaben und Grenzen

Eingabe

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "calendarIds": {
      "minItems": 1,
      "maxItems": 20,
      "type": "array",
      "items": {
        "type": "string"
      }
    },
    "start": {
      "type": "string",
      "description": "Inclusive ISO 8601 date-time."
    },
    "end": {
      "type": "string",
      "description": "Exclusive ISO 8601 date-time, at most 744 elapsed hours after start. Split longer periods into consecutive windows; daylight-saving changes affect elapsed duration."
    },
    "timeZone": {
      "description": "User-confirmed IANA timezone for CalDAV all-day and floating times, e.g. Europe/Berlin. Supply it for CalDAV; ask the user if unknown. Does not change absolute event timestamps.",
      "type": "string",
      "minLength": 1,
      "maxLength": 128
    }
  },
  "required": [
    "calendarIds",
    "start",
    "end"
  ],
  "additionalProperties": false
}

Ausgabe

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "ok": {
      "type": "boolean",
      "const": true
    },
    "termine": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "eventId": {
            "type": "string"
          },
          "calendarId": {
            "type": "string"
          },
          "occurrenceId": {
            "type": "string"
          },
          "title": {
            "type": "string"
          },
          "description": {
            "type": "string"
          },
          "locations": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "name": {
                  "type": "string"
                },
                "description": {
                  "type": "string"
                },
                "coordinates": {
                  "type": "string"
                }
              },
              "required": [
                "name"
              ],
              "additionalProperties": false
            }
          },
          "virtualLocations": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "name": {
                  "type": "string"
                },
                "uri": {
                  "type": "string"
                }
              },
              "required": [
                "uri"
              ],
              "additionalProperties": false
            }
          },
          "links": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "href": {
                  "type": "string"
                },
                "title": {
                  "type": "string"
                },
                "rel": {
                  "type": "string"
                }
              },
              "required": [
                "href"
              ],
              "additionalProperties": false
            }
          },
          "categories": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "keywords": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "color": {
            "type": "string"
          },
          "start": {
            "type": "string"
          },
          "timeZone": {
            "type": "string"
          },
          "duration": {
            "type": "string"
          },
          "showWithoutTime": {
            "type": "boolean"
          },
          "status": {
            "type": "string",
            "enum": [
              "confirmed",
              "tentative",
              "cancelled"
            ]
          },
          "freeBusyStatus": {
            "type": "string",
            "enum": [
              "free",
              "busy"
            ]
          },
          "canRespond": {
            "type": "boolean",
            "description": "Whether this assistant may respond, subject to a fresh provider check."
          },
          "editBlockedReason": {
            "description": "Why editing is unavailable. Only calendar_read_only means the calendar is read-only; unknown means no verified reason.",
            "type": "string",
            "enum": [
              "calendar_read_only",
              "access_denied",
              "recurring_event",
              "not_organizer",
              "guests_or_scheduling",
              "conference",
              "managed_copy",
              "version_unavailable",
              "unknown"
            ]
          },
          "canEdit": {
            "type": "boolean",
            "description": "Whether this assistant may edit or delete, subject to a fresh provider check."
          },
          "responseStatus": {
            "type": "string",
            "enum": [
              "needs-action",
              "accepted",
              "declined",
              "tentative"
            ]
          },
          "privacy": {
            "type": "string",
            "enum": [
              "public",
              "private",
              "secret"
            ]
          },
          "alerts": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "offset": {
                  "type": "string"
                },
                "action": {
                  "type": "string",
                  "enum": [
                    "display",
                    "email"
                  ]
                }
              },
              "required": [
                "offset"
              ],
              "additionalProperties": false
            }
          },
          "workingLocation": {
            "type": "object",
            "properties": {
              "type": {
                "type": "string",
                "enum": [
                  "home",
                  "office",
                  "custom"
                ]
              },
              "label": {
                "type": "string"
              }
            },
            "required": [
              "type"
            ],
            "additionalProperties": false
          }
        },
        "required": [
          "eventId",
          "calendarId",
          "occurrenceId",
          "title",
          "start",
          "duration",
          "showWithoutTime",
          "status",
          "freeBusyStatus",
          "canRespond",
          "canEdit"
        ],
        "additionalProperties": false
      }
    },
    "warnings": {
      "description": "Present only when the result is incomplete: names each calendar and UTC range whose events are missing. Tell the user the result does not cover them.",
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "calendarId": {
            "type": "string"
          },
          "reason": {
            "type": "string",
            "enum": [
              "calendar_unavailable",
              "time_range_incomplete",
              "events_skipped"
            ]
          },
          "ranges": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "start": {
                  "type": "string"
                },
                "end": {
                  "type": "string"
                }
              },
              "required": [
                "start",
                "end"
              ],
              "additionalProperties": false
            }
          },
          "skippedEvents": {
            "type": "integer",
            "exclusiveMinimum": 0,
            "maximum": 9007199254740991
          },
          "message": {
            "type": "string"
          }
        },
        "required": [
          "calendarId",
          "reason",
          "message"
        ],
        "additionalProperties": false
      }
    }
  },
  "required": [
    "ok",
    "termine"
  ],
  "additionalProperties": false
}

Fehler und Wiederholungen

Prüfe das Werkzeugergebnis auf Fehler. Wiederhole Schreiboperationen nicht blind nach einem Timeout. Prüfe zuerst den aktuellen Ressourcen- oder Sendestatus.

Fehlerbehandlung