sondaggi

Una risorsa sondaggio contiene informazioni su una richiesta specifica di dati. Una volta creato un sondaggio, verrà avviata la creazione di una o più attività per completare la richiesta.

attributi

Compiti

Il ruolo più importante della risorsa sondaggio è quello di riflettere l'avanzamento delle attività associate e consentire all'utente finale di iniziare a recuperare i risultati da questi non appena diventano disponibili. Pertanto, la risorsa di polling espone gli attributi relativi alle attività in cui le attività associate sono classificate in base al loro stato.

risultati

Tutti i risultati pubblicati dalle attività in esecuzione nel sondaggio vengono visualizzati nell'attributo dei results del sondaggio. Ciò consente il consumo dei risultati prima del completamento del sondaggio.

Errori

Tutti gli errori generati dalle attività in esecuzione nel sondaggio verranno visualizzati nell'attributo errors del sondaggio.

stati

Lo stato di un sondaggio riflette solo se il sondaggio è in attesa di inizializzazione (in pending ), è in corso ( processing ), o tutte le attività hanno terminato l'esecuzione ( completed ).

Un sondaggio non riflette nessuno stato di errore se non attraverso i suoi compiti associati.

Carico utile

Il payload del sondaggio indica quali tipi di informazioni, tipi di dati e file devono funzionare per il recupero. Lo schema dell'attributo del payload del poll è descritto di seguito.

Ad esempio, il payload del sondaggio per recuperare tutti i tipi di informazioni su un'origine dell'account iCloud sarebbe:

{
  "info_types": ["*"]
}

Per recuperare una varietà di dati di messaggistica da una copia di backup iCloud o Reincubate Relay, ma solo da una determinata data:

{
  "data_types": ["ios_messages.messages", "whatsapp.messages", "viber.messages"],
  "filters": {
    "since": "2019-09-15T22:04:12Z",
    "until": "2021-06-02T12:00:00Z"
  }
}

Per recuperare i dati dei file per le immagini a cui fa riferimento un risultato della Libreria foto iCloud:

{
  "files": ["icpl://xyz123", "icpl://abc321"]
}

I diversi attributi possono anche essere usati contemporaneamente:

{
  "info_types": ["*"],
  "data_types": ["ios_phone.calls"]
}

Filtri

I filtri consentono al cliente di ridurre la quantità di dati restituiti solo a quelli che potrebbero essere di interesse. Ad esempio, potresti filtrare un sondaggio per i dati SMS solo in base ai dati dell'ultimo mese.

Filtri nei payload del sondaggio di abbonamento

Quando si utilizzano gli abbonamenti per generare sondaggi regolari, tutti i filtri impostati nel payload del sondaggio verranno utilizzati solo nel sondaggio iniziale dell'abbonamento. Successivamente, l'API eseguirà le seguenti operazioni:

• Qualsiasi valore per until viene ignorato per evitare di ripetere semplicemente il polling ripetutamente dello stesso intervallo
• Se è stato impostato until , il sondaggio successivo recupererà i dati da quel momento in poi
• Se until non è stato impostato, il sondaggio successivo recupererà i dati dal momento del sondaggio iniziale in poi (ovvero l'API eseguirà il polling progressivamente come di consueto)

Filtri a livello di dati

I filtri a livello di dati, come phone_numbers e email_addresses , sono utili per ridurre i dati elaborati solo agli elementi pertinenti per te. Si tratta di filtri di inclusione che eliminano eventuali elementi di dati che non corrispondono o che sono correlati a un altro elemento che corrisponde a uno dei valori nell'elenco del filtro. Prendiamo ad esempio il payload riportato di seguito:

{
  "data_types": ["ios_messages.messages"],
  "filters": {
    "phone_numbers": ["0123456789"],
    "email_addresses": ["test@example.com"]
  }
}

Ciò restituirebbe tutti i messaggi di Messaggi iOS relativi a una conversazione che coinvolge il numero di telefono o l'indirizzo e-mail specificato, incluse eventuali conversazioni di gruppo. Può essere utile specificare più valori in base ai quali filtrare, poiché molti contatti avranno un mix di numeri di telefono e account identificati tramite posta elettronica, come gli account iCloud di Messaggi.

I filtri basati sull'esclusione, come exclude_phone_numbers ed exclude_email_addresses , fanno l'opposto: rimuovono tutti i dati relativi ai valori forniti. Se vengono forniti sia filtri basati sull'inclusione che su quelli basati sull'esclusione, e un elemento si riferisce a entrambi, il filtro basato sull'esclusione prevale. Ad esempio, una conversazione di gruppo che contiene un contatto con un indirizzo email incluso ma anche un altro contatto con un numero di telefono escluso verrà filtrata e esclusa dai dati.

Filtri di esclusione di campo

Il filtro exclude opera a livello di campo anziché a livello di elemento: invece di eliminare interi elementi di dati, omette i campi specificati da ciascun elemento estratto. Si consiglia di utilizzare questo filtro nei filtri per tipi di dati specifici anziché nei filtri generici, per evitare di escludere inavvertitamente campi di altri tipi di dati.

{
  "data_types": [{
    "data_type: ""ios_contacts.contacts",
    "filters": {
      "exclude": ["photo"]
    }
  }],
}

In questo modo verrebbero restituiti i dati dei contatti senza le foto.

Il filtro exclude è attualmente supportato solo dal tipo di dati ios_contacts.contacts e l'unico campo escludibile è photo . I valori non riconosciuti vengono ignorati.

Crea POST /polls

Crea un sondaggio per i dati rispetto a una sessione specifica.

Il parametro source deve essere utilizzato solo quando si sceglie come target un'origine figlio dell'origine principale della sessione. Ad esempio, se si recuperano dati da una source rirelay.source il parametro source dovrebbe essere l'ID di quella sorgente.

Utilizzando cURL

curl https://ricloud-api.reincubate.com/polls \
  -X POST \
  -H 'Authorization: Token <your key_token>' \
  -H 'Content-Type: application/json' \
  -d '{
  "session": "<session ID>",
  "payload": {
    "info_types": ["*"]
  }
}'

