已驗證的發行者認證程序

  • 發行項

此程序適用於已驗證的發行者 (不包括獨立發行者)。 如果您是獨立發行者，請移至獨立發行者認證程序。

完成自訂連接器的建立後，請遵循這些步驟為該連接器做好認證準備，並產生連接器檔案以提交給 Microsoft。

注意

此主題提供在 Azure Logic Apps、Power Automate 和 Power Apps 中，認證自訂連接器的資訊。 在執行本文中的步驟之前，請先閱讀取得您的連接器認證，和向 Microsoft 註冊您的自訂連接器。

基本認證程序工作流程

下列流程圖顯示了基本認證程序工作流程。 本文中的編號步驟對應於工作流程。 它們應提供完成認證程序所需的詳細資料。

如需流程圖的展開檢視，請在右下角選取放大鏡圖示。

連接器認證程序工作流程

如需此流程圖的深度視覺效果，請移至深度連接器認證程序工作流程。

步驟 1: 註冊您的連接器

您不需要完成自訂連接器的建立就能申請認證。 若要開始認證程序，請填寫我們的註冊表單來註冊您的連接器以取得認證。

應該會在兩個工作日內收到一封來自 Microsoft 連絡人的電子郵件，他將：

  • 了解您的自訂連接器。
  • 了解您的開發進度。
  • 引導您完成認證程序。

步驟 2：符合提交需求

為了維持我們認證連接器中品質和一致性的高標準，Microsoft 有一套需求和指導方針，您的自訂連接器必須遵守才能進行認證。

為您的連接器命名

  • 必須存在並以英文撰寫。
  • 必須是唯一的，且可與任何現有的連接器標題區別。
  • 應為您的產品或組織的名稱。
  • 應遵循認證連接器的現有命名模式。 如果是獨立發行者，則連接器名稱應遵循連接器名稱 (獨立發行者) 模式。
  • 長度不能超過 30 個字元。
  • 不能包含 API、連接器 等字眼，或任何 Power Platform 產品名稱 (例如，Power Apps)。
  • 不能以非英數的字元結尾，包括歸位字元、換行或空格。

範例

  • 好的連接器標題：Azure Sentinel、Office 365 Outlook
  • 不好的連接器標題：Azure Sentinel 的 Power Apps 連接器、Office 365 Outlook API

為您的連接器撰寫描述

  • 必須存在並以英文撰寫。
  • 必須沒有語法和拼字錯誤。
  • 應該簡潔描述您的連接器所提供的主要目的和價值。
  • 不能少於 30 個字元或多於 500 個字元。
  • 不能包含任何 Power Platform 產品名稱 (例如「Power Apps」)。

為您的連接器設計圖示

