REST Resource: indexing.datasources.items

Risorsa: elemento

Rappresenta un singolo oggetto che è un elemento nell'indice di ricerca, ad esempio un file, una cartella o un record di database.

Rappresentazione JSON 
{
  "name": string,
  "acl": {
    object (ItemAcl)
  },
  "metadata": {
    object (ItemMetadata)
  },
  "structuredData": {
    object (ItemStructuredData)
  },
  "content": {
    object (ItemContent)
  },
  "version": string,
  "status": {
    object (ItemStatus)
  },
  "queue": string,
  "payload": string,
  "itemType": enum (Item.ItemType)
}
Campi
name

string

Il nome dell'articolo. Formato: datasources/{sourceId}/items/{itemId}

Questo campo è obbligatorio. La lunghezza massima è di 1536 caratteri.
acl

object (ItemAcl)

Elenco di controllo dell'accesso per questo elemento.
metadata

object (ItemMetadata)

Le informazioni sui metadati.
structuredData

object (ItemStructuredData)

I dati strutturati per l'elemento che devono essere conformi a una definizione di oggetto registrata nello schema dell'origine dati.
content

object (ItemContent)

Contenuti dell'elemento da indicizzare e rendere disponibili per la ricerca.
version

string (bytes format)

Obbligatorio. Il sistema di indicizzazione memorizza la versione della sorgente dati come stringa di byte e confronta la versione dell'articolo nell'indice con la versione dell'articolo in coda utilizzando l'ordinamento lessicale.

L'indice di Cloud Search non indicizza né elimina gli elementi in coda con un valore di versione inferiore o uguale alla versione dell'elemento attualmente indicizzato. La lunghezza massima per questo campo è di 1024 byte.

Per informazioni su come la versione dell'elemento influisce sul processo di eliminazione, consulta Gestire le revisioni dopo le eliminazioni manuali.

Una stringa con codifica Base64.
status

object (ItemStatus)

Stato dell'articolo. Campo di sola uscita.
queue

string

La coda a cui appartiene questo elemento. La lunghezza massima è di 100 caratteri.
payload

string (bytes format)

Il connettore dello stato aggiuntivo può essere memorizzato per questo elemento. La lunghezza massima è di 10000 byte.

Una stringa con codifica Base64.
itemType

enum (Item.ItemType)

Il tipo di questo elemento.

ItemAcl

Informazioni sull'elenco di controllo dell'accesso per l'elemento. Per ulteriori informazioni, consulta Map ACLs (Mappa ACL).

Rappresentazione JSON 
{
  "inheritAclFrom": string,
  "aclInheritanceType": enum (ItemAcl.AclInheritanceType),
  "readers": [
    {
      object (Principal)
    }
  ],
  "deniedReaders": [
    {
      object (Principal)
    }
  ],
  "owners": [
    {
      object (Principal)
    }
  ]
}
Campi
inheritAclFrom

string

Il nome dell'elemento da cui ereditare l'elenco delle autorizzazioni di accesso (ACL). Nota: l'eredità ACL solo fornisce autorizzazioni di accesso agli elementi secondari e non definisce relazioni strutturali né fornisce modi pratici per eliminare grandi gruppi di elementi. L'eliminazione di un ACL principale dall'indice modifica solo le autorizzazioni di accesso degli elementi secondari che fanno riferimento all'elemento principale nel campo inheritAclFrom. L'elemento è ancora nell'indice, ma potrebbe non essere visibile nei risultati di ricerca. Al contrario, l'eliminazione di un elemento contenitore comporta l'eliminazione anche di tutti gli elementi che fanno riferimento al contenitore tramite il campo containerName. La lunghezza massima per questo campo è di 1536 caratteri.
aclInheritanceType

enum (ItemAcl.AclInheritanceType)

Imposta il tipo di regole di accesso da applicare quando un elemento eredita l'ACL da un elemento principale. Deve essere sempre impostato in tandem con il campo inheritAclFrom. Inoltre, quando il campo inheritAclFrom è impostato, deve essere impostato su un valore AclInheritanceType valido.
readers[]

object (Principal)

