Özel bağlantı için OpenAPI tanımını genişletme

Makale
09/27/2021
Okumak için 10 dakika

Azure Logic Apps, Microsoft Power Automate ya da Microsoft Power Apps’e yönelik özel bağlayıcı oluşturmanın bir yolu, API’nizin işlemlerini ve parametrelerini açıklayan, dilden bağımsız ve makine tarafından okunabilir bir belge olan bir OpenAPI tanım dosyası sağlamaktır. OpenAPI’nin kullanıma hazır işlevselliğinin yanı sıra, Logic Apps ve Power Automate için özel bağlayıcılar oluştururken bu OpenAPI uzantılarını da ekleyebilirsiniz:

summary
x-ms-summary
description
x-ms-visibility
x-ms-api-annotation
x-ms-operation-context
x-ms-capabilities
x-ms-trigger
x-ms-trigger-hint
x-ms-notification-content
x-ms-notification-url
x-ms-url-encoding
x-ms-dynamic-values and x-ms-dynamic-list
x-ms-dynamic-schema and x-ms-dynamic-properties

Bu uzantılar hakkında daha fazla ayrıntıyı aşağıda bulabilirsiniz:

Özet

Eylem (işlem) için başlığı belirtir.
Uygulandığı öğe: İşlemler
Önerilen: summary için tümce olay setini kullanın.
Örnek: "Takvime bir olay eklendiğinde" veya "E-posta gönder"

her işlem için "özet"

"actions" {
  "Send_an_email": {
    /// Other action properties here...
    "summary": "Send an email",
    /// Other action properties here...
  }
},

x-ms-summary

Bir varlığın başlığını belirtir.
Uygulandığı öğe: Parametreler, Yanıt Şeması
Önerilen: x-ms-summary için ilk harfler büyük stilini kullanın.
Örnek: "Takvim Kimliği", "Konu", "Olay Açıklaması" vb.

her varlık için "x-ms-summary"

"actions" {
    "Send_an_email": {
        /// Other action properties here...
        "parameters": [{
            /// Other parameters here...
            "x-ms-summary": "Subject",
            /// Other parameters here...
        }]
    }
},

açıklama

İşlemin işlevleri veya varlığın biçimiyle işlevi hakkında ayrıntılı bir açıklama belirtir.
Uygulandığı öğe: İşlemler, Parametreler, Yanıt Şeması
Önerilen: description için tümce olay setini kullanın.
Örnek: "Bu işlem takvime yeni bir etkinlik eklendiğinde tetiklenir", "E-postanın konusunu belirtin." vb.

her işlem veya varlık için "description"

"actions" {
    "Send_an_email": {
        "description": "Specify the subject of the mail",
        /// Other action properties here...
    }
},

x-ms-visibility

Varlığın kullanıcıya sunulacak görünürlüğünü belirtir.
Olası değerler: important, advanced ve internal
Uygulandığı öğe: İşlemler, Parametreler, Şemalar

important işlemleri ve parametreleri her zaman önce kullanıcıya gösterilir.
advanced işlemleri ve parametreleri ek bir menü altında gizlenir.
internal işlemleri ve parametreleri kullanıcıdan gizlenir.

Not

internal ve required olan parametreler için, bu parametrelerin varsayılan değerini sağlamanız gerekir.

Örnek: Daha fazla menüsü ve Gelişmiş seçenekleri göster menüsü advanced işlemleri ve parametrelerini gizler.

işlem ve parametreleri göstermek veya gizlemek için "x-ms-visibility"

"actions" {
    "Send_an_email": {
        /// Other action properties here...
        "parameters": [{
            "name": "Subject",
            "type": "string",
            "description": "Specify the subject of the mail",
            "x-ms-summary": "Subject",
            "x-ms-visibility": "important",
            /// Other parameter properties here...
        }]
        /// Other action properties here...
    }
},

x-ms-api-annotation

İşlemin sürümünü oluşturmak ve yaşam döngüsü yönetimi için kullanılır.
Uygulandığı öğe: İşlem

family—İşlem ailesi klasörünü belirten bir dize.
revision—Düzeltme numarasını belirten bir int.
replacement—Değiştirme API’sı bilgilerini ve işlemlerini içeren bir nesne.

"x-ms-api-annotation": {
        "family": "ListFolder",
        "revision": 1,
        "replacement": {
          "api": "SftpWithSsh",
          "operationId": "ListFolder"
        }
      }

x-ms-operation-context