本節不適用於獨立發行者。

  • 建立 1:1 尺寸、畫素介於 100 x 100 與 230×230 之間 (無圓角) 的標誌。
  • 使用與您指定的圖示背景色彩相符的非透明、非白色 (#ffffff) 背景，和非預設色彩 (#007ee5)。
  • 請確認圖示對於其他已認證的連接器圖示是唯一的。
  • 以 PNG 格式，如 <icon>.png 提交標誌。
  • 將圖像高度和寬度的標誌尺寸設定為 70%以下，並保持一致的背景。
  • 確定品牌色彩是有效的十六進位顏色，且不能是白色 (#ffffff) 或預設色彩 (#007ee5)。

定義作業和參數摘要及描述

  • 必須存在並以英文撰寫。
  • 必須沒有語法和拼字錯誤。
  • 作業和參數摘要應為 80 個字元以下的片語，且只包含英數字元或括弧。
  • 作業和參數描述應為完整、敘述性的句子並以標點符號結束。
  • 不能包含任何 Microsoft Power Platform 產品名稱 (例如「Power Apps」)。

定義精確的作業回覆

  • 只使用預期回覆定義具有精確結構描述的作業回覆。
  • 請勿使用具有精確結構描述的預設回覆。
  • 為 Swagger 中的所有作業提供有效的回覆結構描述定義。
  • 除非回應結構描述為動態的特殊案例，否則不允許使用空白的回應結構描述。 這表示在輸出中不會顯示任何動態內容，且製作者必須使用 JSON 來解析回覆。
  • 不允許空白的作業。
  • 除非是必要屬性，否則刪除空白屬性。

驗證 swagger 屬性

  • 確定「openapidefinition」 是正確格式化的 JSON 檔案。
  • 確認 swagger 的定義符合 OpenAPI 2.0 標準和連接器擴充標準。

驗證連線參數

  • 確定已使用 「UIDefinition」(顯示名稱、描述) 的適當值更新屬性。

  • 如果您的連線參數使用基本驗證，請確認 JSON 已依照下列範例正確格式化。

    {
  "username": {
    "type": "securestring",
    "uiDefinition": {
      "displayName": "YourUsernameLabel",
      "description": "The description of YourUsernameLabel for this api",
      "tooltip": "Provide the YourUsernameLabel tooltip text",
      "constraints": {
        "tabIndex": 2,
        "clearText": true,
        "required": "true"
        }
  }
},
  "password": {
    "type": "securestring",
    "uiDefinition": {
      "displayName": "YourPasswordLabel",
      "description": "The description of YourPasswordLabel for this api",
      "tooltip": "Provide the YourPasswordLabel tooltip text",
      "constraints": {
        "tabIndex": 3,
        "clearText": false,
        "required": "true"
      }
    }
  }
}

  • 如果您的連線參數使用 APIKey 作為驗證，請確認 JSON 已依照下列範例正確格式化。

    {
  "api_key": {
    "type": "securestring",
    "uiDefinition": {
      "displayName": "YourApiKeyParameterLabel",
      "tooltip": "Provide your YourApiKeyParameterLabel tooltip text",
      "constraints": {
        "tabIndex": 2,
        "clearText": false,
        "required": "true"
      }
    }
  }
}

  • 如果您的連線參數使用 Generic OAuth 作為驗證，請確認 JSON 已依照下列範例正確格式化。

    {
  "token": {
    "type": "oAuthSetting",
    "oAuthSettings": {
      "identityProvider": "oauth2",
      "scopes": [
        "scope1"
      ],
      "redirectMode": "GlobalPerConnector",
      "customParameters": {
        "AuthorizationUrl": {
          "value": "https://contoso.com"
        },
        "TokenUrl": {
          "value": "https://contoso.com"
        },
        "RefreshUrl": {
          "value": "https://contoso.com"
        }
      },
      "clientId": "YourClientID"
    },
    "uiDefinition": null
  }
}

  • 如果您的連線參數具有 OAuth2 識別提供者，請確認該識別提供者來自支援的 OAuth2 提供者清單。 以下是 GitHub OAuth2 識別提供者的範例：

    {
  "token": {
    "type": "oAuthSetting",
    "oAuthSettings": {
      "identityProvider": "github",
      "scopes": [
        "scope1"
      ],
      "redirectMode": "GlobalPerConnector",
      "customParameters": {},
      "clientId": "YourClientId"
    },
    "uiDefinition": null
  }
}

  • 如果您的連線參數使用 Microsoft Entra 識別碼作為驗證，請確認 JSON 已依照下列範例正確格式化。

    {
  "token": {
    "type": "oAuthSetting",
    "oAuthSettings": {
      "identityProvider": "aad",
      "scopes": [
        "scope1"
      ],
      "redirectMode": "GlobalPerConnector",
      "customParameters": {
        "LoginUri": {
          "value": "https://login.microsoftonline.com"
        },
        "TenantId": {
          "value": "common"
        },
        "ResourceUri": {
          "value": "resourceUri"
        },
        "EnableOnbehalfOfLogin": {
          "value": false
        }
      },
      "clientId": "AzureActiveDirectoryClientId"
    },
    "uiDefinition": null
  }
}

建立優質的英文語言字串

連接器會當地語系化為 Power Automate 當地語系化的一部分; 因此，當您在開發連接器時，英文語言字串的品質是翻譯品質的關鍵。 在建立要提供的字串值時，請注意以下重要部分。

  • 請務必執行拼字檢查程式，以確保所有字串值都沒有打錯字。 如有任何不完整的英語字串，則內容中的翻譯結果會不完整或不正確。

  • 請確定句子格式完整。 如果句子不完整，產生的翻譯品質也會較低。

  • 請確認該句子的含義是清晰的。 如果該句子的含義不明確，產生的翻譯品質也會較低或不正確。

  • 請確定摘要、 x-ms-summaries 和描述的語法正確。 請勿複製和貼上它們。 若要了解它們在產品中的顯示方式，請移至連接器字串指南。

  • 請盡量避免執行階段複合字串。 請改用格式完整的句子。 串連字串或句子會使翻譯變得困難，或造成錯誤的翻譯。

  • 如果您使用縮寫，請確保將它們大寫以免混淆。 這會減少被誤認為是拼字錯誤的機會。

  • CaMel 形式的字串 (例如 minimizeHighways 或 MinimizeHighways) 通常被視為無法翻譯。 如果您想要當地語系化字串值，則應修正 CaMel 格式字串。

步驟 3：執行解決方案檢查工具來驗證您的連接器

解決方案檢查工具是一種執行靜態分析的機制，可確保您的連接器符合 Microsoft 認證所需的標準。 按照使用解決方案檢查工具驗證自訂連接器中的指示，將您的連接器新增至 Power Automate 或 Power Apps 中的解決方案，並執行解決方案檢查工具。

觀看此影片以了解如何執行解決方案檢查工具！

步驟 4：新增中繼資料

您的連接器成品 (檔案) 必須包含描述連接器及其最終服務的特定中繼資料。 中繼資料中提供的資訊會發佈在我們的連接器文件中，而且所有使用者都可以公開存取。 請勿提供任何私人或機密資訊，如果有任何關於提供此資訊給我們的問題，請透過您的 Microsoft 連絡人告知我們。 若要了解中繼資料的記載方式，請造訪連接器參考 底下的任一連接器特定文件頁面。

步驟 4a：Publisher 和 stackOwner 屬性

  • "Publisher" 是您的公司或組織的名稱。 提供完整的公司名稱 (例如，"Contoso Corporation")。 這必須是英數字元格式。

  • "stackOwner" 是連接器所連線後端服務堆疊的擁有公司或組織。 這必須是英數字元格式。

發行者 Description 範例
已驗證 除非 ISV 是代表 stackOwner 組建連接器，否則發行者和 stackOwner 會是相同的。 「發行者」："Tesla",
"stackOwner": "Tesla"
獨立 您必須提供堆疊負責人和發行者負責人。 「發行者」："Nirmal Kumar",
"stackOwner": "ITGlue"

檔案位置： APIProperties.json
若要深入了解，請移至 API 屬性檔案。

語法：在 apiProperties.json 檔案中出現的 publisher 和 stackOwner 屬性是做為最上層屬性。 新增醒目提示行，如下所示。 請確認您完全按照所示輸入屬性名稱和架構。

顯示可在範例程式碼片斷中使用之發佈者和 stackOwner 屬性的螢幕截圖。

步驟 4c：範例程式碼片段

您可以使用下列程式碼片段複製和輸入您的資訊。 請確定將程式碼片段新增至正確位置的正確檔案中，如上一節所述。

    "publisher": "_____",
    "stackOwner": "_____"

    "contact": {
      "name": "_____",
      "url": "_____",
      "email": "_____"
    }

    "x-ms-connector-metadata": [
      {
        "propertyName": "Website",
        "propertyValue": "_____"
      },
      {
        "propertyName": "Privacy policy",
        "propertyValue": "_____"
      },
      {
        "propertyName": "Categories",
        "propertyValue": "_____;_____"
      }
    ]

注意

目前在使用 stackOwner 屬性和 Paconn CLI 工具方面存在限制。 如需詳細資訊，請移至 README 檔案中的限制。

步驟 4d：JSON 檔案格式和限制

  • 請確定您的屬性已正確對齊。

  • 將您的 JSON 貼上至 Visual Studio Code 中。 可隨意使用拼字檢查工具和外掛程式 (例如 JSON 外掛程式) 之類的擴充功能。

  • Swagger 檔案不應大於 1 MB。

    • 開始組建之前，請先考慮連接器的設計。 評估連接器是否應分成兩 (2) 個或多個連接器。
    • 較大的 Swagger 檔案可能會在使用連接器時造成延遲。

    例如，平台上有三 (3) 個不同的 HubSpot 連接器。

    三個 HubSpot 連接器的資料夾螢幕擷取畫面。

步驟 4e：驗證您的自訂連接器檔案

執行 paconn validate --api-def [Location of apiDefinition.swagger.json]。 此工具會驗證您的連接器定義，並讓您知道在提交前必須修正的任何錯誤。

如果您的連接器使用 OAuth 做為其驗證類型，請將這些已列入允許清單的重新導向 URL 新增至您的應用程式。

  • https://global.consent.azure-apim.net/redirect/{apiname}

  • https://global-test.consent.azure-apim.net/redirect/{apiname}

步驟 5：準備連接器成品

此步驟應該需要大約一週的時間才能完成。

注意

  • 在認證之前，請先確定您已遵循規格，並確保連接器的品質。 若未能做到將會導致認證延遲，因為系統會要求您進行變更。
  • 提供主機 URL 的產品版本。 不允許使用暫存、開發及測試主機 URL。

您要向 Microsoft 提交一組名為連接器成品的檔案，這些檔案可使用 Microsoft 提供的命令列介面 (CLI) 工具來下載。 此工具會驗證您的連接器是否存在任何中斷性錯誤。

遵循下列步驟以開始使用：

  1. 遵循安裝指示，安裝 Microsoft Power Platform 連接器 CLI 工具。

  2. 使用命令列執行 paconn login 來登入 Microsoft Power Platform。 遵循指示以使用 Microsoft 的裝置程式碼流程來登入。

  3. 在通過驗證之後，請下載您的自訂連接器檔案：

    • 執行 paconn download。 在命令列中指定自訂連接器的號碼來選取其所在的環境，接著選取自訂連接器名稱。

    工具會將資料夾中的連接器成品下載至您用來執行 paconn 的檔案系統位置。 根據發行者的類型，您會看到各種成品：

發行者 成品
已驗證 apiDefinition.swagger.json
apiProperties.json
settings.json
連接器圖示
獨立 apiDefinition.swagger.json
apiProperties.json

已驗證的發行者和獨立發行者都會在其成品中下載 apiProperties.json。 您需要在此文件中設定 IconBrandColor。

  • 已驗證的發行者： 在 apiProperties 檔案中將 iconBrandColor 設定為品牌色彩。
  • 獨立發行者： 在 apiProperties 檔案中將 iconBrandColor 設定為 "#da3b01"。
    亮橙色 (da3b01) 圖示的螢幕擷取畫面。

建立讀我檔案成品

獨立發行者和已驗證發行者都需要 Readme.md 檔案。 您需要建立 Readme.md 檔案，以記錄連接器的特性和功能。 有關要包含的文件範例，請移至 Readme.md 範例。 若要了解如何編寫 Readme.md 檔，請參閱 GitHub 存放庫中的其他 Readme.md 檔。

如果您是獨立發行者，且您的連接器使用 OAuth，請務必包含取得認證的指示。

提示

可維護已知問題和限制區段，讓您的使用者保持最新狀態。

步驟 6：提交您的連接器以進行部署

在提交過程中，您會開放您連接器的源碼給我們的 Microsoft Power Platform 連接器存放庫。

  1. 請遵循提交您的連接器以取得 Microsoft 認證中的指示，提交到 GitHub 和連接器認證入口網站 (預覽版)。

    如果您是已驗證的發行者，且您使用的是自訂程式碼，則需要提交 script.csx 檔案。

  2. 向開放原始存放庫提交提取要求後，Microsoft 會在一到兩週內部署和驗證您的連接器。 如果需要更新，請允許額外的一到兩週。

    如果您的連接器具有 OAuth，請在連接器認證入口網站 (預覽版) 中提交封裝。 此外，從連接器提交請求中取得 APIname 以更新您的應用程式。

    作為提交的一部分，Microsoft 會使用「CLA-bot」、「Swagger 驗證程式」和「中斷性變更偵測」工具驗證您的連接器。 如果您需要疑難排解 Swagger 錯誤，請移至修正 Swagger 驗證程式錯誤。

步驟 7：對已驗證發行者進行測試的預期

在驗證完您的連接器之後，我們會要求您執行全面測試。

  1. 若要在預覽版區域中建立環境以準備測試，請按照在認證中測試連接器中的指示。

  2. 請在一週內通知您的 Microsoft 連絡人您已完成測試，以便我們開始部署。

  3. 在您與 Microsoft 驗證完您的連接器功能和內容之後，我們會在預覽版區域中預備連接器進行部署以供測試。

步驟 8：等待部署

在您的連接器通過測試驗證後，我們會將連接器部署到所有產品和區域。

重要

平均來說，部署連接器需要三到四週。 無論連接器的大小或複雜程度如何，不論是新的連接器還是更新過的連接器，這都是必要的。 為了保護完整性，連接器需接受相同的驗證工作，以測試每次部署中所遵循的功能和內容。

我們將透過電子郵件通知您連接器將部署到的區域名稱，因為部署到各區域是分階段完成的。 如果出現部署延遲或凍結，則已驗證的發行者可以在連接器驗證入口網站 (預覽版) 中的活動控制項中找到狀態。 獨立發行者會收到電子郵件通知。

生產部署

我們的生產連接器部署時程安排會從太平洋標準時間/太平洋夏令時間週五早上開始。 您需要至少提前 24 小時讓 Microsoft 知道您已準備好進行生產部署，以便我們將您的連接器包含在下一次排定的部署中。 經過驗證的發行者可以在連接器認證入口網站 (預覽版) 的活動控制項中通知我們。 獨立發行者可以通知其 Microsoft 連絡人。

區域部署

會按照預先確定的每日順序部署到各個不同的地區。 地區包括：

  • 正在測試。
  • 美國預覽。
  • 亞洲，除了日本和印度之外。
  • 歐洲，除了英國之外。
  • 巴西、加拿大、日本和印度。
  • 澳洲、英國和美國。

例如，如果您的連接器計劃在星期一部署，它就會在第 1 天部署到測試區域。 然後，它會在第 2 天部署到美國預覽區域。 部署會每天持續進行，直到將連接器部署到所有六個區域。

我們不會在星期六、星期日和美國假日進行部署。

當您的連接器完成認證時，我們會在 Power Automate 部落格上與您就連接器的行銷商機互動。

步驟 9：探索部署後選項

部署連接器後，您可以探索以下選項：

  • 向連接器提交更新。 如需詳細資訊，請移至更新您的認證連接器。

  • 在社群研討論壇上監視您的連接器，以了解客戶是否有遇到任何問題，或是否對您的連接器有功能要求。

  • 要求移除預覽標籤。 當連接器公開使用一段時間並符合特定要求後，就有資格重新被指派正式發行標籤。 此標籤會顯示連接器為可生產的產品。 如需深入了解，請移至將您的連接器從預覽版轉為正式發行。

提交前的檢查清單

在繼續提交連接器以進行 Microsoft 認證之前，請先確定：

提示

  • 建立 YouTube 影片、部落格或其他內容，以分享如何開始使用連接器的範例或螢幕擷取畫面。
    - 包括 Readme.md 檔案中的連結，讓我們可以新增至文件中。
  • 將工具提示新增至 Swagger 檔案，以幫助使用者更加順利。

如果您是已驗證的發行者 (且不是獨立發行者)，則系統會在您提交 Microsoft 認證時，要求您同意我們的合作夥伴合約和保密協議。 如果您想要先檢閱這些條款和語言再提交，請洽詢 Microsoft 連絡人。

下一個步驟

將您的連接器提交給 Microsoft 進行認證

提供意見反應

非常感謝您提供有關連接器平台問題，或新功能構想的意見反應。 若要提供意見反應，請移至提交問題或取得連接器說明，然後選取您的意見反應類型。