フィードバックを送信
Consuming APIs
ご覧のページは、お客様の利便性のために一部機械翻訳されています。また、ドキュメントは頻繁に更新が加えられており、翻訳は未完成の部分が含まれることをご了承ください。最新情報は都度公開されておりますため、必ず英語版をご参照ください。翻訳に問題がある場合は、 こちら までご連絡ください。

GraphQL APIの使用

Liferay DXP には、ほとんどのアプリケーション用の GraphQL API が含まれています。 GraphQL API は http://[host]:[port]/o/graphql で利用できます。

それらを消費する方法は、以下の3つのステップで説明します。

  1. 使用するAPIを特定します。

  2. 必要なデータを含むサイトを特定します。

  3. データにアクセスできる資格情報を使用してAPI呼び出しを行います。

注

Liferay DXP 2025.Q3以降では、 {siteId} を使用するGraphQL APIエンドポイントは、サイトのキーまたは外部参照コードでも動作します。 値が矛盾する場合は、次の順序で解決されます。

  1. サイトキー（デフォルト言語でのサイト名）
  2. サイトID
  3. サイト外部参照コード

まず、Liferay DXPを実行して、そのGraphQL APIを呼び出します。

新しいLiferay インスタンスを起動し、以下を実行します。

docker run -it -m 8g -p 8080:8080 liferay/portal:7.4.3.132-ga132

http://localhost:8080 で Liferay にサインインしてください。 メールアドレス test@liferay.com とパスワード test を使用してください。 プロンプトが表示されたら、パスワードを learnに変更します。

使用するサービスを特定する

  1. http://localhost:8080/o/api にアクセスしてください。

  2. 画面右上の GraphQL をクリックして、Liferay の GraphiQL ブラウザを開きます。

    APIエクスプローラーを通じてLiferayのGraphiQLにアクセスできます。

  3. クリックしたボタンの下にある ドキュメント リンクをクリックしてください。 これでAPIを閲覧できます。

  4. GraphQLでは、最初の操作を query 、2番目の操作を mutationと呼び、読み込みと書き込みを分離します。 まず最初にブログのエントリーを投稿したいので、 ［mutation］をクリックします。 API一覧が表示されます。

    重要

    Liferay DXP 2024.Q2+/Portal GA120+ バージョン付き名前空間 GraphQL API を使用することで、異なる API の操作間の名前の競合を回避し、各 API 操作のソースとバージョンを明確に示すことで可読性と保守性を向上させ、アプリケーションが進化する API と互換性を維持できるようにし、互換性の問題のリスクと頻繁な更新の必要性を軽減します。

    バージョン管理されたAPI呼び出しは、バージョン管理されていないAPI呼び出しと同様に機能します。 唯一の違いは、クエリに名前空間レベルが追加されている点です。 両方の例を以下に示します。

    バージョン付きとバージョンなしのGraphQL APIの両方を使用できますが、バージョンなしのAPIは 非推奨 であり、将来削除される予定であることに注意してください。

  5. 上部の検索機能を使用するか、下にスクロールして createSiteBlogPosting の呼び出しを見つけてください。

    createSiteBlogPosting(
   siteKey: String!
   blogPosting: InputBlogPosting
   ): BlogPosting

    Liferay DXP 2024.Q2+/Portal GA120+ または headlessDelivery_v1_0/MutationHeadlessDelivery_v1_0 名前空間で見つけることができます。

注

ローカルインストール環境の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クライアントを使用することをお勧めします。

含まれているGraphQLクライアントには、スキーマドキュメントブラウザがあります。

APIを利用するには、投稿先のブログが掲載されているサイトを知る必要があるため、まずサイトIDを特定する必要があります。

データを含むサイトを特定する

  1. http://localhost:8080にアクセスしてください。

  2. グローバルメニュー Global Menuを開き、 コントロールパネル タブをクリックし、 サイト → サイトに移動します。

  3. Liferay サイトの横にある アクション ボタン Actions Button をクリックし、 サイト設定に移動 を選択します。

  4. サイト設定 へ移動してください。

サイトIDが［Details］セクションの上部に表示されます。 これは整数です。例えば、 20117 のようになります。

データにアクセスできる認証情報を使用してサービス呼び出しを行う

これで電話をかけるために必要なものはすべて揃いました。 すべてのウェブサービスにアクセスするには、要求するデータへのアクセス権限を付与する認証情報を使用する必要があります。 付属のGraphQLクライアントは、ブラウザを介して認証を行います。 スタンドアロン クライアントを作成する場合は、 OAuth2 を介してユーザーを認証する必要があります。

