Loading
Estender o Salesforce com cliques, não com código
Esquema do OpenAPI 2.0 de serviços externos

Você está aqui:

  1. Ajuda do Salesforce
  2. Documentação
  3. Estender o Salesforce com cliques, não com código

Esquema do OpenAPI 2.0 de serviços externos

Esta seção apresenta exemplos de esquema OpenAPI 2.0 de serviços externos.

Edições obrigatórias

Disponível em: Lightning Experience
Disponível em: Enterprise, Performance, Unlimited e Developer Editions

Exemplo 1: Especificação OpenAPI básica com solicitação e resposta (OAS 2.0)

Aqui está um exemplo de uma especificação de API que contém um esquema JSON compatível para OpenAPI 2.0. Os parâmetros (em negrito) contêm a definição para a entrada de accountId. As respostas (também em negrito) contêm as definições da saída, que é creditRating. Os parâmetros e respostas são traduzidos em entradas e saídas, respectivamente, para suas ações de fluxo.

{  
   "swagger":"2.0",
   "info":{  
      "description":"A service for checking credit for an account.",
      "version":"1.0.0",
      "title":"Credit Decision",
      "termsOfService":"http://swagger.io/terms/",
      "contact":{  
         "email":"apiteam@swagger.io"
      },
      "license":{  
         "name":"Apache 2.0",
         "url":"http://www.apache.org/licenses/LICENSE-2.0.html"
      }
   },
   "host":"<YourHostName>",
   "paths":{  
      "/account/lastCreditRating":{  
         "get":{  
            "summary":"Evaluates credit rating and decides what payment terms to offer.",
            "description":"",
            "consumes":[  
               "application/json",
               "application/xml"
            ],
            "produces":[  
               "application/xml",
               "application/json"
            ],
            "parameters":[{  
               "in":"body",
               "name":"body",
               "description":"Specifies input parameters to calculate payment term",
               "required":true,
               "schema":{  
                  "$ref":"#/definitions/accountId"
               }
            }],
            "responses":{  
               "200":{  
                  "description":"success",
                  "schema":{  
                     "$ref":"#/definitions/creditRating"
                  }
               },
               "405":{  
                  "description":"Invalid input"
               }
            }
         }
      }
   },
   "definitions":{  
      "accountId":{  
         "type":"object",
         "properties":{  
            "accountIdString":{  
               "type":"string"
            }
         },
         "xml":{  
            "name":"accountId"
         }
      },
      "creditRating":{  
         "type":"object",
         "properties":{  
            "creditRatingString":{  
               "type":"string"
            }
         },
         "xml":{  
            "name":"creditRating"
         }
      }
   }
}

Exemplo 2: Referência de esquema de objeto nomeado (OAS 2.0)

Configuração básica

  • Para a credencial nomeada que sua organização usa para acessar o sistema bancário, atribua o rótulo Bank e um URL de espaço reservado, como https://api.example.com. Use example.com porque você colará o esquema no horário de registro, em vez de usar um URL para apontar para uma especificação de API.
  • Registre o serviço externo do sistema bancário do funcionário. Use o nome Bank e a credencial nomeada Bank e copie e cole no esquema a seguir.
  • O serviço externo do sistema bancário mostra duas maneiras de definir parâmetros com tipos de objeto: um tipo de objeto nomeado sob um bloco de "definições" ou um tipo de objeto declarado de modo anônimo em linha.
    Nota
    Nota O nome do tipo de objeto do parâmetro definido ou derivado ou uma propriedade com tipo de objeto deve ter menos de 255 caracteres para ser usado no Apex ou no Flow Builder.

Aqui você encontra um esquema com o tipo de objeto nomeado definido sob o bloco "definições". O nome do tipo de objeto telefone é ExternalService__Bank_Phone no Apex ou no Flow Builder.

