Method: mediaItems.search

Sucht nach Medienelementen in der Google Fotos-Galerie eines Nutzers. Wenn keine Filter festgelegt sind, werden alle Medienelemente in der Mediathek des Nutzers zurückgegeben. Wenn ein Album festgelegt wurde, werden alle Medienelemente im angegebenen Album zurückgegeben. Wenn Filter angegeben sind, werden Medienelemente aufgelistet, die mit den Filtern aus der Mediathek des Nutzers übereinstimmen. Wenn Sie sowohl das Album als auch die Filter festlegen, führt die Anfrage zu einem Fehler.

HTTP-Anfrage

POST https://photoslibrary.googleapis.com/v1/mediaItems:search

Die URL verwendet die Syntax der gRPC-Transcodierung.

Anfragetext

Der Anfragetext enthält Daten mit folgender Struktur:

JSON-Darstellung
{
  "albumId": string,
  "pageSize": integer,
  "pageToken": string,
  "filters": {
    object (Filters)
  },
  "orderBy": string
}
Felder
albumId

string

ID eines Albums. Wenn dieses Feld ausgefüllt ist, werden alle Medienelemente im angegebenen Album aufgelistet. Kann nicht in Verbindung mit Filtern festgelegt werden.

pageSize

integer

Maximale Anzahl von Medienelementen, die in der Antwort zurückgegeben werden sollen. Es werden möglicherweise weniger Medienelemente zurückgegeben als die angegebene Anzahl. Der Standardwert für pageSize ist 25, der Höchstwert ist 100.

pageToken

string

Fortsetzungs-Token zum Aufrufen der nächsten Seite der Ergebnisse. Wenn Sie diese Zeile zur Anfrage hinzufügen, werden die Zeilen nach pageToken zurückgegeben. pageToken sollte der Wert sein, der im Parameter nextPageToken in der Antwort auf die searchMediaItems-Anfrage zurückgegeben wird.

filters

object (Filters)

Filter, die auf die Anfrage angewendet werden sollen. Kann nicht in Verbindung mit einem albumId festgelegt werden.

orderBy

string

Ein optionales Feld zur Angabe der Sortierreihenfolge der Suchergebnisse. Das Feld orderBy funktioniert nur, wenn dateFilter verwendet wird. Wenn dieses Feld nicht angegeben ist, werden die Ergebnisse anhand ihrer creationTime als neueste zuerst, älteste als Letztes angezeigt. Bei Angabe von MediaMetadata.creation_time werden Suchergebnisse in umgekehrter Reihenfolge angezeigt, d. h. die ältesten zuerst, dann die neuesten zuletzt. Wenn Sie die neuesten Ergebnisse zuerst und dann die ältesten Ergebnisse sehen möchten, fügen Sie das Argument desc so ein: MediaMetadata.creation_time desc.

Die einzigen zusätzlichen Filter, die mit diesem Parameter verwendet werden können, sind includeArchivedMedia und excludeNonAppCreatedData. Andere Filter werden nicht unterstützt.

Antworttext

Liste der Medienelemente, die den Suchparametern entsprechen.

Bei Erfolg enthält der Antworttext Daten mit der folgenden Struktur:

JSON-Darstellung
{
  "mediaItems": [
    {
      object (MediaItem)
    }
  ],
  "nextPageToken": string
}
Felder
mediaItems[]

object (MediaItem)

Nur Ausgabe. Liste der Medienelemente, die den Suchparametern entsprechen.

nextPageToken

string

Nur Ausgabe. Verwenden Sie dieses Token, um den nächsten Satz von Medienelementen abzurufen. Ihr Vorhandensein ist der einzige zuverlässige Indikator dafür, dass in der nächsten Anfrage mehr Medienelemente verfügbar sind.

Autorisierungsbereiche

Erfordert einen der folgenden OAuth-Bereiche:

  • https://www.googleapis.com/auth/photoslibrary
  • https://www.googleapis.com/auth/photoslibrary.readonly
  • https://www.googleapis.com/auth/photoslibrary.readonly.appcreateddata
  • https://www.googleapis.com/auth/photoslibrary.readonly.originals

Filter

Filter, die auf die Suche nach Medienelementen angewendet werden können. Mehrere Filteroptionen werden als UND miteinander behandelt.

JSON-Darstellung
{
  "dateFilter": {
    object (DateFilter)
  },
  "contentFilter": {
    object (ContentFilter)
  },
  "mediaTypeFilter": {
    object (MediaTypeFilter)
  },
  "featureFilter": {
    object (FeatureFilter)
  },
  "includeArchivedMedia": boolean,
  "excludeNonAppCreatedData": boolean
}
Felder
dateFilter

object (DateFilter)

Die Medienelemente werden anhand ihres Erstellungsdatums gefiltert.

contentFilter

object (ContentFilter)

