GraphQL APIの使用¶
Liferay DXPには、ほとんどのアプリケーションに対応している GraphQL APIが含まれています。 ここでは、それらを使用する方法を紹介します。 必要なステップはわずか3つです。
使用するAPIを特定します。
必要なデータを含むサイトを特定します。
データにアクセスできる資格情報を使用してAPI呼び出しを行います。
GraphQL APIを呼び出すには、実行中のLiferay DXPが必要です。
新しいLiferay インスタンスを起動し、以下を実行します。
docker run -it -m 8g -p 8080:8080 liferay/portal:7.4.3.29-ga29。
http://localhost:8080でLiferayへのサインインします。 メールアドレス_test@liferay.com_とパスワード_test_を使用してください。 プロンプトが表示されたら、パスワードを _learn_に変更します。
Identify the Service to Consume¶
Follow these steps:
Go to
http://localhost:8080/o/api.At the top-left of the screen that appears, pick headless-delivery from the selector. これはブログ投稿APIを含むカテゴリです。
Click the Show GraphQL button at the top-right of the screen to open Liferay's GraphiQL browser.
Click the Docs link below the button you just clicked. これでAPIを閲覧できます。
GraphQL separates read and write operations by calling the first a query and the second a mutation . Since the first thing you want to do is post a blog entry, click mutation .
A list appears of the entire API use the search at the top or scroll down and find the call to
createSiteBlogPosting:createSiteBlogPosting( blogPosting: InputBlogPosting siteKey: String! ): BlogPosting
注釈
スキーマを直接要求することで、ローカルインストールのAPIを見つけることもできます
curl 'http://localhost:8080/o/graphql' -H 'Content-Type: application/json' --data '{"query":"query{ __schema{ queryType{ name fields{ name args{ name } description } } } }","variables":{}}'
このURLは認証を必要としませんが、返されたスキーマを管理するのはかなり面倒です。 このため、付属のGraphQLクライアントを使用することをお勧めします。
APIでは、エントリが投稿されるブログを含むサイトを把握している必要があるため、最初にサイトIDを見つける必要があります。
データを含むサイトを特定する¶
ここで、Site IDを見つける必要があります。
http://localhost:8080にアクセスしてください。グローバルメニュー
を開き、 コントロールパネル タブをクリックし、 サイト → サイトを表示します。Liferay Site の横にある Actions ボタン
をクリックし、 Go to Site Settings を選択します。サイト構成 にアクセスしてください。
サイトIDが[Details]セクションの上部に表示されます。 20122のような整数になります。
データにアクセスできる認証情報を使用してサービス呼び出しを行う¶
これで、呼び出しを行うために必要なものがすべて揃いました。 すべてのWebサービスには、要求しているデータにアクセスできる資格情報を使用してアクセスする必要があります。 含まれているGraphQLクライアントは、ブラウザーを使用して認証します。 スタンドアロンのクライアントを作成する場合は、OAuth2経由でユーザーを認証する必要があります。
開発中は、URLで資格情報データを渡す基本認証を使用する方がはるかに簡単です。 しかし、これは安全ではないので、 この方法をプロダクションに決して使用しないでください。
基本認証を使用したGraphQL APIの呼び出し（開発中のみ）¶
基本認証を使用してサービスを呼び出すには、URLに資格情報を指定します。
curl --request POST --url http://localhost:8080/o/graphql \ -u [email protected]:learn --header 'content-type: application/json' --data '{"query":"query {blogPostings(filter: \"\", page: 1, pageSize: 10, search: \"\", siteKey: \"20122\", sort: \"\"){ page items{ id articleBody headline creator{ name }}}}"}'
OAuth2を使用してサービスを呼び出す¶
本番環境では、OAuth2アプリケーションを作成し、OAuth2プロセスを使用して認証トークンを取得します。 トークンを取得したら、それをHTTPヘッダーに指定します。
curl --request POST --url http://localhost:8080/o/graphql -H "Authorization: Bearer d5571ff781dc555415c478872f0755c773fa159" --header 'content-type: application/json' --data '{"query":"query {blogPostings(filter: \"\", page: 1, pageSize: 10, search: \"\", siteKey: \"20122\", sort: \"\"){ page items{ id articleBody headline creator{ name }}}}"}'
データの取得と投稿¶
GraphQLクライアントの左上のウィンドウに、すべてのブログエントリを取得する次のコードを配置します。
query {blogPostings(filter:"",page:1,pageSize:10,search:"",siteKey:"20122",sort:"")
{page
items {
id
articleBody
headline
creator
{name
}
}
}
}
再生ボタンをクリックして実行すると、ブログエントリが表示されません。
{"data":{"blogPostings":{"page":1,"items":［］}}}
次に、ブログエントリを投稿します。
ブログエントリの投稿¶
GraphQLスキーマによって、ブログエントリを投稿するために行う必要がある呼び出しが明らかになりました。
公開したいエントリを含むJSONドキュメントを作成します。
{ "blog": { "articleBody": "This Blog entry was created by calling the GraphQL service!", "headline": "GraphQL Blog Entry" } }
スキーマドキュメンテーションに基づいてGraphQLクエリを作成します。
mutation CreateBlog($blog: InputBlogPosting){ createSiteBlogPosting(blogPosting: $blog, siteKey: "20122" ) { headline articleBody id friendlyUrlPath } }再度
http://localhost:8080/o/apiにアクセスしてリクエストを行います。 ［GraphQLを表示］ ボタンをクリックします。左下のクエリ変数ボックスにJSONドキュメントを貼り付けます。
Mutationを右上のラベルのないボックスに貼り付けます。
上部の再生ボタンをクリックしてクエリを実行します。
追加したブログエントリがGraphQLクライアントの右ペインに表示されます。
Liferay DXPは、ミューテーションでリクエストされたフィールドを含むブログエントリのJSON表現を返します。
{
"data": {
"createSiteBlogPosting": {
"headline": "GraphQL Blog Entry",
"articleBody": "This Blog entry was created by calling the GraphQL service!",
"id": 35541,
"friendlyUrlPath": "graphql-blog-entry"
}
}
}
注釈
これらのリクエストは、cURL などの任意のウェブクライアントで行うことができます。
curl --request POST --url http://localhost:8080/o/graphql -u test@liferay.com:learn --header 'content-type: application/json' --data '{"query": "mutation CreateBlog($blog: InputBlogPosting){ createSiteBlogPosting(blogPosting: $blog, siteKey: \"20122" ) { headline articleBody id friendlyUrlPath } }"".", "variables":{"blog": {"articleBody": "This Blog entry was created by using cURL to call the GraphQL service!", "headline": "cURL GraphQL Blog Entry"}}, "operationName": "CreateBlog"}'".
すべてのブログエントリを取得する¶
これで、最初のクエリを繰り返すことができます。
query {blogPostings(filter:"",page:1,pageSize:10,search:"",siteKey:"20122",sort:"")
{page
items {
id
articleBody
headline
creator
{name
}
}
}
}
Liferay DXPは、投稿したブログエントリを含むJSONを返します。
{
"data": {
"blogPostings": {
"page": 1,
"items": ［
{
"id": 35541,
"articleBody": "This Blog entry was created by calling the GraphQL service!",
"headline": "GraphQL Blog Entry",
"creator": {
"name": "Test Test"
}
}
］
}
}
}
単一のブログエントリを取得する¶
単一のブログエントリを取得するためのGraphQLスキーマからのAPI呼び出しには、パラメーターが1つしかありません。
blogPosting(
blogPostingId: Long
): BlogPosting
上記のクエリでブログ投稿のIDが判明したため、必要な投稿のみを取得できます。
query {blogPosting(blogPostingId: 35541)
{ id
headline
articleBody}
}
これをクライアントの左上のウィンドウに貼り付け、［再生］ボタンをクリックします。 同じブログエントリを返します。
{
"data": {
"blogPosting": {
"id": 35541,
"headline": "GraphQL Blog Entry",
"articleBody": "This Blog entry was created by calling the GraphQL service!"
}
}
}
ブログエントリの削除¶
ブログエントリの削除は、作成と同様にミューテーションです。 その呼び出しは、単一のブログエントリを取得するのとほぼ同じです。
deleteBlogPosting(
blogPostingId: Long
): Boolean
クライアントを使用して、次のような呼び出しを行うことができます。
mutation {
deleteBlogPosting(blogPostingId: 35541)
}
この呼び出しは、成功または失敗を示すブール値をJSONドキュメントで返します。
{
"data": {
"deleteBlogPosting": true
}
}
これで、LiferayDXPのGraphQLサービスを呼び出す方法を習得しました。 上記の例では基本認証を使用していることに注意してください。本番環境では、OAuth2を使用して安全な方法でサービスを呼び出します。