Elenco dei principali che possono vedere l'elemento nei risultati di ricerca. Facoltativo se le autorizzazioni vengono ereditate da un altro elemento o se l'elemento non deve essere visibile, ad esempio virtual containers. Il numero massimo di elementi è 1000.
deniedReaders[]

object (Principal)

Elenco dei principali a cui è stato negato esplicitamente l'accesso all'elemento nei risultati di ricerca. Sebbene l'accesso venga negato per impostazione predefinita, utilizza i lettori con accesso negato per gestire le eccezioni e sostituire l'elenco dei lettori consentiti. Il numero massimo di elementi è 100.
owners[]

object (Principal)

Facoltativo. Elenco dei proprietari dell'articolo. Questo campo non influisce sulle autorizzazioni di accesso ai documenti. Tuttavia, offre un leggero aumento del ranking degli elementi in cui l'utente che esegue la query è un proprietario. Il numero massimo di elementi è 5.

ItemAcl.AclInheritanceType

I tipi di ereditarietà delle ACL.

Enum
NOT_APPLICABLE Il valore predefinito quando questo elemento non eredita un'ACL. Utilizza NOT_APPLICABLE quando inheritAclFrom è vuoto. Un elemento senza ereditarietà ACL può comunque avere ACL fornite dai propri campi readers e deniedReaders.
CHILD_OVERRIDE Durante un conflitto di autorizzazione, l'ACL dell'elemento secondario ne determina l'accesso in lettura.
PARENT_OVERRIDE Durante un conflitto di autorizzazione, l'ACL dell'elemento principale specificato nel campo inheritAclFrom determina l'accesso in lettura.
BOTH_PERMIT L'accesso viene concesso solo se questo elemento e l'elemento principale specificato nel campo inheritAclFrom consentono entrambi l'accesso in lettura.

Entità

Riferimento a un utente, un gruppo o un dominio.

Rappresentazione JSON 
{

  // Union field principal can be only one of the following:
  "gsuitePrincipal": {
    object (GSuitePrincipal)
  },
  "userResourceName": string,
  "groupResourceName": string
  // End of list of possible types for union field principal.
}
Campi

Campo unione principal.

principal può essere solo uno dei seguenti:
gsuitePrincipal

object (GSuitePrincipal)

Questa entità è un utente, un gruppo o un dominio Google Workspace.
userResourceName

string

Questo principale è un utente identificato utilizzando un'identità esterna. Il campo name deve specificare il nome della risorsa utente con questo formato: identitysources/{sourceId}/users/{ID}
groupResourceName

string

Questo principale è un gruppo identificato utilizzando un'identità esterna. Il campo name deve specificare il nome della risorsa del gruppo con questo formato: identitysources/{sourceId}/groups/{ID}

ItemMetadata

Campi dei metadati disponibili per l'elemento.

Rappresentazione JSON 
{
  "title": string,
  "sourceRepositoryUrl": string,
  "containerName": string,
  "objectType": string,
  "createTime": string,
  "updateTime": string,
  "interactions": [
    {
      object (Interaction)
    }
  ],
  "contentLanguage": string,
  "mimeType": string,
  "searchQualityMetadata": {
    object (SearchQualityMetadata)
  },
  "keywords": [
    string
  ],
  "hash": string,
  "contextAttributes": [
    {
      object (ContextAttribute)
    }
  ]
}
Campi
title

string

Il titolo dell'articolo. Se specificato, questo sarà il titolo visualizzato del risultato della query.search. La lunghezza massima è di 2048 caratteri.
sourceRepositoryUrl

string

Link al repository di origine che fornisce i dati. I risultati di ricerca applicano questo link al titolo. Gli spazi o i caratteri speciali possono causare l'attivazione di una notifica di reindirizzamento nei link ai risultati di ricerca Cloud. Per evitare questo problema, codifica l'URL. La lunghezza massima è di 2048 caratteri.
containerName

string

Il nome del contenitore per questo articolo. L'eliminazione dell'elemento contenitore comporta l'eliminazione automatica di questo elemento. Nota: le ACL non vengono ereditate da un elemento contenitore. Per fornire l'ereditarietà ACL per un elemento, utilizza il campo inheritAclFrom. La lunghezza massima è di 1536 caratteri.
objectType

