カスタム ドキュメントの追加

OpenAPI   |  gRPC

2022 年 3 月 21 日をもって、Cloud Endpoints Portal はサポートが終了しました。2023 年 3 月 21 日以降、Cloud Endpoints Portal は利用できなくなります。Cloud Endpoints が管理する API トラフィックは、この変更の影響を受けません。詳細については、機能のサポート終了をご覧ください。

SmartDocs API リファレンス ドキュメントに加えて、API のユーザーに必要なカスタム ドキュメントをポータルに追加できます。ユーザーに追加のドキュメント ページを提供する必要がない場合でも、API の使用方法を説明するために、ポータルに表示されるサンプルのスタートガイドを更新する必要があります。

このページでは、サンプルのスタートガイドを変更する方法と、ポータルに追加するドキュメント ページを作成して表示する方法について説明します。また、それぞれのタスクを実行するために最低限必要な Identity and Access Management のロールについても説明します。IAM の権限について詳しくは、以下をご覧ください。

• ロールについて
• リソースへのアクセス権の付与、変更、取り消し
• カスタム役割の作成と管理

要件

このページでは、次の作業がすでに行われていることを前提としています。

• ポータルが作成されていること。
• Google Cloud CLI がインストールされ、初期化されていること。
• Git がインストールされていること。
• Git のメールと名前を設定していること。

カスタム ドキュメントについて

ポータルにカスタム ドキュメントを表示するには、ファイルを Git リポジトリに保存し、ポータルの [設定] ページで Git リポジトリの URL を構成する必要があります。カスタム ドキュメント用のファイルは次の場所に追加できます。

• API と同じ Google Cloud プロジェクトにある Cloud Source Repositories 内の非公開リポジトリ。
• GitHub または Bitbucket の公開リポジトリ。

Cloud Endpoints Portal でカスタム ドキュメントが認識されて表示されるには、リポジトリ内のファイルとフォルダが特定の構造になっている必要があります。リポジトリのルートには、名前が Cloud Endpoints サービス名のフォルダが必要です。必要に応じて追加のサブフォルダを作成できます。左側のナビゲーション バーには、フォルダとファイルへのリンクが含まれています。詳細については、ディレクトリ構造の要件をご覧ください。

スタートガイドのコンテンツの編集や、追加のドキュメント ページ用のコンテンツの記述には、Markdown を使用します。Endpoints Portal は CommonMark の仕様に加えて、GitHub Flavored Markdown 仕様の table 拡張にも従います。

リポジトリに画像を追加して、その画像を Markdown ファイルから参照することもできます。

カスタム ドキュメントの更新

更新を始めるにあたり、まずは以下のファイルが含まれている GitHub 上の endpoints-developer-portal-sample-content リポジトリのクローンを作成することをおすすめします。

• Getting Started.md: ポータルに表示されるサンプルの [スタートガイド] ページのコンテンツを含む Markdown ファイル。
• Example Page.md: Markdown を使い始める際に役立つサンプル ファイル。
• navigation.yaml: ポータルの左側のナビゲーション バーに表示されるページとフォルダの順序を記述するファイル。

• add_example_page: 以下の処理を行うスクリプト。

  • Google Cloud プロジェクトの Cloud Source Repositories に Git リポジトリを作成する。
  • default-content-repo フォルダにローカル Git リポジトリを作成する。
  • Endpoints のサービス名と同じ名前のフォルダを作成し、Guides というサブフォルダを作成する。
  • Guides フォルダに Example Page.md と Getting Started.md というファイルを追加する。
  • Example Page を navigation.yaml ファイルに追加する。
  • これらの変更を commit し、Cloud Source Repositories 内の新しく作成した Git リポジトリに push する。

  スクリプトには 2 つのバージョンがあります。

  • Linux ユーザーと Mac ユーザーには add_example_page.sh（Bash シェル）が用意されています。
  • Windows ユーザーには add_example_page.ps1（PowerShell）が用意されています。

  スクリプトの実行は任意です。必要に応じて、Cloud Source Repositories 内あるいは GitHub や Bitbucket の公開リポジトリ内にリポジトリを手動で作成することもできます。その場合、カスタム ドキュメントの必要なディレクトリ構造を設定する必要があります。

  スクリプトを実行する前に、Cloud Source Repositories の料金と割り当てに関するドキュメントをご確認ください。スクリプトを実行した後に GitHub や Bitbucket の公開リポジトリを使用することを選択した場合、Cloud Source Repositories からリポジトリを削除できます。

カスタム ドキュメントのスターター ファイルを取得する

このセクションでは、add_example_page スクリプトを実行できるよう準備する方法について説明します。

このタスクに必要な権限

このタスクを行うには、プロジェクトに対するプロジェクト編集者の役割が必要です。この役割には、以下を行うための権限が付与されています。

• Cloud Source Repositories API を有効にする。
• Cloud Source Repositories でリポジトリを作成する。
• API のポータルとリポジトリのコンテンツを同期する。

