Definir um esquema para um serviço externo

Objetivos de aprendizagem

Após concluir esta unidade, você estará apto a:

  • Descrever o objetivo da definição de esquema.
  • Explicar os elementos de uma definição de esquema de Serviços externos com suporte.
  • Nomear três problemas que podem fazer com que seu esquema falhe.

Por que você precisa de uma definição de esquema?

Independentemente de você ser a pessoa que cria uma definição de esquema para seu registro dos Serviços externos ou não, é útil entender para que serve e como ela é usada. Já está familiarizado com a definição de um esquema de uma API baseada em REST? Vá em frente e pule para a próxima seção E... O que faz um esquema com suporte?

Lembra-se de nossos exemplos anteriores: o serviço Web de API externa baseada em REST de um aplicativo de folha de pagamento e um serviço de crédito? Embora tenhamos uma API de banco baseada em REST, ainda precisamos de um formato comum e padronizado para descrever a estrutura da API baseada em REST do nosso banco. É aqui que entra a definição de esquema de API. O Salesforce usa a especificação OpenAPI comumente adotada como o formato de descrição. 

Sua definição de esquema contém os tipos de entradas e saídas que você pode incluir nas chamadas, ou solicitações, que sua organização faz ao serviço Web externo. Por exemplo, suas chamadas podem incluir ID como entrada numérica ou nome como saída de texto.

Ela também contém as informações de ponto de extremidade e os parâmetros de autenticação para os serviços da web de API baseada em REST que você pode acessar. (Lembre-se de que o ponto de extremidade é simplesmente o que expõe os recursos de serviços da web com os quais os Serviços Externos precisam interagir.) Por exemplo, este esquema de um banco fictício inclui métodos para adicionar e excluir contas. https://th-external-services.herokuapp.com/accounts/schema

Nota

Em um aplicativo do mundo real, seguindo as melhores práticas de segurança, você incluiria uma etapa de autenticação antes de acessar a API de um banco!

Já que nossa definição de esquema representa dados estruturados que podem ser lidos por humanos, vamos vê-los juntos.
Aqui estão as operações de conta básicas do nosso esquema:

Operações para o caminho: /accounts/{accountName}
Descrição
GET
Recupera uma conta
POST
Adiciona uma conta
PUT
Atualiza uma conta
DELETE
Exclui uma conta

Veja um trecho de código da definição de esquema que contém informações sobre um método GET. Se você não sabe, um método GET simplesmente recupera informações de recursos de um serviço Web. Esse método GET em particular recupera informações sobre uma conta usando o caminho do recurso, neste caso, /accounts/{accountName}, em que {accountName} é uma conta especificada. Se você olhar em "parameters", poderá ver "name":"accountName". Esse parâmetro deve corresponder ao nome da conta que você especificou e é obrigatório ("required":true). Ele também deve assumir a forma de uma sequência de caracteres.