string

Il tipo di articolo. Deve corrispondere al nome di una definizione di oggetto nello schema registrato per l'origine dati. Ad esempio, se lo schema dell'origine dati contiene una definizione di oggetto con il nome "documento", le richieste di indicizzazione degli elementi per gli oggetti di questo tipo devono impostare objectType su "documento". La lunghezza massima è di 256 caratteri.
createTime

string (Timestamp format)

L'ora in cui l'elemento è stato creato nel repository di origine.

Un timestamp in formato "Zulu" UTC RFC3339, con risoluzione in nanosecondi e fino a nove cifre frazionarie. Esempi: "2014-10-02T15:01:23Z" e "2014-10-02T15:01:23.045123456Z".
updateTime

string (Timestamp format)

L'ora dell'ultima modifica dell'elemento nel repository di origine.

Un timestamp in formato "Zulu" UTC RFC3339, con risoluzione in nanosecondi e fino a nove cifre frazionarie. Esempi: "2014-10-02T15:01:23Z" e "2014-10-02T15:01:23.045123456Z".
interactions[]

object (Interaction)

Un elenco di interazioni per l'articolo. Le interazioni vengono utilizzate per migliorare la qualità di query.search, ma non sono esposte agli utenti finali. Il numero massimo di elementi è 1000.
contentLanguage

string

Il codice lingua BCP-47 dell'articolo, ad esempio "en-US" o "sr-Latn". Per ulteriori informazioni, visita la pagina http://www.unicode.org/reports/tr35/#Unicode_locale_identifier. La lunghezza massima è di 32 caratteri.
mimeType

string

Il tipo MIME originale di ItemContent.content nel repository di origine. La lunghezza massima è di 256 caratteri.
searchQualityMetadata

object (SearchQualityMetadata)

Metadati aggiuntivi sulla qualità della ricerca dell'elemento
keywords[]

string

Parole chiave o frasi aggiuntive che devono corrispondere all'articolo. Utilizzato internamente per i contenuti generati dagli utenti. Il numero massimo di elementi è 100. La lunghezza massima è di 8192 caratteri.
hash

string

Valore di hashing fornito dal chiamante dell'API. Questo può essere utilizzato con il metodo items.push per calcolare lo stato modificato. La lunghezza massima è di 2048 caratteri.
contextAttributes[]

object (ContextAttribute)

Un insieme di attributi denominati associati all'elemento. Questo può essere utilizzato per influenzare il ranking dell'elemento in base al contesto della richiesta. Il numero massimo di elementi è 10.

Interazione

Rappresenta un'interazione tra un utente e un articolo.

Rappresentazione JSON 
{
  "type": enum (Interaction.InteractionType),
  "principal": {
    object (Principal)
  },
  "interactionTime": string
}
Campi
type

enum (Interaction.InteractionType)
principal

object (Principal)

L'utente che ha eseguito un'azione sull'elemento.
interactionTime

string (Timestamp format)

L'ora in cui l'utente ha eseguito un'azione sull'elemento. Se per un singolo utente esistono più azioni dello stesso tipo, viene registrata solo l'azione più recente.

Un timestamp in formato "Zulu" UTC RFC3339, con risoluzione in nanosecondi e fino a nove cifre frazionarie. Esempi: "2014-10-02T15:01:23Z" e "2014-10-02T15:01:23.045123456Z".

Interaction.InteractionType

Il tipo di attività eseguita dall'utente sull'articolo.

Enum
UNSPECIFIED Valore non valido.
VIEW Questa interazione indica che l'utente ha visualizzato l'elemento.
EDIT Questa interazione indica che l'utente ha modificato l'elemento.

SearchQualityMetadata

Metadati aggiuntivi sulla qualità della ricerca dell'elemento.

Rappresentazione JSON 
{
  "quality": number
}
Campi
quality

number

Un'indicazione della qualità dell'elemento, utilizzata per influenzare la qualità della ricerca. Il valore deve essere compreso tra 0,0 (qualità più bassa) e 1,0 (qualità più alta). Il valore predefinito è 0,0.

