コーディング標準に従う

[アーティクル]
06/27/2024

カスタムコネクタを作成するときは、以下のグッドプラクティスに従ってコードを作成してください。

API の定義

apiDefinition.swagger.json は、swagger とも呼ばれ、ここでコネクタの動作が定義されています。

インデント: ソフトタブには 4 つのスペースを使用し、ハードタブは使用しないでください。
末尾のスペースを削除: 末尾のスペースとは、後続の文字がない場合に行の終わりにあるすべての空白を意味します。ハードタブの後に何もない場合、ハードタブは末尾のスペースと見なされます。

ファイルの構造

読み取り可能な Swagger の定義を作成するには、次の構造で API の定義を作成します:

SwaggerOpenAPI バージョン (現在、 2.0 のみに対応しています)
コネクタに関する情報 (タイトル、説明、ステータス、連絡先)
ホストおよびサポートされているスキーム
セクションを消費/生成します
パス (アクションとトリガーの定義)
定義 (アクションとトリガーで使用されるデータ型)
パラメーター (操作全体で使用できるパラメーター)

アクションとトリガー

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 の操作は、definitions セクションで一度定義された同じオブジェクト応答 UserResponse を参照します。

{
  "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
      }
    }
  }
}

参照

フィードバックを提供する

コネクタプラットフォームの問題点や新機能のアイデアなどのフィードバックをお待ちしています。フィードバックを提供するには、「問題を送信するか、コネクタに関するヘルプを入手する」にアクセスし、フィードバックの種類を選択します。

次の方法で共有