Solicitando dados com asapi (v2)

Atualizada

o asapi é um mecanismo de controle assíncrono para a API ricloud . Ele permite que os usuários:

  • Descubra serviços , ações e endpoints que eles estão autorizados a usar
  • Registre-se, cancele o registro e aprenda sobre contas
  • Enviar tarefas assíncronas
  • Consultar o status das tarefas

Depois de concluídos, os dados das tarefas podem ser obtidos no aschannel ou no asstore , dependendo do caso de uso do cliente.

Métodos de relance

Serviço, ação e descoberta de endpoint

/account/

Usando o /account/ endpoint, os clientes podem obter informações sobre:

  • Serviços disponíveis
  • Ações disponíveis e seus parâmetros e permissões
  • Pontos de extremidade disponíveis para envio e recuperação de tarefas

Para fazer isso, uma solicitação de descoberta é feita:

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

Isso retornará um conjunto de JSON descrevendo os serviços, ações e terminais disponíveis. O exemplo abaixo é abreviado:

{ "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/"
  }]
}

Nesse caso, o cliente teria acesso ao serviço icloud e à ação fetch-data . Eles precisariam enviar parâmetros de device e data ao usá-lo e, opcionalmente, também since .

Este último parâmetro de data deve estar no formato de lista; Esse parâmetro pode conter quaisquer valores listados nas permissions > data da seção de data de fetch-data .

O task_submission_endpoint é definido nessa resposta e informa aos clientes onde as ações podem ser submetidas para execução.

O stream_endpoint no exemplo acima é definido como aschannel.reincubate.com , o que significa que o aschannel é configurado como o endpoint de resultados. Como alternativa, isso poderia direcionar os clientes para o asstore , dependendo da configuração de seu token.

Registro de conta e cancelamento de registro

register-account

Para enviar ações, precisamos informar o asapi das contas que podem ter ações executadas contra elas. Para fazer isso, usaremos a /register-account/ endpoint:

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

Nesta solicitação, <SERVICE> é o serviço que possui a ação específica, enquanto que <USERNAME> representa a conta que será usada nas ações.

deregister-account

Se uma conta não for usada mais, ela pode ser cancelada. Para cancelar o registro de uma conta, uma solicitação semelhante pode ser enviada para a /deregister-account/ endpoint:

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

Ambos os métodos, em sucesso, retornarão uma resposta de 200 com

{ "success": true
}

Possíveis erros incluem:

  • unique_together : "Conta com este serviço, cliente e nome de usuário já existe"

Submissão de tarefas

[TASK-SUBMISSION]

As tarefas assíncronas podem ser enviadas usando o terminal especificado em task_submission_endpoint .

Para enviar uma tarefa, o seguinte comando é usado:

$ 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 -

Nesse pedido:

  • <SERVICE> e <ACTION> representam o serviço e a ação de destino
  • <ACCOUNT> refere-se a uma conta registrada anteriormente
  • param1 , param2 e parâmetros subsequentes formam a carga útil específica da tarefa, cujos requisitos são descritos pelo método de descoberta de serviço, ação e terminal

No sucesso, o pedido retornará um 200 com:

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

Nestas respostas: <TASK_ID> fornece um ID para a tarefa que pode ser usada para consultar seu status e para recuperar o resultado da tarefa, se estiver usando o asstore <RETRIEVAL_PROTOCOL> indica o método usado para recuperar os resultados da tarefa e pode assumir o valor de aschannel ou asstore <STREAM> é o ID do fluxo para ser usado na recuperação dos resultados da tarefa, se estiver usando o aschannel *

Se a solicitação foi malformada, a propriedade "success" será falsa e a resposta incluirá uma seção "errors" com feedback. Por exemplo:

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

Os possíveis erros incluem: * invalid_service : 'Nome do serviço inválido' * invalid_parameter_value : 'Valor não permitido para o parâmetro' * no_such_account : 'Nenhuma conta' * invalid : 'Valor inválido' * limit_exceeded : 'Número excessivo de tarefas submetidas' * invalid_action : 'Ação inválida' * missing-param : 'Parameter está desaparecido'

Consultando status das tarefas

/task-status/

Para cada tarefa enviada ao terminal asapi , é fornecido um task_id . O cliente pode enviar periodicamente esse task_id para o ponto de extremidade asapi para descobrir o status de uma tarefa. Seu status pode ser consultado com uma solicitação POST no /task-status/ endpoint. Os clientes podem solicitar o status de até 10.000 tarefas simultaneamente.

$ 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/

Dado pelo menos uma <TASK_ID> correta, a resposta será um 200 neste formato:

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

Se <TASK_SUCCESS> for "True", os resultados serão disponibilizados imediatamente no terminal apropriado.

A propriedade de status pode ter os seguintes valores:

  • Pending
  • In progress
  • Work complete
  • Publish ongoing, with result available
  • Publish complete (neste caso, o valor de success é "true")
  • Publish failed (neste caso, o valor de success é "falso")
  • Task did not complete successfully. (neste caso, o valor de success é "falso")

<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.

O parâmetro <CHECK_SUCCESS> localizado na raiz da árvore JSON se refere ao sucesso da própria verificação de status. Se isso for "falso", a resposta conterá uma entrada adicional de "erros".

Possíveis erros incluem:

  • invalid : "valor de task_id inválido: "
  • limit_exceeded : "Há muitos IDs de tarefas enviados, o limite é "

Um exemplo de saída é mostrado abaixo:

{
  "<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,
}

Como podemos ajudar?

Nossa equipe de suporte está aqui para ajudar!

Nosso horário de atendimento é de segunda a sexta, das 9h às 17h GMT. A hora é atualmente 6:27 PM GMT.

Nosso objetivo é responder a todas as mensagens dentro de um dia útil.

Vá para a seção de apoio › Entre em contato com a equipe da empresa ›
Nossa equipe de suporte incrível

© 2008 - 2019 Reincubate Ltd. Todos os direitos reservados. Registrado na Inglaterra e no País de Gales #5189175, VAT GB151788978. Reincubate® é uma marca registrada. Privacidade e Termos. Recomendamos 2FA. Construído com em Londres.