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

Microsoft Copilot Studio, Azure Logic Apps, Microsoft Power Automate veya Microsoft Power Apps için özel bağlayıcılar oluşturmanın bir yolu bir OpenAPI tanım dosyası sağlamaktır. OpenAPI tanım dosyası, API'nizin işlemlerini ve parametrelerini açıklayan dilden bağımsız, makine tarafından okunabilir bir belgedir. OpenAPI'nin kullanıma hazır işlevselliğinin yanı sıra, Copilot Studio, 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.

Uygulanabilirlik: İşlemler
Önerilen: summary için cümle düzenini 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.

Şunlar için geçerlidir: Parametreler, yanıt şeması
Önerilen: x-ms-summary için başlık büyük/küçük harf kullanımı.
Örnek: Takvim Kimliği, Konu, Olay Açıklaması

her varlık için 

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

açıklama

İşlemin işlevselliği veya bir varlığın biçimi ve işlevi hakkında ayrıntılı bir açıklama sağlar.

Şunlara uygulanır: İşlemler, parametreler, yanıt şeması
Önerilen: description için cümle yapısını kullanın.
Örnek: "Takvime yeni bir olay eklendiğinde bu işlem tetikleniyor", "Postanın konusunu belirtin."

her işlem veya varlık için 

"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
Şunlara uygulanır: İşlemler, parametreler, şemalar

  • Kullanıcı her zaman önce işlemleri ve parametreleri görür important .
  • Kullanıcı yalnızca ek menü kullandığında işlemleri ve parametreleri görür advanced .
  • Kullanıcı işlemleri ve parametreleri görmez internal .

Not

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

Örnek: Daha fazlasını göster ve Gelişmiş seçenekleri göster menüleri işlemleri ve parametreleri gizler advanced .

"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

Bir işlemin sürüm oluşturma ve yaşam döngüsü yönetimi için kullanın.

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ışı test edebilmeniz için tetikleyici tetikleme simülasyonu yapmak için bu özelliği kullanın.

Uygulandığı öğe: İşlemler

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

x-ms-capabilities

Bu özelliği bağlayıcı düzeyinde kullandığınızda, belirli işlemler de dahil olmak üzere bağlayıcının sunduğu özelliklere genel bir bakış sağlar.

Şuna uygulanır: Bağlayıcılar

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

İşlem düzeyinde bu özelliği kullandığınızda, işlemin öbek yükleme ve statik öbek boyutunu desteklediğini ve kullanıcının sağlayabileceğiniz statik öbek boyutunu desteklediğini tanımlar.

Uygulandığı öğe: İşlemler

  • chunkTransfer—Öbek aktarımının desteklenip desteklenmediğini gösteren Boole değeri.
"x-ms-capabilities": {
  "chunkTransfer": true
}

x-ms-trigger

Geçerli işlemin tek bir olay üreten bir tetikleyici olup olmadığını gösterir. Bu alan yoksa, işlem bir actionolur.

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ğini açıklar.

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 şema, dış hizmetlerin bildirim URL'sine gönderebilecekleri web kancası yükünü tanımlar.

Ş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 veya alana web kancası bildirim URL'si eklenip eklenmeyeceğini belirtmek için Boole değeri kullanın.

Şunlar için geçerlidir: Parametreler ve giriş alanları

"x-ms-notification-url": true

x-ms-url-encoding

Geçerli yol parametresinin çift URL kodlaması mı () yoksa tek URL kodlaması mıdouble (single) kullanması gerektiğini belirtin. Bu alan eksikse, varsayılan olarak single kodlaması kullanılır.

Uygulandığı öğe: Yol parametreleri

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

x-ms-dynamic-values

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

Uygulandığı alan: 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 iki şekilde tanımlayabilirsiniz:

  • x-ms-dynamic-values komutunu kullanma

    Ad Gerekli Açıklama
    operationId Evet Değerleri döndüren işlem.
    parameters 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 Değer koleksiyonu içindeki nesnede, değerin açıklamasına atıfta bulunan bir 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ğerlerin kullanılması belirsiz parametre başvurularına yol açabilir. Örneğin, bir işlemin aşağıdaki tanımında dinamik değerler ID alanına başvurur. Tanım, başvurunun parametre kimliğine mi yoksa requestBody/id özelliğine mi olduğunu açıkça belirtmez.