カスタム ドキュメントのスターター ファイルを取得するには:

1. Cloud Source Repositories API を有効にします。

   1. [API とサービス] から [API ライブラリ] ページに移動します。

      [API ライブラリ] に移動

   2. プロジェクト リストから、API が含まれているプロジェクトを選択します。

   3. Cloud Source Repositories API を検索し、そのカードをクリックして情報ページを表示します。

   4. [有効にする] をクリックします。

2. gcloud CLI がデータやサービスにアクセスできるように承認されていることを確認します。

   gcloud auth login
   

3. デフォルト プロジェクトを設定します。次のコマンドで、YOUR_PROJECT_ID は Endpoints API を作成した Google Cloud プロジェクト ID で置き換えます。

   gcloud config set project YOUR_PROJECT_ID
   

4. サンプル コンテンツ、構成、スクリプトをダウンロードします。

   git clone https://github.com/GoogleCloudPlatform/endpoints-developer-portal-sample-content
   

5. スクリプトが含まれているディレクトリに移動します。

   cd endpoints-developer-portal-sample-content/scripts
   

6. Endpoints サービス名を表示します。

   gcloud endpoints services list
   

7. Endpoints サービス名でスクリプトを実行します。

   • Linux ユーザーと Mac ユーザー: ./add_example_page.sh SERVICE_NAME
   • Windows ユーザー: add_example_page.ps1 SERVICE_NAME

   スクリプトが完了すると、次の場所の URL が出力されます。

   • API のポータル設定。

   • Git の URL。これは、Cloud Source Repositories ページの [クローン URL] フィールドに表示されるものと同じ URL です。

8. リポジトリをポータルに同期します。

   1. 最初の URL をハイライト表示してコピーし、ブラウザのアドレスバーに貼り付けて [Settings] ページに移動します。
   2. ログイン プロンプトの指示に従って API の [Settings] ページに進みます。アカウントが複数ある場合は、該当する API が含まれている Google Cloud プロジェクトで使用されているアカウントを選択してください。
   3. Git リポジトリのクローン URL をハイライト表示してコピーし、[Custom Content Settings] フィールドに貼り付けます。
   4. [Sync] をクリックします。
   5. [Save] をクリックします。
   6. API ドキュメントのランディング ページに戻るには、タイトルバーをクリックします。

   左側のナビゲーション バーで、[Example Page] をクリックしてコンテンツを表示します。

9. 新しく作成したリポジトリの内容を参照します。Google Cloud コンソールで、プロジェクトの [ソース リポジトリ] > [ソースコード] ページに移動します。

   ソースコード ブラウザに移動

   ソースコード ブラウザに、最新の commit レベルのリポジトリ コンテンツがディレクトリ表示されます。詳細については、リポジトリの閲覧をご覧ください。

カスタム ドキュメントの変更

Cloud Source Repositories にカスタム ドキュメントが作成されたため、必要に応じてコンテンツを変更したり、ファイルやフォルダを追加または削除したりできます。初めて Git を使用する場合は、Git ドキュメント内のリファレンス ドキュメント、書籍や動画のリンクをご覧ください。

このタスクに必要な権限

このタスクを行うには、プロジェクトに対するプロジェクト編集者の役割が必要です。この役割には、以下を行うための権限が付与されています。

• Cloud Source Repositories のコンテンツを変更する。
• API のポータルとリポジトリのコンテンツを同期する。

Getting Started のコンテンツを変更する

Getting Started のコンテンツを変更するには:

1. ローカルの Git リポジトリのルートから始めて、Endpoints サービスと同じ名前のフォルダに移動します。例:

   cd example-api.example.com
   

2. Getting Started.md を含むフォルダに移動します。

   cd Guides
   

3. テキスト エディタで Getting Started.md を開きます。

4. ユーザーが API を使い始める際に役立つように、必要に応じてコンテンツを変更します。

5. ファイルを保存します。

6. 変更を commit します。

   git commit -a -m "updated getting started"
   

7. Cloud Source Repositories のリポジトリに変更を push します。

   git push
   

8. 次の手順で、更新されたコンテンツをポータルに同期します。

   1. ポータルを参照します。
   2. [Settings] をクリックします。
   3. [Settings] ページで [API] タブをクリックし、リストから API を選択します。
   4. [Sync] をクリックします。
   5. [Save] をクリックします。

   左側のナビゲーション バーで [Getting Started] のリンクをクリックすると、更新されたコンテンツが Endpoints Portal に表示されます。

Example Page を削除する

Example Page を削除するには:

1. ローカルの Git リポジトリのルートから始めて、Endpoints サービスと同じ名前のフォルダに移動します。例:

   cd example-api.example.com
   

2. テキスト エディタで navigation.yaml ファイルを開きます。

3. ordering セクションで、Example Page の行を削除します。