Medienelemente werden anhand ihres Inhalts gefiltert.

mediaTypeFilter

object (MediaTypeFilter)

Die Medienelemente werden nach Medientyp gefiltert.

featureFilter

object (FeatureFilter)

Die Medienelemente werden anhand ihrer Funktionen gefiltert.

includeArchivedMedia

boolean

Wenn dieser Wert festgelegt ist, enthalten die Ergebnisse Mediaelemente, die der Nutzer archiviert hat. Standardeinstellung: „false“ (archivierte Medienelemente sind nicht enthalten).

excludeNonAppCreatedData

boolean

Wenn festgelegt, werden in den Ergebnissen keine Medienelemente angezeigt, die nicht von dieser App erstellt wurden. Die Standardeinstellung ist „false“, d. h., alle Medienelemente werden zurückgegeben. Dieses Feld wird ignoriert, wenn der Bereich „photoslibrary.readonly.appcreateddata“ verwendet wird.

DateFilter

Mit diesem Filter werden die zulässigen Daten oder Zeiträume für die zurückgegebenen Medien definiert. Sie können eine Reihe bestimmter Datumsangaben und mehrere Zeiträume auswählen. Medienelemente, die ohne Metadaten hochgeladen wurden und das Datum der Aufnahme angeben, werden in Abfragen mit Datumsfiltern nicht zurückgegeben. Die Upload-Zeit des Google Fotos-Servers wird in diesem Fall nicht als Fallback verwendet.

JSON-Darstellung
{
  "dates": [
    {
      object (Date)
    }
  ],
  "ranges": [
    {
      object (DateRange)
    }
  ]
}
Felder
dates[]

object (Date)

Liste mit Datumsangaben, die den Medienelementen entsprechen Erstellungsdatum. Pro Anfrage können maximal 5 Daten angegeben werden.

ranges[]

object (DateRange)

Liste der Zeiträume, die den Medienelementen entsprechen Erstellungsdatum. Pro Anfrage können maximal fünf Zeiträume angegeben werden.

Datum

Stellt ein vollständiges Kalenderdatum dar. Setzen Sie day auf 0, wenn nur der Monat und das Jahr relevant sind, z. B. der gesamte Dezember 2018. Setzen Sie day und month auf 0, wenn nur das Jahr signifikant ist, z. B. das gesamte Jahr 2018. Setzen Sie year auf 0, wenn nur der Tag und der Monat wichtig sind, z. B. ein Jahrestag oder ein Geburtstag.

Nicht unterstützt: Alle Werte werden auf 0, nur month auf 0 oder sowohl day als auch year auf 0 gesetzt.

JSON-Darstellung
{
  "year": integer,
  "month": integer,
  "day": integer
}
Felder
year

integer

Das Jahr des Datums. Es muss zwischen 1 und 9999 liegen oder kann 0 sein, wenn ein Datum ohne Jahresangabe angegeben wird.

month

integer

Monat eines Jahres. Die Angabe muss zwischen 1 und 12 liegen. Sie kann auch 0 sein, wenn ein Jahr ohne Monat und Tag angegeben wird.

day

integer

Tag des Monats. Muss zwischen 1 und 31 liegen und für das Jahr und den Monat gültig sein. Sie kann auch 0 sein, wenn ein Jahr/Monat angegeben wird, bei dem der Tag nicht von Bedeutung ist.

DateRange

Definiert einen Zeitraum. Beide Datumsangaben müssen das gleiche Format haben. Weitere Informationen finden Sie unter Date.

JSON-Darstellung
{
  "startDate": {
    object (Date)
  },
  "endDate": {
    object (Date)
  }
}
Felder
startDate

object (Date)

Das Startdatum (im Zeitraum enthalten) in einem der beschriebenen Formate

endDate

object (Date)

Enddatum (im Zeitraum enthalten) Das Startdatum muss dasselbe Format haben wie das Startdatum.

ContentFilter

Mit diesem Filter kannst du Medienelemente nach Inhaltstyp zurückgeben.

Sie können eine Liste mit einzuschließenden Kategorien und/oder eine Liste mit auszuschließenden Kategorien angeben. Innerhalb jeder Liste werden die Kategorien mit einem ODER kombiniert.

Mit dem Inhaltsfilter includedContentCategories: [c1, c2, c3] werden Medienelemente abgerufen, die (c1 OR c2 OR c3) enthalten.

Mit dem Inhaltsfilter excludedContentCategories [c1, c2, c3] werden KEINE Medienelemente abgerufen, die (c1 OR c2 OR c3) enthalten.

Sie können auch einige Kategorien einschließen und andere ausschließen, wie in diesem Beispiel: includedContentCategories: [c1, c2], excludedContentCategories: [c3, c4]