重要

開発中は、URLで資格情報データを渡す基本認証を使用する方がはるかに簡単です。 しかし、これは安全ではないので、 この方法をプロダクションに決して使用しないでください。

基本認証を使用したGraphQL APIの呼び出し（開発中のみ）

基本認証を使用してサービスを呼び出すには、URLに資格情報を指定します。

curl \
   http://localhost:8080/o/graphql \
   --data "{'query':'query {blogPostings(filter: \'\', page: 1, pageSize: 10, search: \'\', siteKey: \'20117\', sort: \'\'){ page  items{ id articleBody headline  creator{ name }}}}'}" \
   --header "content-type: application/json" \
   --request POST \
   --user test@liferay.com:learn \

OAuth2を使用してサービスを呼び出す

注

Liferay DXP 7.4 U77+/Liferay Portal 7.4 GA77+ では、GraphQL と OAuth2 の併用がサポートされています。

本番環境では、 OAuth2 アプリケーション を作成し、OAuth2 プロセスを使用して認証トークンを取得します。 トークンを取得したら、それをHTTPヘッダーに指定します。

curl \
   http://localhost:8080/o/graphql \
   --data '{"query":"query {blogPostings(filter: \"\", page: 1, pageSize: 10, search: \"\", siteKey: \"20117\", sort: \"\"){ page  items{ id articleBody headline  creator{ name }}}}"}' \
   --header "Authorization: Bearer d5571ff781dc555415c478872f0755c773fa159" \
   --header 'content-type: application/json' \
   --request POST \

データの取得と投稿

GraphQLクライアントの左上のウィンドウに、すべてのブログエントリを取得するこのコードを貼り付けてください（ siteKey の値を変更することを忘れないでください！）。

query {
   blogPostings(
      filter: ""
      page: 1
      pageSize: 10
      search: ""
      siteKey: "20117"
      sort: ""
   ) {
      page
      items {
         id
         articleBody
         headline
         creator {
            name
         }
      }
   }
}

Liferay DXP 2024.Q2+/Portal GA120+ または、 headlessDelivery_v1_0 名前空間を追加して、次のようにクエリを記述することもできます。

query {
   headlessDelivery_v1_0 {
      blogPostings(
         filter: ""
         page: 1
         pageSize: 10
         search: ""
         siteKey: "20117"
         sort: ""
      ) {
         page
         items {
         id
         articleBody
         headline
         creator {
            name
         }
         }
      }
   }
}

再生ボタンをクリックして実行し、ブログ記事がないことを確認してください。

{
   "data": {
      "blogPostings": {
         "page": 1,
         "items": []
      }
   }
}

それでは、ブログ記事を投稿してください。

ブログエントリーの投稿

  1. 再度 http://localhost:8080/o/apiにアクセスしてリクエストを行います。 GraphQL をクリックしてください。

  2. 公開したいエントリを含む JSON ドキュメントを作成し、左下のクエリ変数ボックス (1) に配置します (ボックスを展開するには、下にスクロールして クエリ変数 をクリックする必要がある場合があります)。

    {
   "blog": {
      "articleBody": "This Blog entry was created by calling the GraphQL service!",
      "headline": "GraphQL Blog Entry"
   }
}

  3. スキーマドキュメントに基づいてGraphQLクエリを作成し、GraphQLクライアントの左上のウィンドウにあるクエリ領域に配置します（2）。

    mutation CreateBlog($blog: InputBlogPosting) {
   createSiteBlogPosting(blogPosting: $blog, siteKey: "20117") {
      headline
      articleBody
      id
      friendlyUrlPath
   }
}

    Liferay DXP 2024.Q2+/Portal GA120+ または、 headlessDelivery_v1_0 名前空間を追加して、次のようにクエリを記述することもできます。

    mutation CreateBlog($blog: InputBlogPosting) {
   headlessDelivery_v1_0 {
      createSiteBlogPosting(blogPosting: $blog, siteKey: "20117") {
         headline
         articleBody
         id
         friendlyUrlPath
      }
   }
}

  4. 上部の再生ボタンをクリックしてクエリを実行します。

    追加したブログ記事がGraphQLクライアントの右ペインに表示されます（3）。

Liferay DXPは、ミューテーションでリクエストされたフィールドを含むブログエントリーのJSON表現を返します。

