Aracılığıyla paylaş

Bir OpenAPI uzantısıyla özel bağlayıcı oluşturma

  • Makale

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 aşağıdaki OpenAPI uzantılarını da ekleyebilirsiniz:

Aşağıdaki bölümler bu uzantıları açıklar.

Ö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ı"

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...
        }]
    }
},

description

İş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"

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, varsayılan değerini sağlamanız gerekir.

Örnek: Daha fazla ve Gelişmiş seçenekleri göster menüleri 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: İşlemler

  • family—İşlem ailesi klasörünü belirten bir dize.
  • revision—Düzeltme numarasını belirten bir tamsayı.
  • replacement—Değiştirme API’si 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: İşlemler

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

x-ms-capabilities

Bağlayıcı düzeyinde kullanıldığında 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ılar

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

İşlem düzeyinde kullanıldığında 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: İşlemler

  • 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: İşlemler

  • 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: İşlemler

"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.

Şunlar için geçerlidir: Kaynaklar

"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: Parametreler/giriş alanları

"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 parametreleri

"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 dinamik değerler.

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/childPropertyve bu bir yol dizesidir: Property/childproperty.

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

  1. 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."
        }
    }
}

  2. 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. Aşağıdaki örnekte, version adındaki GetDynamicList işleminin giriş parametresi, 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.

      Veri Akışı Adı Zorunlu Tanım
      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/childPropertyve bu bir yol dizesidir: Property/childproperty.

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

  1. 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
    Connector Senaryo Bağlantı ekleyin
    Anahtar oluşturma Seçili etkinliğin ayrıntıları için şema Al Anahtar oluşturma

  2. 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. Aşağıdaki örnekte, version adındaki GetDynamicSchema işleminin giriş parametresi, 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

      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 şemadaki varsayılan değer kullanılmaz.

      Veri Akışı Adı Zorunlu Tanım
      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."
        }
      }
    }

Sonraki adım

Bir OpenAPI tanımından özel bağlayıcı oluşturma

Özel bağlayıcılara genel bakış

Geri bildirimde bulunun

Bağlayıcı platformumuzla ilgili sorunlar veya yeni özellik fikirleri hakkındaki geri bildiriminiz bizim için çok önemlidir. Geri bildirimde bulunmak için Sorun gönderme veya bağlayıcılarla ilgili yardım alma bölümüne gidip geri bildirim türünü seçin.