initial commit

2 files changed, 216 insertions, 0 deletions

diff --git a/files/ja/web/api/permissions_api/index.html b/files/ja/web/api/permissions_api/index.html
new file mode 100644
index 0000000000..2c7048fffc
--- /dev/null
+++ b/files/ja/web/api/permissions_api/index.html
@@ -0,0 +1,91 @@
+---
+title: Permissions API
+slug: Web/API/Permissions_API
+tags:
+  - API
+  - Overview
+  - Permissions
+  - Reference
+translation_of: Web/API/Permissions_API
+---
+<div>{{DefaultAPISidebar("Permissions API")}}</div>
+
+<div class="summary">
+<p><span class="seoSummary"><strong>Permissions API</strong> は、現在のコンテキストに起因する API のパーミッションの状態を照会するための一貫したプログラム方法を提供します。 例えば、Permissions API を使用して、特定の API にアクセスするためのパーミッションが付与（granted）または拒否（denied）されているかどうかを確認できます。</span></p>
+</div>
+
+<h2 id="Concepts_and_usage" name="Concepts_and_usage">概念と使い方</h2>
+
+<p>歴史的に異なる API は独自のパーミッションを一貫性のない方法で扱います。 例えば、<a href="/ja/docs/Web/API/Notifications_API">Notifications API</a> はパーミッションの状態の明示的なチェックとパーミッションの要求を許可しますが、<a href="/ja/docs/Web/API/Geolocation">Geolocation API</a> はできません（ユーザーが最初のパーミッションの要求を拒否すると問題を引き起こします）。 Permissions API は、パーミッションに関する限り、開発者がより良いユーザーエクスペリエンスを実装できるようにするためのツールを提供します。</p>
+
+<p><code>permissions</code> プロパティが {{domxref("Navigator")}} オブジェクトで利用可能になり、標準の閲覧コンテキストとワーカーコンテキスト（{{domxref("WorkerNavigator")}} — したがって、ワーカー内でパーミッションの確認が可能）の両方で、Permissions API 機能へのアクセスを提供する {{domxref("Permissions")}} オブジェクトを返します。</p>
+
+<p>このオブジェクトを取得した後は、{{domxref("Permissions.query()")}} メソッドを使用して特定の API の {{domxref("PermissionStatus")}} で解決される Promise を返すなど、パーミッション関連のタスクを実行できます。</p>
+
+<p>Permissions API を使用してすべての API のパーミッションの状態を照会できるわけではありません。 Permissions に対応している注目すべき API は次のとおりです。</p>
+
+<ul>
+ <li><a href="/ja/docs/Web/API/Clipboard_API">Clipboard API</a></li>
+ <li><a href="/ja/docs/Web/API/Notifications_API">Notifications API</a></li>
+ <li><a href="/ja/docs/Web/API/Push_API">Push API</a></li>
+ <li>Web MIDI API</li>
+</ul>
+
+<p>今後、より多くの API が Permissions API のサポートを取得する予定です。</p>
+
+<h2 id="Examples" name="Examples">例</h2>
+
+<p>Location Finder という簡単な例を用意しました。 <a href="https://chrisdavidmills.github.io/location-finder-permissions-api/">例をライブで実行する</a>か、<a href="https://github.com/chrisdavidmills/location-finder-permissions-api/tree/gh-pages">Github でソースコードを見る</a>ことができます。</p>
+
+<p>それがどのように機能するかについてもっと読むには <a href="/ja/docs/Web/API/Permissions_API/Using_the_Permissions_API">Permissions API の使用</a>を見てください。</p>
+
+<h2 id="Interfaces" name="Interfaces">インターフェイス</h2>
+
+<dl>
+ <dt>{{domxref("Navigator.permissions")}} と {{domxref("WorkerNavigator.permissions")}} {{readonlyinline}}</dt>
+ <dd>それぞれメインコンテキストとワーカーコンテキストから {{domxref("Permissions")}} オブジェクトへのアクセスを提供します。</dd>
+ <dt>{{domxref("Permissions")}}</dt>
+ <dd>パーミッションの照会や取り消しのためのメソッドなど、コアとなる Permission API 機能を提供します。</dd>
+ <dt>{{domxref("PermissionStatus")}}</dt>
+ <dd>パーミッションの現在の状態、およびパーミッションの状態の変更に応答するためのイベントハンドラーへのアクセスを提供します。</dd>
+</dl>
+
+<h2 id="Specifications" name="Specifications">仕様書</h2>
+
+<table class="standard-table">
+ <thead>
+  <tr>
+   <th scope="col">仕様書</th>
+   <th scope="col">状態</th>
+   <th scope="col">備考</th>
+  </tr>
+ </thead>
+ <tbody>
+  <tr>
+   <td>{{SpecName('Permissions API')}}</td>
+   <td>{{Spec2('Permissions API')}}</td>
+   <td>初期定義</td>
+  </tr>
+ </tbody>
+</table>
+
+<h2 id="Browser_compatibility" name="Browser_compatibility">ブラウザーの互換性</h2>
+
+<div>
+<h3 id="Permissions_interface" name="Permissions_interface">Permissions インターフェイス</h3>
+
+<div>
+<div class="hidden">このページの互換性一覧表は構造化データから生成されています。データに協力していただけるのであれば、 <a class="external" href="https://github.com/mdn/browser-compat-data">https://github.com/mdn/browser-compat-data</a> をチェックアウトしてプルリクエストを送信してください。</div>
+
+<p>{{Compat("api.Permissions")}}</p>
+</div>
+</div>
+
+<h2 id="See_also" name="See_also">関連情報</h2>
+
+<ul>
+ <li><a href="/ja/docs/Web/API/Permissions_API/Using_the_Permissions_API">Permissions API の使用</a></li>
+ <li><a href="https://blog.addpipe.com/using-permissions-api-to-detect-getusermedia-responses/">Permissions API を使用して、ユーザーがカメラへのアクセスを許可または拒否する頻度を検出する</a>（英語）</li>
+ <li>{{DOMxRef("Notification.permission")}}</li>
+ <li><a href="/ja/docs/Web/Privacy">プライバシー、パーミッション、そして情報セキュリティ</a></li>
+</ul>
diff --git a/files/ja/web/api/permissions_api/using_the_permissions_api/index.html b/files/ja/web/api/permissions_api/using_the_permissions_api/index.html
new file mode 100644
index 0000000000..f7d7005428
--- /dev/null
+++ b/files/ja/web/api/permissions_api/using_the_permissions_api/index.html
@@ -0,0 +1,125 @@
+---
+title: Permissions API の使用
+slug: Web/API/Permissions_API/Using_the_Permissions_API
+tags:
+  - API
+  - Experimental
+  - Geolocation
+  - Guide
+  - Permissions
+translation_of: Web/API/Permissions_API/Using_the_Permissions_API
+---
+<p>{{DefaultAPISidebar("Permissions API")}}{{SeeCompatTable}}</p>
+
+<p class="summary"><span class="seoSummary">この記事では、W3C の Permissions API を使用するための基本的なガイドを提供します。 これは、現在のコンテキストに起因する API のパーミッションの状態を照会するためのプログラムによる方法を提供します。</span></p>
+
+<h2 id="The_trouble_with_asking_for_permission..." name="The_trouble_with_asking_for_permission...">パーミッションを求めるのが面倒...</h2>
+
+<p>ウェブ上のパーミッションは必要悪であり、そしてそれらは開発者として対処するのはそれほど面白くありませんが、それに立ち向かいましょう。</p>
+
+<p>歴史的には、異なる API は独自のパーミッションを一貫性のない方法で扱います。 例えば、Notifications API はパーミッションの状態の明示的なチェックとパーミッションの要求を許可しますが、Geolocation API はそうではありません（以下に示すように、ユーザーが最初のパーミッションの要求を拒否すると問題を引き起こします）。</p>
+
+<p><a href="/ja/docs/Web/API/Permissions_API">Permissions API</a> は、パーミッションに関する限り、開発者がより良いユーザーエクスペリエンスを実装できるようにするためのツールを提供します。 例えば、特定の API を使用するためのパーミッションが付与されているか拒否されているかを照会し、API を使用するためのパーミッションを具体的に要求することができます。</p>
+
+<p>現時点では、API の実装は初期段階にあるため、ブラウザーでのサポートは次のようにかなりむらがあります。</p>
+
+<ul>
+ <li>Chrome 44 以降と Firefox 43 以降でしか見つかりません。</li>
+ <li>現在サポートしている唯一のメソッドは {{domxref("Permissions.query()")}} で、これはパーミッションの状態を問い合わせます。</li>
+ <li>Chrome の Permissions API が現在認識している API は、<a href="/ja/docs/Web/API/Geolocation">Geolocation</a> と Notification の2つだけです。 Firefox は <a href="/ja/docs/Web/API/Push_API">Push</a> と WebMIDI も認識します。</li>
+</ul>
+
+<p>時間が経つにつれて、より多くの機能が追加されます。</p>
+
+<h2 id="A_simple_example" name="A_simple_example">簡単な例</h2>
+
+<p>この記事では、Location Finder という簡単なデモをまとめました。 Geolocation を使用してユーザーの現在地を照会し、それをグーグルマップに表示します。</p>
+
+<p><img alt="英国 Greenfield の地図を表示したスクリーンショット。" src="https://mdn.mozillademos.org/files/11501/location-finder-with-permissions-api.png" style="display: block; height: 428px; margin: 0px auto; width: 700px;"></p>
+
+<p><a href="https://chrisdavidmills.github.io/location-finder-permissions-api/">サンプルをライブで実行する</a>か、<a href="https://github.com/chrisdavidmills/location-finder-permissions-api/tree/gh-pages">Github でソースコードを見る</a>ことができます。 コードの大部分は単純で目立たないものです。 以下では Permissions API 関連のコードを見ていきますので、他の部分を調べたい場合はコードを自分で確認してください。</p>
+
+<h3 id="Accessing_the_Permissions_API" name="Accessing_the_Permissions_API">Permissions API へのアクセス</h3>
+
+<p>グローバルな {{domxref("Permissions")}} オブジェクトへのアクセスを許可するために、{{domxref("Navigator.permissions")}} プロパティがブラウザーに追加されました。 現在、このオブジェクトには {{domxref("Permissions.query()")}} しか含まれていませんが、最終的にはパーミッションの照会、要求、および取り消しのためのメソッドが含まれます。 下記参照。</p>
+
+<h3 id="Querying_permission_state" name="Querying_permission_state">パーミッションの状態の照会</h3>
+
+<p>この例では、Permissions 機能は <code>handlePermission()</code> という1つの関数によって処理されます。 これは、{{domxref("Permissions.query()")}} を使用してパーミッションの状態を照会することから始まります。 Promise が解決されたときに返される {{domxref("PermissionStatus")}} オブジェクトの {{domxref("PermissionStatus.state", "state")}} プロパティの値に応じて、次のように反応は異なります。</p>
+
+<dl>
+ <dt><code>"granted"</code>（付与）</dt>
+ <dd>[Geolocation を有効にする（Enable Geolocation）] ボタンは非表示です。 これは、Geolocation がすでにアクティブになっている場合は必要ないためです。</dd>
+ <dt><code>"prompt"</code>（プロンプト）</dt>
+ <dd>[Geolocation を有効にする] ボタンは非表示です。 これは、ユーザーに Geolocation のパーミッションを付与するように求めるプロンプトが表示される場合は必要ないためです。 {{domxref("Geolocation.getCurrentPosition()")}} 関数を実行し、ユーザーにパーミッションを求めるプロンプトを表示します。 それは、パーミッションが付与されている場合、<code>revealPosition()</code> 関数を実行し（地図を表示します）、パーミッションが拒否されている場合、<code>positionDenied()</code> 関数を実行します（[Geolocation を有効にする] ボタンを表示します）。</dd>
+ <dt><code>"denied"</code>（拒否）</dt>
+ <dd>[Geolocation を有効にする] ボタンを表示します（ページが最初に読み込まれたときに、パーミッションの状態がこのオリジンに対して既に拒否に設定されている場合も、このコードにくる必要があります）。</dd>
+</dl>
+
+<pre class="brush: js">function handlePermission() {
+  navigator.permissions.query({name:'geolocation'}).then(function(result) {
+    if (result.state == 'granted') {
+      report(result.state);
+      geoBtn.style.display = 'none';
+    } else if (result.state == 'prompt') {
+      report(result.state);
+      geoBtn.style.display = 'none';
+      navigator.geolocation.getCurrentPosition(revealPosition,positionDenied,geoSettings);
+    } else if (result.state == 'denied') {
+      report(result.state);
+      geoBtn.style.display = 'inline';
+    }
+    result.onchange = function() {
+      report(result.state);
+    }
+  });
+}
+
+function report(state) {
+  console.log('Permission ' + state);
+}
+
+handlePermission();</pre>
+
+<h3 id="Permission_descriptors" name="Permission_descriptors">パーミッション記述子</h3>
+
+<p>{{domxref("Permissions.query()")}} メソッドはパラメータとして <code>PermissionDescriptor</code> ディクショナリを取ります — これはあなたが興味を持っている API の名前を含みます。 いくつかの API は、デフォルトの <code>PermissionDescriptor</code> から継承した、追加情報を含んだ、より複雑な <code>PermissionDescriptor</code> を持っています。 例えば、<code>PushPermissionDescriptor</code> には、<code><a href="https://developer.mozilla.org/ja/docs/Web/API/PushManager/subscribe#Parameters">userVisibleOnly</a></code> が <code>true</code> か <code>false</code> かを指定する Boolean も含める必要があります。</p>
+
+<h3 id="Revoking_permissions" name="Revoking_permissions">パーミッションの取り消し</h3>
+
+<p>Firefox 47 以降、{{domxref("Permissions.revoke()")}} メソッドを使用して既存のパーミッションを取り消すことができるようになりました。 これは {{domxref("Permissions.query()")}} メソッドとまったく同じように機能しますが、Promise が正常に解決されると、既存のパーミッションがデフォルトの状態（通常は <code>prompt</code>）に戻される点が異なります。 デモで次のコードを見てください。</p>
+
+<pre class="brush: js">var revokeBtn = document.querySelector('.revoke');
+
+  ...
+
+revokeBtn.onclick = function() {
+  revokePermission();
+}
+
+  ...
+
+function revokePermission() {
+  navigator.permissions.revoke({name:'geolocation'}).then(function(result) {
+    report(result.state);
+  });
+}</pre>
+
+<div class="note">
+<p>Firefox 51 以降、<a href="https://www.w3.org/2011/webappsec/">Web Applications Security Working Group</a> で設計が問題になっているため、<code>revoke()</code> 関数はデフォルトで無効になっています。 設定 <code>dom.permissions.revoke.enable</code> を <code>true</code> に設定することで再度有効にすることができます。</p>
+</div>
+
+<h3 id="Responding_to_permission_state_changes" name="Responding_to_permission_state_changes">パーミッションの状態の変更への対応</h3>
+
+<p>上記のコードには、{{domxref("PermissionStatus")}} オブジェクトにアタッチされた <code>onchange</code> イベントハンドラがあることに気付くでしょう。 これにより、関心のある API のパーミッションの状態の変更に対応できるようになります。 現時点では、状態の変化を報告しているだけです。</p>
+
+<h2 id="Conclusion_and_future_work" name="Conclusion_and_future_work">まとめと今後の課題</h2>
+
+<p>現時点では、これは私たちがすでに持っていたもの以上のものを提供するものではありません。 パーミッションのプロンプトから位置を決して共有しないことを選択した場合（パーミッションを拒否した場合）、ブラウザーのメニューオプションを使用しないとパーミッションのプロンプトに戻ることはできません。</p>
+
+<ul>
+ <li><strong>Firefox</strong>: [ツール] &gt; [ページの情報] &gt; [サイト別設定] の順にクリックします。  [位置情報の送信] で [標準設定を使用する] をチェックします。</li>
+ <li><strong>Chrome</strong>: [ハンバーガーメニュー] &gt; [設定] &gt; [詳細設定] の順にクリックします。 [プライバシーとセキュリティ] セクションで [サイトの設定] をクリックします。 表示されたダイアログで、[位置情報] セクションを探し、[アクセスする前に確認する] を選択します。 最後に、[すべてのサイトに保存されている権限とデータを表示する] をクリックして、関心のあるサイトに付与されているパーミッションを削除します。</li>
+</ul>
+
+<p>しかしながら、ブラウザー機能への将来の追加は <code>request()</code> メソッドを提供するべきです、それは私たちが好きなときにいつでもプログラム的にパーミッションを要求することを可能にするでしょう。 うまくいけばこれらはすぐに利用可能になるはずです。</p>