{
   "data": {
      "headlessDelivery_v1_0": {
         "createSiteBlogPosting": {
         "headline": "GraphQL Blog Entry",
         "articleBody": "This Blog entry was created by calling the GraphQL service!",
         "id": 32198,
         "friendlyUrlPath": "graphql-blog-entry-3"
         }
      }
   }
}

JSONドキュメントは「クエリ変数」ボックスに入力し、ミューテーションは「クエリ」領域に入力します。 その結果、作成されたブログ記事の情報がGraphQLクライアントの右ペインに表示されます。

注

これらのリクエストは、cURLなどの任意のWebクライアントを使用して行うことができます。

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: \"20117\" ) { 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: "20117"
      sort: ""
   ) {
      page
      items {
         id
         articleBody
         headline
         creator {
            name
         }
      }
   }
}

Liferay DXP 2024.Q2+/Portal GA120+ または、 headlessDelivery_v1_0 名前空間を追加して、次のようにクエリを記述することもできます。

query {
   headlessDelivery_v1_0 {
      blogPostings(
         filter: ""
         page: 1
         pageSize: 10
         search: ""
         siteKey: "20117"
         sort: ""
      ) {
         page
         items {
            id
            articleBody
            headline
            creator {
               name
            }
         }
      }
   }
}

Liferay DXPは、投稿したブログエントリーを含むJSONを返します。

{
   "data": {
      "blogPostings": {
         "page": 1,
         "items": [
         {
            "id": 32010,
            "articleBody": "This Blog entry was created by calling the GraphQL service!",
            "headline": "GraphQL Blog Entry",
            "creator": {
               "name": "Test Test"
            }
         }
         ]
      }
   }
}
注

このようなコレクションクエリは検索インデックスから読み取りますが、Liferayはデータベースへの作成コミット後すぐにこのインデックスを更新します。 新しく作成されたエンティティがフィルタリングされたクエリまたはリストクエリに含まれていない場合は、 データの取得: 検索インデックスとデータベースの比較 を参照してください。

単一のブログエントリーを取得する

単一のブログエントリーを取得するためのGraphQLスキーマからのAPI呼び出しには、パラメーターが1つしかありません。

blogPosting(
   blogPostingId: Long
): BlogPosting

上記のクエリでブログ記事のIDが判明したので、必要な記事だけを取得できます。

query {
   blogPosting(blogPostingId: 32010) {
      id
      headline
      articleBody
   }
}

Liferay DXP 2024.Q2+/Portal GA120+ または、 headlessDelivery_v1_0 名前空間を追加して、次のようにクエリを記述することもできます。

query {
   headlessDelivery_v1_0 {
      blogPosting(blogPostingId: 32010) {
         id
         headline
         articleBody
      }
   }
}

これをクライアントの左上のウィンドウにあるクエリ領域に貼り付けて、 再生 ボタンをクリックします。 同じブログエントリを返します。

{
   "data": {
      "blogPosting": {
         "id": 32010,
         "headline": "GraphQL Blog Entry",
         "articleBody": "This Blog entry was created by calling the GraphQL service!"
      }
   }
}

ブログエントリーを削除する

ブログエントリの削除は、作成と同様にミューテーションです。 その呼び出しは、単一のブログエントリを取得するのとほぼ同じです。

deleteBlogPosting(
  blogPostingId: Long
): Boolean

クライアントを使用して、次のような呼び出しを行うことができます。

mutation {
   deleteBlogPosting(blogPostingId: 32010)
}

Liferay DXP 2024.Q2+/Portal GA120+ または、 headlessDelivery_v1_0 名前空間を追加して、次のようにクエリを記述することもできます。

mutation {
   headlessDelivery_v1_0 {
      deleteBlogPosting(blogPostingId: 32010)
   }
}

この呼び出しは、成功または失敗を示すブール値をJSONドキュメントで返します。

{
   "data": {
      "deleteBlogPosting": true
   }
}

これで、 これで、LiferayDXPのGraphQLサービスを呼び出す方法を習得しました。 上記の例では基本認証を使用していることに注意してください。本番環境では、OAuth2を使用して安全な方法でサービスを呼び出します。

Capability:
Platform
Resource Type:
Official Documentation
Feature:
API Development
Multi-Channel Experiences (Headless Delivery)
Deployment Approach:
Liferay PaaS
Liferay SaaS
Liferay Self-Hosted