Tetikleyiciye bağımlı bir akışın test edilmesini sağlamak üzere bir tetikleyicinin harekete geçmesinin benzetimini yapmak için kullanılır.
Uygulandığı öğe: İşlem

"x-ms-operation-context": {
        "simulate": {
          "operationId": "GetItems_V2",
          "parameters": {
            "$top": 1
          }
        }

x-ms-capabilities

Bağlayıcı düzeyinde bu, belirli işlemler de dahil olmak üzere bağlayıcı tarafından sunulan olanaklara yönelik bir genel bakıştır.
Şuna uygulanır: Bağlayıcı

"x-ms-capabilities": {
  "testConnection": {
    "operationId": "GetCurrentUser"
  },
}

İşlem düzeyinde bu, işlemin karşıya yüklemeyi öbeklemeyi ve/veya statik öbek boyutunu desteklediğini belirtmek için kullanılır ve kullanıcı tarafından sağlanabilir.
Uygulandığı öğe: İşlem

chunkTransfer—Öbek aktarımının desteklenip desteklenmediğini belirten bir boole değeri.

"x-ms-capabilities": {
  "chunkTransfer": true
}

x-ms-trigger

Geçerli işlemin tek bir olay üreten bir tetikleyici olup olmadığını belirtir. Bu alanın olmaması, bunun bir Action işlemi olduğunu gösterir.
Uygulandığı öğe: İşlem

single—Nesne yanıtı
batch—Dizi yanıtı

"x-ms-trigger": "batch"

x-ms-trigger-hint

Bir tetikleme işlemi için bir olayın nasıl tetikleneceği hakkında açıklama.
Uygulandığı öğe: İşlem

"x-ms-trigger-hint": "To see it work, add a task in Outlook."

x-ms-notification-content

Web kancası bildirim isteğinin şema tanımını içerir. Bu, dış hizmetler tarafından bildirim URL’sine gönderilen bir web kancası yükünün şemasıdır.
Uygulandığı öğe: İşlem

"x-ms-notification-content": {
      "schema": {
        "$ref": "#/definitions/WebhookPayload"
      }
    },

x-ms-notification-url

Web kancası kayıt işlemi için bu parametreye/alana bir web kancası bildirim URL’si yerleştirilmesi gerekip gerekmediğini bir boole değeri olarak belirtir.
Uygulama hedefi: parametre/giriş alanı

"x-ms-notification-url": true

x-ms-url-encoding

Geçerli yol parametresinin çift URL kodlamalı double veya tek URL kodlamalı single olması gerektiğini belirtir. Bu alanın olmaması, single kodlaması olduğu anlamına gelir.
Uygulandığı öğe: Yol Parametresi

"x-ms-url-encoding": "double"

Dinamik değerler kullan

Dinamik değerler, kullanıcıya bir operasyonun giriş parametrelerini seçme seçeneklerinin bir listesidir. 

Uygulandığı öğe: Parametreler 

Listeleri göstermek için dynamic-values

Dinamik değerleri kullanma

Not

Yol dizesi, baştaki eğik çizgiyi içermeyen bir JSON işaretçisidir. Bu nedenle, bu bir JSON işaretçisi: /property/childProperty ve bu bir yol dizesidir: Property/childproperty.

Dinamik değerleri tanımlamanın iki yolu vardır:

x-ms-dynamic-values kullanma

Ad	Gerekli	Açıklama
operationId	Evet	Değerleri döndüren işlem.
Parametreler	Evet	Bir dynamic-values işlemini çağırmak için gereken giriş parametrelerini belirten nesne.
value-collection	Hayır	Yanıt yükünde nesne dizisini değerlendiren yol dizesi. Value-collection belirtilmediyse, yanıt bir dizi olarak değerlendirilir.
value-title	Hayır	Value-collection içinde değer açıklamasına başvuran nesnenin yol dizesi.
value-path	Hayır	Value-collection içinde parametre değerine başvuran nesnenin yol dizesi.

"x-ms-dynamic-values": {
    "operationId": "PopulateDropdown",
    "value-path": "name",
    "value-title": "properties/displayName",
    "value-collection": "value",
    "parameters": {
        "staticParameter": "<value>",
        "dynamicParameter": {
            "parameter": "<name of the parameter to be referenced>"
        }
    }
}

Not

Dinamik değerleri kullanırken belirsiz parametre başvuruları olabilir. Örneğin, aşağıdaki bir işlemin tanımında, dinamik değerler, parametre kimliğine veya requestbody/ID özelliğine başvuruda bulunsa net değilse, tanımı belirsiz olan alan kimliğine başvurur.

{
    "summary": "Tests dynamic values with ambiguous references",
    "description": "Tests dynamic values with ambiguous references.",
    "operationId": "TestDynamicValuesWithAmbiguousReferences",
    "parameters": [{
        "name": "id",
        "in": "path",
        "description": "The request id.",
        "required": true
    }, {
        "name": "requestBody",
        "in": "body",
        "description": "query text.",
        "required": true,
        "schema": {
            "description": "Input body to execute the request",
            "type": "object",
            "properties": {
                "id": {
                    "description": "The request Id",
                    "type": "string"
                },
                "model": {
                    "description": "The model",
                    "type": "string",
                    "x-ms-dynamic-values": {
                        "operationId": "GetSupportedModels",
                        "value-path": "name",
                        "value-title": "properties/displayName",
                        "value-collection": "value",
                        "parameters": {
                            "requestId": {
                                "parameter": "id"
                            }
                        }
                    }
                }
            }
        }
    }],
    "responses": {
        "200": {
            "description": "OK",
            "schema": {
                "type": "object"
            }
        },
        "default": {
            "description": "Operation Failed."
        }
    }
}

x-ms-dynamic-list

Parametrelere belirsiz şekilde başvurmanın bir yolu yoktur. Bu özellik gelecekte sağlanıyor olabilir. İşleminizin yeni güncelleştirmelerden faydalanmasını istiyorsanız x-ms-dynamic-values ile birlikte yeni x-ms-dynamic-list uzantısını ekleyin. Ayrıca dinamik uzantınız parametrelerde bulunan özelliklere başvuruyorsa x-ms-dynamic-values ile birlikte yeni x-ms-dynamic-list uzantısını eklemeniz gerekir. Özelliklere işaret eden parametre başvuruları yol dizeleri olarak ifade edilmesi gerekir.

parameters—Bu özellik, dinamik işlemin çağrılan her giriş özelliğinin bir statik değer alanı veya kaynak işlemin özelliğine yapılan dinamik bir başvuru ile tanımlandığı bir nesnedir. Bu seçeneklerin her ikisi de aşağıda tanımlanmıştır.
value—Giriş parametresi için kullanılacak sabit değer budur. Örneğin, version adındaki GetDynamicList işleminin giriş parametresi, aşağıdaki örnekte 2.0 statik değeriyle tanımlanmıştır.
```
{
    "operationId": "GetDynamicList",
    "parameters": {
      "version": {
        "value": "2.0"
      }
    }
}
```

parameterReference—Bu, parametre adından başlayan, başvurulacak özelliğin yol dizesinin takip ettiği tam parametre başvuru adıdır. Örneğin, destinationInputParam1 parametresinin altındaki Property1 adlı getdynamiclist öğesinin giriş özelliği, kaynak işlemin sourceInputParam1 altında Property1 adlı bir özelliğe dinamik başvuru olarak tanımlanır.

{
    "operationId": "GetDynamicList",
      "parameters": {
          "destinationInputParam1/property1": {
            "parameterReference": "sourceInputParam1/property1"
    }
  }
}

Not

Varsayılan bir değer ile dahili olarak işaretlenmiş herhangi bir özelliğe başvurmak istiyorsanız, varsayılan değeri parameterReference öğesi yerine buradaki tanımda statik değer olarak kullanmanız gerekir. parameterReference kullanılarak tanımlanırsa listedeki varsayılan değer kullanılmaz.

Ad	Gerekli	Açıklama
operationId	Evet	Listeyi döndüren işlem.
Parametreler	Evet	Bir dinamik liste işlemini çağırmak için gereken giriş parametrelerini belirten nesne.
itemsPath	Hayır	Yanıt yükünde nesne dizisini değerlendiren yol dizesi.  `itemsPath`  verilmezse yanıt bir dizi olarak değerlendirilir.
itemTitlePath	Hayır	`itemsPath`  içinde değerin açıklamasına başvuran nesnenin yol dizesi.
itemValuePath	Hayır	Öğenin değerine başvuran  `itemsPath`  içindeki nesnede yer alan yol dizesi.

x-ms-dynamic-list ile başvurduğunuz özelliğin yol dizesiyle parametre başvurularını kullanın. Bu parametre başvurularını hem anahtar hem de dinamik işlem parametresi başvurusunun değeri için kullanın.

{
  "summary": "Tests dynamic values with ambiguous references",
  "description": "Tests dynamic values with ambiguous references.",
  "operationId": "TestDynamicListWithAmbiguousReferences",
  "parameters": [
    {
      "name": "id",
      "in": "path",
      "description": "The request id.",
      "required": true
    },
    {
      "name": "requestBody",
      "in": "body",
      "description": "query text.",
      "required": true,
      "schema": {
        "description": "Input body to execute the request",
        "type": "object",
        "properties": {
          "id": {
            "description": "The request Id",
            "type": "string"
          },
          "model": {
            "description": "The model",
            "type": "string",
            "x-ms-dynamic-values": {
              "operationId": "GetSupportedModels",
              "value-path": "name",
              "value-title": "properties/displayName",
              "value-collection": "cardTypes",
              "parameters": {
                "requestId": {
                  "parameter": "id"
                }
              }
            },
            "x-ms-dynamic-list": {
              "operationId": "GetSupportedModels",
              "itemsPath": "cardTypes",
              "itemValuePath": "name",
              "itemTitlePath": "properties/displayName",
              "parameters": {
                "requestId": {
                  "parameterReference": "requestBody/id"
                }
              }
            }
          }
        }
      }
    }
  ],
  "responses": {
    "200": {
      "description": "OK",
      "schema": {
        "type": "object"
      }
    },
    "default": {
      "description": "Operation Failed."
    }
  }
}

Dinamik şema kullanma

Geçerli parametre veya yanıt için şemanın dinamik olduğunu belirten dinamik şema. Bu nesne bu alanın değeri tarafından tanımlanan, şemayı dinamik olarak keşfeden ve kullanıcı girişlerini toplamak veya kullanılabilir alanları göstermek için uygun kullanıcı arabirimini gösteren bir işlemi çağırabilir.

Uygulandığı öğe: Parametreler, Yanıtlar

Bu görüntüde, kullanıcının listeden seçtiği öğeye bağlı olarak giriş formunun nasıl değiştiği gösterilmektedir:

Form, kullanıcının yaptığı seçime göre değişir.

Bu görüntüde ise kullanıcının açılır listeden seçtiği öğeye bağlı olarak çıktıların nasıl değiştiği gösterilmektedir. Bu sürümde, kullanıcı Otomobiller öğesini seçer:

Kullanıcı otomobilleri seçer

Bu sürümde, kullanıcı Yemek öğesini seçer:

Kullanıcı yemeği seçer

Dinamik şemayı kullanma

Not

Yol dizesi, baştaki eğik çizgiyi içermeyen bir JSON işaretçisidir. Bu nedenle, bu bir JSON işaretçisi: /property/childProperty ve bu bir yol dizesidir: Property/childproperty.

Dinamik şemayı tanımlamanın iki yolu vardır:

x-ms-dynamic-schema:

Ad	Gerekli	Açıklama
operationId	Evet	Şemayı döndüren işlem.
Parametreler	Evet	Bir dinamik şema işlemini çağırmak için gereken giriş parametrelerini belirten nesne.
value-path	Hayır	Şemayı içeren özelliğe başvuran yol dizesi.Belirtilmezse, yanıtın kök nesnesinin özelliklerindeki şemayı içerdiği varsayılır. Belirtilmişse başarılı yanıtın özelliğini içermesi gerekir. Boş veya tanımlanmamış bir şema için değeri null olmalıdır.

  {
  "name": "dynamicListSchema",
  "in": "body",
  "description": "Dynamic schema for items in the selected list",
  "schema": {
      "type": "object",
      "x-ms-dynamic-schema": {
          "operationId": "GetListSchema",
          "parameters": {
              "listID": {
                  "parameter": "listID-dynamic"
              }
          },
          "value-path": "items"
      }
    }
  }

Not

Parametrelerde belirsiz başvurular olabilir. Örneğin, aşağıdaki işlem tanımında dinamik şema query adında bir alana başvurur. Ancak, parametre nesnesi olan query öğesine mi yoksa query/query dize özelliğine mi başvurduğu—tanıma bakarak belirleyici şekilde anlaşılamaz.

{

    "summary": "Tests dynamic schema with ambiguous references",
    "description": "Tests dynamic schema with ambiguous references.",
    "operationId": "TestDynamicSchemaWithAmbiguousReferences",
    "parameters": [{
        "name": "query",
        "in": "body",
        "description": "query text.",
        "required": true,
        "schema": {
            "description": "Input body to execute the request",
            "type": "object",
            "properties": {
                "query": {
                    "description": "Query Text",
                    "type": "string"
                }
            }
        },
        "x-ms-summary": "query text"
    }],
    "responses": {
        "200": {
            "description": "OK",
            "schema": {
                "x-ms-dynamic-schema": {
                    "operationId": "GetDynamicSchema",
                    "parameters": {
                        "query": {
                            "parameter": "query"
                        }
                    },
                    "value-path": "schema/valuePath"
                }
            }
        },
        "default": {
            "description": "Operation Failed."
        }
    }
}

Açık kaynak bağlayıcılarının örnekleri

Bağlayıcı	Senaryo	Bağlantı ekleyin
Anahtar oluşturma	Seçili etkinliğin ayrıntıları için şema Al	Anahtar oluşturma

x-ms-dynamic-properties:

Parametrelere belirsiz şekilde başvurmanın bir yolu yoktur. Bu özellik gelecekte sağlanıyor olabilir. İşleminizin yeni güncelleştirmelerden faydalanmasını istiyorsanız x-ms-dynamic-schema ile birlikte yeni x-ms-dynamic-properties uzantısını ekleyin. Ayrıca dinamik uzantınız parametrelerde bulunan özelliklere başvuruyorsa x-ms-dynamic-schema ile birlikte yeni x-ms-dynamic-properties uzantısını eklemeniz gerekir. Özelliklere işaret eden parametre başvuruları yol dizeleri olarak ifade edilmesi gerekir.

parameters—Bu özellik, dinamik işlemin çağrılan her giriş özelliğinin bir statik değer alanı veya kaynak işlemin özelliğine yapılan dinamik bir başvuru ile tanımlandığı bir nesnedir. Bu seçeneklerin her ikisi de aşağıda tanımlanmıştır.
value—Giriş parametresi için kullanılacak sabit değer budur. Örneğin, version adındaki GetDynamicSchema işleminin giriş parametresi, aşağıdaki örnekte 2.0 statik değeriyle tanımlanmıştır.
```
{
    "operationId": "GetDynamicSchema",
    "parameters": {
      "version": {
        "value": "2.0"
      }
    }
}
```

parameterReference—Bu, parametre adından başlayan, başvurulacak özelliğin yol dizesinin takip ettiği tam parametre başvuru adıdır. Örneğin, destinationInputParam1 parametresinin altındaki Property1 adlı GetDynamicSchema öğesinin giriş özelliği, kaynak işlemin sourceInputParam1 altında Property1 adlı bir özelliğe dinamik başvuru olarak tanımlanır.

{
    "operationId": "GetDynamicSchema",
      "parameters": {
          "destinationInputParam1/property1": {
            "parameterReference": "sourceInputParam1/property1"
    }
  }
}

Not

Ad	Gerekli	Açıklama
operationId	Evet	Şemayı döndüren işlem.
Parametreler	Evet	Bir dinamik şema işlemini çağırmak için gereken giriş parametrelerini belirten nesne.
itemValuePath	Hayır	Şemayı içeren özelliğe başvuran yol dizesi.Belirtilmezse, yanıtın kök nesnesinin şemayı içerdiği varsayılır. Belirtilmişse başarılı yanıtın özelliğini içermesi gerekir. Boş veya tanımlanmamış bir şema için değeri null olmalıdır.

x-ms-dynamic-properties ile parametre özellikleri dinamik işlem parametresi başvurusunun hem anahtar hem de değeri için başvurulacak özelliğin yol dizesi ile kullanılabilir.

    {
    "summary": "Tests dynamic schema with ambiguous references",
    "description": "Tests dynamic schema with ambiguous references.",
    "operationId": "TestDynamicSchemaWithAmbiguousReferences",
    "parameters": [{
        "name": "query",
        "in": "body",
        "description": "query text.",
        "required": true,
        "schema": {
            "description": "Input body to execute the request",
            "type": "object",
            "properties": {
                "query": {
                    "description": "Query Text",
                    "type": "string"
                }
            }
        },
        "x-ms-summary": "query text"
    }],
    "responses": {
        "200": {
            "description": "OK",
            "schema": {
                "x-ms-dynamic-schema": {
                    "operationId": "GetDynamicSchema",
                    "parameters": {
                        "version": "2.0",
                        "query": {
                            "parameter": "query"
                        }
                    },
                    "value-path": "schema/valuePath"
                },
                "x-ms-dynamic-properties": {
                    "operationId": "GetDynamicSchema",
                    "parameters": {
                        "version": {
                            "value": "2.0"
                        },
                        "query/query": {
                            "parameterReference": "query/query"
                        }
                    },
                    "itemValuePath": "schema/valuePath"
                }
            }
        },
        "default": {
            "description": "Operation Failed."
        }
      }
    }