Gegevens opvragen met asapi (v2)

bijgewerkt

asapi is een asynchroon besturingsmechanisme voor de ricloud- API. Het stelt gebruikers in staat om:

  • Ontdek services , acties en eindpunten die ze mogen gebruiken
  • Registreer, deregistreren en leer over accounts
  • Asynchrone taken verzenden
  • Vraag de status van taken op

Na voltooiing kunnen gegevens van taken worden verkregen via het aschannel of de asstore , afhankelijk van de use-case van de klant.

Methoden in één oogopslag

Service, actie en eindpuntherkenning

/account/

Met het /account/ eindpunt kunnen klanten informatie verkrijgen over:

  • Beschikbare services
  • Beschikbare acties en hun parameters en rechten
  • Eindpunten beschikbaar voor het indienen en ophalen van taken

Om dit te doen, wordt een ontdekkingsverzoek gedaan:

$ curl \
    -X GET \
    -H 'Authorization: Token <TOKEN>' \
    https://asapi.reincubate.com/account/ -D -

Hiermee wordt een set JSON geretourneerd die de beschikbare services, acties en eindpunten beschrijft. Het onderstaande voorbeeld is afgekort:

{ "services": [{
    "name": "iCloud",
    "actions": [{
      "description": "",
      "parameters": [{
        "type": "string",
        "description": "",
        "optional": false,
        "name": "Device",
        "slug": "device"
      }, {
        "type": "date",
        "description": "",
        "optional": true,
        "name": "Since",
        "slug": "since"
      }],
      "name": "Fetch Data",
      "execution": "Asynchronous",
      "slug": "fetch-data",
      "permissions": {
        "data": ["sms"]
      }
    }],
    "slug": "icloud"
  }],
  "task_submission_endpoint": {
    "host": "asapi.reincubate.com",
    "protocol": "https",
    "uri": "/submit-task/"
  },
  "stream_endpoints": [{
    "host": "aschannel.reincubate.com",
    "protocol": "https",
    "uri": "/stream/"
  }]
}

In dit geval zou de client toegang hebben tot de icloud service en de fetch-data . Ze zouden device en data moeten indienen bij gebruik, en optioneel ook since .

Deze laatste data moet in het lijstformaat zijn; deze parameter kan alle waarden bevatten die worden vermeld in de permissions > data van de fetch-data sectie.

Het task_submission_endpoint is gedefinieerd in dit antwoord en informeert klanten over acties die voor uitvoering kunnen worden ingediend.

Het stream_endpoint in het bovenstaande voorbeeld is gedefinieerd als aschannel.reincubate.com , wat betekent dat aschannel is geconfigureerd als het eindpunt van de resultaten. Als alternatief kan dit klanten naar een winkel leiden , afhankelijk van de configuratie van hun token.

Accountregistratie en uitschrijving

register-account

Om acties in te dienen, moeten we asapi op de hoogte brengen van de accounts die mogelijk acties tegen hen hebben uitgevoerd. Om dit te doen, zullen we het /register-account/ eindpunt gebruiken:

$ curl \
    -X POST \
    -H 'Authorization: Token <TOKEN>' \
    -d "service=<SERVICE>" \
    -d "username=<USERNAME>" \
    https://asapi.reincubate.com/register-account/ -D -

In dit verzoek is <SERVICE> service die de specifieke actie bezit, terwijl <USERNAME> vertegenwoordigt voor het account dat in de acties wordt gebruikt.

deregister-account

Als een account niet verder wordt gebruikt, kan het worden uitgeschreven. Om een account te deregistreren, kan een soortgelijk verzoek worden verzonden naar het /deregister-account/ eindpunt:

$ curl \
    -X POST \
    -H 'Authorization: Token <TOKEN>' \
    -d "service=<SERVICE>" \
    -d "username=<USERNAME>" \
    https://asapi.reincubate.com/deregister-account/ -D -

Beide methoden, bij succes, zullen een antwoord van 200

{ "success": true
}

Mogelijke fouten zijn:

  • unique_together : "Account met deze service, client en gebruikersnaam bestaat al"

Taak indienen

[TASK-SUBMISSION]

Asynchrone taken kunnen worden ingediend met behulp van het eindpunt dat is opgegeven in task_submission_endpoint .

Om een taak in te dienen, wordt de volgende opdracht gebruikt:

$ curl \
    -X POST \
    -H "Authorization: Token <TOKEN>" \
    -d "service=<SERVICE>" \
    -d "action=<ACTION>" \
    -d "account=<ACCOUNT>" \
    -d "param1=<VALUE1>" \
    -d "param2=<VALUE2>" \
    <TASK_SUBMISSION_ENDPOINT> -D -

Op dat verzoek:

Bij succes retourneert het verzoek een 200 met:

{ "task_id": "<TASK_ID>",
  "retrieval_protocol": "<RETRIEVAL_PROTOCOL>",
  "stream": "<STREAM>",
  "success": true
}

In deze antwoorden: <TASK_ID> biedt een ID voor de taak die kan worden gebruikt om de status ervan te bevragen en om het resultaat van de taak op te halen, als de asstore wordt gebruikt <RETRIEVAL_PROTOCOL> geeft de methode aan die wordt gebruikt om de resultaten van de taak op te halen en kan de waarde van aschannel of asstore nemen <STREAM> is stroom-ID voor gebruik bij het ophalen van de taakresultaten , als het aschannel wordt gebruikt *

