search_events

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

Verhalten und Grenzen

Sucht Termine in einem begrenzten Zeitraum über ausgewählte Kalender und gibt die Treffer in derselben Form wie list_events zurück. Gesucht wird in genau dem Text, den dieser Assistent auf seiner Detailstufe sehen darf: Bei einem Kalender mit Busy-only ist der Titel bereits ein Platzhalter, eine Suche kann also keinen verborgenen Titel treffen, und ein ausbleibender Treffer beweist nichts über das Verborgene. Orte und Teilnehmer werden nicht durchsucht. matched und truncated beschreiben die Suche selbst: Ein gekapptes Ergebnis ist kein Beweis, dass nichts weiter passt. Alle Wörter müssen vorkommen, in beliebiger Reihenfolge. Wie list_events enthält jeder nicht bearbeitbare Termin editBlockedReason. 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"
      }
    },
    "query": {
      "type": "string",
      "minLength": 1,
      "maxLength": 200
    },
    "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."
    },
    "limit": {
      "type": "integer",
      "minimum": 1,
      "maximum": 50
    },
    "timeZone": {
      "description": "User-confirmed IANA timezone for CalDAV all-day and floating times, e.g. Europe/Berlin.",
      "type": "string",
      "minLength": 1,
      "maxLength": 128
    }
  },
  "required": [
    "calendarIds",
    "query",
    "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
      }
    },
    "matched": {
      "type": "number"
    },
    "truncated": {
      "type": "boolean"
    },
    "searchedFields": {
      "type": "array",
      "items": {
        "type": "string"
      }
    }
  },
  "required": [
    "ok",
    "termine",
    "matched",
    "truncated",
    "searchedFields"
  ],
  "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