Enable thumbnails

Thumbnails are shown for documents returned by search results. Thumbnails allow the user to better identify relevance of returned documents. Thumbnails have the following characteristics:

  • Width of 1024 px.
  • URL for Google Workspace file thumbnails is ACL-protected. The URL for other file types isn't ACL-protected
  • URLs expire after 5 minutes.
  • Thumbnails aren't generated for files larger than 50 MB.
  • If a thumbnail can't be generated, a placeholder icon is used. If a thumbnail for a Google Workspace item can't be generated, the thumbnail URL returns "404 Not Found." Your application must handle this behavior.

Thumbnails are automatically created for Google Drive files that naturally support thumbnails, such as Google Workspace document types (Docs, Sheets, Slides, and so on). Additionally, Cloud Search automatically creates thumbnails for the following file types:

  • Microsoft Word (DOC)
  • Microsoft Word (DOCX)
  • Microsoft Excel (XLS)
  • Microsoft Excel (XLSX)
  • Microsoft Powerpoint (PPT)
  • Microsoft Powerpoint (PPTX)
  • Adobe Portable Document Format (PDF)
  • Rich Text Format (RTF)
  • Text Format (TXT)
  • Hypertext Markup Language (HTML)
  • Extensible Markup Language (XML)

Thumbnails are only returned for items whose data source and search applications have them enabled.

Enable thumbnail URLs for a data source

Your Cloud Search platform project contains service account credentials. However, to enable thumbnail URLs, you must create an API key and web application credentials and use the web application credentials to obtain an access token. Finally, you use these credentials to get and update a data source.

  1. If you haven't already, create or select a project for your app and enable the API. For information on these two steps, refer to step 1 and 2 of Configure access to the Google Cloud Search API.
  2. Create an API key:
    1. In the Google Cloud console, click the Create Credentials drop-down list and select API Key. The "API Key created" page appears.
    2. Note the API key.
    3. Click Close. The newly created credential appears under "API Keys."
  3. Create Web application credentials. Use https://developers.google.com/oauthplayground as the redirect URI. . For the steps to create these credentials, refer to Create Web application credentials (client-side JavaScript).
  4. In the OAuth 2.0 Playground, click OAuth 2.0 Configuration .
  5. Check Use your own credentials.
  6. Enter the client ID and client secret generated in step 3.
  7. In the scopes field, type https://www.googleapis.com/auth/cloud_search.settings and click Authorize APIs.
  8. (optional) If presented with a Sign in screen, select the account to use.
  9. (optional) If presented with an authorization screen, click Accept.
  10. Click Exchange authorization code for tokens. A token is returned.
  11. Identify the data source for which you want to enable the thumbnail controls.

  12. Call settings.datasources.get to obtain the ID of the data source:

    curl
'https://cloudsearch.googleapis.com/v1/settings/datasource_id?key=[YOUR_API_KEY]' \
--header 'Authorization: Bearer [YOUR_ACCESS_TOKEN]'\
--header 'Accept: application/json'  \
--compressed

    Where:

    • datasource_id is the name of the data source to retrieve.
    • YOUR_API_KEY is the API key for your project (obtained from step 2).
    • YOUR_ACCESS_TOKEN is OAuth 2.0 access token for your project (obtained from step 10).

    The successful result from this command is similar to:

    {
 "source": {
   "name": "datasources/datasource_id",
   "displayName": "DataSource_Display_Name",
   "itemsVisibility": [
     {
       "gsuiteDomain": true
     }
   ]
 }
}

  13. Call setting.datasource.update withh returnThumbnailUrls set to true to enable thumbnail URLs for the data source:

    curl --request PUT \  'https://cloudsearch.googleapis.com/v1/settings/datasources/datasource_id?key=[YOUR_API_KEY]' \
  --header 'Authorization: Bearer [YOUR_ACCESS_TOKEN]' \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --data '{"source":{"name":"datasources/datasource_id","displayName":"DataSource_Display_Name","itemsVisibility":
    [{"gsuiteDomain":true}],"returnThumbnailUrls":true}}' \
  --compressed

    Where:

    • datasource_id is the ID of the data source to retrieve.
    • YOUR_API_KEY is the API key for your project (obtained from step 2).
    • YOUR_ACCESS_TOKEN is OAuth 2.0 access token for your project (obtained from step 10).
    • DataSource_DisplayName is the display name returned from the previous cURL command.
    • "returnThumbnailsUrls":true enables thumbnails.

    The successful result from this command is similar to:

    {
  "source": {
    "name": "datasources/datasource_id",
    "displayName": "DataSource_Display_Name",
    "itemsVisibility": [
      {
        "gsuiteDomain": true
      }
    ],
    "returnThumbnailUrls": true
  }
}

