Endpoint de notas

Na API do Reactor, as notas são anotações textuais que podem ser adicionadas a determinados recursos. Basicamente, as notas são comentários sobre os respectivos recursos. O conteúdo das notas não tem impacto sobre o comportamento dos recursos e pode ser usados para diversos casos de uso, inclusive os seguintes:

  • Fornecer informações de referência
  • Funcionar como listas de tarefas
  • Repassar conselhos sobre o uso de recursos
  • Dar instruções a outros membros da equipe
  • Registrar contexto histórico

O endpoint /notes na API do Reactor permite gerenciar essas notas de forma programática.

As notas podem ser aplicadas aos seguintes recursos:

Esses seis tipos são coletivamente conhecidos como recursos “anotáveis”. Quando um recurso anotável é excluído, as notas associadas a ele também são excluídas.

OBSERVAÇÃO

Para recursos que podem ter várias revisões, quaisquer notas devem ser criadas na revisão atual (head). Elas não podem ser anexadas a outras revisões.

No entanto, as notas ainda podem ser lidas nas revisões. Nesses casos, a API retorna apenas as notas existentes antes da criação da revisão. É fornecida uma captura de tela que mostra a aparência das anotações antes de a revisão ser removida. Por outro lado, a leitura de notas na revisão atual (head) retorna todas as notas.

Introdução

O endpoint usado neste manual faz parte da API do Reactor. Antes de continuar, consulte novamente o guia de introdução para obter informações importantes sobre como realizar a autenticação para a API.

Recuperar uma lista de notas

Você pode recuperar uma lista de notas para um recurso acrescentando /notes ao caminho de uma solicitação GET para o recurso em questão.

Formato da API

GET /{RESOURCE_TYPE}/{RESOURCE_ID}/notes
Parâmetro Descrição
RESOURCE_TYPE O tipo de recurso para o qual você está buscando notas. Deve ser um dos seguintes valores:
  • data_elements
  • extensions
  • libraries
  • properties
  • rule_components
  • rules
RESOURCE_ID O id do recurso específico cujas notas você deseja listar.

Solicitação

A solicitação a seguir lista as notas anexadas a uma biblioteca.

curl -X GET \
  https://reactor.adobe.io/libraries/LBcffea1a38c52408cae2398868625a12d/notes \
  -H 'Authorization: Bearer {ACCESS_TOKEN}' \
  -H 'x-api-key: {API_KEY}' \
  -H 'x-gw-ims-org-id: {ORG_ID}' \
  -H "Content-Type: application/vnd.api+json" \
  -H 'Accept: application/vnd.api+json;revision=1'

Resposta

Uma resposta bem-sucedida retorna uma lista de notas anexadas ao recurso especificado.

{
  "data": [
    {
      "id": "NTa40de8d76bfd4e40835830900ce83b7b",
      "type": "notes",
      "attributes": {
        "author_display_name": "John Smith",
        "author_email": "jsmith@example.com",
        "created_at": "2020-12-14T17:51:00.411Z",
        "text": "this is a note on a library"
      },
      "relationships": {
        "resource": {
          "links": {
            "related": "https://reactor.adobe.io/libraries/LBcffea1a38c52408cae2398868625a12d"
          },
          "data": {
            "id": "LBcffea1a38c52408cae2398868625a12d",
            "type": "libraries"
          }
        }
      },
      "links": {
        "resource": "https://reactor.adobe.io/libraries/LBcffea1a38c52408cae2398868625a12d",
        "self": "https://reactor.adobe.io/notes/NTa40de8d76bfd4e40835830900ce83b7b"
      }
    }
  ],
  "meta": {
    "pagination": {
      "current_page": 1,
      "next_page": null,
      "prev_page": null,
      "total_pages": 1,
      "total_count": 1
    }
  }
}

Pesquisar uma nota

É possível pesquisar uma nota fornecendo a respectiva ID no caminho de uma solicitação GET.

Formato da API

GET /notes/{NOTE_ID}
Parâmetro Descrição
NOTE_ID O id da nota que você deseja pesquisar.