Als het verzoek is misvormd, is de eigenschap 'succes' onwaar en bevat de reactie een sectie 'fouten' met feedback. Bijvoorbeeld:

{ "errors": {
    "service": [
      ["[u'Invalid service name']", "invalid_service"]
    ]
  },
  "success": false
}

Mogelijke fouten zijn: * invalid_service : 'Ongeldige servicenaam' * invalid_parameter_value : 'Waarde niet toegestaan voor parameter' * no_such_account : 'Geen account' * invalid : 'Ongeldige waarde' * limit_exceeded : 'Te veel taak-ID's verzonden' * invalid_action : 'Ongeldige actie' * missing-param : 'Parameter ontbreekt'

Takenstatussen opvragen

/task-status/

Voor elke taak die wordt ingediend bij het asapi- eindpunt, wordt een task_id verstrekt. De client kan deze task_id periodiek indienen bij het asapi- eindpunt om de status van een taak te achterhalen . De status kan worden opgevraagd met een POST verzoek in de /task-status/ eindpunt. Cliënten kunnen de status van maximaal 10.000 taken gelijktijdig aanvragen.

$ curl \
    -X POST \
    -H "Authorization: Token <TOKEN>" \
    -d "task_ids=<TASK_ID_1>,<TASK_ID_2>,<TASK_ID_3>,<TASK_ID_4>,<TASK_ID_5>,<TASK_ID_6>,<TASK_ID_7>" \
    https://asapi.reincubate.com/task-status/

Gegeven ten minste één correcte <TASK_ID> , is de respons 200 in dit formaat:

{ "<TASK_ID_1>": {
    "status": "<TASK_STATUS>",
    "retrieval_protocol": "<RETRIEVAL_PROTOCOL>",
    "result_retrieved": "<RETRIEVAL_STATUS>",
    "success": "<TASK_SUCCESS>"
  },
  "success": "<CHECK_SUCCESS>"
}

Als <TASK_SUCCESS> "True" is, zijn de resultaten onmiddellijk beschikbaar bij het juiste eindpunt.

De status kan de volgende waarden aannemen:

  • Pending
  • In progress
  • Work complete
  • Publish ongoing, with result available
  • Publish complete (in dit geval is de success "waar")
  • Publish failed (in dit geval is de success "false")
  • Task did not complete successfully. (in dit geval is de success "false")

<RETRIEVAL_PROTOCOL> indicates the method used to retrieve the task results and can take the value of aschannel or asstore depending on the token.

<RETRIEVAL_STATUS> is a boolean, indicating whether the task's results have already been consumed by a client. If <RETRIEVAL_STATUS> is "True", then the results have already been consumed and are no longer available.

De parameter <CHECK_SUCCESS> die zich in de hoofdmap van de JSON-structuur bevindt, verwijst naar het succes van statuscontrole zelf. Als dit "false" is, bevat het antwoord een extra "fouten" -vermelding.

Mogelijke fouten zijn:

  • invalid : "Ongeldige waarde task_id: "
  • limit_exceeded : "Te veel taak-id's ingediend, limiet is "

Een voorbeeld van uitvoer wordt hieronder getoond:

{
  "<TASK_ID_1>": {
    "success": false,
    "error": "No task with this ID was found."
  },
  "<TASK_ID_2>": {
    "status": "Publish complete",
    "retrieval_protocol": "aschannel",
    "result_retrieved": false,
    "success": true
  },
  "<TASK_ID_3>": {
    "status": "Publish complete",
    "retrieval_protocol": "asstore",
    "retrieval_endpoint": "https://asstore.reincubate.com/fetch/aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee/",
    "result_retrieved": true,
    "success": true
  },
  "<TASK_ID_4>": {
    "status": "Publish failed",
    "retrieval_endpoint": "https://asstore.reincubate.com/fetch/1111111-2222-3333-4444-555555555555/",
    "success": false,
    "error": "Task did not complete successfully.",
    "retrieval_protocol": "asstore",
    "result_retrieved": false
  },
  "<TASK_ID_5>": {
    "status": "Pending",
    "result_retrieved": false,
    "success": false
  },
  "<TASK_ID_6>": {
    "status": "In progress",
    "result_retrieved": false,
    "success": false
  },
  "<TASK_ID_7>": {
    "status": "Work complete",
    "result_retrieved": false,
    "success": false
  },
  "success": true,
}

Hoe kunnen we helpen?

Ons ondersteuningsteam is er om u te helpen!

Onze kantooruren zijn van maandag tot vrijdag van 09.00 tot 17.00 uur GMT. De tijd is momenteel 2:26 AM GMT.

We streven ernaar om alle berichten binnen één werkdag te beantwoorden.

Ga naar het ondersteuningsgedeelte › Neem contact op met het Enterprise-team ›
Ons geweldige ondersteuningsteam

© 2008 - 2019 Reincubate Ltd. Alle rechten voorbehouden. Geregistreerd in Engeland en Wales #5189175, VAT GB151788978. Reincubate® is een geregistreerd handelsmerk. Privacy en voorwaarden. Wij bevelen 2FA aan. Gebouwd met in Londen.