Usando ricloud-py

import ricloud

poll_payload = {
  'info_types': ['*'],
}

poll = ricloud.Poll.create(
  session='<session ID or ricloud.Session instance>',
  payload=poll_payload,
)

Risposta del campione

{
  "id": "54554389-5f1a-4ccf-9bb8-024a031cf948",
  "resource": "poll",
  "organisation": 1,
  "key": 1,
  "user": 1,
  "source": 1,
  "session": "f5a7a7ef-ff21-47fe-9aa6-7ebd08123623",
  "subscription": null,
  "tasks_pending": [],
  "tasks_processing": [],
  "tasks_succeeded": [],
  "tasks_failed": [],
  "tasks_suspended": [],
  "results": {
      "data": [],
      "has_more": false,
      "total_count": 0,
      "url": "/polls/54554389-5f1a-4ccf-9bb8-024a031cf948/results"
  },
  "errors": {
    "data": [],
      "has_more": false,
      "total_count": 0,
      "url": "/polls/54554389-5f1a-4ccf-9bb8-024a031cf948/errors"
  },
  "state": "pending",
  "date_created": "2020-02-20T11:59:14.694337Z",
  "date_started": null,
  "date_completed": null
}

Riprendi POST /polls/{poll ID}/resume

Riprendi un'operazione di polling riavviando le attività sospese e riprovando le attività sui file non riuscite. Questa funzionalità può essere utilizzata per attivare una nuova valutazione dei file richiesti dalle istanze dell'app Relay o per riprovare le attività sui file che potrebbero essere fallite a causa di un problema temporaneo.

Utilizzando cURL

curl https://ricloud-api.reincubate.com/polls/<poll ID>/resume \
  -X POST \
  -H 'Authorization: Token <your key_token>' \
  -H 'Content-Type: application/json' \
  -d '{}'

Per riprendere con opzioni specifiche:

curl https://ricloud-api.reincubate.com/polls/<poll ID>/resume \
  -X POST \
  -H 'Authorization: Token <your key_token>' \
  -H 'Content-Type: application/json' \
  -d '{
  "skip_missing": true,
  "retry_files": false
}'

Recupera GET /polls/{poll ID}

Utilizzando cURL

curl https://ricloud-api.reincubate.com/polls/<poll ID> \
  -H 'Authorization: Token <your key_token>'

Usando ricloud-py

import ricloud

poll = ricloud.Poll.retrieve(<poll ID>)

Elenca GET /polls

Utilizzando cURL

curl https://ricloud-api.reincubate.com/polls \
  -H 'Authorization: Token <your key_token>'

Usando ricloud-py

import ricloud

polls = ricloud.Poll.list()

changelog

2026-06-04

• Aggiunto il supporto per il filtro exclude nei payload dei sondaggi. Ciò consente di omettere i campi di output denominati dagli elementi di dati estratti. Attualmente supportato solo dal tipo di dati ios_contacts.contacts , per il campo photo .

2026-03-06

• Aggiungi l'endpoint POST /polls/{poll ID}/resume per riprendere le attività sospese e riprovare le attività sui file non riuscite. Le attività sui file non riuscite vengono riprovate per impostazione predefinita.

2024-12-09

• Aggiungere il supporto per escludere i dati relativi a specifici indirizzi e-mail e numeri di telefono di contatto, tramite i parametri payload del sondaggio exclude_phone_numbers ed exclude_emails .

28-11-2023

• Aggiungere il supporto per il filtraggio dei dati utilizzando indirizzi email e numeri di telefono di contatto tramite i parametri payload del sondaggio phone_numbers ed emails .

2022-07-08

• È stato aggiunto il supporto per il filtro until ai payload del sondaggio per l'estrazione degli SMS. Ciò integra il filtro since per consentire ai client di specificare un intervallo di date e ore esatto da cui recuperare i dati.

2020/05/05

• L'attributo errors stato aggiunto all'oggetto poll. Questo è un oggetto elenco nidificato contenente oggetti di errore associati al sondaggio.

2020/02/20

• Maggiore : l'attributo dei results dell'oggetto sondaggio è ora un oggetto elenco nidificato, anziché un semplice attributo elenco. Ciò consente di impaginare i risultati quando un sondaggio pubblica un numero elevato di risultati.

2019/10/16

• Aggiunge l'attributo di subscription all'oggetto sondaggio per indicare se il sondaggio è stato attivato da una sottoscrizione.

2019/06/01

• L'attributo payload dell'oggetto poll può ora essere composto da più tipi di operazioni. Ciò significa che è possibile creare un sondaggio con uno o tutti info-types di info-types data-types e files nel payload.
• Maggiore L'attributo type sull'oggetto poll è deprecato a favore dei payload di poll componibili.