Solicitação

curl -X GET \
  https://reactor.adobe.io/notes/NT550b7a17ab304d49ba289a2978d673e5 \
  -H 'Authorization: Bearer {ACCESS_TOKEN}' \
  -H 'x-api-key: {API_KEY}' \
  -H 'x-gw-ims-org-id: {ORG_ID}' \
  -H "Content-Type: application/vnd.api+json" \
  -H 'Accept: application/vnd.api+json;revision=1'

Resposta

Uma resposta bem-sucedida retorna os detalhes da nota.

{
  "data": {
    "id": "NT550b7a17ab304d49ba289a2978d673e5",
    "type": "notes",
    "attributes": {
      "author_display_name": "John Smith",
      "author_email": "jsmith@example.com",
      "created_at": "2020-12-14T17:51:10.316Z",
      "text": "this is a note on a property"
    },
    "relationships": {
      "resource": {
        "links": {
          "related": "https://reactor.adobe.io/properties/PR4537ac6f1f204ffd864ec47c4b27c2e8"
        },
        "data": {
          "id": "PR4537ac6f1f204ffd864ec47c4b27c2e8",
          "type": "properties"
        }
      }
    },
    "links": {
      "resource": "https://reactor.adobe.io/properties/PR4537ac6f1f204ffd864ec47c4b27c2e8",
      "self": "https://reactor.adobe.io/notes/NT550b7a17ab304d49ba289a2978d673e5"
    }
  }
}

Criar notas

AVISO

Antes de criar uma nova nota, lembre-se de que elas não são editáveis e a única maneira de excluí-las é excluir o recurso correspondente.

Você pode criar uma nova nota acrescentando /notes ao caminho de uma solicitação POST para o recurso em questão.

Formato da API

POST /{RESOURCE_TYPE}/{RESOURCE_ID}/notes
Parâmetro Descrição
RESOURCE_TYPE O tipo de recurso para o qual você está criando uma nota. Deve ser um dos seguintes valores:
  • data_elements
  • extensions
  • libraries
  • properties
  • rule_components
  • rules
RESOURCE_ID A id do recurso específico para o qual você deseja criar uma nota.

Solicitação

A solicitação a seguir cria uma nova nota para uma propriedade.

curl -X POST \
  https://reactor.adobe.io/properties/PRb25a704c0b7c4562835ccdf96d3afd31/notes \
  -H 'Authorization: Bearer {ACCESS_TOKEN}' \
  -H 'x-api-key: {API_KEY}' \
  -H 'x-gw-ims-org-id: {ORG_ID}' \
  -H 'Content-Type: application/json' \
  -d '{
        "data": {
          "type": "notes",
          "attributes": {
            "text": "this is a note on a property"
          }
        }
      }'
Propriedade Descrição
type (Obrigatório) O tipo de recurso que está sendo atualizado. Para esse endpoint, o valor deve ser notes.
attributes.text (Obrigatório) O texto que compõe a nota. Cada nota é limitada a 512 caracteres Unicode.

Resposta

Uma resposta bem-sucedida retorna os detalhes da nota recém-criada.

{
  "data": {
    "id": "NT550b7a17ab304d49ba289a2978d673e5",
    "type": "notes",
    "attributes": {
      "author_display_name": "John Smith",
      "author_email": "jsmith@example.com",
      "created_at": "2020-12-14T17:51:10.316Z",
      "text": "This is a note on a property"
    },
    "relationships": {
      "resource": {
        "links": {
          "related": "https://reactor.adobe.io/properties/PR4537ac6f1f204ffd864ec47c4b27c2e8"
        },
        "data": {
          "id": "PR4537ac6f1f204ffd864ec47c4b27c2e8",
          "type": "properties"
        }
      }
    },
    "links": {
      "resource": "https://reactor.adobe.io/properties/PR4537ac6f1f204ffd864ec47c4b27c2e8",
      "self": "https://reactor.adobe.io/notes/NT550b7a17ab304d49ba289a2978d673e5"
    }
  }
}

Nesta página