Im vorherigen Beispiel würden Medienelemente abgerufen werden, die (c1 OR c2) AND NOT (c3 OR c4) enthalten. Eine Kategorie, die in includedContentategories angezeigt wird, darf nicht in excludedContentCategories enthalten sein.

JSON-Darstellung
{
  "includedContentCategories": [
    enum (ContentCategory)
  ],
  "excludedContentCategories": [
    enum (ContentCategory)
  ]
}
Felder
includedContentCategories[]

enum (ContentCategory)

Die Kategorien, die in den Suchergebnissen für Medienelemente enthalten sein sollen. Die Elemente im Satz sind mit ODER verknüpft. Pro Anfrage sind maximal 10 includedContentCategories möglich.

excludedContentCategories[]

enum (ContentCategory)

Die Kategorien, die nicht in den Suchergebnissen für Medienelemente enthalten sein sollen. Die Elemente im Satz sind mit ODER verknüpft. Pro Anfrage sind maximal 10 excludedContentCategories möglich.

ContentCategory

Hierbei handelt es sich um eine Reihe vordefinierter Inhaltskategorien, nach denen Sie filtern können.

Enums
NONE Standard-Inhaltskategorie. Diese Kategorie wird ignoriert, wenn eine andere Kategorie im Filter verwendet wird.
LANDSCAPES Medienobjekte, die Landschaften enthalten
RECEIPTS Medienobjekte mit Belegen
CITYSCAPES Medieninhalte, die Stadtansichten enthalten.
LANDMARKS Medienelemente mit Markierungen
SELFIES Selfies
PEOPLE Medieninhalte, die Personen enthalten.
PETS Medienelemente mit Haustieren.
WEDDINGS Medienartikel von Hochzeiten
BIRTHDAYS Medienelemente von Geburtstagen
DOCUMENTS Medienobjekte, die Dokumente enthalten
TRAVEL Medieninhalte, die während einer Reise aufgenommen wurden
ANIMALS Medienelemente mit Tieren
FOOD Medienelemente mit Lebensmitteln
SPORT Medienelemente von Sportereignissen.
NIGHT Medieninhalte, die bei Nacht aufgenommen wurden
PERFORMANCES Medienelemente aus Aufführungen
WHITEBOARDS Medienelemente, die Whiteboards enthalten.
SCREENSHOTS Medienelemente, die Screenshots sind.
UTILITY Medienelemente, die als nützlich erachtet werden. Dazu gehören unter anderem Dokumente, Screenshots, Whiteboards usw.
ARTS Medienobjekte, die Kunstwerke enthalten
CRAFTS Medienobjekte, die Bastelarbeiten enthalten.
FASHION Medienelemente, die sich auf Mode beziehen.
HOUSES Medienobjekte, die Häuser enthalten.
GARDENS Medienobjekte mit Gärten.
FLOWERS Medienelemente mit Blumen.
HOLIDAYS Medienelemente von Feiertagen.

MediaTypeFilter

Dieser Filter definiert den Typ der Medienelemente, die zurückgegeben werden sollen, z. B. Videos oder Fotos. Es wird nur ein Medientyp unterstützt.

JSON-Darstellung
{
  "mediaTypes": [
    enum (MediaType)
  ]
}
Felder
mediaTypes[]

enum (MediaType)

Die Typen der Medienelemente, die einbezogen werden sollen. Dieses Feld sollte nur einen Medientyp enthalten. Wenn Sie mehrere Medientypen angeben, wird ein Fehler ausgegeben.

MediaType

Die Medientypen, nach denen gesucht werden kann.

Enums
ALL_MEDIA Wird so behandelt, als wären keine Filter angewendet worden. Alle Medientypen sind enthalten.
VIDEO Alle Medienelemente, die als Videos betrachtet werden. Das gilt auch für Filme, die der Nutzer mit der Google Fotos App erstellt hat.
PHOTO Alle Medienelemente, die als Fotos betrachtet werden. Dazu gehören .bmp, .gif, .ico, .jpg (und andere Schreibweisen), .tiff, .webp und spezielle Fototypen wie iOS-Livefotos, Android-Bewegungsfotos, Panoramen und 360°-Fotos.

FeatureFilter

Mit diesem Filter werden die Funktionen definiert, die die Medienelemente haben sollten.

JSON-Darstellung
{
  "includedFeatures": [
    enum (Feature)
  ]
}
Felder
includedFeatures[]

enum (Feature)

Die Funktionen, die in den Suchergebnissen von Medienelementen enthalten sein sollen. Die Elemente in der Gruppe sind mit ODER verknüpft und können mit jedem der angegebenen Elemente übereinstimmen.

Funktion

Die Funktionen, nach denen gefiltert werden kann.

Enums
NONE Wird so behandelt, als wären keine Filter angewendet worden. Alle Funktionen sind inbegriffen.
FAVORITES Medienelemente, die der Nutzer in der Google Fotos App als Favoriten markiert hat.