{
  "swagger": "2.0",
  "info": {
    "title": "bankService",
    "description": "API description in Markdown.",
    "version": "1.0.0"
  },
  "host": "api.example.com",
  "basePath": "/v1",
  "schemes": [
    "https"
  ],
  "definitions": {
    "User": {
      "properties": {
        "id": {
          "type": "integer"
        },
        "name": {
          "type": "string"
        },
        "phones":{
          "type":"array",
          "items":{
             "type": "object",
             "$ref": "#/definitions/Phone"
          }
        }
      }
    },
    "Phone":{
      "properties":{
        "typeofphone":{
          "type":"string"
        },
        "phone":{
          "type":"string"
        }
      }
    }
  },
  "paths": {
    "/users/{userId}": {
      "get": {
        "summary": "Returns a user by ID.",
        "parameters": [{
          "in": "path",
          "name": "userId",
          "required": true,
          "type": "integer"
        }],
        "responses": {
          "200": {
            "description": "OK",
            "schema": {
              "$ref": "#/definitions/User"
            }
          }
        }
      }
    },
    "/users": {
      "post": {
        "summary": "Creates a new user.",
        "parameters": [{
          "in": "body",
          "name": "user",
          "schema": {
            "$ref": "#/definitions/User"
          }
        }],
        "responses": {
          "200": {
            "description": "OK"
          }
        }
      }
    }
  }
}

Aqui está o mesmo esquema, mas formatado com YAML.

swagger: '2.0'
info:
  title: bankService
  description: API description in Markdown.
  version: 1.0.0
host: api.example.com
basePath: /v1
schemes:
  - https
definitions:
  User:
    properties:
      id:
        type: integer
      name:
        type: string
      phones:
        type: array
        items:
          type: object
          $ref: '#/definitions/Phone'
  Phone:
    properties:
      typeofphone:
        type: string
      phone:
        type: string
paths:
  /users/{userId}:
    get:
      summary: Returns a user by ID.
      parameters:
        - in: path
          name: userId
          required: true
          type: integer
      responses:
        '200':
          description: OK
          schema:
            $ref: '#/definitions/User'
  /users:
    post:
      summary: Creates a new user.
      parameters:
        - in: body
          name: user
          schema:
            $ref: '#/definitions/User'
      responses:
        '200':
          description: OK

Exemplo 3: Esquema de objeto anônimo aninhado (OAS 2.0)

Aqui você encontra uma especificação da API com um esquema JSON com tipos de objeto anônimos definidos em linha. O nome do tipo de objeto telefone derivado é ExternalService__Bank_getUsers_OUT_200_phones.

