Nota
O acesso a esta página requer autorização. Pode tentar iniciar sessão ou alterar os diretórios.
O acesso a esta página requer autorização. Pode tentar alterar os diretórios.
Conectores personalizados para Microsoft Copilot Studio, Aplicativos Lógicos Microsoft Power Automate do Azure ou Microsoft Power Apps devem fornecer um arquivo de OpenAPI especificação. Esta especificação OpenAPI define pontos de entrada individuais, que são chamados operações. Cada operação tem um único operationId e um único e urlPath uma HttpVerb combinação.
{
"/items": {
"get": {
"summary": "Get rows",
"description": "This operation gets a list of items.",
"operationId": "GetItems"
},
"post": {
"summary": "Insert row",
"description": "This operation inserts an item.",
"operationId": "PostItem"
}
}
}
Estas operações podem crescer e sofrer alterações ao longo do tempo, à medida que são adicionadas funcionalidades ou que estas se expandem. Algumas alterações são meros acrescentos e não quebram necessariamente o contrato que existe entre os clientes e os servidores. Esta categoria inclui adicionar parâmetros novos, devolver mais dados ou permitir entradas mais flexíveis.
No entanto, há muitas alterações que podem efetivamente quebrar o contrato descrito na especificação OpenAPI. Esta categoria de "alterações interruptivas" inclui remover parâmetros, deixar de suportar determinadas entradas ou mudar o significado e o comportamento de uma entrada ou saída ou da própria operação.
Para desenvolver uma API em segurança, é importante seguir um padrão que os clientes consigam navegar. Cabe à API manter a retrocompatibilidade, comunicar a intenção e delinear atributos de versão. É da responsabilidade do cliente mostrar ou ocultar as operações preteridas, expiradas ou que possam ter versões novas disponíveis. Dessa forma, as operações podem crescer e desenvolver-se ao longo do tempo sem provocar fragilidades indevidas nas aplicações que dependem das mesmas.
Anotação de API
OpenAPI não tem suporte intrínseco para controlo de versão operacional. Para atingir nosso objetivo, grande parte do trabalho é feito através do x-ms-api-annotation objeto, que é aplicado tanto no escopo global quanto no escopo da operação. O objeto global contém propriedades que se aplicam à API como um todo:
{
"x-ms-api-annotation": {
"status": "Preview"
}
}
| Propriedade | Valores | Predefinido | Description |
|---|---|---|---|
| Situação |
"Preview"
"Production"
|
"Preview" |
Status da API como um todo — começando em Visualização e escalando para Produção conforme o uso e a estabilidade ditarem |
No âmbito operacional, este objeto contém propriedades mais detalhadas. Também existem propriedades adicionais fora do objeto que se aplicam e participam no processo de desenvolvimento de versões:
{
"deprecated": true,
"x-ms-api-annotation": {
"status": "Production",
"family": "MyOperation",
"revision": 2
}
}
| Propriedade | Valores | Predefinição | Descrição |
|---|---|---|---|
| preterido |
null
false
true
|
false |
Indica se a operação foi preterida |
| x-ms-visibilidade |
null
""
"Important"
"Advanced"
"Internal"
|
"" |
Visibilidade e proeminência pretendidas desta operação, onde null ou "" implica um estado Normal |
| Situação |
"Preview"
"Production"
|
"Production" |
Status da operação — isso pode diferir do estado da própria API, mas se não for especificado herdará do estatuto da API de nível superior |
| Família | {nome comum da operação} | operationName | O nome que se aplica a todas as revisões desta operação |
| revisão | numérico (1,2,3...) | 1 |
A revisão da família operacional especificada |
| expira | Data do ISO8601 | (nenhum) | Sugestão opcional para o cliente para indicar o fim projetado do suporte |
Preterido pode ser definido como true quando não for mais desejável para os clientes usar essa operação. Esta propriedade existe na especificação Campos Fixos OpenAPI .
A visibilidade é um indicador da proeminência relativa pretendida da operação. Uma "Important" visibilidade indica que a operação deve estar no topo da lista, exibida em destaque. Uma visibilidade normal (indicada por null ou cadeia de caracteres "" vazia) é o padrão, e significa que a operação aparecerá na lista, provavelmente após as operações Importantes. Uma "Advanced" visibilidade indica que a operação pode estar na parte inferior da lista ou até mesmo escondida inicialmente atrás de um controle expando. As operações avançadas podem ser de utilização mais difícil, menos populares ou ter uma aplicação mais restrita. Uma "Internal" visibilidade indica que a operação não deve ser exposta aos usuários e só deve ser usada internamente. As operações internas são programaticamente úteis e importantes, mas não se destinam a ser utilizadas pelos utilizadores finais. Também podem ser marcadas como tal para que sejam ocultadas de qualquer tipo de IU durante o processo de preterição sem as remover efetivamente da API, o que originaria uma alteração interruptiva.
Status indica a estabilidade da API ou operação.
"Preview" indica que a operação ou API é nova e potencialmente não comprovada. A pré-visualização é um indicador de que os sistemas de produção devem ser reservados no que diz respeito a presumir dependências. Uma vez que a operação ou API tenha se tornado mais estabelecida e provado que atende aos padrões de fiabilidade, taxa de sucesso e escalabilidade, ela pode ser intencionalmente atualizada para "Production" estatuto.
Os seguintes requisitos métricos geralmente se aplicam às operações que buscam "Production" estatuto:
- Taxa de sucesso de 80% por um período de três semanas
- definida como percentagem dos códigos de resposta HTTP no intervalo 2xx
- 99,9% de fiabilidade sustentada por um período de três semanas
- definida como percentagem dos códigos de resposta HTTP no intervalo não 5xx (502, 504 e 520 estão excluídos deste cálculo)
Família indica a relação entre operações que são conceitualmente a mesma operação, mas são revisões diferentes com mudanças potencialmente revolucionárias entre elas. Várias operações partilharão o mesmo nome de família caso devam ser consideradas revisões umas das outras e são ordenadas pelos números de revisão exclusivos.
A revisão indica a ordem evolutiva da operação dentro da família de operações. Cada operação numa família terá uma revisão que é um índice integral que pressupõe sequência. Uma revisão vazia será considerada como revisão 1. Quando estiverem disponíveis revisões mais recentes de uma operação, os clientes devem apresentá-las de forma mais proeminente e recomendá-las mais intencionalmente, mas, ainda assim, permitir que sejam selecionadas revisões potencialmente mais antigas que ainda não tenham sido preteridas.
Expira é opcional e indica um potencial prazo de fim de vida em que o suporte para a operação não está mais garantido. Só deve ser definido para operações preteridas e, atualmente, não está refletido em nenhuma interface.
Tempo de Vida Operacional
As operações têm um tempo de vida previsível que pode ser mostrado por exemplo.
Ponto de Início
De início, as operações podem não necessariamente indicar nada sobre as revisões. Essas operações têm padrões aplicados e, portanto, são consideradas como revisão 1 em um nome de família equivalente ao operationId.
{
"/{list}/items": {
"get": {
"summary": "Get rows",
"description": "This operation gets a list of items.",
"operationId": "GetItems"
}
}
}
Isto é equivalente à definição mais explícita:
{
"/{list}/items": {
"get": {
"summary": "Get rows",
"description": "This operation gets a list of items.",
"operationId": "GetItems",
"deprecated": false,
"x-ms-api-annotation": {
"status": "Production",
"family": "GetItems",
"revision": 1
}
}
}
}
Início da Operação
A maioria das evoluções das APIs constituem o acrescento de uma operação. Por exemplo, novos métodos e novas revisões de métodos já existentes. Para iniciar uma revisão nova em segurança, pode ajustar a especificação OpenAPI da seguinte forma:
{
"/{list}/items": {
"get": {
"summary": "Get rows (V1 - downplayed)",
"description": "This operation gets a list of items.",
"operationId": "GetItems",
"deprecated": false,
"x-ms-visibility": "advanced",
"x-ms-api-annotation": {
"status": "Production",
"family": "GetItems",
"revision": 1
}
}
}
"/v2/{list}/items": {
"get": {
"summary": "Get rows (V2 - new hotness)",
"description": "This operation gets a list of items.",
"operationId": "GetItems_V2",
"deprecated": false,
"x-ms-api-annotation": {
"status": "Preview",
"family": "GetItems",
"revision": 2
}
}
}
}
Importante
Observe que GetItems V2 tem um exclusivo operationId e está inicialmente listado no estatuto de visualização.
Repare também que, agora, a visibilidade de GetItems V1 é avançada, pelo que não é apresentado com tanta proeminência.
Preterição da Operação
Por vezes, os pontos de entrada V1 já existentes permanecem indefinidamente caso continuem a gerar valor e não houver nenhum motivo convincente para os terminar. No entanto, muitos pontos de entrada V2 substituem intencionalmente o ponto de entrada V1. Para o fazer em segurança, todo o tráfego deve atingir zero nominal na operação original. Quando a telemetria confirmar esta circunstância, pode ser feita a seguinte alteração:
{
"/{list}/items": {
"get": {
"summary": "Get rows (deprecated)",
"description": "This operation gets a list of items.",
"operationId": "GetItems",
"deprecated": true,
"x-ms-api-annotation": {
"status": "Production",
"family": "GetItems",
"revision": 1
}
}
}
"/v2/{list}/items": {
"get": {
"summary": "Get rows",
"description": "This operation gets a list of items.",
"operationId": "GetItems_V2",
"deprecated": false,
"x-ms-api-annotation": {
"status": "Production",
"family": "GetItems",
"revision": 2
}
}
}
}
Importante
Repare que GetItems V1 está agora marcado como preterido. Esta é a transição final para preterir operações. GetItems V2 substituiu agora completamente GetItems V1.
Porquê dar-se ao trabalho?
Há muitos motivos para aderir ao controlo de versões operacionais. Em primeiro lugar, é uma forma de garantir que os clientes como o Azure Logic Apps e o Power Automate continuam a funcionar corretamente quando os utilizadores integram operações de conectores nos respetivos fluxos de dados. O controlo de versões deve ser aplicado às operações com o método anterior sempre que:
- É adicionada uma revisão nova de uma operação
- Uma operação já existente adiciona ou remove parâmetros
- Uma operação já existente altera a entrada ou a saída de forma significativa
Estritamente falando
Pode haver casos em que você pode escapar sem controle de versão, mas você deve ter cuidado ao fazer isso e fazer muitos testes para garantir que você não tenha negligenciado casos de borda em que os usuários podem ser quebrados inesperadamente. Segue-se a lista resumida de precauções a ter se optar por não o utilizar:
É adicionada uma operação nova.
Isto não interromperá especificamente os clientes existentes.
É adicionado um novo parâmetro opcional a uma operação existente.
Isto não interromperá as chamadas existentes, mas deve ser considerado cuidadosamente.
O comportamento de uma operação existente muda subtilmente.
Esta situação pode danificar os chamadores existentes dependendo da natureza da alteração e naquilo de que os utilizadores dependem. e é a mas precária de todas as situações, pois uma diferença significativa na aceitação de entradas, na geração de saídas, no timing ou no processamento poderá afetar o comportamento da operação de formas que tornam difícil determinar o risco da alteração.
É sempre recomendável errar, por questões de cuidado, e iterar uma revisão sempre que fizer alterações não triviais às APIs.
Enviar comentários
Apreciamos os comentários sobre problemas com a nossa plataforma de conectores ou novas ideias de funcionalidades. Para fornecer comentários, vá para Enviar problemas ou obter ajuda com conectores e selecione seu tipo de feedback.