ContextAttribute

Un attributo denominato associato a un elemento che può essere utilizzato per influenzare il ranking dell'elemento in base al contesto nella richiesta.

Rappresentazione JSON 
{
  "name": string,
  "values": [
    string
  ]
}
Campi
name

string

Il nome dell'attributo. Non deve essere vuoto. La lunghezza massima è di 32 caratteri. Il nome deve iniziare con una lettera e può contenere solo lettere (A-Z, a-z) o numeri (0-9). Il nome verrà normalizzato (in minuscolo) prima di essere associato.
values[]

string

Valori di testo dell'attributo. Il numero massimo di elementi è 10. La lunghezza massima di un elemento nell'array è di 32 caratteri. Il valore verrà normalizzato (in minuscolo) prima di essere associato.

ItemStructuredData

Campi di dati strutturati disponibili per l'elemento.

Rappresentazione JSON 
{
  "object": {
    object (StructuredDataObject)
  },
  "hash": string
}
Campi
object

object (StructuredDataObject)

L'oggetto di dati strutturati che deve essere conforme a una definizione di oggetto registrata nello schema dell'origine dati.
hash

string

Valore di hashing fornito dal chiamante dell'API. Questo può essere utilizzato con il metodo items.push per calcolare lo stato modificato. La lunghezza massima è di 2048 caratteri.

StructuredDataObject

Un oggetto di dati strutturati costituito da proprietà denominate.

Rappresentazione JSON 
{
  "properties": [
    {
      object (NamedProperty)
    }
  ]
}
Campi
properties[]

object (NamedProperty)

Le proprietà dell'oggetto. Il numero massimo di elementi è 1000.

NamedProperty

Una coppia nome-valore con tipo per i dati strutturati. Il tipo del valore deve corrispondere a quello registrato per la proprietà name nella definizione dell'oggetto objectType.

Rappresentazione JSON 
{
  "name": string,

  // Union field value can be only one of the following:
  "integerValues": {
    object (NamedProperty.IntegerValues)
  },
  "doubleValues": {
    object (NamedProperty.DoubleValues)
  },
  "timestampValues": {
    object (NamedProperty.TimestampValues)
  },
  "booleanValue": boolean,
  "objectValues": {
    object (NamedProperty.ObjectValues)
  },
  "enumValues": {
    object (NamedProperty.EnumValues)
  },
  "dateValues": {
    object (NamedProperty.DateValues)
  },
  "textValues": {
    object (NamedProperty.TextValues)
  },
  "htmlValues": {
    object (NamedProperty.HtmlValues)
  }
  // End of list of possible types for union field value.
}
Campi
name

string

Il nome della proprietà. Questo nome deve corrispondere al nome della proprietà registrata per la definizione dell'oggetto nello schema. La lunghezza massima consentita per questa proprietà è di 256 caratteri.
Campo unione value. I valori della proprietà denominata. Tieni presente che una proprietà può contenere solo valori di un tipo. value può essere solo uno dei seguenti:
integerValues

object (NamedProperty.IntegerValues)
doubleValues

object (NamedProperty.DoubleValues)
timestampValues

object (NamedProperty.TimestampValues)
booleanValue

boolean
objectValues

object (NamedProperty.ObjectValues)
enumValues

object (NamedProperty.EnumValues)
dateValues

object (NamedProperty.DateValues)
textValues

object (NamedProperty.TextValues)
htmlValues

object (NamedProperty.HtmlValues)

NamedProperty.IntegerValues

Elenco di valori interi.

Rappresentazione JSON 
{
  "values": [
    string
  ]
}
Campi
values[]

string (int64 format)

NamedProperty.DoubleValues

Elenco di valori doppi.

Rappresentazione JSON 
{
  "values": [
    number
  ]
}
Campi
values[]

number

NamedProperty.TimestampValues

Elenco di valori timestamp.

Rappresentazione JSON 
{
  "values": [
    string
  ]
}
Campi
values[]

string (Timestamp format)