4. ファイルを保存します。

5. Git から Example Page.md ファイルを削除します。

   git rm ‘Guides/Example Page.md'
   

6. 変更を commit します。

   git commit -a -m "removed example page"
   

7. Cloud Source Repositories のリポジトリに変更を push します。

   git push
   

8. 次の手順で、更新されたコンテンツをポータルに同期します。

   1. ポータルを参照します。
   2. [Settings] をクリックします。
   3. [Settings] ページで [API] タブをクリックし、リストから API を選択します。
   4. [Sync] をクリックします。
   5. [Save] をクリックします。

Example Page が左ナビゲーション バーからなくなっています。

Example Page の名前を変更する

Example Page の名前を変更するには:

1. ローカルの Git リポジトリのルートから始めて、Endpoints サービスと同じ名前のフォルダに移動します。例:

   cd example-api.example.com
   

2. テキスト エディタで navigation.yaml ファイルを開きます。

3. ordering セクションにある Example Page を自分のガイドのタイトルに変更します。ここでの名前は、Guides ディレクトリの実際のファイル名と一致している必要があります。

4. ファイルを保存します。

5. Git で Example Page.md ファイルの名前を変更します。

   git mv 'Guides/Example Page.md' 'Guides/NEW FILENAME.md'

6. 必要に応じて、名前変更したファイルのコンテンツを変更します。

7. 変更を commit します。

   git commit -a -m "removed example page"
   

8. Cloud Source Repositories のリポジトリに変更を push します。

   git push
   

9. 次の手順で、更新されたコンテンツをポータルに同期します。

   1. ポータルを参照します。
   2. [Settings] をクリックします。
   3. [Settings] ページで [API] タブをクリックし、リストから API を選択します。
   4. [Sync] をクリックします。
   5. [Save] をクリックします。

左側のナビゲーション バーに、名前変更したページが表示されます。

ディレクトリ構造の要件

カスタム コンテンツが Endpoints Portal で認識されて表示されるには、リポジトリ内のファイルとフォルダは特定の構造になっている必要があります。

リポジトリのルートには、名前が Endpoints サービス名のフォルダを配置する必要があります。この構造では、API ごとに別々のルートレベルのフォルダを用意することで、複数の API に対して 1 つのリポジトリを使用できます。

サービス フォルダ内でサブフォルダを使用すると、関連するページを 1 つのセクションの下にグループ化でき、その下にさらにサブフォルダを含めることもできます。フォルダのタイトルとファイル名はナビゲーションに使用されます。たとえば、Getting Started.md という名前のファイルは左側のナビゲーション バーで Getting Started と表示されます。Endpoints サービス名が付いたフォルダ内には、navigation.yaml というファイルが必要です。このファイルは、ポータルの左側のナビゲーション バーにコンテンツを表示する方法を示します。デフォルトでは次のようになっています。

ordering:
- Introduction
- Guides
- API Reference
- Resources

folders:
  Guides:
    ordering:
    - Getting Started
    - Example Page

最初の ordering リストは、そのレベルで表示するエントリの順序を指定します。たとえばデフォルトの navigation.yaml ファイルでは、Introduction ページが最初に表示され、その後に Guides セクションが続くように指定されています。

Introduction、API Reference、Resources は特別なセクションであるため、navigation.yaml から削除することはできませんが、順序は変更できます。

各フォルダとページの構成は、その親の navigation.yaml 内の folders 構成と対応している必要があります。これを省略すると、ページやフォルダがポータルに表示されません。たとえばデフォルトの navigation.yaml ファイルでは、folders キーに Guides というサブキーが含まれていますが、これは同じ名前のフォルダが存在するためです。

画像を追加する

画像をカスタム コンテンツの Git リポジトリに追加して、その画像を Markdown ファイルの中で参照できます。画像とその画像を参照する Markdown ファイルが Endpoints サービス名と同じディレクトリにある場合は、（/ で始まる）相対 URL で画像を参照できます。

たとえば、ディレクトリ構造が次のとおりであるとします。

~/example-api.example.com/
    get-started.md
    images/
        example.jpg

画像 images/example.jpg を get-started.md に追加して、次のようにマークアップできます。

    ![alt-text](/images/example.jpg "Optional title")

別の場所にある画像を追加するには、標準の Markdown 構文と画像の完全 URL を使用します。

    ![alt-text](https://example.com/image.png "Optional title")

ポータルでサポートされる画像の種類は次のとおりです。

• BMP
• GIF
• JPEG
• PNG
• TIFF
• WEBP

カスタム コンテンツに関する制限

ポータルでは、カスタム コンテンツに関して次の制限があります。

• Markdown ページの最大数は API あたり 200。
• 画像の最大数は API あたり 200。
• 画像の最大サイズは 1 つあたり 4 MiB。

次のステップ

• API によるカスタム ドキュメントの同期
• SmartDocs API リファレンス ドキュメントの更新