PlanningPME API - 開発者向けドキュメント
計画データを残りの情報システムと相互接続します。
PlanningPMEを使用すると、専用のAPIを介してデータベースへの読み取りおよび書き込みアクセスが可能になります。
PlanningPME APIは、同期と統合の簡単なプログラミングのために、現在の開発標準（REST実装とJSON形式のデータトランスポート）に従います。
このドキュメントでは、以下についての情報を提供します：
- PlanningPME APIアドレスを決定する方法は？
- 対話型ドキュメントはどこにありますか？
- PlanningPME APIでセキュリティをどのように実装しますか？
- PlanningPME APIでの一般的なデータの考慮事項は何ですか？
- PlanningPME APIに最初のリクエストを行う方法は？
PlanningPME APIはRESTfulの原則に基づいており、デフォルトのデータ転送形式はJSONです。
このドキュメントは主に開発者向けです。先に進む前に、JSON REST APIプログラミングに精通することをお勧めします。
専用URL
各PlanningPMEクライアントには、専用のAPIアドレスがあります。
ブランド名が「MyCompany」であるとすると、APIアドレスを作成するために、おそらくブランドキー「mycompany」（大文字と小文字を区別しない）を使用する必要があります。
このキーは、このドキュメントの残りの部分で「your_brand」と表記されます。
ブランドのベースAPIアドレスは常に次のようになります：
https://api.planningpme.com/your_brand/
または
https://try.planningpme.com/your_brand/
対話型ドキュメント
各ブランドAPIは、PlanningPME APIメソッドとモデルを発見し、API呼び出しを構築するのに非常に役立つインタラクティブなドキュメントも提供します。
このドキュメントは、次のアドレスで入手できます：
https://api.planningpme.com/your_brand/doc/index
または
https://try.planningpme.com/your_brand/doc/index
これらの2つのアドレスは、アプリケーションキーの提示なしでは呼び出すことができません。
セキュリティー
1 /アプリケーションキーのプレゼンテーション
APIにアクセスして、呼び出し元のアプリケーションを識別するには、アプリケーションキー（appkey）が必要です。
このアプリキーは、PlanningPMEアカウントで、またはサポートへのオンデマンドで利用できます。
アプリキーを使用すると、APIアクセスを保護するだけでなく、APIへの呼び出しを識別するための独自のキーをパートナーまたは階層アプリケーションに提供することで、パートナーまたは層アプリケーションへのアクセスを許可できます。
アプリキーは、専用の「X-APPKEY」ヘッダーを使用して、常にAPI呼び出しのヘッダーで渡す必要があります。
GET /your_brand/api/config HTTP/1.1 Host: api.planningpme.com X-APPKEY: e991573da5ffd4sab9b1e26bc6b64aac
インタラクティブなドキュメントにアクセスするには、以下のサンプルのように、アプリキーをクエリパラメータとして使用します。
https://api.planningpme.com/your_brand/doc/index?appkey=e991573da5ffd4sab9b1e26bc6b64aac
2 /ユーザートークンと権限のあるユーザーなりすまし
データアクセス中に権限のあるユーザーを装うなどにより、定義されたユーザーおよびグループの承認に配慮するために、ほとんどのAPI呼び出しはユーザー認証を受ける必要があります。
承認は、ユーザーの名前とパスワードをAPIに送信し、その後のAPI呼び出しを認証または権限のあるユーザーを装うなどにより使用されるトークンを取得することで付与されます。
認証トークンの取得は、常にこれらのデータを「/token」URLに投稿することによって行われます。
POST /votre_marque/token HTTP/1.1 Host: api.planningpme.com X-APPKEY: e991573da5ffd4sab9b1e26bc6b64aac grant_type=password&username=your_username&password=your_password
認証が成功した場合、応答本文には次のようにJSONエレメントが含まれます。
{
"access_token": "KTuZYDLG2qjUMqMVXDuiP9giFbqDXstESvpUWzBFLpkfdlMiB3PD5s2K7En-3o39u56hpr_DlyjEc_oUzBbR0PoEQfOb_O7m5BrLz9vwDzV_YjtRRrQ_7QxYnxO9uZs38SJ7UxTjDZgx_JKRUoZ3Wk6RNnXRpSkcmOrINvJLDMYXptYFiTjn9Op-vkPdtOKFp9M1cNjrH1ho2uaRBpUUMH_vJ-8W8mTH9wgFrJlecGIpntb7jet2GYpGs3Is0gcH",
"token_type": "bearer",
"expires_in": 86399,
"username": "your_username"
}
「access_token」プロパティの値は、APIへの後続の承認されたリクエストで使用する必要があります。
また、「token_type」プロパティで示されているように、この値はベアラートークンです。
その後の承認された呼び出しは、「Authorization」ヘッダーにこの特定の「Bearer」値を提示する必要があります。
POST /your_brand/api/customer HTTP/1.1 Host: api.planningpme.com X-APPKEY: e991573da5ffd4sab9b1e26bc6b64aac Authorization: Bearer KTuZYDLG2qjUMqMVXDuiP9giFbqDXstESvpUWzBFLpkfdlMiB3PD5s2K7En-3o39u56hpr_DlyjEc_oUzBbR0PoEQfOb_O7m5BrLz9vwDzV_YjtRRrQ_7QxYnxO9uZs38SJ7UxTjDZgx_JKRUoZ3Wk6RNnXRpSkcmOrINvJLDMYXptYFiTjn9Op-vkPdtOKFp9M1cNjrH1ho2uaRBpUUMH_vJ-8W8mTH9wgFrJlecGIpntb7jet2GYpGs3Is0gcH
APIの使用法
1 /一般的なデータの考慮事項
a）モデル
PlanningPMEデータモデルの詳細は、APIのインタラクティブドキュメントでご説明しております。
b）日付形式
APIで使用され、各JSONリクエストで予期される日付形式は ISO8601形式です。 Ex:
2018-01-25T18:05:00Z
c）リストの並べ替え
GETメソッドは、多くの場合、「sortInfo」パラメータを使用して、返される完全な/ページ付けされたリストの並べ替え順序を設定します。
この情報は、プロパティの名前の直後に+または-記号が続く形式で構成されます。
たとえば、「label+」を使用して、「label」プロパティを昇順で並べ替えます。
複数の注文を追加して組み合わせることができます。
たとえば、「notValid-label+」を使用して、「notValid」プロパティを降順で並べ替え、次に「label」プロパティを昇順で並べ替えます。
プロパティラベルでは大文字と小文字が区別されることに注意してください。
d）一定の列挙
APIバージョンで使用されている列挙型の完全なリストは、「/api/config」メソッドを呼び出すことで取得されます。このリストは、将来の追加を除いて変更する権利を付与するものではありません。
GET /your_brand/api/config HTTP/1.1 Host: api.planningpme.com X-APPKEY: e991573da5ffd4sab9b1e26bc6b64aac
リストの下には、APIのバージョン4.1.1.117の列挙型があります。
{
...
enums: {
"Access": {
"All": 0,
"Read": 82,
"Write": 87
},
"BillingType": {
"Package": 0,
"Unit": 1
},
"ConstraintAction": {
"NoTaskBeforeNbHours": 0,
"NoTaskBeforeNbDays": 1,
"NoTaskSamePeriod": 2,
"NbMaxHours": 3,
"NbMax": 4,
"DurationMaxHours": 5,
"DurationMaxDays": 6
},
"ConstraintFor": {
"All": 0,
"Resources": 1,
"Departments": 2
},
"ConstraintIf": {
"Nothing": 0,
"Nb": 1,
"NbHours": 2,
"Begin": 3,
"End": 4
},
"ConstraintOp": {
"Nothing": 0,
"Equal": 1,
"Inf": 2,
"InfEqual": 3,
"Sup": 4,
"SupEqual": 5,
"Before": 6,
"After": 7
},
"ConstraintType": {
"Task": 0,
"Unavailability": 1
},
"ConstraintWhat": {
"LabelAll": 0,
"LabelExact": 1,
"LabelBegin": 2
},
"ConstraintWhen": {
"Nothing": 0,
"Day": 1,
"Week": 2,
"Month": 3,
"Year": 4
},
"CustomerType": {
"Individual": 1026,
"Company": 1027
},
"DataFieldType": {
"Date": 1,
"Time": 2,
"Text": 3,
"Numeric": 4,
"Double": 5,
"Combo": 6,
"Link": 7,
"Check": 8,
"Memo": 9,
"Separator": 10,
"File": 11,
"Position": 12,
"SignatureMobile": 13,
"Hyperlink": 16,
"Startdate": 17,
"Enddate": 18,
"Duration": 19,
"Signature": 20
},
"DescriptionFieldType": {
"Index1": 49,
"Index2": 50,
"EmailBody": 69,
"Label": 76,
"Mobile": 77,
"Calendar": 79,
"EmailSubject": 83,
"Tooltip": 84
},
"Destination": {
"Task0": 48,
"Task2": 50,
"Task3": 51,
"Task4": 52,
"Task5": 53,
"Equipment0": 65,
"Customer1": 67,
"MaterialResource1": 77,
"MaterialResource2": 78,
"MaterialResource3": 79,
"Project0": 80,
"HumanResource1": 82,
"HumanResource2": 83,
"Task1": 84,
"HumanResource3": 86,
"Customer0": 97,
"HumanResource0": 98,
"Customer2": 99,
"MaterialResource0": 100
},
"DestinationType": {
"Task": 0,
"Customer": 1,
"Equipment": 2,
"Resource": 3,
"Project": 4
},
"HistoryOp": {
"Insert": 65,
"Delete": 68,
"Email": 69,
"Invitation": 73,
"Update": 85
},
"HistoryType": {
"Customer": 67,
"Unavailability": 73,
"Project": 80,
"Resource": 82,
"Task": 84
},
"JsonWritingType": {
"Normal": 1,
"KeyLabel": 2,
"String": 3,
"Data": 4
},
"LicenseStatus": {
"Other": 0,
"Evaluation": 1,
"Ok": 2,
"NoExpirationDate": -8,
"WrongDatabase": -7,
"WrongMachine": -6,
"ResourceCount": -5,
"LicenseCount": -4,
"Expired": -3,
"Empty": -2,
"Corrupted": -1
},
"NotificationType": {
"None": 0,
"TaskInsert": 1,
"TaskUpdate": 2,
"UnavailabilityInsert": 4,
"UnavailabilityUpdate": 8
},
"OneOrMoreCustomers": {
"OneCustomer": 1422,
"MoreCustomer": 1423
},
"OneOrMoreResources": {
"OneResource": 1076,
"MoreResource": 1077
},
"RecurrenceDaily": {
"AllThe": 1255,
"AllWorkingDays": 1256
},
"RecurrenceMonthly": {
"Date": 1258,
"Day": 1259
},
"RecurrenceMonthlyDayWhich": {
"First": 0,
"Second": 1,
"Third": 2,
"Fourth": 3,
"Last": 4
},
"RecurrenceRange": {
"NoEndDate": 1250,
"EndThe": 1252
},
"RecurrenceType": {
"Daily": 1246,
"Weekly": 1247,
"Monthly": 1248,
"Yearly": 1249
},
"ResourceFilter": {
"All": 40960,
"Human": 45056,
"Material": 49152,
"ToPlan": 53248
},
"ResourceType": {
"Human": 1035,
"Material": 1036,
"ToPlan": 1537
},
"TaskType": {
"Default": 1467,
"Duration": 1468,
"Time": 1469
},
"Title": {
"Miss": 0,
"Mr": 1,
"Ms": 2
},
"TimeLapseUnit": {
"Day": 0,
"Week": 1,
"Month": 2,
"Year": 3
},
"TypeHatch": {
"BDIAGONAL": 0,
"CROSS": 1,
"DIAGCROSS": 2,
"FDIAGONAL": 3,
"HORIZONTAL": 4,
"VERTICAL": 5
},
"WorkCapacity": {
"Hours": 1590,
"Slots": 1591
}
}
...
e）応答言語
エラーメッセージなどの応答テキストで使用される言語は、「Accept-Language」ヘッダーで指定できます。
Accept-Language: 英語
PlanningPMEAPIおよびPlanningPMEWebAccessで使用可能な言語は日本語（ja）、デンマーク語（da）、オランダ語（nl）、英語（en）、フィンランド語（fi）、フランス語（fr）、ドイツ語（de）、イタリア語（it）、ノルウェー語（no) 、ポーランド語（pl）、ロシア語（ru）、スペイン語（es）、スウェーデン語（sv）です。
2 / API呼び出しの例
以下の例では、
/api/task
→ GET "/api/task"メソッドを使用して、タスクの完全なリストまたはページ付けされたリストを取得します。
GET /your_brand/api/task?pageIndex=1&pageSize=20&sortInfo=label+ HTTP/1.1 Host: api.planningpme.com X-APPKEY: your_key Authorization: Bearer your_token
ラベルの降順で並べ替えられた20個のタスクの2ページ目を含むタスクの配列を返します。
{
"totalItems": 97,
"items": [
{
"key": 756,
"label": "Cours d'anglais pour enfant",
"type": 1467,
"style": {
"backgroundColor": "#65A18D",
"color": "#000000"
}
},
...
{
"key": 131,
"label": "Coaching",
"type": 1467,
"style": {
"backgroundColor": "#214DE9",
"color": "#000000"
}
}
]
}
→ GET "/api/task/{id}"メソッドを使用して詳細なタスクを取得します。
GET /your_brand/api/task/756 HTTP/1.1 Host: api.planningpme.com X-APPKEY: votre_clé Authorization: Bearer your_token
ID756のタスクの詳細なタスクオブジェクト表現を返します。
{
"key": 756,
"label": "Cours d'anglais pour enfant",
"type": 1467,
"style": {
"backgroundColor": "#65A18D",
"color": "#000000"
},
"skills": [
[
{
"key": 12,
"name": "Enfant",
"label": "Pédagogie > Enfant",
"level": 1,
"domain": {
"key": 4,
"label": "Pédagogie"
}
},
{
"key": 83,
"name": "Anglais",
"label": "Langue > Anglais",
"level": 1,
"domain": {
"key": 4,
"label": "Langue"
}
}
]
]
}