Enable thumbnail URLs for a search application

Your Cloud Search platform project contains service account credentials. However, to enable thumbnail URLs, you must create an API key and web application credentials and use the web application credentials to obtain an access token. Finally, you use these credentials to get and update a search application.

  1. If you haven't already, create or select a project for your app and enable the API. For information on these two steps, refer to step 1 and 2 of Configure access to the Google Cloud Search API.
  2. Create an API key:
    1. In the cloud console, click the Create Credentials drop-down list and select API Key. The "API Key created" page appears.
    2. Note the API key.
    3. Click Close. The newly created credential appears under "API Keys."
  3. Create Web application credentials. Use https://developers.google.com/oauthplayground as the redirect URI. . For the steps to create these credentials, refer to Create Web application credentials (client-side JavaScript).
  4. In the OAuth 2.0 Playground, click OAuth 2.0 Configuration .
  5. Check Use your own credentials.
  6. Enter the client ID and client secret generated in step 3.
  7. In the scopes field, type https://www.googleapis.com/auth/cloud_search.settings and click Authorize APIs.
  8. (optional) If presented with a Sign in screen, select the account to use.
  9. (optional) If presented with an authorization screen, click Accept.
  10. Click Exchange authorization code for tokens. A token is returned.
  11. Identify the search application for which you want to enable the thumbnail controls.

  12. Call settings.searchapplications.get to obtain the ID of the search application:

    curl \ 'https://cloudsearch.googleapis.com/v1/settings/searchapplications/search_application_id?key=[YOUR_API_KEY]' \
 --header 'Authorization: Bearer [YOUR_ACCESS_TOKEN]' \
 --header 'Accept: application/json' \
 --compressed

    Where:

    • is the ID of the search application to retrieve.
    • YOUR_API_KEY is the API key for your project (obtained from step 2).
    • YOUR_ACCESS_TOKEN is OAuth 2.0 access token for your project (obtained from step 10).

    The successful result from this command is similar to:

    {
 "name": "searchapplications/search_application_id",
 "displayName": "SearchApp_Display_Name",
 "dataSourceRestrictions": [
   {
     "source": {
       "name": "datasources/datasource_id"
     }
   }
 ]
}

  13. Call setting.searchapplications.update with returnResultThumbnailUrls set to true to enable thumbnail URLs for the search application:

    curl --request PUT \  'https://cloudsearch.googleapis.com/v1/settings/searchapplications/search_application_id?key=[YOUR_API_KEY]' \
  --header 'Authorization: Bearer [YOUR_ACCESS_TOKEN]' \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --data '{"name":"searchapplications/search_application_id","displayName":"SearchApp_Display_Name","dataSourceRestrictions":[{"source":
    {"name":"datasources/datasource_id"}}],"returnResultThumbnailUrls":true}' \
  --compressed

    Where:

    • is the ID of the search application to retrieve.
    • YOUR_API_KEY is the API key for your project (obtained from step 2).
    • YOUR_ACCESS_TOKEN is OAuth 2.0 access token for your project (obtained from step 10).
    • SearchApp_DisplayName is the display name returned from the previous cURL command.
    • "returnResultThumbnailUrls":true enables thumbnails.

    The successful result from this command is similar to:

    {
  "name": "searchapplications/search_application_id",
  "displayName": "SearchApp_Display_Name",
  "dataSourceRestrictions": [
    {
      "source": {
        "name": "datasources/datasource_id"
      }
    }
  ],
  "returnResultThumbnailUrls": true
}

Access thumbnails

To access a thumbnail for a Google Workspace file in Drive, the user or application must pass the same account credentials that they use to access the item in Google Drive.