"paths": {
     "/accounts/{accountName}": {
       "get": {
         "operationId": "getAccount",
         "summary": "Retrieves an account",
         "description": "Retrieves the account with specific name",
         "consumes": ["text/plain"],
         "produces": ["application/json"],
         "parameters": [{
           "name": "accountName",
           "in": "path",
           "required": true,
           "type": "string",
           "description": "Name of the account"
        }],
         "responses": {
           "200": {
             "description": "The response when system finds an account with given name",
             "schema": {
               "$ref": "#/definitions/accountDetails"
            }
           },
           "400": {
             "description": "Error response if the account name parameter is
            less than minimum characters",
             "schema": {
               "$ref": "#/definitions/errorModel"
            }
           },
           "404": {
             "description": "Error response if the account is not supported by service or account is not found",
             "schema": {
               "$ref": "#/definitions/errorModel"
            }

É claro que o esquema é um pouco mais complexo que isso. Mas você pode ver que, embora seja projetado para consumo pelos Serviços externos, ele também pode ser lido por pessoas. Ele também é formatado de maneira lógica que permite que os Serviços externos processem os dados para possam emergir como ações invocáveis no fluxo. Essas ações de fluxo são o que mais tarde usaremos como entradas e saídas em um fluxo.

As próximas etapas são para registrar seu serviço Web de forma declarativa. Mas, primeiro, vamos abordar os elementos que compõem uma definição de esquema com suporte.

E...o que faz um esquema válido e com suporte?

Agora sabemos o que é um esquema ou, mais precisamente, uma definição de esquema. Mas o que queremos dizer com um esquema válido e com suporte? 

Há requisitos gerais de validação de esquema que a especificação OpenAPI define e há requisitos específicos de esquema de Serviços externos. Os Serviços externos podem dar suporte adequado ao seu esquema e chamar seu serviço Web quando esses dois critérios são atendidos.  

Uma introdução sobre validação de esquema

Embora um esquema possa ser lido por pessoas, ele também deve poder ser lido por máquina. Ele precisa seguir uma estrutura lógica para que os Serviços externos possam consumi-lo facilmente. Um esquema estruturado incorretamente significa que o serviço Web externo não pode se comunicar (retorna mensagens de erro e exceção) e, por fim, os Serviços externos não podem ingeri-lo. O atendimento a restrições estruturais, lógicas e de sintaxe é uma primeira aprovação necessária da validação de esquema. A especificação OpenAPI define essas regras gerais e remove as dúvidas em chamar um serviço Web externo.

Esquema de Serviços externos com suporte 

Além das diretrizes gerais do OpenAPI para validação de esquema, existem também limitações de esquema específicas aos Serviços externos. É melhor examinar esses requisitos antes de registrar seu esquema nos Serviços externos. Um esquema com suporte pelos Serviços externos significa que seu esquema é válido de acordo com a especificação OpenAPI e também atende aos requisitos de Serviços externos específicos.

Para uma lista de requisitos principais para criar um esquema suportado pelos Serviços externos, consulte a Ajuda do Salesforce: Considerações sobre Serviços externos aprimorados

Vamos nos aprofundar no que é um esquema com suporte. A próxima etapa deixa tudo montado. É uma peça básica, porém essencial, para que as ferramentas como o Flow Builder possam chamar serviços Web externos com êxito.

Nota

Se você usa a estrutura de código aberto OpenAPI, pode usar o Editor do Swagger para confirmar se seu esquema está em conformidade com a especificação OpenAPI. Se quiser fazer um pequeno desvio, copie o esquema em https://th-external-Services.herokuapp.com/accounts/Schema para o editor do Swagger. Você não deve receber nenhum erro.

Abordamos alguns conceitos sobre esquemas e também alguns requisitos. Quer se aprofundar e ver na prática os Serviços Externos? Claro que sim! Veremos isso na próxima unidade. No entanto, antes de prosseguir, vamos rever as duas primeiras etapas que discutimos na primeira unidade.

  1. Um provedor de serviços Web externos, como um banco, compartilha sua API baseada em REST: Recebemos estas informações de nosso banco fictício.
  2. Com base na especificação, o provedor de serviços da Web (como no nosso exemplo de serviço bancário), um desenvolvedor (ou até mesmo você) cria uma definição de esquema baseada em JSON que descreve a API: Embora não tenhamos criado esse esquema por conta própria, analisamos os elementos de um esquema e os requisitos para garantir que ele terá suporte. Quando você trabalha com serviços Web externos, você ou seu desenvolvedor podem definir o esquema que atende seu caso de uso.

Recursos

Continue a aprender de graça!
Inscreva-se em uma conta para continuar.
O que você ganha com isso?
  • Receba recomendações personalizadas para suas metas de carreira
  • Pratique suas habilidades com desafios práticos e testes
  • Monitore e compartilhe seu progresso com os empregadores
  • Conecte-se a orientação e oportunidades de carreira