События
Мощная конференция разработчиков и хак вместе
12 февр., 23 - 28 февр., 23
Присоединяйтесь к онлайн-конференции и 2-недельным хакатоном, чтобы изучить создание мощных решений с помощью Power Platform.
ЗарегистрироватьсяЭтот браузер больше не поддерживается.
Выполните обновление до Microsoft Edge, чтобы воспользоваться новейшими функциями, обновлениями для системы безопасности и технической поддержкой.
При создании пользовательского соединителя следуйте этим рекомендациям в своем коде.
apiDefinition.swagger.json
, также известный как Swagger, определяет поведение соединителя.
Чтобы иметь удобочитаемое определение Swagger, создайте определение API со следующей структурой:
Используйте оболочку Pascal для operationId
: каждое слово (включая первое) пишите заглавными буквами. Не добавляйте дефисы (-
) или подчеркивания (_
) для разделения слов.
Хороший
"operationId": "GetMessages",
Плохо
"operationId": "getMessages",
"operationId": "Get-Messages",
"operationId": "Get_Messages",
Операции всегда должны иметь сводку и описание. В сводке будет название операции, поэтому сделайте ее краткой и точной, описание должно содержать больше информации и заканчиваться точкой (.
).
Большинство описаний помещаются в виде подсказок в поля параметров, обязательно предоставьте короткий и содержательный текст. Описания и сводки не должны иметь одно и то же содержание.
Хороший
"summary": "List Name",
"description": "The list to check for messages.",
Плохо
"summary": "List",
"description": "List.",
Определите свой код успеха с помощью HTTP типа ответа 2xx
. Не используйте default
как единственный определенный ответ, вместо этого соедините его с определением успеха. Если возможно, также перечислите известные ответы 4xx
/5xx
.
Используйте ошибки типа 4xx
, когда проблема возникла на стороне клиента, вот несколько примеров:
401 - The username is invalid (it can only contain lowercase letters and numbers)
Используйте ошибки типа 5xx
, когда проблема возникла на стороне сервера
504 - The request timed-out
Хороший
{
"responses": {
"200": {
"description": "OK",
"schema": {
"$ref": "#/definitions/Message"
}
},
"400": {
"description": "Bad Request"
},
"404": {
"description": "Not Found"
},
"401": {
"description": "Unauthorized"
},
"403": {
"description": "Forbidden"
},
"500": {
"description": "Internal Server Error. Unknown error occurred"
},
"default": {
"description": "Operation Failed."
}
}
}
Плохо
{
"responses": {
"default": {
"description": "OK",
"schema": {
"type": "string"
}
}
}
}
Для параметров, которые появляются более чем в одной операции, создайте параметр имени в разделе parameters
вместо определения этого параметра в каждой операции, которая его использует.
Хороший
В этом примере параметр id
определяется в IdInPath
и используется в операциях GetMemberGroups
и RemoveMemberFromGroup
.
{
"paths": {
"/groups/{id}/getMemberGroups": {
"post": {
"summary": "Get groups of a user",
"description": "Get the groups a user is a member of.",
"operationId": "GetMemberGroups",
"parameters": [
{
"$ref": "#/parameters/IdInPath"
}
],
"responses": {
// response definitions
}
}
},
"/groups/{id}/members/{memberId}/delete": {
"delete": {
"summary": "Remove member",
"description": "Delete a member from a group.",
"operationId": "RemoveMemberFromGroup",
"parameters": [
{
"$ref": "#/parameters/IdInPath"
},
{
"name": "memberId",
"in": "path",
"required": true,
"description": "The Id of the member to be deleted.",
"x-ms-summary": "Member Id",
"type": "string"
}
],
"responses": {
// response definitions
}
}
}
},
// definitions
"parameters":{
"IdInPath": {
"name": "id",
"in": "path",
"description": "Unique identifer of a group (Ex. 'id_group1').",
"required": true,
"x-ms-summary": "Group Id",
"type": "string"
},
}
}
Использование ссылок на параметры и определения сделает ApiDefinition более удобным в поддержке. Например, если описание нуждается в обновлении, оно будет выполнено только в одном месте, а не во всех операциях, которые его используют.
Плохо
{
"paths": {
"/groups/{id}/getMemberGroups": {
"post": {
"summary": "Get groups of a user",
"description": "Get the groups a user is a member of.",
"operationId": "GetMemberGroups",
"parameters": [
{
"name": "id",
"in": "path",
"description": "Unique identifer of a group (Ex. 'id_group1').",
"required": true,
"x-ms-summary": "Group Id",
"type": "string"
}
],
"responses": {
// response definitions
}
}
},
"/groups/{id}/members/{memberId}/delete": {
"delete": {
"summary": "Remove member",
"description": "Delete a member from a group.",
"operationId": "RemoveMemberFromGroup",
"parameters": [
{
"name": "id",
"in": "path",
"description": "Unique identifer of a group (Ex. 'id_group1').",
"required": true,
"x-ms-summary": "Group Id",
"type": "string"
},
{
"name": "memberId",
"in": "path",
"required": true,
"description": "The Id of the member to be deleted.",
"x-ms-summary": "Member Id",
"type": "string"
}
],
"responses": {
// response definitions
}
}
}
}
}
Создайте запись об определениях и используйте эту ссылку во всех операциях, которые имеют один и тот же ответ объекта.
Хороший
В этом примере, помимо использования параметра, на который имеется ссылка, операции GetUser
и UpdateUser
ссылаются на один и тот же ответ объекта UserResponse
, определенный один раз в разделе definitions
.
{
"paths": {
"/v1.0/users/{id}": {
"get": {
"summary": "Get user",
"description": "Get details for a user.",
"operationId": "GetUser",
"parameters": [
{
"$ref": "#/parameters/IdInPath"
}
],
"responses": {
"200": {
"description": "200",
"schema": {
"$ref": "#/definitions/UserResponse"
}
}
}
},
"patch": {
"summary": "Update user",
"description": "Update the info for a user.",
"operationId": "UpdateUser",
"parameters": [
{
"$ref": "#/parameters/IdInPath"
}
],
"responses": {
"201": {
"description": "Accepted",
"schema": {
"$ref": "#/definitions/UserResponse"
}
}
},
"deprecated": false,
"x-ms-no-generic-test": true
}
},
},
// definitions
"definitions":{
"UserResponse": {
"type": "object",
"properties": {
"id": {
"description": "The unique identifier for the user.",
"type": "string",
"x-ms-summary": "Id"
},
"email": {
"description": "The email associated to the user.",
"type": "string",
"x-ms-summary": "Email"
},
// more fields here
}
}
}
}
Плохо
{
"paths": {
"/v1.0/users/{id}": {
"get": {
"summary": "Get user",
"description": "Get details for a user.",
"operationId": "GetUser",
"parameters": [
{
"$ref": "#/parameters/IdInPath"
}
],
"responses": {
"200": {
"description": "200",
"schema": {
"$ref": "#/definitions/UserResponse"
}
}
}
},
"patch": {
"summary": "Update user",
"description": "Update the info for a user.",
"operationId": "UpdateUser",
"parameters": [
{
"$ref": "#/parameters/IdInPath"
}
],
"responses": {
"201": {
"description": "Accepted",
"schema": {
"$ref": "#/definitions/UserResponse"
}
}
},
"deprecated": false,
"x-ms-no-generic-test": true
}
},
},
// definitions
"definitions":{
"UserResponse": {
"type": "object",
"properties": {
"id": {
"description": "The unique identifier for the user.",
"type": "string",
"x-ms-summary": "Id"
},
"email": {
"description": "The email associated to the user.",
"type": "string",
"x-ms-summary": "Email"
},
// more fields here
}
}
}
}
Для нас очень важны отзывы о проблемах с нашей платформой соединителей и новые идеи о функциях. Чтобы оставить отзыв, выберите пункт Сообщить о проблемах или получить помощь с соединителями и выберите тип отзыва.
События
Мощная конференция разработчиков и хак вместе
12 февр., 23 - 28 февр., 23
Присоединяйтесь к онлайн-конференции и 2-недельным хакатоном, чтобы изучить создание мощных решений с помощью Power Platform.
ЗарегистрироватьсяОбучение
Схема обучения
Build custom connectors for Microsoft Power Platform - Training
Learn how to build custom connectors for Microsoft Power Platform.
Сертификация
Microsoft Certified: Power Platform Developer Associate - Certifications
Узнайте, как упростить, автоматизировать и преобразовать бизнес-задачи и процессы с помощью разработчика Microsoft Power Platform.