{
    "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 komutunu kullanma

    Parametrelere açıkça başvuramazsınız. Bu özellik gelecekte sağlanıyor olabilir. İşleminizin yeni güncelleştirmelerden faydalanmasını istiyorsanız x-ms-dynamic-list ile birlikte yeni x-ms-dynamic-values uzantısını ekleyin. Ayrıca, dinamik uzantınız parametreler içindeki özelliklere başvuruyorsa, yeni uzantıyı x-ms-dynamic-list ile x-ms-dynamic-valuesbirlikte eklemeniz gerekir. Özelliklere işaret eden parametre başvuruları yol dizeleri olarak ifade edilmesi gerekir.

    • parameters—Bu özellik, çağrılan dinamik işlemin her giriş özelliğini statik değer alanıyla veya kaynak işlemin özelliğine yönelik dinamik başvuruyla tanımladığınız bir nesnedir. Bu seçeneklerin her ikisi de aşağıdaki bölümde tanımlanmıştır.

    • value—Bu, giriş parametresi için kullanılacak değişmez değerdir. 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ı ve ardından başvurulacak özelliğin yol dizesiyle başlayan tam parametre başvuru yoludur. Ö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 değerle dahili olarak işaretlenmiş herhangi bir özelliğe başvurmak için, varsayılan değeri buradaki parameterReferencetanımda yerine statik değer olarak kullanın. 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.
parameters 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çindeki nesnede, değerin açıklamasına başvuran bir 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 bir özelliğin yol dizesini kullanarak parametre referansları oluşturun. 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."
    }
  }
}

x-ms-dynamic-schema

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.

Şunlara uygulanır: Parametreler, yanıtlar

Aşağıdaki görüntüde, kullanıcının listeden seçtiği öğeye göre giriş formunun nasıl değiştiği gösterilmektedir:

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

Aşağıdaki görüntüde, kullanıcının açılan listeden seçtiği öğeye göre çıkış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ı iki şekilde tanımlayabilirsiniz:

  • x-ms-dynamic-schema:

    Ad Gerekli Açıklama
    operationId Evet Şemayı döndüren işlem.
    parameters 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. Bu özelliği belirtmezseniz, yanıtın kök nesnenin özelliklerinde şemayı içerdiği varsayılır. Belirtilmişse başarılı yanıt, özelliği içermelidir. 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

Parametreler belirsiz başvurular içerebilir. Ö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ından örnekler

Bağlayıcı Senaryo Bağlantı
Bilet yönetimi Seçili etkinliğin ayrıntıları için şema Al Biletleme

  • x-ms-dynamic-properties:

    Parametrelere açık ve net bir ş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-properties ile birlikte yeni x-ms-dynamic-schema uzantısını ekleyin. Ayrıca, dinamik uzantınız parametreler içindeki özelliklere başvuruyorsa, yeni uzantıyı x-ms-dynamic-properties ile x-ms-dynamic-schemabirlikte eklemeniz gerekir. Özelliklere işaret eden parametre başvuruları yol dizeleri olarak ifade edilmesi gerekir.

    • parameters—Bu özellik, çağrılan dinamik işlemin her giriş özelliğini statik değer alanıyla veya kaynak işlemin özelliğine yönelik dinamik başvuruyla tanımladığınız bir nesnedir. Bu seçeneklerin her ikisi de aşağıdaki bölümde tanımlanmıştır.

    • value—Bu, giriş parametresi için kullanılacak değişmez değerdir. 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 değerle dahili olarak işaretlenmiş herhangi bir özelliğe başvurmak için, varsayılan değeri buradaki parameterReferencetanımda yerine statik değer olarak kullanın. parameterReference kullanılarak tanımlanırsa şemadaki varsayılan değer kullanılmaz.

    Ad Gerekli Açıklama
    operationId Evet Şemayı döndüren işlem.
    parameters 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, özelliği içermelidir. Boş veya tanımlanmamış bir şema için değeri null olmalıdır.

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

        {
    "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 veya yeni özellik fikirlerimizle ilgili sorunlar hakkındaki geri bildirimleriniz 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.

  • Last updated on