Un timestamp in formato "Zulu" UTC RFC3339, con risoluzione in nanosecondi e fino a nove cifre frazionarie. Esempi: "2014-10-02T15:01:23Z" e "2014-10-02T15:01:23.045123456Z".

NamedProperty.ObjectValues

Elenco di valori dell'oggetto.

Rappresentazione JSON 
{
  "values": [
    {
      object (StructuredDataObject)
    }
  ]
}
Campi
values[]

object (StructuredDataObject)

NamedProperty.EnumValues

Elenco di valori enum.

Rappresentazione JSON 
{
  "values": [
    string
  ]
}
Campi
values[]

string

La lunghezza massima consentita per i valori di stringa è di 32 caratteri.

NamedProperty.DateValues

Elenco di valori data.

Rappresentazione JSON 
{
  "values": [
    {
      object (Date)
    }
  ]
}
Campi
values[]

object (Date)

NamedProperty.TextValues

Elenco di valori di testo.

Rappresentazione JSON 
{
  "values": [
    string
  ]
}
Campi
values[]

string

La lunghezza massima consentita per i valori di testo è di 2048 caratteri.

NamedProperty.HtmlValues

Elenco di valori HTML.

Rappresentazione JSON 
{
  "values": [
    string
  ]
}
Campi
values[]

string

La lunghezza massima consentita per i valori HTML è di 2048 caratteri.

ItemContent

Contenuti di un elemento da indicizzare e mostrare da Cloud Search. Come inlineContent sono consentite solo stringhe con codifica UTF-8. Se i contenuti sono caricati e non binari, devono essere codificati in UTF-8.

Rappresentazione JSON 
{
  "contentFormat": enum (ItemContent.ContentFormat),
  "hash": string,

  // Union field content can be only one of the following:
  "inlineContent": string,
  "contentDataRef": {
    object (UploadItemRef)
  }
  // End of list of possible types for union field content.
}
Campi
contentFormat

enum (ItemContent.ContentFormat)
hash

string

Informazioni sull'hashing calcolate e fornite dal client dell'API per i contenuti. Può essere utilizzato con il metodo items.push per calcolare lo stato modificato. La lunghezza massima è di 2048 caratteri.

Campo unione content.

content può essere solo uno dei seguenti:
inlineContent

string (bytes format)

Contenuti forniti in linea all'interno del metodo di aggiornamento. La lunghezza massima è di 102400 byte (100 KiB).

Una stringa con codifica Base64.
contentDataRef

object (UploadItemRef)

Carica l'ID di riferimento di contenuti caricati in precedenza tramite il metodo write.

ItemContent.ContentFormat

Il formato dei contenuti. Se il formato è RAW, i contenuti devono essere nel formato specificato da mimeType.

Enum
UNSPECIFIED Valore non valido.
HTML contentFormat è HTML.
TEXT contentFormat è un testo libero.
RAW contentFormat è costituito da byte non elaborati.

UploadItemRef

Rappresenta un riferimento alla sessione di caricamento. Questo riferimento viene creato tramite upload method. Questo riferimento è valido per 30 giorni dalla sua creazione. L'aggiornamento dei contenuti dell'articolo potrebbe fare riferimento a questi contenuti caricati tramite contentDataRef.

Rappresentazione JSON 
{
  "name": string
}
Campi
name

string

Il nome del riferimento ai contenuti. La lunghezza massima è di 2048 caratteri.

ItemStatus

Questo contiene lo stato dell'elemento ed eventuali errori.

Rappresentazione JSON 
{
  "code": enum (ItemStatus.Code),
  "processingErrors": [
    {
      object (ProcessingError)
    }
  ],
  "repositoryErrors": [
    {
      object (RepositoryError)
    }
  ]
}
Campi
code

enum (ItemStatus.Code)

Codice di stato.
processingErrors[]

object (ProcessingError)

Dettagli dell'errore nel caso in cui l'elemento sia in stato ERROR.
repositoryErrors[]

object (RepositoryError)

Errore del repository segnalato dal connettore.

ProcessingError

Rappresentazione JSON 
{
  "code": enum (ProcessingErrorCode),
  "errorMessage": string,
  "fieldViolations": [
    {
      object (FieldViolation)
    }
  ]
}
Campi
code