Nota
Nota Para tipos de objeto anônimos, o Salesforce deriva automaticamente os nomes do tipo de objeto com base no serviço externo, na operação pai, no parâmetro da operação, no objeto pai e no nome da propriedade do objeto. O nome derivado deve ter menos de 255 caracteres. Para obter mais informações, consulte "Nomes de classe do Apex de serviço externo e nomes de desenvolvedor" em Considerações sobre serviços externos.
{
  "swagger": "2.0",
  "info": {
    "title": "bankService",
    "description": "API description in Markdown.",
    "version": "1.0.0"
  },
  "host": "api.example.com",
  "basePath": "/v1",
  "schemes": [
    "https"
  ],
  "paths": {
    "/users/{userId}": {
      "get": {
        "summary": "Returns a user by ID.",
        "parameters": [{
          "in": "path",
          "name": "userId",
          "required": true,
          "type": "integer"
        }],
        "responses": {
          "200": {
            "description": "OK",
            "schema": {
              "type": "object",
              "properties": {
                "id": {
                  "type": "integer"
                },
                "name": {
                  "type": "string"
                },
                "phones": {
                  "type":"array",
                  "items": {
                    "type": "object",
                    "properties": {
                      "typeofphone": {
                        "type":"string"
                      },
                      "phone": {
                        "type":"string"
                      }
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/users": {
      "post": {
        "summary": "Creates a new user.",
        "parameters": [{
          "in": "body",
          "name": "user",
          "schema": {
          "type": "object",
            "properties": {
              "id": {
                "type": "integer"
              },
              "name": {
                "type": "string"
              },
              "phones": {
                "type":"array",
                "items": {
                  "type": "object",
                  "properties": {
                    "typeofphone": {
                      "type":"string"
                    },
                    "phone": {
                      "type":"string"
                    }
                  }
                }
              }
            }
          }
        }],
        "responses": {
          "200": {
            "description": "OK"
          }
        }
      }
    }
  }
}

Exemplo 4: Nome da classe de objeto do Apex (OAS 2.0)

Aqui está uma especificação de API registrada com o nome de serviço externo BankingAutomaticTellerMachine. No entanto, os nomes de objeto derivados não devem ter mais de 255 caracteres:

  • ExternalService__BankingAutomaticTellerMachine_VeryImportantCustomer_phone
  • ExternalService__BankingAutomaticTellerMachine_getBalanceAccountTypeChecking_OUT_200

Para usar o Apex ou o Flow Builder, é necessário reduzir o nome do esquema de serviço externo e o esquema (exibido no Exemplo 5).

Dica
Dica Se o nome do objeto derivado for maior que 255 caracteres, tente um dos métodos a seguir para resolver o problema.
  • Reduza o nome do serviço externo.
  • Se o objeto for declarado em linha sob um parâmetro de operação, reduza o nome de operação adicionando um operationId ao esquema.
  • Se o objeto for declarado em linha sob uma propriedade de objeto pai, reduza o nome do objeto pai no esquema.
  • Declare o objeto aninhado como um objeto de nível superior sob "definições" de esquema.
{
  "swagger": "2.0",
  ...
  "paths": {
    "/balance/account/{accountId}/type/checking": {
      "get": {
        "parameters": [{
          "in": "path",
          "name": "accountId",
          "required": true,
          "type": "integer"
        }],
        "responses": {
          "200": {
            "schema": {
              "type": "object",
              "properties": {
                "balance": {
                  "type": "integer"
                },
                "owner": {
                  "$ref": "#/definitions/VeryImportantCustomer"
                }
              }
            }
          }
        }
      }
    }
  },
  "definitions": {
    "VeryImportantCustomer": {
      "type": "object",
      "properties": {
        "name": {
          "type": "string"
        },
        "phone": {
          "type": "object",
          "properties": {
            "number": {
              "type": "string"
            }
          }
        }
      }
    }
  }
}

Exemplo 5: Reduzindo nomes de classe de objeto do Apex (OAS 2.0)

Aqui está um exemplo de especificação de API com um esquema que resulta em nomes abreviados. Ela está registrada com o nome abreviado BankAtm.

Reduza o nome do esquema de serviço externo para BankAtm, o nome do objeto do esquema para VIP e adicione operationId como getBalance:

  • ExternalService__BankAtm_VIP_phone
  • ExternalService__BankAtm_getBalance_200
{
  "swagger": "2.0",
  ...
  "paths": {
    "/balance/account/{accountId}/type/checking": {
      "get": {
        "operationId": "getBalance",
        "parameters": [{
          "in": "path",
          "name": "accountId",
          "required": true,
          "type": "integer"
        }],
        "responses": {
          "200": {
            "schema": {
              "type": "object",
              "properties": {
                "balance": {
                  "type": "integer"
                },
                "owner": {
                  "$ref": "#/definitions/VIP"
                }
              }
            }
          }
        }
      }
    }
  },
  "definitions": {
    "VIP": {
      "type": "object",
      "properties": {
        "name": {
          "type": "string"
        },
        "phone": {
          "type": "object",
          "properties": {
            "number": {
              "type": "string"
            }
          }
        }
      }
    }
  }
}

Exemplo 6: Matrizes em linha (OAS 2.0)

Aqui está um exemplo com uma definição de matriz em linha. 

{
  "swagger": "2.0",
  "host": "Employees.org",
  "basePath": "/",
  ...
  "paths": {
    "/employees/{employeeId}": {
      "get": {
        "operationId": "getEmployee",
        "parameters": [{
          "in": "path",
          "name": "employeeId",
          "required": true,
          "type": "string"
        }],
        "responses": {
          "200": {
            "schema": {
              "type": "object",
              "properties": {
                "employee": {"$ref": "#/definitions/Employee"},
                "manager": {"$ref": "#/definitions/Employee"},
                "team": {
                  "type": "array",
                  "items": {"$ref": "#/definitions/Employee"}
                }
              }
            }
          }
        }
      }
    }
  },
  "definitions": {
    "Employee" : {
      "type": "object",
        "properties": {
          "employeeId": {"type": "string"},
          "firstName": {"type": "string"},
          "middleName": {"type": "string"},
          "lastName": {"type": "string"},
          "dateOfHire": {"type": "date"}
        }
      }
    }
  }
}

Exemplo 7: Parâmetros de cabeçalho HTTP (OAS 2.0)

Veja como um parâmetro de cabeçalho é declarado em um esquema OpenAPI. No Apex ou no Fluxo, o nome "apiKey" aparece como um parâmetro de string. Agora, quando você define qualquer valor de string no Apex ou em um fluxo como apiKey, ele funciona como um parâmetro HTTP ao fazer uma solicitação de chamada.

{
  "swagger": "2.0",
  "info": {
    "description": "A service for checking credit for an account.",
    "version": "1.0.0",
    "title": "Credit Decision",
    "termsOfService": "http://swagger.io/terms/",
    "contact": {
      "email": "apiteam@swagger.io"
    },
    "license": {
      "name": "Apache 2.0",
      "url": "http://www.apache.org/licenses/LICENSE-2.0.html"
    }
  },
  "host": "<YourHostName>",
  "paths": {
    "/account/lastCreditRating": {
      "get": {
        "summary": "Evaluates credit rating and decides what payment terms to offer.",
        "description": "",
        "consumes": [
          "application/json",
          "application/xml"
        ],
        "produces": [
          "application/xml",
          "application/json"
        ],
        "parameters": [{
          "name": "body",
          "description": "Specifies input parameters to calculate payment term",
          "in": "body",
          "required": true,
          "schema": {
            "$ref": "#/definitions/accountId"
          }
        },{
          "name": "apiKey",
          "description": "Your API Key for calling the credit rating service",
          "in": "header",
          "type": "string"
        }],
        "responses": {
          "200": {
            "description": "success",
            "schema": {
              "$ref": "#/definitions/creditRating"
            }
          },
          "405": {
            "description": "Invalid input"
          }
        }
      }
    }
  },
  "definitions": {
    "accountId": {
      "type": "object",
      "properties": {
        "accountIdString": {
          "type": "string"
        }
      },
      "xml": {
        "name": "accountId"
      }
    },
    "creditRating": {
      "type": "object",
      "properties": {
        "creditRatingString": {
          "type": "string"
        }
      },
      "xml": {
        "name": "creditRating"
      }
    }
  }
}

Exemplo 8: Tipo de mídia de formulário codificado em URL (OAS 2.0)

Dados do formulário de resposta e solicitação são declarados em conjunto com as diretivas consumes e produces correspondentes.

{
  "swagger": "2.0",
  "info": {
    "description": "Apply here for your next mortgage",
    "version": "1.0.0",
    "title": "My Mortgage Buddy",
    "contact": {
      "email": "apiteam@swagger.io"
    }
  },
  "host": "MyMortgageBuddy.org",
  "basePath": "/mortgages",
  "paths": {
    "/apply": {
      "post": {
        "operationId": "applyMortgage",
        "consumes":  [
          "application/x-www-form-urlencoded; charset=utf-8"
        ],
        "produces":  [
          "application/x-www-form-urlencoded; charset=utf-8"
        ],
        "parameters": [{
          "description": "Desired mortgage terms",
          "name": "terms",
          "in":  "formData",
          "type": "array",
          "items": {
            "type": "integer"
          },
          "collectionFormat": "multi",
          "required": true
        },{
          "description": "Full Name",
          "name": "fullName",
          "in":  "formData",
          "type": "string",
          "required": true
        },{
          "description": "Loan amount",
          "name": "loanAmount",
          "in":  "formData",
          "type": "number",
          "required": true
        }],
        "responses": {
          "200": {
            "description": "200",
            "schema": {
              "type": "object",
              "properties": {
                "formApplicationId": {
                  "type": "string"
                },
                "loanOfficerFullName": {
                  "type": "string"
                }
              }
            }
          }
        }
      }
    }
  }
}

Exemplo 9: Diretivas de esquema allOf e additionalProperties (OAS 2.0)

Esta definição de esquema JSON destaca os constructos allOf para composição do objeto do esquema e additionalProperties para valores de dicionário. O esquema de amostra é registrado como serviço externo MyBank com a credencial nomeada MyBank. O registro é invocado por um fluxo de amostra que acessa as propriedades de dicionário com uma ação invocável do Apex. Um teste de unidade do Apex de fluxo vincula tudo.

O esquema define um serviço bancário que obtém detalhes do cliente para um ID do cliente.

  • O objeto de esquema Customer tem propriedades de dicionário do tipo objeto de esquema CreditRating. No Apex, a classe ExternalService.MyBank_Customer tem a propriedade properties do tipo Map<String, ExternalService_CreditRating> com as classificações de crédito do cliente.
  • Telefones e emails são compostos por suas próprias propriedades em conjunto com as propriedades comuns allOf do objeto de esquema Contact.
{
  "swagger": "2.0",

  "info": {
    "title": "myBank",
    "description": "Sample Banking Service with allOf and additionalProperties schema constructs",
    "version": "1.0.0"
  },

  "host": "api.mybank.com",
  "basePath": "/v1",
  "schemes": [
    "https"
  ],

  "definitions": {
    "Customer": {
      "type": "object",
      "properties": {
        "id": {
          "type": "integer"
        },
        "name": {
          "type": "string"
        },
        "phones": {
          "type":"array",
          "items": {
            "$ref": "#/definitions/Phone"
          }
        },
        "emails": {
          "type": "array",
          "items": {
            "$ref": "#/definitions/Email"
          }
        }
      },
      "additionalProperties": {
        "$ref": "#/definitions/CreditRating"
      },
      "required": [
        "id",
        "name"
      ]
    },

    "Contact": {
      "type": "object",
      "properties": {
        "primary": {
          "type": "boolean"
        },
        "timeOfDay": {
          "type": "string"
        }
      },
      "required": [
        "primary"
      ]
    },
    "Phone": {
      "allOf": [
        {
          "$ref": "#/definitions/Contact"
        },
        {
          "type": "object",
          "properties": {
            "typeOfPhone": {
              "type":"string"
            },
            "phoneNumber":{
              "type":"string"
            }
          }
        }
      ]
    },
    "Email": {
      "allOf": [
        {
          "$ref": "#/definitions/Contact"
        },
        {
          "type": "object",
          "properties": {
            "email": {
              "type":"string"
            }
          }
        }
      ]
    },

    "CreditRating": {
      "type": "object",
      "properties": {
        "rating": {
          "type": "string"
        },
        "score": {
          "type": "number",
          "format": "double"
        }
      }
    }
  },

  "paths": {
    "/customers/{customerId}": {
      "get": {
        "summary": "Get the customer by ID.",
        "parameters": [{
          "in": "path",
          "name": "customerId",
          "required": true,
          "type": "integer"
        }],
        "responses": {
          "200": {
            "description": "OK",
            "schema": {
              "$ref": "#/definitions/Customer"
            }
          }
        }
      }
    }
  }
}

Para usar a composição allOf e additionalProperties, consulte Para Exemplos 9: uso de allOf Composition e additionalProperties no Fluxo com testes de unidade do Apex.

Exemplo 10: Diretivas allOf e Discriminator (OAS 2.0)

Para especificar uma lista extensível geral de contatos para um cliente, a diretiva discriminator pode ser combinada com allOf para declarar se um contato é um email ou um número de telefone:

{
  "swagger": "2.0",

  "info": {
    "title": "myBank",
    "description": "Sample Banking Service with allOf and discriminator",
    "version": "1.0.0"
  },
  "host": "api.mybank.com",
  "basePath": "/v1",
  "schemes": [
    "https"
  ],
  "definitions": {
    "Customer": {
      "type": "object",
      "properties": {
        "id": {
          "type": "integer"
        },
        "name": {
          "type": "string"
        },
        "contacts": {
          "type":"array",
          "items": {
            "$ref": "#/definitions/Contact"
          }
        }
      },
      "required": [
        "id",
        "name"
      ]
    },

    "Contact": {
      "type": "object",
      "discriminator": "contactType",
      "properties": {
        "contactType": {
          "type": "string"
        },
        "primary": {
          "type": "boolean"
        },
        "timeOfDay": {
          "type": "string"
        }
      },
      "required": [
        "contactType",
        "primary"
      ]
    },
    "Phone": {
      "allOf": [
        {
          "$ref": "#/definitions/Contact"
        },
        {
          "type": "object",
          "properties": {
            "typeOfPhone": {
              "type":"string"
            },
            "phoneNumber":{
              "type":"string"
            }
          }
        }
      ]
    },
    "Email": {
      "allOf": [
        {
          "$ref": "#/definitions/Contact"
        },
        {
          "type": "object",
          "properties": {
            "email": {
              "type":"string"
            }
          }
        }
      ]
    }
  },

  "paths": {
    "/customers/{customerId}": {
      "get": {
        "summary": "Get the customer by ID.",
        "parameters": [{
          "in": "path",
          "name": "customerId",
          "required": true,
          "type": "integer"
        }],
        "responses": {
          "200": {
            "description": "OK",
            "schema": {
              "$ref": "#/definitions/Customer"
            }
          }
        }
      }
    }
  }
}

Para usar a composição e as estruturas de esquema OpenAPI polimórficos, consulte Para exemplos 10: Polimorfismo com allOf e Discriminator.

Definição de matriz (OAS 2.0)

Os Serviços externos são compatíveis com definições de matriz em linha e matrizes nomeadas referenciaáveis. Os tipos de lista em Serviços externos são identificados pelo tipo de elemento de objeto.

Definição de matriz em linha com suporte com referência à definição de itens de matriz

{
    "swagger": "2.0",
    ...
       "name": "myObjects",
       "in": "body",
       "schema": {
           "type": "array",
           "items": {
               "$ref": "#definitions/MyObject"
           }
       }
    ...
    "definitions": {
        "MyObject": {
            "type": "object",
            "properties": {...}
        }
    }
}

No Apex e no Flow Builder, declare uma variável para o parâmetro myObjects marcando a variável como uma coleção e escolhendo seu tipo de elemento do Apex ExternalService__RegistrationName_MyObject.

Definição de matriz em linha com a definição de itens de matriz em linha

{
    "swagger": "2.0",
    ...
       "name": "myObjects",
       "in": "body",
       "schema": {
           "type": "array",
           "items": {
               "type": "object",
               "properties": {...}
           }
       }
    ...
    "definitions": {
        ...
    }
}

No Apex e no Flow Builder, declare uma variável de coleção para o parâmetro myObjects e o tipo de elemento do Apex ExternalService__RegistrationName_OperationName_IN_myObjects.

Definição de matriz referenciável com referência às definições do item da matriz

{
    "swagger": "2.0",
    ...
       "name": "myObjects",
       "in": "body",
       "schema": {
           "$ref": "#definitions/MyObjectList"
       }
    ...
    "definitions": {
        "MyObjectList": {
            "type": "array",
            "items": {
                 "$ref": "#definitions/MyObject"
            }
        }
        "MyObject": {
            "type": "object",
            "properties": {...}
        }
    }
}

No Apex e no Flow Builder, declare uma variável de coleção para o parâmetro myObjects e o tipo de elemento do Apex ExternalService__RegistrationName_MyObject.

Definição de matriz referenciável com a definição de itens de matriz em linha

{
    "swagger": "2.0",
    ...
       "name": "myObjects",
       "in": "body",
       "schema": {
           "$ref": "#definitions/MyObjectList"
       }
    ...
    "definitions": {
        "MyObjectList": {
            "type": "array",
            "items": {
                "type": "object",
                "properties": {...}
            }
        }
    }
}

No Apex e no Flow Builder, declare uma variável de coleção para o parâmetro myObjects e o tipo de elemento do Apex ExternalService__RegistrationName_MyObjectList.

Consulte também:

 
Carregando
Salesforce Help | Article