enum (ProcessingErrorCode)

Codice di errore che indica la natura dell'errore.
errorMessage

string

La descrizione dell'errore.
fieldViolations[]

object (FieldViolation)

Se i campi degli articoli non sono validi, questo campo contiene i dettagli sugli errori di convalida.

ProcessingErrorCode

Codici per indicare l'errore riscontrato durante l'elaborazione degli elementi dal server Cloud Search. Un singolo elemento può contenere più errori di elaborazione.

Enum
PROCESSING_ERROR_CODE_UNSPECIFIED Inserisci solo il valore. Utilizza questo valore in Elementi.
MALFORMED_REQUEST L'ACL, i metadati o i contenuti dell'elemento non sono validi o non sono formattati correttamente. FieldViolations contiene ulteriori dettagli sulla posizione del problema.
UNSUPPORTED_CONTENT_FORMAT Il formato dei contenuti non è supportato.
INDIRECT_BROKEN_ACL Elementi con informazioni ACL incomplete a causa dell'eredità di altri elementi con ACL non funzionanti o con gruppi con discendenti non mappati.
ACL_CYCLE Il grafo di ereditarietà delle ACL ha formato un ciclo.

FieldViolation

Rappresentazione JSON 
{
  "field": string,
  "description": string
}
Campi
field

string

Percorso del campo con violazione.
description

string

La descrizione dell'errore.

RepositoryError

Errori durante la comunicazione del connettore con il repository di origine.

Rappresentazione JSON 
{
  "type": enum (RepositoryError.Type),
  "httpStatusCode": integer,
  "errorMessage": string
}
Campi
type

enum (RepositoryError.Type)

Il tipo di errore.
httpStatusCode

integer

Codici di errore. Corrisponde alla definizione dei codici di stato HTTP.
errorMessage

string

Messaggio che descrive l'errore. La lunghezza massima consentita del messaggio è di 8192 caratteri.

RepositoryError.Type

Elenco dei codici di errore per i problemi di comunicazione con il repository.

Enum
UNKNOWN Errore sconosciuto.
NETWORK_ERROR Host sconosciuto o non raggiungibile.
DNS_ERROR Problema DNS, ad esempio il server DNS non risponde.
CONNECTION_ERROR Impossibile connettersi al server del repository.
AUTHENTICATION_ERROR Autenticazione non riuscita a causa di credenziali errate.
AUTHORIZATION_ERROR L'account di servizio non è autorizzato per il repository.
SERVER_ERROR Errore del server del repository.
QUOTA_EXCEEDED La quota è stata superata.
SERVICE_UNAVAILABLE Server temporaneamente non disponibile.
CLIENT_ERROR Errore relativo al client, ad esempio una richiesta non valida dal connettore al server del repository.

Item.ItemType

Enum
UNSPECIFIED
CONTENT_ITEM Un elemento indicizzato al solo scopo di fornire informazioni. Questi elementi non possono essere indicati nei campi containerName o inheritAclFrom.
CONTAINER_ITEM Un elemento che viene indicizzato e il cui scopo è fornire ad altri elementi ACL e/o contenere altri elementi.
VIRTUAL_CONTAINER_ITEM Un elemento che non viene indicizzato, ma che ha lo stesso scopo di CONTAINER_ITEM.

Metodi

delete

 Consente di eliminare Item resource per il nome della risorsa specificato.

deleteQueueItems

 Consente di eliminare tutti gli elementi di una coda.

get

 Recupera Item resource per nome articolo.

index

 Aggiorna Item ACL, metadati e contenuti.

list

 Elenca tutti o un sottoinsieme di Item resources.

poll

 Esegue il polling degli elementi non riservati dalla coda di indicizzazione e contrassegna un insieme come riservato, a partire dagli elementi con il timestamp più antico della priorità più alta ItemStatus.

push

 Inserisce un elemento in una coda per il successivo polling e aggiornamento.

unreserve

 Annullare la prenotazione di tutti gli elementi di una coda, rendendoli idonei per il polling.

upload

 Crea una sessione di caricamento per il caricamento dei contenuti degli articoli.